fancy-ui-react 0.2.1 → 0.4.0

package/README.md

@@ -4,7 +4,7 @@ React counterpart of [`fancy-ui-svelte`](https://www.npmjs.com/package/fancy-ui-
 same components, same visual contract, ported from the Svelte 5 reference
 implementation that lives at the root of this repo.
 
-Status: at parity. All 144 components of `fancy-ui-svelte` are ported and
+Status: at parity. All 145 components of `fancy-ui-svelte` are ported and
 exported from the package root, alongside the `sound` family; the cameleon
 skin engine (FancyProvider + primitives + skins) ships on the
 `fancy-ui-react/cameleon` subpath. The Svelte package remains the reference;
@@ -183,22 +183,17 @@ Deliberate, small, and documented — everything else is a faithful transpose:
   README example inherits that bug. Ported as-is per the fidelity law; fix it
   upstream first if it bothers you.
 - Compiler-scoped selectors with no root anchor in the source gained one
-  (`fancy-marquee`, `ripple-button`) so their CSS does not leak into consumer
+  (`line-reveal`) so their CSS does not leak into consumer
   pages — see PORTING.md, styling rule 2.
-- **`Meteors` takes a `seed`** the Svelte side has no equivalent for. Svelte
-  runs its randomiser once, in the browser; React runs the same initializer on
-  the server AND again during hydration, and `Math.random()` disagrees with
-  itself across the two — a hydration mismatch React may settle by keeping the
-  server values. A seeded PRNG makes both renders agree while leaving the
-  shower in the server HTML. The default seed is shared, so two unseeded
-  showers fall the same way; pass different seeds to separate them.
 
 - **agent-plan**: Svelte's `item` prop is a Snippet<[PlanStepData, number]>; ported as a render-prop function `(step, index) => ReactNode` per PORTING.md's Snippet->ReactNode mapping.
 - **agent-plan**: Svelte's `ref = $bindable(null)` became a standard forwardRef<HTMLDivElement, AgentPlanProps> on the root div; no functional difference.
 - **ai-data-table**: The `cell` snippet prop became a render-function prop `cell?: (value, at) => ReactNode` instead of a ReactNode, since the Svelte Snippet<[unknown,{row,key}]> takes arguments — same call-site shape, a JS function instead of a snippet.
 - **animated-beam**: containerRef/fromRef/toRef additionally accept a React ref object ({ current: HTMLElement | null }) alongside a plain HTMLElement, resolved at effect/observer time (exported helper type AnimatedBeamTarget), and are typed nullable since a ref may not be populated yet
-- **animated-beam**: gradient id comes from useFancyId("beam") (SSR-stable) instead of the Svelte side's Math.random() id
-- **animated-beam**: new seed prop (default 1): the default duration (Svelte: Math.random() * 3 + 4) is derived from a deterministic mulberry32 PRNG so server render and hydration agree
+- **animated-beam**: the svg root carries a port-added `animated-beam` anchor class (first token of the root cn() call) because the source's styles relied on compiler scoping; every rule in animated-beam.css (fibre glass, packet-core, packet-layer, bloom, reduced-motion) is anchored on it, and the keyframes beam-packet / beam-bloom / beam-ring ship under those exact names instead of compiler-hashed ones
+- **animated-tooltip**: The tooltip positioner's lean transform is written imperatively to the active item's node from refs (pointer offset, size, reduced-motion flag) instead of flowing through render state, so a pointer sample rewrites one style attribute without re-rendering the row; writing only to the active item's positioner is what reproduces the source's frozen pose on a leaving tooltip.
+- **animated-tooltip**: The exit-only `sink` transition on `.at-card` runs on the shared presence clock (`usePresence`) with a duration-0 enter leg, so the card still enters through the CSS `at-rise` / `at-fade` keyframe and a re-hover mid-exit snaps back to rest; the tooltip node mounts one extra pre-paint render pass after the hover.
+- **animated-tooltip**: The colocated stylesheet anchors every rule under `.at-root` (dark theme on `.dark .at-root`) because plain CSS has no compiler scoping; class hooks, custom property names, `@property --at-angle` and the `at-rise` / `at-fade` / `at-sweep` keyframes are identical to the source.
 - **apple-card-carousel**: AppleCard's props interface is now exported as AppleCardProps (the Svelte side kept it a local, unexported interface) to satisfy the <Name>Props tooling contract.
 - **apple-card-carousel**: AppleCardData.content is a ReactNode instead of a Svelte Snippet (rendered directly rather than invoked).
 - **apple-card-carousel**: Svelte's await tick() + inline rAF chain after expand became two effects keyed on overlayVisible: a layout effect that focuses the close button (and commits the reduced-motion still frame), then a passive effect whose double rAF flips fullyExpanded; the rAFs are cancelled on cleanup (Svelte had no cancellation, but the timing/behaviour is identical). The reduced-motion branch is read from a ref so it is decided once per expand, like the source handler.
@@ -209,12 +204,18 @@ Deliberate, small, and documented — everything else is a faithful transpose:
 - **approval-card**: children (Snippet) becomes ReactNode children as usual for the detail region.
 - **bento-grid**: BentoGridItemProps uses Omit<HTMLAttributes<HTMLDivElement>, 'title'> to avoid a TS conflict between the DOM 'title' attribute and the Svelte 'title' snippet prop (same intersection pattern PORTING.md prescribes for RainbowButton).
 - **bento-grid**: BentoGridItemProps and BentoGridCardProps extend HTMLAttributes<HTMLDivElement>, so they accept every div attribute — including a `children` the components render fixed JSX in place of and therefore silently drop; the Svelte parts declare a closed prop list.
+- **bento-grid**: BentoFrame's compiler-scoped `.bento-panel`, `.bento-glow` and `.bento-edge` rules are anchored as descendants of `.bento-tile` in bento-frame.css (port-added anchor, since plain CSS is global); cascade outcomes match the Svelte source, including the reduced-motion glow fade.
+- **bento-grid**: BentoGrid spreads rest props onto the grid root like the rest of the React port; a consumer `style` is merged with the `accent` prop, with `--bento-accent` from `accent` taking precedence as the Svelte `style:` directive does, and a consumer `onFocus` is chained after the focus-reveal handler.
+- **bento-grid**: The focus-in reveal uses React's `onFocus`, which React delivers as a bubbling focusin, in place of the Svelte `onfocusin` attribute.
 - **bg-falling-stars**: Added optional `seed?: number` (default 1) + mulberry32 PRNG replacing every `Math.random()` (star layout and respawn), per PORTING.md's randomisation rule; consequence: two `<FallingStarsBg />` with no seed show an identical sky, where the Svelte side gave each instance a different one.
 - **bg-falling-stars**: `count` re-initialises the starfield in React (it is a dependency of the canvas effect); the Svelte side reads `count` only inside `onMount`, so a later `count` change there is silently ignored. `color` keeps Svelte's behaviour exactly (live, next-frame, no re-seed) via a ref rather than an effect dependency.
 - **bg-stars**: Added a `seed` prop (default 1) with a deterministic mulberry32 PRNG replacing the Svelte side's Math.random() star scatter — required by the SSR/hydration rule (PORTING.md, C-7); same seed = same sky.
 - **bg-stars**: Per-frame spring transform is written imperatively to the parallax element's style in the rAF loop (per group guidance) instead of re-rendering through state; a stiffness/damping change restarts the loop but spring position/velocity persist in refs, so motion resumes from the in-flight position.
 - **bg-stars**: Port-added root anchor class `fancy-bg-stars` for the colocated CSS (Svelte compiler-scoped .stars-parallax/.star-layer/.star-field). The bare slug `bg-stars` was avoided deliberately: tailwind-merge classifies `bg-*` tokens as background utilities and would drop the anchor against any consumer bg-* override.
 - **bg-stars**: Star box-shadows are derived in render (useMemo on starColor+seed) instead of a client-only effect, so stars appear in server-rendered HTML; the Svelte side renders empty shadows until the effect runs.
+- **border-beam**: The compiler-scoped `bb-*` rules are anchored under the root class `.border-beam` in plain CSS (for example `.border-beam .bb-ride`), and the dark theme reads `.dark .border-beam`. Specificity keeps the same relative order, so the render is identical.
+- **border-beam**: The keyframes `bb-travel` and `bb-ignite` ship under those exact names as global keyframes, where the Svelte compiler hashes them. They are only referenced from inside `.border-beam` rules.
+- **border-beam**: The tail and bloom piece lists (`tailSegments(18)` / `tailSegments(8)`) are computed once at module load instead of once per instance. The values are the same and nothing visible changes.
 - **box-reveal**: Rest props: React BoxRevealProps extends HTMLAttributes<HTMLDivElement> and spreads rest onto the root div; the Svelte BoxRevealProps declares only color/duration/delay/class and spreads nothing, so the React component accepts id/onClick/data-* attributes the Svelte one silently drops. Kept per PORTING.md's general 'rest props spread onto the root element' rule, recorded here because it is consumer-visible.
 - **breadcrumb**: `class` becomes `className` (standard rename).
 - **breadcrumb**: `item` snippet prop (`Snippet<[BreadcrumbItem, number]>`) becomes a render-prop function: `item?: (item: BreadcrumbItem, index: number) => ReactNode`.
@@ -240,6 +241,12 @@ Deliberate, small, and documented — everything else is a faithful transpose:
 - **confetti**: No behavioural divergence in `ConfettiButton`: no className, no rest-prop spread, no `type` attribute — the Svelte source declares only `options`, `children` and `sound` on a bare `<button>`.
 - **confetti**: `Confetti` gains one extra file over the Svelte tree (`context.ts`), mirroring the `button-group` precedent; one file per Svelte file is otherwise preserved.
 - **confetti**: `fire()` reaches consumers through the ref channel, not a component instance. Svelte declares `export function fire(opts)` (callable via `bind:this`); React has no instance, so `Confetti` is a `forwardRef<ConfettiHandle, ConfettiProps>` whose ref carries `{ fire }` rather than the DOM node. This is the one forwardRef in the port not backed by a `ref = $bindable` declaration (PORTING.md C-4); the alternative was deleting a public method. `ConfettiHandle` is exported from `Confetti.tsx` but deliberately NOT from `index.ts`, since the mandated export list is exactly Confetti/ConfettiButton + Props types.
+- **container-scroll**: The first measurement runs in an isomorphic layout effect rather than a passive effect. This matches the Svelte effect, which measures before paint, so a card that is already in view never paints one shut frame.
+- **container-scroll**: Scoped selectors from the Svelte `<style>` block are anchored under the component's own `.cs-root` class in `container-scroll.css` (for example `.cs-root .cs-title`). The Svelte `:global(.dark)` and `:global(html:not(.dark))` wrappers become plain `.dark .cs-root` and `html:not(.dark) .cs-root`. Class names, custom property names and values are identical.
+- **container-scroll**: Reduced motion is read through `useReducedMotion` (useSyncExternalStore). The server render and the hydration render therefore always report motion allowed (progress 0, no `data-reduced-motion`), and the still frame applies on the next commit. The CSS `@media (prefers-reduced-motion: reduce)` block still shows the open still frame from the first paint.
+- **datamosh-transition**: `cover()`, `reveal()` and `play()` reach consumers through the ref channel, not a component instance. Svelte declares them with `export function` (callable via `bind:this`) and also binds the overlay element through `ref = $bindable(null)`; React has no instance, so `DatamoshTransition` is a `forwardRef<DatamoshTransitionHandle, DatamoshTransitionProps>` whose ref carries `{ cover, reveal, play, element }` — the three methods plus the overlay element that the Svelte `ref` published.
+- **datamosh-transition**: The read-only bindable `phase` becomes an `onPhaseChange(phase)` callback, called on every change (`covering`, `covered`, `revealing`, `idle`); `data-state` on the overlay carries the same value on both sides.
+- **datamosh-transition**: SSR markup: React serialises the overlay's inline style as `style="z-index:9999"` (no space after the colon) where Svelte emits `z-index: 9999`. Same declaration, different byte string.
 - **direction-aware-hover**: fade transitions on the overlay and caption are reproduced via usePresence + a local fade300 TransitionSpec (WAAPI mechanism per internals-api §5) instead of a framework transition directive — same 300ms linear opacity curve
 - **direction-aware-hover**: isMobile lives in a ref rather than state — it is only read in event handlers and never drives markup, so resize events no longer trigger re-renders (no observable difference)
 - **direction-aware-hover**: non-null assertion added on event.touches[0] to satisfy the React tsconfig's indexed-access checking (no runtime change)
@@ -261,7 +268,6 @@ Deliberate, small, and documented — everything else is a faithful transpose:
 - **flip-words**: The flip cycle is keyed on `words.length`, not on the `words` array identity the Svelte $effect tracks, so a parent handing down a new array reference (or a same-length content swap) no longer clears the pending timer and re-arms a full `duration` wait.
 - **flip-words**: The next-index computation guards an empty `words` list: if the array empties while the 600 ms exit is in flight the React component falls back to index 0 and resumes when the list is repopulated, where the Svelte source computes `(index + 1) % 0` = NaN and stays blank forever.
 - **fluid-cursor**: Dev-only console diagnostics (singleton warning, WebGPU fallback/tone-mapping/device-lost logs, HDR-level info) are gated on a `typeof`-guarded `process.env.NODE_ENV !== "production"` instead of `import.meta.env.DEV` — the react package's tsconfig does not load Vite client types. In an unbundled browser load where `process` is undefined the diagnostics are silent. No non-diagnostic behavior differs; `hexToRgb`'s invalid-hex `console.warn` is NOT gated on either side (the test asserts it).
-- **fluid-cursor**: WebGPU is typed by module-scoped minimal interfaces instead of `@webgpu/types` (not declared in react/package.json; it is only reachable here by accident, transitively through `@types/three`). Type-level only — no runtime difference — but it also keeps the emitted `.d.ts` free of an external type reference consumers would have to install.
 - **fluid-cursor**: `FluidCursorAdvancedProps` is a new exported type (empty interface extending `FluidCursorProps`). The Svelte index exports the deprecated `FluidCursorAdvanced` alias with no Props type of its own; PORTING.md's `<Name>Props` tooling contract requires one.
 - **fluid-cursor**: `interactive` and `contained` are captured at mount and used for BOTH listener registration and removal. The Svelte source re-reads them (reactive getters) at cleanup time, so flipping either prop mid-life leaks or mis-pairs listeners there; here add/remove always pair. Unobservable unless a consumer mutates those props on a live instance, which the props are documented not to support.
 - **frosted-glass**: Filter id generator: the Svelte `onMount` mints `fg-dist-${Math.random().toString(36).slice(2,8)}`; the port mints `uid("fg-dist")` from `src/internals/use-id.ts` inside the equivalent mount effect. Consumer-visible ids are now `fg-dist-1`, `fg-dist-2`, ... instead of a random base-36 suffix. Timing is unchanged (still client-only, still after mount, so the filter layer and its <defs> are still absent from the server HTML), and no seed prop was added — the existing `seed` prop stays the feTurbulence seed it is on the Svelte side.
@@ -271,7 +277,7 @@ Deliberate, small, and documented — everything else is a faithful transpose:
 - **image-trail-cursor**: Root `touch-action: none` is emitted through React's inline-style object instead of Svelte's literal style string. Identical in browsers (style="touch-action: none;"), but jsdom's cssstyle does not implement `touch-action` and silently drops any CSSOM write, so the transposed assertion reads the server markup (renderToStaticMarkup contains style="touch-action:none") rather than the live node's style attribute. Same fact, jsdom-observable form.
 - **image-trail-cursor**: `ImageItem.defaultStyle` is `private` here where the Svelte class declares it `public`: a public TweenVars member emits a bare animation-library namespace reference into the shipped .d.ts that a deep-importing consumer cannot resolve. The member is read only by `initEvents()`, and `ImageItem` is not re-exported from index.ts on either side.
 - **interactive-grid-pattern**: Root SVG carries an extra class token `interactive-grid-pattern` that the Svelte source does not emit: the Svelte <style> rule `.interactive-grid-square:not(:hover){transition-duration:1000ms}` was compiler-scoped, so the port adds the slug as an anchor per PORTING.md styling rule 2. This was already present in the ported component before this fix and is commented as port-added in interactive-grid-pattern.css.
-- **line-reveal**: Port-added root anchor class `line-reveal` (first token of the root `cn()`), so the compiler-scoped `.line-mask` / `.line` / `.revealed` rules do not leak globally — same treatment as `fancy-marquee` and `ripple-button`; README's 'Compiler-scoped selectors ... gained one' bullet should list `line-reveal` too.
+- **line-reveal**: Port-added root anchor class `line-reveal` (first token of the root `cn()`), so the compiler-scoped `.line-mask` / `.line` / `.revealed` rules do not leak globally; README's 'Compiler-scoped selectors ... gained one' bullet lists `line-reveal` too.
 - **line-reveal**: `class` -> `className` (standard PORTING.md rename); no ref/forwardRef and no rest-prop spread, matching the Svelte source which declares neither.
 - **line-reveal**: LineReveal creates one ResizeObserver per mounted instance where the Svelte `bind:clientWidth` routes through the framework's process-wide observer singleton; each disconnects on unmount and nothing leaks.
 - **link**: Native click handler is `onClick` (React convention/rest-props spread) rather than Svelte's `onclick` prop name.
@@ -294,12 +300,13 @@ Deliberate, small, and documented — everything else is a faithful transpose:
 - **mosaic-glow**: `MosaicGlowProps` extends `Omit<HTMLAttributes<HTMLDivElement>, "color" | "children">` rather than omitting every `keyof BaseProps` — those two are the only names that actually collide in `@types/react`, so the surviving attribute surface is one entry wider than the Svelte type (e.g. `title`, `role` were never omitted on either side anyway). No runtime effect.
 - **navbar**: NavbarLink's onclick prop is renamed onClick (React event-prop casing convention, consistent with other ports)
 - **navbar**: Svelte source had two <style> blocks (one per .svelte file); ported as two colocated CSS files, navbar.css and navbar-link.css, each imported by its own component
-- **neon-border**: `neon-border.css` carries the Svelte `<style>` rules unanchored (`.neon-layer-one`, `.neon-layer-two`, `.neon-animated`) instead of nesting them under the root class, so they are global where the Svelte compiler scoped them. Known deviation from PORTING.md styling rule 2, shared with `meteors.css`.
 - **neon-border**: NeonBorderProps extends HTMLAttributes<HTMLDivElement> and spreads rest onto the root, so id/role/onClick/data-* reach the element; the Svelte component declares a closed six-prop list and spreads nothing.
 - **noise-reveal**: `class` prop renamed to `className` (package-wide PORTING.md convention); every other prop name, type and default is identical.
 - **noise-reveal**: The viewport-trigger effect lists `delay` in its dependency array, which the Svelte `$effect` does not track, so changing `delay` after the element has intersected cancels a reveal already waiting out its delay and re-observes; `delay` is a mount-time setting.
 - **pagination**: Pagination: Svelte's `bind:page` becomes the standard controlled/uncontrolled split — uncontrolled by default (internal page state starting at 1), controlled when the `page` prop is passed; `onPageChange` fires with the same value either way.
 - **pagination**: Pagination: `previousLabel`/`nextLabel` snippets become `ReactNode` props; the nav element is exposed via `forwardRef` instead of `bind:ref`.
+- **pagination**: Svelte's `animate:flip` + `in:fade` on the page items become a hand-rolled FLIP in a layout effect (Web Animations API, 300ms with the library's out curve; new items fade in over 150ms after a 60ms delay; skipped on first commit, under reduced motion, or where `Element.animate` is missing). An interrupted glide continues from the item's live position.
+- **pagination**: Arming the slide and placing the pill run in one isomorphic layout effect (not an `$effect` plus `tick()`); same visible behaviour.
 - **prompt-suggestions**: Svelte $effect.pre (pre-flush) mapped to useLayoutEffect (closest React equivalent for pre-paint DOM updates); no functional difference observed in tests.
 - **prompt-suggestions**: Svelte 'item' prop was a Snippet<[string,number]>; ported as item?: (suggestion, index) => ReactNode, per PORTING.md snippet->ReactNode rule.
 - **prompt-suggestions**: class prop renamed to className per PORTING.md convention.
