@sharedex/ui 0.0.0-stage → 0.9.0

package/dist/carousel/layout/types.d.ts

@@ -0,0 +1,103 @@
+import type { Axis, CarouselFrame, SlotFrameBuffer, SlotState } from "../engine/types.js";
+/**
+ * A layout is a chain of small mutators over a preallocated buffer, not one
+ * monolithic function.
+ *
+ * The whole variation surface of a carousel is "what transform does a card at
+ * distance d get?" -- a pure function, which is the cheapest extension point a
+ * language offers. No plugin registry, no lifecycle, no ordering protocol.
+ *
+ * Chaining rather than a single function matters for one practical reason:
+ * `coverflow` reuses `track()` verbatim. Without the chain, preset N+1
+ * copy-pastes preset N's placement math and the two silently drift.
+ */
+export type SlotModifier = (buf: SlotFrameBuffer, slot: SlotState, frame: CarouselFrame) => void;
+export interface CarouselLayout {
+    readonly name: string;
+    /** A constraint the preset asserts, not a setting. Undefined = works on both. */
+    readonly axis?: Axis | "both";
+    readonly modifiers: readonly SlotModifier[];
+    /**
+     * Used instead of this layout while the user prefers reduced motion (and
+     * `a11y.respectReducedMotion` is on). `stage()` sets it to `fade()`, so a
+     * one-card look still shows that the card changed. Undefined = no swap.
+     */
+    readonly reduced?: CarouselLayout;
+    /**
+     * How many slots past the centre the look keeps visible on one side. The
+     * engine mounts at least `reach + 1` slots each side (one more, so a card is
+     * mounted before it shows); `Infinity` mounts the whole ring. `stage()` also
+     * sizes the mount buffer from it. Undefined = whatever the viewport needs.
+     */
+    readonly reach?: number;
+    /**
+     * The range `--sx-distance` is published in: a slot further out publishes the
+     * bound. The layout itself still reads the real distance. `stage()` sets
+     * `[-reach, reach]`: past it a one-card slot is invisible, and a value that
+     * stops changing stops the browser restyling that slot and everything in it
+     * every frame (measured: `pixelGrid` restyled all 7 slots' 784 cells per frame,
+     * `randomGrid` re-resolved 7 polygons). Undefined = the real distance.
+     */
+    readonly distanceRange?: readonly [number, number];
+    /**
+     * `"closed"`: the cards close into a full circle (a barrel, a dial). The ring
+     * then holds exactly the real items, never placeholder gaps, and no card
+     * mounts twice (at `d` and `d ± count`), so `frame.count` is the number of
+     * cards around the circle. Undefined = the usual open ring, padded to fill
+     * the viewport.
+     */
+    readonly ring?: "closed";
+    /**
+     * A CSS transition the slots play (`stage(wipe())`): its stylesheet ships with
+     * the Root, each slot carries `data-sx-tr` + its vars + its nodes, and CSS
+     * derives the progress from `--sx-distance`. Undefined = transforms only.
+     */
+    readonly transition?: LayoutTransition;
+}
+/**
+ * The part of a transition descriptor the carousel needs. Declared here so the
+ * carousel does not depend on `src/transitions`; `CssTransition` matches it.
+ */
+export interface LayoutTransition {
+    readonly id: string;
+    readonly tier: "all" | "mid" | "high";
+    readonly css: string;
+    readonly vars: Readonly<Record<`--${string}`, string | number>>;
+    /** Generated children; the transitions host renders them, the carousel only passes them on. */
+    readonly nodes: readonly object[];
+    readonly media?: ((item: unknown) => string | undefined) | undefined;
+    readonly fallback?: LayoutTransition | undefined;
+}
+export declare function composeLayout(name: string, ...modifiers: SlotModifier[]): CarouselLayout;
+/**
+ * A preset with more modifiers run after its own, e.g. a speed effect on any
+ * shape: `modify(barrel(), ripple())`. Under reduced motion the extras are
+ * dropped: the result's `reduced` is the preset's own `reduced`, else the
+ * preset as it was.
+ */
+export declare function modify(layout: CarouselLayout, ...modifiers: SlotModifier[]): CarouselLayout;
+/** Same, with an axis constraint the engine checks in dev. */
+export declare function composeAxialLayout(name: string, axis: Axis, ...modifiers: SlotModifier[]): CarouselLayout;
+/**
+ * Run one layout pass into `buf`. Resets to identity first so a modifier that
+ * skipped a property this frame can never leak last frame's value.
+ */
+export declare function applyLayout(layout: CarouselLayout, buf: SlotFrameBuffer, slot: SlotState, frame: CarouselFrame): void;
+/**
+ * Serialise the transform half of the buffer into ONE string.
+ *
+ * Verified against motion 12.43: `transform` is absent from `transformProps`
+ * (motion-dom/render/utils/keys-transform), and `buildHTMLStyles` guards with
+ * `if (!latestValues.transform)` before calling `buildTransform`. So writing a
+ * raw transform string short-circuits motion's 18-property serialisation loop
+ * entirely -- one scheduler entry and one `.set` per slot per frame, and the
+ * cost stops scaling with how rich the preset is.
+ *
+ * Term order matches motion's own `transformPropOrder` so a preset ported from
+ * `style={{ x, scaleY }}` produces an identical matrix.
+ *
+ * Identity terms are skipped, and a slot with no 3D stays on the 2D
+ * `translateX/Y` path so its computed style remains `matrix(...)` rather than
+ * `matrix3d(...)` -- which keeps the 0.1.0 wave byte-comparable.
+ */
+export declare function serializeTransform(b: SlotFrameBuffer): string;

