feat/discovery

FeatureHighlight fires without the discovery feature flag

apps/platform/src/components/discovery/FeatureHighlight.tsx:34

FeatureSpotlight gates on `(flagEnabled || isPreviewDeployment()) && isDesktop && !!page && !!orgId`. FeatureHighlight has no such guard — it processes any `?descubre=<key>` URL unconditionally. DescubreMenu is flag-gated so ordinary users won't see the link, but a stale bookmark or hand-crafted URL will pulse the control even when `feature-discovery-spotlights` is disabled. Failure mode is benign (visual only, param is stripped), but the flag doesn't fully suppress the surface. Also: DescubreMenu is md-gated (768px) while FeatureSpotlight is lg-gated (1024px), so on tablets (768–1024px) the hub can generate ?descubre links whose visual cue has no breakpoint guard.

Stale ring position during rapid key A→B switch

apps/platform/src/components/discovery/FeatureHighlight.tsx:60

When the user clicks a second hub item before the first pulse expires, the locate effect cleanup clears A's timers but does not call `setRect(null)`. Because `key` is now B but `rect` still holds A's DOMRect, the ring briefly renders at A's position during the `setTimeout(0)` + retry window (up to 300ms if B's element is async). Adding `setRect(null)` as the first statement in the locate effect for truthy `key` eliminates the artefact.

Dead `typeof document === 'undefined'` guard after hooks

apps/platform/src/components/discovery/FeatureHighlight.tsx:116

This guard is dead code in a `'use client'` component — document is always defined. If ever reached in SSR, all the hooks above would have thrown first. Remove it or move the check before any hooks.

querySelector key not CSS.escape()d — safe today, fragile by convention

apps/platform/src/components/discovery/FeatureHighlight.tsx:68

`[data-tour="${key}"]` is safe today because `key` is catalog-validated. But if a catalog key ever contains a CSS metacharacter (dot, bracket, quote), the selector silently misbehaves or throws. `CSS.escape(key)` would make the contract independent of catalog authors remembering to avoid those characters.

router.replace strip path is safe — no open redirect

apps/platform/src/components/discovery/FeatureHighlight.tsx:53

The strip path derives the query string from the browser's own URLSearchParams (not the raw param value) and calls next-intl's internal router.replace. No open-redirect surface.

Multi-paragraph docstrings prohibited by CLAUDE.md

apps/platform/src/components/discovery/FeatureHighlight.tsx:3

The file-level JSDoc (lines 3–19) is an 18-line, 3-paragraph rationale block ('Why a pulse and not a floating card...'). CLAUDE.md prohibits multi-paragraph docstrings. Also: HIGHLIGHT_PARAM in spotlight-catalog.ts has a 10-line multi-paragraph JSDoc (lines 72–82). Architectural rationale belongs in ADRs or commit messages.

eslint-disable masking non-idiomatic deps expression

apps/platform/src/components/discovery/FeatureHighlight.tsx:113

The scroll/resize effect uses `[rect !== null, key]` with `// eslint-disable-line react-hooks/exhaustive-deps`. Passing a derived boolean into deps is non-idiomatic. Extracting `const pulsing = rect !== null` and using `[pulsing, key]` expresses the intent clearly with no suppression needed.

Redundant SSR guard in render return of 'use client' component

apps/platform/src/components/discovery/FeatureHighlight.tsx:116

`typeof document === 'undefined'` in the render return of a `'use client'` component is always false — client components never run server-side in App Router. The guard is dead code.

resolveSpotlightPage and pathForPage have no direct unit tests

apps/platform/src/components/discovery/spotlight-catalog.ts:34

Both are pure functions with branching logic (sub-path matching, fallback path) exercised only indirectly via tutorialHref tests. A handful of direct assertions would give complete coverage cheaply.

resolveHighlightKey coverage is complete

apps/platform/src/components/discovery/__tests__/highlight-key.test.ts

Full catalog enumeration, prototype-chain guards (constructor/toString), and absent/empty inputs are all covered. No gaps.

Locate retry constants duplicated between FeatureHighlight and FeatureSpotlight

apps/platform/src/components/discovery/FeatureSpotlight.tsx:218

FeatureHighlight.tsx defines LOCATE_RETRY_MS=300 and LOCATE_MAX_ATTEMPTS=10 as named constants; FeatureSpotlight.tsx still uses bare magic numbers 300 and 10 in its locate loop. If the retry budget needs tuning, both files must be updated in sync. Centralise in spotlight-catalog.ts or a shared constants file.

Effect 3 re-queries DOM per scroll event instead of caching element ref

apps/platform/src/components/discovery/FeatureHighlight.tsx:103

Effect 3 runs `document.querySelector(...)` on every scroll/resize event. FeatureSpotlight avoids this by caching the element in `anchorRef.current` (with `.isConnected` guard). Caching the found element in a ref in Effect 2 and reading it in Effect 3 saves a DOM query per event and makes the element-gone case explicit.

Effect 1 no-dep-array pattern benefits from an inline clarifying comment

apps/platform/src/components/discovery/FeatureHighlight.tsx:48

The no-dep-array effect that keeps stripRef and pageRef current is correct and intentional, but maintainers may add a dep array as a 'fix'. An inline 'intentional: no dep array — kept current every render' note would make it unmissable.