@@ -312,6 +319,11 @@ Deliberate, small, and documented — everything else is a faithful transpose:
 - **sidebar**: `ref` props become forwardRef on Sidebar, SidebarItem, SidebarSeparator and SidebarFooter (the four declaring `ref = $bindable(null)`); SidebarGroup declares none and gets none. The `ref` field is therefore absent from every Props interface.
 - **smooth-cursor**: `class` prop becomes `className` (standard mapping).
 - **smooth-cursor**: `cursor` prop is a ReactNode instead of a Svelte Snippet (standard snippet->ReactNode mapping); truthiness check preserved, so a falsy node falls back to the default arrow exactly like the Svelte {#if}.
+- **smooth-cursor**: the wrapper now drives the shared framework-free engine (`smooth-cursor-core.ts`, a byte-identical copy of the Svelte core) instead of re-implementing the spring loop inline; the core's own test file is copied byte-for-byte as well.
+- **smooth-cursor**: the Svelte scoped `<style>` block ships as the colocated `smooth-cursor.css`, with every rule anchored under the existing root class `.smooth-cursor`. Class names (`sc-pointer`, `sc-pointer--rotate`, `sc-arrow`, `sc-arrow-rim`, `sc-stop-*`, `sc-label`, `sc-label-text`, `is-idle`) and custom properties (`--_sc-color`, `--smooth-cursor-color`, `--smooth-cursor-label-color`) are identical to the Svelte source.
+- **smooth-cursor**: the arrow's gradient id comes from React's `useId()` with every character outside `[A-Za-z0-9_-]` stripped (the counterpart of `$props.id()`), keeping the `url(#smooth-cursor-fill-…)` paint reference ASCII-clean while staying SSR-stable.
+- **smooth-cursor**: reduced motion is read with the shared `useReducedMotion()` hook rather than a raw `matchMedia` call; the mount value is passed to the engine as a creation option, and only a later change is pushed through `setOptions({ reducedMotion })`. The hook reports `false` during the hydration render, so on a machine that asks for reduced motion the preference reaches a hydrated cursor as a change right after hydration — one snap to the origin while the cursor is still hidden.
+- **smooth-cursor**: the name pill is handed to the engine through a callback ref (`setLabel(node)` on mount, `setLabel(null)` on unmount), replacing the Svelte `bind:this` + `$effect`; the hotspot `translate` is set as a single React style key, so re-renders never touch the engine-written `transform`.
 - **sound**: Svelte's `use:soundFeedback` action has no React counterpart: it ships as `attachSoundFeedback(element, options)` (the imperative attach/detach core, callable from a ref callback) plus the `useSoundFeedback(options)` hook that returns a ref callback for the common case. The action name `soundFeedback` is therefore absent from the package root.
 - **sound**: The React engine clamps a custom theme's layer duration to `SOUND_LIMITS.MAX_LAYER_MS` before scheduling; the Svelte engine schedules the declared duration. Only `validateSoundTheme()` enforces the limit on the Svelte side, so a theme passed straight to `engine.setTheme()` with a layer longer than 400 ms plays in full under Svelte and truncated under React.
 - **sound**: The sound family adds `useSound`, `useSoundCue`, `useSoundEnabled` and `useSoundStatus` — the React counterpart of reading the `sound` controller's runes directly.
@@ -322,7 +334,10 @@ Deliberate, small, and documented — everything else is a faithful transpose:
 - **sparkles-text**: Adds a `seed` prop (default 1) with a deterministic mulberry32 PRNG replacing the source's Math.random() — required for identical server render and hydration; same seed yields the same initial field.
 - **sparkles-text**: Post-mount star regeneration draws from a second seeded stream (mulberry32(seed+1)) instead of Math.random(), so the animation timeline is also deterministic per seed.
 - **sparkles-text**: Sparkle ids drop the source's Date.now()+Math.random() composition in favor of an extra PRNG draw (`${x}-${y}-${random()}`) — ids stay unique per field but are deterministic.
-- **stepper**: Step.svelte's scoped `<style>` block ships as colocated `step.css` imported by `Step.tsx`. Every rule was already anchored on a class the component owns (`.ft-step`, `.ft-step-bullet`, `.ft-step-connector`, `.ft-step-trigger`), so no port-added anchor class was needed; keyframe-free, and the deliberate no-`prefers-reduced-motion` decision is preserved verbatim with its rationale.
+- **stepper**: Step.svelte's scoped `<style>` block ships as colocated `step.css` imported by `Step.tsx`, copied verbatim. That includes the lit-rail layers, the halo, the glyph flip and check draw, every `ft-step-*` keyframe and the `prefers-reduced-motion: no-preference` gate. Every rule is already anchored on a class the component owns (`.ft-step`, `.ft-step-bullet*`, `.ft-step-connector*`, `.ft-step-glyph`, `.ft-step-check`, `.ft-step-trigger`, `.ft-step-animate`), so the port adds no anchor class.
+- **stepper**: The Svelte `createReducedMotion()` + `reduced.start()` + `asked = true` sequence becomes `useReducedMotion()` (useSyncExternalStore, `false` on the server and during hydration) plus an `asked` state flag set in a mount `useEffect`. `animate = asked && !reduced`, so neither the server render nor the hydration pass ever carries `ft-step-animate`, and `data-motion` reads `reduced` until mount, as on the Svelte side.
+- **stepper**: The Svelte `$effect.pre` that writes `origin` (the active index before the latest change) becomes React's adjust-state-while-rendering pattern: a `{ settled, origin }` state pair that is updated during render whenever the active index differs from `settled`. React re-renders before committing, so no committed frame pairs the new index with a stale origin. `origin` starts at 0, so the first paint plays the arrival run.
+- **stepper**: The Svelte `style:--ft-step-order` / `style:--ft-step-arrival` directives become inline `style` objects cast to `CSSProperties`. An `undefined` arrival passes `style={undefined}`, so the bullet carries no style attribute, as the directive omits it.
 - **stepper**: The Svelte `untrack` guard around register/unregister becomes two React rules: `register` is `useCallback(..., [])` over a ref-held registry (identity never changes), and a Step's registration effect depends on `[register, id]`, never on the context object — depending on the context (rebuilt whenever the registry changes) would re-run the effect from its own call and loop forever, the same bug in React shape.
 - **stepper**: `STEPPER_KEY` is a `React.Context<StepperContext | undefined>` object, not a `Symbol` context key — read with `useContext(STEPPER_KEY)`. Same exported name, same optional-outside-the-root semantics (button-group's `BUTTON_GROUP_CONTEXT_KEY` precedent).
 - **stepper**: `Step`'s custom-bullet branch is `children ?? default` (null/undefined only) rather than Svelte's snippet-existence test, so a falsy-but-present child such as `0` or `false` overrides the glyph where Svelte would have rendered the default.
@@ -338,6 +353,11 @@ Deliberate, small, and documented — everything else is a faithful transpose:
 - **text-reveal-card**: touchmove is attached natively via useEffect with { passive: false } instead of React's onTouchMove: the handler calls preventDefault() and React registers its touchmove root listener as passive. Same listener semantics as the Svelte attribute; behavior identical.
 - **timeline**: `class` prop becomes `className` (standard port convention)
 - **timeline**: `content` snippet becomes a `content?: (item: TimelineItem) => ReactNode` render prop
+- **timeline**: The Svelte `<style>` block ships as the colocated `timeline.css`. Every selector is anchored under the source's own root class `.tl-root`, so no anchor class was added, and `:global(.dark) .tl-root` becomes `.dark .tl-root`. The custom property names, the `tl-ignite` keyframes, the `prefers-reduced-motion` block and the reduced-motion trail are all copied verbatim.
+- **timeline**: The head position is not React state. `place()` writes `--tl-progress` straight to the root node each rAF frame, and the render repeats the latest value from a ref, so scrolling re-renders nothing until the head crosses a dot. `activeIndex` is state that updates only on a crossing, and `ready` and the measured track height are state too.
+- **timeline**: Row content renders through a memoised `TimelineContent` keyed on (`content`, `item`). When a dot lights, the rows re-render to flip `data-state` and `data-lit`, but the consumer's `content` render prop is not called again for the whole list.
+- **timeline**: The first measurement and placement run in a layout effect (`useIsomorphicLayoutEffect`) instead of `onMount`, so the rail height and head position are written before the first paint.
+- **timeline**: Reduced motion reads `useReducedMotion()` (useSyncExternalStore) in place of `createReducedMotion()`. On the server and during hydration it reports full motion, so the head is rendered and `data-motion="full"` until the client snapshot resolves.
 - **toggle**: ToggleHarness.test.svelte (Svelte bind: rig) became ToggleHarness.tsx (not .test.tsx, so vitest's src/**/*.test.{ts,tsx} include does not collect it as its own empty suite); its assertions live in Toggle.test.tsx as before.
 - **toggle**: pressed is React state seeded once from the `pressed` prop (mirrors Svelte's pressed = $bindable(false)), not a controlled/uncontrolled toggle via `pressed ?? state` — re-passing a different `pressed` value after mount does not resync it, matching the Svelte bindable-prop semantics exactly.
 - **toggle-group**: Test transposition: the two `bind:value` round-trip tests become "round-trips a single/multiple selection through the value channel", asserting the same values via the harness's `onValueChange`; "binds the root element" becomes "exposes the root element through the ref" using `createRef` + `forwardRef`. `ToggleGroupHarness.test.svelte` is now an inline `Harness` component inside `ToggleGroup.test.tsx`. Every `await tick()` flush is dropped as Svelte-scheduler mechanics (RTL's `fireEvent` already acts).
@@ -420,10 +440,12 @@ Deliberate, small, and documented — everything else is a faithful transpose:
 - **date-picker**: `ref = $bindable` on the trigger button becomes `forwardRef` exposing the `<button>` element
 - **date-picker**: `viewDate`/`focusedDate` start as `null` and are seeded on first open rather than with `dayOnly(new Date())` at construction (C-7: no `new Date()` in a render path); not observable — nothing reads either before `openPanel` seeds them and the live region is empty while closed on both sides
 - **dock**: Context key: Svelte's `DOCK_CONTEXT_KEY = Symbol("dock-context")` becomes a React context object of the same name in types.ts. Neither barrel exports it, so the public API surface is unchanged.
-- **dock**: Dock tracks and cancels any rAF still queued at unmount; the Svelte source relies on its scheduler tearing the component down first. No observable behaviour change — a cancelled frame had nothing left to paint into.
 - **dock**: Media queries go through `useMediaQuery`/`useReducedMotion` (useSyncExternalStore) instead of `createMediaQuery().start()` in an `$effect` — internals-contract divergence D-4. SSR and the hydration render still answer `false`/`false` (identical to the Svelte fallback), but on a client-only first render `magnify` is already correct instead of settling one effect pass later.
 - **dock**: `DockContext.mouseX`/`mouseY` keep the exact `{ current: number }` shape, but the box is REBUILT by Dock on every pointer frame instead of being mutated in place — a mutated object is invisible to React and the new identity is what re-renders the icons.
 - **dock**: index.ts re-exports the three components plus their Props types AND the `DataOrientation`, `Direction`, `DockContext` types, mirroring the Svelte index.ts exactly (a superset of the three components + Props types requested in the brief; DockProps references `Direction`/`DataOrientation`, so consumers need them).
+- **dock**: One frame writes the pointer, the shelf-local spot (`--dock-x`/`--dock-y`) and the hover flag as a single state object, because an updater must stay pure. The shelf rect is read in the rAF callback before the state update, not inside it, so there is still one `getBoundingClientRect()` per frame and the output is identical.
+- **dock**: The shelf's decorative CSS lives in colocated `dock.css`, with every rule anchored on the source's own `.dock-shelf` root class (`.dock-shelf .dock-spot`, `.dark .dock-shelf .dock-frame`, …). The icon rules live in `dock-icon.css`, anchored on `.dock-icon`. `:global(.dark)` becomes a plain `.dark` ancestor selector. The class names, custom property names and media blocks are verbatim.
+- **dock**: `dockIconSize` and `DOCK_BASE_SIZE` are exported from DockIcon.tsx, the counterpart of the Svelte `<script module>`. Like the Svelte side, they are not re-exported from the folder index.ts.
 - **drawer**: No portal-before-focus-trap ordering ceremony (contract divergence D-10): createPortal commits before effects, so the trap always focuses a connected node
 - **drawer**: Per-frame drag offset lives in a ref with direct element.style writes instead of reactive state (group guidance); the spring-back class is applied via flushSync so the CSS transition and the transform reset land in the same frame, matching Svelte's batched flush
 - **drawer**: Scroll lock is `useScrollLock(presence.mounted)` rather than an outro-delayed action destroy — identical release timing (page unlocks when the slide-out finishes)
@@ -592,15 +614,14 @@ Deliberate, small, and documented — everything else is a faithful transpose:
 
 - **approval-card**: onApprove/onDeny receive the committed decision as an argument — React batches the onStateChange parent update, so the argument is the only synchronously-committed signal (Svelte writes through bind:state and needs none).
 - **code-diff**: inert is written to the collapsed views imperatively via internals/dom/use-inert-attribute (React 18 drops the boolean JSX prop); absent from server HTML where Svelte SSRs it. A local DiffBody sub-component hosts the hook — markup unchanged.
-- **compare**: new ariaLabel prop (default "Image comparison slider") and full keyboard operation (Arrow ±1, PageUp/PageDown ±10, Home/End) on the role=slider root; the Svelte source exposes a focusable slider with no name and no key handling.
+- **compare**: `label` (default "Comparison slider") is the accessible name, as on the Svelte side; the older React-only `ariaLabel` prop still works as a deprecated alias, and `label` wins when both are given.
+- **compare**: A burst of pointer moves within one frame commits once (and a pending move frame is dropped on unmount); the Svelte side schedules and commits each move.
 - **compare**: The autoplay loop is started once: the Svelte source starts it twice (onMount plus the $effect tracking hover and drag), so two rAF loops run there and `onpercentagechange` fires twice per frame. The divider position is identical on both sides, but a consumer counting or debouncing that callback sees half the invocations here.
-- **dock**: pointer tracked in viewport coordinates (clientX/clientY); the Svelte source reads pageX/pageY against getBoundingClientRect() and mis-magnifies on a scrolled page.
-- **dock**: React adds an `ariaLabel` prop (rendered as `aria-label` on the toolbar) and emits `aria-orientation` matching `orientation`; the Svelte source has neither, so this is a temporary React-only addition until the Svelte side mirrors it.
 - **dock**: While the pointer is inside the dock every animation frame produces a new context value, so the Dock root and every DockSeparator re-render and re-run their `cn()` calls where Svelte mutates two `{ current }` boxes and re-renders neither; visual output is identical.
 - **dropdown-menu**: Tab/Shift+Tab return focus to the trigger before the browser continues traversal; the source passes returnFocus: false and leaves focus in a portalled panel, wrapping traversal to the body.
 - **dropdown-menu**: Post-open focus is moved in a passive effect where the source moves it in a `tick()` microtask, so the panel paints one frame before the focus ring lands on the first or last item; the anchored entrance is still animating at that point.
 - **file-upload**: The native file input is reset on picker-open (not on change) so `name`/`required` see a real FileList; `removeFile` clears it again when a removal invalidates it. A cancelled picker leaves the input empty while the row list keeps the earlier pick; dropped files never feed the native input, as in the Svelte source.
-- **glow-border**: style custom properties are built as a React style object during render (present in server HTML); the Svelte source emits one raw CSS string — byte order differs, rendered result identical.
+- **glow-border**: the style custom properties, including the --gb-metal-* and --gb-glint-* gradients, are built as a React style object during render, so they are in the server HTML. The Svelte source emits one raw CSS string, so the byte order differs but the rendered result is the same. `:global(.dark) .glow-border` becomes `.dark .glow-border`, and the compiler-scoped `.animate-glow` rule and its reduced-motion override are anchored as `.glow-border.animate-glow`.
 - **inline-citation**: a scheme-less host like docs.example.dev/guide is promoted to https:// before sanitizing, matching SourceCard and WebSearch; genuine relative paths pass through.
 - **link**: The new-tab announcement and the safe-`rel` tokens are gated on the RESOLVED target, not on the bare `external` flag, so an `external` link whose `target` is overridden to `_self`/`_parent`/`_top` stays silent and keeps the caller's own `rel`; the Svelte source announces a new tab whenever `external` is set.
 - **logo-cloud**: the four cloned marquee tracks carry aria-hidden and empty alt, so assistive tech hears the brand list once; the Svelte source announces all five copies.
@@ -627,15 +648,30 @@ Deliberate, small, and documented — everything else is a faithful transpose:
 - **animated-testimonials**: Autoplay pauses on keyboard focus inside the region as well as on pointer hover, and does not start at all under `prefers-reduced-motion` — temporarily ahead of the Svelte source, which mirrors it next.
 - **button**: `onclick` is renamed `onClick` and typed with React's synthetic MouseEvent, matching the event-prop casing NavbarLink, Sidebar, ChatMessageAction, Toggle and ToggleGroupItem already use.
 - **chat-panel**: ChatEmptyState's `icon` fallback uses `??`, so a nullish `icon` falls back to the default sparkle but a falsy-but-defined node such as `icon={false}` or `icon={""}` renders an empty decorative span where the Svelte `{#if icon}` branch still draws the sparkle; pass `undefined` to get the default mark.
+- **compare**: The beam/autoplay/glide loops read live values from refs that mirror the state; the observable behaviour is the same as the reference's closures reading $state.
+- **compare**: compare.css anchors every component rule under the root `.compare` class, because plain CSS is global where the reference's rules were compiler-scoped. Class names, keyframes (cmp-pulse, cmp-spin), @property --cmp-angle and custom properties are unchanged.
+- **compare**: Compare no longer renders StarField, matching the reference. StarField is still exported on its own, as the Svelte index does.
 - **container-text-flip**: ContainerTextFlipProps extends HTMLAttributes<HTMLParagraphElement> and spreads rest onto the root, so id/onClick/data-*/aria-* reach the element where the Svelte component drops them; the inherited `children` is type-accepted and dropped, since the component renders its own.
+- **flip-card**: `bind:flipped` becomes a seed-and-resync prop: `flipped` sets the starting face on mount, and a later change to it turns the card the rest of the way, calling `onFlip` as Svelte does; internal flips report only through `onFlip` (pass both for two-way behaviour).
+- **flip-card**: Svelte's `onflip` callback is named `onFlip`, following the package-wide camelCase convention for callbacks; same signature, fires at the same times.
+- **flip-card**: The `inert` attribute on the hidden face is written by `useInertAttribute` at commit, not rendered inline, because no JSX spelling works on both React 18 and 19; it is therefore missing from server HTML until hydration.
+- **flip-card**: React's onBlur bubbles (it listens to focusout), so the handler ignores blurs whose target is not the card root. This keeps the Svelte behaviour, where the non-bubbling root blur listener does not fire when focus leaves from a control inside a face, so the card stays on its back in that case.
 - **gradient-button**: GradientButton forwards a ref to the underlying `<button>` even though the Svelte source declares no bindable ref; additive only, recorded rather than removed.
+- **interactive-hover-button**: forwardRef to the <button> kept although the Svelte source exposes no bindable ref (pre-existing React API, same as the other button ports).
+- **interactive-hover-button**: The React tests keep four sound tests (press cue on click, silent by default, silent while disabled, silent on hover) that the Svelte test file does not have; the sound behaviour is identical.
 - **letter-pullup**: LetterPullupProps extends HTMLAttributes<HTMLDivElement> and spreads rest onto the root div, so id/style/onClick/role/aria-*/data-* reach the element; the Svelte component's surface is exactly {words, delay, class} and it spreads nothing.
 - **line-hover-link**: Props extend AnchorHTMLAttributes minus className and spread ...rest onto the `<a>`, per PORTING.md's rest-props-spread rule; the Svelte side exposed a fixed prop list and spread nothing.
 - **marquee**: `ReviewCardProps` is exported as a named type from the folder barrel; the Svelte README states the prop shape is deliberately not re-exported, so a consumer writing their own card need not match it.
+- **marquee**: The per-instance conveyor state (engaged flag, eased factor, live animations, rAF id, resume point) lives in one lazily created ref object instead of loose component-scoped variables. `speed` and `pauseOnHover` are mirrored into it from effects, so an enter or leave event reads the value from the last commit. The easing maths are unchanged: time constant 140 ms, settle epsilon 0.002, dt capped at 64 ms.
+- **marquee**: The Svelte `onfocusin`/`onfocusout` handlers map to React `onFocus`/`onBlur`, which React attaches as focusin/focusout. The relatedTarget containment check is kept as-is.
+- **marquee**: The compiler-scoped rules are anchored on the source's own root class `.marquee`, as `.marquee > .animate-marquee` and `.marquee.marquee-fade`, and the ReviewCard rules on `.review-card`. The `.marquee.marquee-upgraded > …` override is kept more specific than the base keyframe rule, so the cascade result matches the Svelte scoped output.
+- **marquee**: ReviewCard's style block ships as its own colocated `review-card.css`, imported by ReviewCard.tsx, so the card is styled even when it is used without a Marquee. `:global(.dark) .review-card` becomes `.dark .review-card`.
 - **number-ticker**: Duration and delay are captured when the animation starts; the Svelte source re-reads both props each frame, so a mid-animation duration change re-times the count there and not here.
 - **number-ticker**: The re-animate effect depends on the animation target only; the Svelte $effect also re-runs on displayValue and on delay, so a delay-only change restarts the count in Svelte and not in React.
 - **pixel-loader**: PixelLoaderProps extends HTMLAttributes<HTMLDivElement> and spreads rest onto the root, so a consumer's `style` can override the component's own `--ft-pixel-*` custom properties; the Svelte component accepts exactly nine props and spreads nothing.
 - **ripple-button**: Port-added `ref`: RippleButton is a forwardRef publishing the root `<button>`, which the Svelte source does not expose; the consumer's ref is composed through `useComposedRefs`, so it attaches once and is never churned by the ripple state.
+- **ripple-button**: inner `.ripple-hover` / `.ripple-animation` rules are anchored under the source's root class `.ripple-button`, since plain CSS is global.
+- **shimmer-button**: React keeps forwardRef<HTMLButtonElement> (pre-existing public API); the Svelte source exposes no bindable ref.
 - **toast**: The per-toast entrance and exit are owned by `<Toaster>`'s per-item presence clock rather than by `<Toast>` itself, so a `<Toast>` rendered directly outside a `<Toaster>` is static where the Svelte one still plays its 300 ms rise in and 200 ms sink out.
 - **toast**: A dismissed toast is `inert` for the length of its exit (the presence clock's default), so its Retry and Dismiss buttons stop answering clicks and focus inside it is released; the Svelte toast root carries no `inert` and stays interactive until the outro destroys it.
 - **tracing-beam**: Per-frame spring values are written imperatively to the gradient node in the rAF loop (setAttribute "y1"/"y2") instead of round-tripping through state, so the component and its children never re-render during the animation; the rendered JSX keeps y1/y2 at their 0 seed, which is also what the server markup emits.

package/dist/components/animated-beam/AnimatedBeam.d.ts

@@ -11,29 +11,65 @@ export interface AnimatedBeamProps {
     containerRef: AnimatedBeamTarget | null;
     fromRef: AnimatedBeamTarget | null;
     toRef: AnimatedBeamTarget | null;
+    /** Vertical bend of the fibre in px (the quadratic control point sits this far above the start). */
     curvature?: number;
+    /** Send the light from `toRef` back to `fromRef` (the bloom then lands on `fromRef`). */
     reverse?: boolean;
+    /** Fibre colour. Unset = theme-aware glass (dark on light, pale on dark). */
     pathColor?: string;
+    /** Width of the fibre core and of the light packet, in px. */
     pathWidth?: number;
+    /** Opacity of the fibre. Unset = 1 for the theme-aware glass, 0.2 when `pathColor` is set. */
     pathOpacity?: number;
+    /** Colour of the packet's leading edge (its white-hot head is this colour mixed with white). */
     gradientStartColor?: string;
+    /** Colour of the far end of the dispersing tail, and of the arrival bloom. */
     gradientStopColor?: string;
-    /** Seconds the beam waits before its first travel. Feeds the gradient
-     * animations' `begin`, so a group of beams can be staggered. */
+    /** Seconds before the first packet leaves. */
     delay?: number;
+    /** Seconds per packet cycle. Unset = derived from `seed` (between 4 and 7). */
     duration?: number;
     startXOffset?: number;
     startYOffset?: number;
     endXOffset?: number;
     endYOffset?: number;
-    /**
-     * Seed for the default animation duration. The Svelte side randomises the
-     * default (`Math.random() * 3 + 4`); a render-path `Math.random()` would
-     * make the server render and its hydration disagree, so the default is
-     * derived deterministically from this seed instead. Two beams with no
-     * `seed` and no `duration` share the same pace — vary the seed (or pass
-     * `duration`) to desynchronise them.
-     */
+    /** Packets in flight at once, spaced evenly over one cycle. */
+    pulses?: number;
+    /** Length of the packet's tail as a fraction of the fibre (0.05–0.9). */
+    tail?: number;
+    /** Strength of the soft glow under the packet and the arrival bloom (0–1). */
+    glow?: number;
+    /** Seed for the default `duration`, so server and browser agree. */
     seed?: number;
 }
-export declare function AnimatedBeam({ className, containerRef, fromRef, toRef, curvature, reverse, pathColor, pathWidth, pathOpacity, gradientStartColor, gradientStopColor, delay, duration, startXOffset, startYOffset, endXOffset, endYOffset, seed, }: AnimatedBeamProps): import("react").JSX.Element;
+/** The default cycle length for a seed: somewhere between 4 and 7 seconds. */
+export declare function beamDuration(seed?: number): number;
+/** Share of the cycle the head spends travelling; the rest drains the tail into the node. */
+export declare const ARRIVAL = 0.78;
+export interface PacketLayer {
+    key: "stop" | "mid" | "start" | "head";
+    color: string;
+    /** Dash length, in PATH_LENGTH units. */
+    len: number;
+    /** How far this layer has fallen behind the head by the moment of arrival. */
+    lag: number;
+    opacity: number;
+    /** Stroke width as a multiple of `pathWidth`. */
+    width: number;
+    /** The white-hot core: on light surfaces it keeps more of its colour so it never vanishes. */
+    core?: boolean;
+}
+/**
+ * The packet: a white-hot head followed by three chromatic sub-pulses,
+ * each longer, dimmer and further behind than the one before, so the tail
+ * spreads out as it travels — light dispersing through glass. Listed bottom
+ * to top (the order they are painted).
+ *
+ * Each chromatic band is drawn as three stacked dashes sharing one leading
+ * edge (full, two thirds, one third of its length), so its brightness ramps
+ * up toward the head instead of ending in a hard block.
+ */
+export declare function packetLayers(tail: number, start: string, stop: string): PacketLayer[];
+/** The blurred copies under the packet: one per band plus a wide head. */
+export declare function glowLayers(tail: number, start: string, stop: string): PacketLayer[];
+export declare function AnimatedBeam({ className, containerRef, fromRef, toRef, curvature, reverse, pathColor, pathWidth, pathOpacity, gradientStartColor, gradientStopColor, delay, duration, startXOffset, startYOffset, endXOffset, endYOffset, pulses, tail, glow, seed, }: AnimatedBeamProps): import("react").JSX.Element;