package/dist/carousel/layout/types.js

@@ -0,0 +1,91 @@
+import { resetSlotFrameBuffer } from "../engine/types.js";
+export function composeLayout(name, ...modifiers) {
+    return { name, modifiers };
+}
+/**
+ * A preset with more modifiers run after its own, e.g. a speed effect on any
+ * shape: `modify(barrel(), ripple())`. Under reduced motion the extras are
+ * dropped: the result's `reduced` is the preset's own `reduced`, else the
+ * preset as it was.
+ */
+export function modify(layout, ...modifiers) {
+    return {
+        ...layout,
+        modifiers: [...layout.modifiers, ...modifiers],
+        reduced: layout.reduced ?? layout,
+    };
+}
+/** Same, with an axis constraint the engine checks in dev. */
+export function composeAxialLayout(name, axis, ...modifiers) {
+    return { name, axis, modifiers };
+}
+/**
+ * Run one layout pass into `buf`. Resets to identity first so a modifier that
+ * skipped a property this frame can never leak last frame's value.
+ */
+export function applyLayout(layout, buf, slot, frame) {
+    resetSlotFrameBuffer(buf);
+    const mods = layout.modifiers;
+    for (let i = 0; i < mods.length; i++) {
+        const mod = mods[i];
+        if (mod)
+            mod(buf, slot, frame);
+    }
+}
+/**
+ * Serialise the transform half of the buffer into ONE string.
+ *
+ * Verified against motion 12.43: `transform` is absent from `transformProps`
+ * (motion-dom/render/utils/keys-transform), and `buildHTMLStyles` guards with
+ * `if (!latestValues.transform)` before calling `buildTransform`. So writing a
+ * raw transform string short-circuits motion's 18-property serialisation loop
+ * entirely -- one scheduler entry and one `.set` per slot per frame, and the
+ * cost stops scaling with how rich the preset is.
+ *
+ * Term order matches motion's own `transformPropOrder` so a preset ported from
+ * `style={{ x, scaleY }}` produces an identical matrix.
+ *
+ * Identity terms are skipped, and a slot with no 3D stays on the 2D
+ * `translateX/Y` path so its computed style remains `matrix(...)` rather than
+ * `matrix3d(...)` -- which keeps the 0.1.0 wave byte-comparable.
+ */
+export function serializeTransform(b) {
+    const is3d = b.perspective !== 0 || b.z !== 0 || b.rotateX !== 0 || b.rotateY !== 0;
+    let out = "";
+    if (b.perspective !== 0)
+        out += `perspective(${b.perspective}px) `;
+    if (is3d) {
+        out += `translate3d(${b.x}px, ${b.y}px, ${b.z}px) `;
+    }
+    else {
+        if (b.x !== 0)
+            out += `translateX(${b.x}px) `;
+        if (b.y !== 0)
+            out += `translateY(${b.y}px) `;
+    }
+    // scaleZ only matters to a turned card in 3D (place3d), and only then is it
+    // written, so every other preset's string is unchanged.
+    if (b.scaleZ !== 1) {
+        out += `scale3d(${b.scaleX}, ${b.scaleY}, ${b.scaleZ}) `;
+    }
+    else if (b.scaleX !== 1 && b.scaleX === b.scaleY) {
+        out += `scale(${b.scaleX}) `;
+    }
+    else {
+        if (b.scaleX !== 1)
+            out += `scaleX(${b.scaleX}) `;
+        if (b.scaleY !== 1)
+            out += `scaleY(${b.scaleY}) `;
+    }
+    if (b.rotateX !== 0)
+        out += `rotateX(${b.rotateX}deg) `;
+    if (b.rotateY !== 0)
+        out += `rotateY(${b.rotateY}deg) `;
+    if (b.rotateZ !== 0)
+        out += `rotateZ(${b.rotateZ}deg) `;
+    if (b.skewX !== 0)
+        out += `skewX(${b.skewX}deg) `;
+    if (b.skewY !== 0)
+        out += `skewY(${b.skewY}deg) `;
+    return out === "" ? "none" : out.trimEnd();
+}

package/dist/carousel/parts/Panel.d.ts

@@ -0,0 +1,19 @@
+import { type CarouselHandle } from "../engine/handle.js";
+export interface PanelProps<T> {
+    /** The panel's content for the open item (its index into `items` too). */
+    readonly children: (item: T, itemIndex: number) => React.ReactNode;
+    readonly className?: string;
+    readonly engine?: CarouselHandle<T>;
+}
+/**
+ * The consumer's content about the open card (a title, a description, a
+ * spec sheet), shown while a card is open: it fades and slides in with
+ * `openProgress` and out again on close, and follows the focus when the
+ * arrows move between open cards.
+ *
+ * With `openView.panel()` it takes the panel's share of the viewport at the
+ * end side (inline-end on a horizontal carousel, block-end on a vertical
+ * one); with the other views it is not positioned, so place it with
+ * `className`. Render it inside `Carousel.Viewport`, after the Track.
+ */
+export declare function Panel<T>({ children, className, engine }: PanelProps<T>): import("react").JSX.Element | null;

package/dist/carousel/parts/Panel.js

@@ -0,0 +1,53 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useRef, useState } from "react";
+import { motion, useMotionValueEvent, useTransform } from "motion/react";
+import { useCarouselHandle } from "../engine/handle.js";
+import { wrapIndex } from "../engine/ring.js";
+/**
+ * The consumer's content about the open card (a title, a description, a
+ * spec sheet), shown while a card is open: it fades and slides in with
+ * `openProgress` and out again on close, and follows the focus when the
+ * arrows move between open cards.
+ *
+ * With `openView.panel()` it takes the panel's share of the viewport at the
+ * end side (inline-end on a horizontal carousel, block-end on a vertical
+ * one); with the other views it is not positioned, so place it with
+ * `className`. Render it inside `Carousel.Viewport`, after the Track.
+ */
+export function Panel({ children, className = "", engine }) {
+    const handle = useCarouselHandle(engine);
+    const focusedItem = () => {
+        const entry = handle.ring[wrapIndex(Math.round(handle.position.get()), handle.count)];
+        return entry === undefined || entry < 0 ? null : (handle.visibleIndices[entry] ?? null);
+    };
+    const [itemIndex, setItemIndex] = useState(focusedItem);
+    const [fading, setFading] = useState(false);
+    const last = useRef(itemIndex);
+    useMotionValueEvent(handle.position, "change", () => {
+        const next = focusedItem();
+        if (next === last.current)
+            return;
+        last.current = next;
+        setItemIndex(next);
+    });
+    // still visible while it fades out after close()
+    useMotionValueEvent(handle.openProgress, "change", (v) => {
+        const on = v > 0.001;
+        if (on !== fading)
+            setFading(on);
+    });
+    const axis = handle.config.engine.axis;
+    const shift = useTransform(handle.openProgress, [0, 1], [32, 0]);
+    const view = handle.config.engine.open;
+    const share = view ? view.panel : 0;
+    if (!(handle.isOpen || fading) || itemIndex === null)
+        return null;
+    const item = handle.items[itemIndex];
+    const box = share <= 0
+        ? {}
+        : axis === "x"
+            ? { position: "absolute", insetBlock: 0, insetInlineEnd: 0, inlineSize: `${share * 100}%` }
+            : { position: "absolute", insetInline: 0, insetBlockEnd: 0, blockSize: `${share * 100}%` };
+    return (_jsx(motion.div, { "data-sx-panel": true, "aria-live": "polite", className: className, style: { ...box, zIndex: 2000, opacity: handle.openProgress, ...(axis === "x" ? { x: shift } : { y: shift }) }, children: children(item, itemIndex) }));
+}

package/dist/carousel/parts/Parallax.d.ts

@@ -0,0 +1,22 @@
+import { type CarouselEngine } from "../engine/handle.js";
+export interface ParallaxProps {
+    /**
+     * How far the layer lags behind its card, as a fraction of its own size per
+     * slot of distance. `0` moves with the card, `1` stays put. Negative values
+     * run ahead. Default `0.3`.
+     */
+    readonly amount?: number;
+    readonly children?: React.ReactNode;
+    readonly className?: string;
+    readonly engine?: CarouselEngine;
+}
+/**
+ * A layer inside a card that moves at its own speed while the card moves
+ * (title, picture and background drifting apart during a swipe).
+ *
+ * Pure CSS: every slot already publishes `--sx-distance`, so the offset is one
+ * `calc()` on `translate` with no hook, subscription or per-frame JavaScript.
+ * Size the layer like the card (or bigger, for pictures) so its edge never
+ * shows; percentages in `translate` refer to the layer's own box.
+ */
+export declare function Parallax({ amount, children, className, engine }: ParallaxProps): import("react").JSX.Element;

package/dist/carousel/parts/Parallax.js

@@ -0,0 +1,18 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCarouselMotion } from "../engine/handle.js";
+/**
+ * A layer inside a card that moves at its own speed while the card moves
+ * (title, picture and background drifting apart during a swipe).
+ *
+ * Pure CSS: every slot already publishes `--sx-distance`, so the offset is one
+ * `calc()` on `translate` with no hook, subscription or per-frame JavaScript.
+ * Size the layer like the card (or bigger, for pictures) so its edge never
+ * shows; percentages in `translate` refer to the layer's own box.
+ */
+export function Parallax({ amount = 0.3, children, className = "", engine }) {
+    const handle = useCarouselMotion(engine);
+    const shift = `calc(var(--sx-distance, 0) * ${-amount * 100}%)`;
+    const translate = handle.config.engine.axis === "x" ? `${shift} 0` : `0 ${shift}`;
+    return (_jsx("div", { "data-sx-parallax": true, className: className, style: { translate }, children: children }));
+}

package/dist/carousel/parts/Root.d.ts

@@ -0,0 +1,41 @@
+import type { CarouselConfig, CarouselOptions } from "../config.js";
+import type { CarouselFilter } from "../types.js";
+import { type CarouselHandle } from "../engine/handle.js";
+import type { LayoutTransition } from "../layout/types.js";
+/**
+ * Presentation that both the sizing probe and every slot must share.
+ *
+ * Kept out of the engine handle on purpose: the engine has no business knowing
+ * about class names, and this is the one string that has to reach two places.
+ */
+export interface CarouselStyle {
+    /**
+     * Applied to the engine's probe AND to every `<Carousel.Slot>`, so a slot box
+     * and the measured pitch can never disagree.
+     *
+     * This is also where responsiveness lives -- `"w-[260px] sm:w-[280px] h-105"`
+     * and the engine re-measures on resize. No breakpoint logic in TypeScript.
+     */
+    readonly slotClassName: string;
+    /**
+     * The layout's CSS transition after the device-tier pick (its fallback on a
+     * weaker device). Every slot renders it; undefined for transform-only layouts.
+     */
+    readonly transition?: LayoutTransition | undefined;
+}
+export declare function useCarouselStyle(): CarouselStyle;
+export interface RootProps<T> {
+    readonly items: readonly T[];
+    readonly filters?: readonly CarouselFilter<T>[];
+    /** Per-instance overrides. Memoize it, or the engine re-resolves each render. */
+    readonly config?: CarouselOptions;
+    /** Project-wide defaults from `defineCarouselDefaults`. */
+    readonly base?: CarouselConfig;
+    readonly slotClassName?: string;
+    /**
+     * Render-prop form hands you the engine without an extra component, which is
+     * what an external filter driver or a URL-synced `goTo` needs.
+     */
+    readonly children: React.ReactNode | ((handle: CarouselHandle<T>) => React.ReactNode);
+}
+export declare function Root<T>({ items, filters, config, base, slotClassName, children, }: RootProps<T>): import("react").JSX.Element;

package/dist/carousel/parts/Root.js

@@ -0,0 +1,115 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from "react";
+import { CarouselDataContext, CarouselMotionContext, } from "../engine/handle.js";
+import { useCarouselEngine } from "../engine/useCarouselEngine.js";
+import { TransitionStyle, useTransition } from "../../transitions/hosts/shared.js";
+const StyleContext = createContext({ slotClassName: "" });
+export function useCarouselStyle() {
+    return useContext(StyleContext);
+}
+export function Root({ items, filters, config, base, slotClassName = "", children, }) {
+    const handle = useCarouselEngine({ items, filters, options: config, base });
+    const transition = useTransition(handle.config.layout.transition);
+    const style = useMemo(() => ({ slotClassName, transition }), [slotClassName, transition]);
+    // Two provider values instead of one, sliced from the same `handle`.
+    //
+    // `motion` depends only on fields that are refs/MotionValues, stable for the
+    // whole life of this Root, so this useMemo returns the SAME object across a
+    // filter click or a resize -- and a component subscribed to ONLY
+    // CarouselMotionContext (Slot, Viewport) genuinely does not rerender then,
+    // because the value it's watching never changes. `data` depends on the
+    // fields a filter/resize legitimately does change, so it gets a fresh object
+    // exactly when it should.
+    const motion = useMemo(() => ({
+        id: handle.id,
+        config: handle.config,
+        position: handle.position,
+        opacity: handle.opacity,
+        autoplayProgress: handle.autoplayProgress,
+        mode: handle.mode,
+        viewportRef: handle.viewportRef,
+        trackRef: handle.trackRef,
+        probeRef: handle.probeRef,
+        hovering: handle.hovering,
+        focused: handle.focused,
+        visible: handle.visible,
+        reducedMotion: handle.reducedMotion,
+        autoplayClock: handle.autoplayClock,
+        morph: handle.morph,
+        morphClock: handle.morphClock,
+        presence: handle.presence,
+        presenceClock: handle.presenceClock,
+        hide: handle.hide,
+        show: handle.show,
+        openProgress: handle.openProgress,
+        readFrame: handle.readFrame,
+        readSlot: handle.readSlot,
+        stepBy: handle.stepBy,
+        resetAutoplayClock: handle.resetAutoplayClock,
+        resetWithTransition: handle.resetWithTransition,
+    }), [
+        handle.id,
+        handle.config,
+        handle.position,
+        handle.opacity,
+        handle.autoplayProgress,
+        handle.mode,
+        handle.viewportRef,
+        handle.trackRef,
+        handle.probeRef,
+        handle.hovering,
+        handle.focused,
+        handle.visible,
+        handle.reducedMotion,
+        handle.autoplayClock,
+        handle.morph,
+        handle.morphClock,
+        handle.presence,
+        handle.presenceClock,
+        handle.hide,
+        handle.show,
+        handle.openProgress,
+        handle.readFrame,
+        handle.readSlot,
+        handle.stepBy,
+        handle.resetAutoplayClock,
+        handle.resetWithTransition,
+    ]);
+    const data = useMemo(() => ({
+        items: handle.items,
+        visibleIndices: handle.visibleIndices,
+        ring: handle.ring,
+        count: handle.count,
+        itemCount: handle.itemCount,
+        filters: handle.filters,
+        filter: handle.filter,
+        metrics: handle.metrics,
+        half: handle.half,
+        isStatic: handle.isStatic,
+        getMountCentre: handle.getMountCentre,
+        goTo: handle.goTo,
+        setFilter: handle.setFilter,
+        isOpen: handle.isOpen,
+        open: handle.open,
+        close: handle.close,
+    }), [
+        handle.isOpen,
+        handle.open,
+        handle.close,
+        handle.items,
+        handle.visibleIndices,
+        handle.ring,
+        handle.count,
+        handle.itemCount,
+        handle.filters,
+        handle.filter,
+        handle.metrics,
+        handle.half,
+        handle.isStatic,
+        handle.getMountCentre,
+        handle.goTo,
+        handle.setFilter,
+    ]);
+    return (_jsx(CarouselMotionContext.Provider, { value: motion, children: _jsx(CarouselDataContext.Provider, { value: data, children: _jsxs(StyleContext.Provider, { value: style, children: [transition ? _jsx(TransitionStyle, { transition: transition }) : null, typeof children === "function" ? children(handle) : children] }) }) }));
+}

package/dist/carousel/parts/Shader.d.ts

@@ -0,0 +1,32 @@
+import { type CarouselHandle } from "../engine/handle.js";
+import type { ShaderTransition } from "../../transitions/types.js";
+export interface ShaderProps<T> {
+    /** A shader transition: `noiseBurn()`, `ripple()`, `crossZoom()` … */
+    readonly effect: ShaderTransition;
+    /** The picture of an item (same origin, or served with CORS). */
+    readonly image: (item: T) => string | undefined;
+    readonly className?: string;
+    readonly engine?: CarouselHandle<T>;
+}
+/**
+ * Draws the carousel's pictures on one canvas and plays a shader transition
+ * between them (the atlas's "Shaders Slider"). Put it in the Viewport before
+ * the Track; the cards on top carry the text.
+ *
+ * ```tsx
+ * <Carousel.Root items={slides} config={useMemo(() => stage(fade()), [])}>
+ *   <Carousel.Viewport className="aspect-video">
+ *     <Carousel.Shader effect={noiseBurn()} image={(s) => s.src} />
+ *     <Carousel.Track>…text-only cards…</Carousel.Track>
+ *   </Carousel.Viewport>
+ * </Carousel.Root>
+ * ```
+ *
+ * The progress is the fractional part of the carousel's `position`: the
+ * picture at `floor(position)` blends into the next one, so dragging scrubs it
+ * and a fast triple click just re-aims the spring. Only the pictures around the
+ * position (previous / current / next) stay on the GPU; the ones after are
+ * decoded ahead. Without WebGL (or on a weaker device) its fallback CSS
+ * transition plays on two `<img>`s.
+ */
+export declare function Shader<T>({ effect, image, className, engine }: ShaderProps<T>): import("react").JSX.Element;

package/dist/carousel/parts/Shader.js

@@ -0,0 +1,63 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useMemo, useRef } from "react";
+import { motion } from "motion/react";
+import { useCarouselHandle } from "../engine/handle.js";
+import { wrapIndex } from "../engine/ring.js";
+import { ShaderStage } from "../../transitions/hosts/ShaderStage.js";
+/**
+ * Draws the carousel's pictures on one canvas and plays a shader transition
+ * between them (the atlas's "Shaders Slider"). Put it in the Viewport before
+ * the Track; the cards on top carry the text.
+ *
+ * ```tsx
+ * <Carousel.Root items={slides} config={useMemo(() => stage(fade()), [])}>
+ *   <Carousel.Viewport className="aspect-video">
+ *     <Carousel.Shader effect={noiseBurn()} image={(s) => s.src} />
+ *     <Carousel.Track>…text-only cards…</Carousel.Track>
+ *   </Carousel.Viewport>
+ * </Carousel.Root>
+ * ```
+ *
+ * The progress is the fractional part of the carousel's `position`: the
+ * picture at `floor(position)` blends into the next one, so dragging scrubs it
+ * and a fast triple click just re-aims the spring. Only the pictures around the
+ * position (previous / current / next) stay on the GPU; the ones after are
+ * decoded ahead. Without WebGL (or on a weaker device) its fallback CSS
+ * transition plays on two `<img>`s.
+ */
+export function Shader({ effect, image, className = "", engine }) {
+    const handle = useCarouselHandle(engine);
+    const latest = useRef({ handle, image });
+    latest.current = { handle, image };
+    // Stable for the Root's life: it reads the latest handle and picture
+    // function through the ref; `version` tells the stage when they changed.
+    const driver = useMemo(() => {
+        const at = (index) => {
+            const { handle: h, image: pictureOf } = latest.current;
+            if (h.count === 0)
+                return undefined;
+            const entry = h.ring[wrapIndex(index, h.count)];
+            const itemIndex = entry === undefined || entry < 0 ? undefined : h.visibleIndices[entry];
+            const item = itemIndex === undefined ? undefined : h.items[itemIndex];
+            return item === undefined ? undefined : pictureOf(item);
+        };
+        return {
+            read() {
+                const p = latest.current.handle.position.get();
+                const g = Math.floor(p);
+                const t = p - g;
+                // the neighbour the user is more likely to go to next comes first
+                return { from: at(g), to: at(g + 1), progress: t, ahead: t < 0.5 ? [at(g - 1), at(g + 2)] : [at(g + 2), at(g - 1)] };
+            },
+            watch(changed) {
+                return latest.current.handle.position.on("change", changed);
+            },
+        };
+    }, []);
+    const version = useMemo(() => ({}), [handle.ring, handle.visibleIndices, handle.items, image]);
+    return (
+    // follows the Track's opacity: the first-paint reveal and the filter cross-fade
+    // (layout inline, like the stage inside it: it must never depend on the page's utility CSS)
+    _jsx(motion.div, { "data-sx-shader-layer": true, className: className || undefined, style: { position: "absolute", inset: 0, pointerEvents: "none", opacity: handle.opacity }, children: _jsx(ShaderStage, { effect: effect, driver: driver, mode: "carousel", version: version }) }));
+}

package/dist/carousel/parts/Slot.d.ts

@@ -0,0 +1,59 @@
+import { type CarouselEngine } from "../engine/handle.js";
+export interface SlotProps {
+    readonly index: number;
+    readonly ringIndex: number;
+    readonly itemIndex: number | null;
+    readonly children?: React.ReactNode;
+    readonly className?: string;
+    readonly engine?: CarouselEngine;
+}
+/**
+ * The required part. It owns position, sizing and the engine contract; the
+ * child owns every pixel.
+ *
+ * The card is a 100%-by-100% tenant of a box the ENGINE sized, which is what
+ * makes an arbitrary card design safe: in 0.1.0 pitch was measured off the
+ * card's own root and silently included a 16px divider the card rendered, so
+ * swapping the card moved every other card. A card can no longer reach the
+ * layout maths at all.
+ *
+ * Three ways for a child to choreograph its own internals, cheapest first:
+ *
+ * 1. `var(--sx-distance)` in plain CSS -- no React, no hook, no context.
+ * 2. `useSlotState().distance` for a MotionValue.
+ * 3. `useSlotValue("scaleY")` for a RESOLVED layout output, materialised lazily.
+ *
+ * Reads the MERGED engine (motion + data), deliberately, not the motion-only
+ * slice. `useSlotWriter`'s render-body write only re-runs when THIS component
+ * re-renders or when `position`/`mode` change -- nothing else re-triggers it.
+ * If Slot subscribed to motion only, a metrics update (the ResizeObserver
+ * landing real numbers after mount, or a resize) would change `centerOffset`/
+ * `pitch` in the data slice while never giving an already-mounted, already-
+ * memoized Slot any reason to notice: `SlotContent`-style memoization (see the
+ * playground) correctly sees an unchanged `itemIndex` and skips calling this
+ * component again, so its write path would stay frozen at whatever geometry
+ * was current on its FIRST render -- typically all zeros, before the probe had
+ * measured anything, stacking every slot at x=0 until something UNRELATED
+ * later touches `position` (autoplay's first tick, a drag, a `stepBy` call)
+ * and finally forces a re-run. Subscribing to the merged engine means Slot's
+ * own context read fires on a metrics/filter change independent of any memo
+ * above it, so the write path always sees current geometry.
+ *
+ * This does not reopen the render-count problem `memo` exists for: the actual
+ * hot path (60fps drag/autoplay) was never about context in the first place --
+ * `position` is a MotionValue mutated in place, and `Window` only re-renders
+ * on a quantized slot-boundary crossing -- so it is unaffected either way. What
+ * changes is that Slot's own (cheap: a handful of MotionValue `.set`s, each an
+ * early-out if unchanged) body now correctly re-runs a few times a minute on a
+ * real filter click or resize, which was never the expensive part.
+ *
+ * `memo` still guards `children`: a consumer that skips the SlotContent-style
+ * memoization pattern and calls `<Carousel.Slot>` straight from Window's
+ * render-prop still benefits from `memo` on a boundary crossing that leaves
+ * this slot's index/ringIndex/itemIndex unchanged, PROVIDED their own child
+ * element is also reference-stable. `Carousel.Slot` cannot safely do that
+ * memoization FOR the consumer with a comparator that ignores `children` -- a
+ * card whose output depends on something besides `itemIndex` would then
+ * silently go stale.
+ */
+export declare const Slot: import("react").NamedExoticComponent<SlotProps>;