@sharedex/ui 0.0.0-stage → 0.9.0

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

@@ -0,0 +1,52 @@
+import type { CarouselFrame } from "../engine/types.js";
+/** The state at the moment the user lets go. */
+export interface Release {
+    readonly position: number;
+    /** Index units per second, signed. */
+    readonly velocity: number;
+    readonly frame: CarouselFrame;
+    /** Non-null only when `loop` is off. Looping carousels have no ends. */
+    readonly bounds: {
+        readonly min: number;
+        readonly max: number;
+    } | null;
+}
+/**
+ * What should happen after a release -- an INTENT, not a target position.
+ *
+ * A bare target would throw away the *shape* of the motion, which is where all
+ * the feel lives: nearest-snap and momentum-carry can compute the same target
+ * and must not move the same way.
+ *
+ * Every variant maps onto a primitive motion already ships, so there is no
+ * bespoke integrator anywhere in this package.
+ */
+export type Settle = {
+    readonly kind: "inertia";
+    readonly power?: number;
+    readonly timeConstant?: number;
+    readonly modifyTarget?: (v: number) => number;
+    readonly min?: number;
+    readonly max?: number;
+    readonly bounceStiffness?: number;
+    readonly bounceDamping?: number;
+    /** How close to the target, in cards, the glide counts as arrived. Default 0.001. */
+    readonly restDelta?: number;
+    /** Cards per second below which the end bounce counts as still. Default 0.01. */
+    readonly restSpeed?: number;
+} | {
+    readonly kind: "spring";
+    readonly to: number;
+    readonly stiffness?: number;
+    readonly damping?: number;
+    readonly mass?: number;
+} | {
+    readonly kind: "none";
+};
+export type SettlePolicy = (release: Release) => Settle;
+/**
+ * Drag-time resistance past an end. Takes how far past the edge the pointer has
+ * pulled (in index units) and returns how far the carousel actually moves.
+ * Only consulted when `loop` is off.
+ */
+export type Overdrag = (overshoot: number, frame: CarouselFrame) => number;

package/dist/carousel/physics/types.js

@@ -0,0 +1 @@
+export {};

package/dist/carousel/slot/context.d.ts

@@ -0,0 +1,42 @@
+import { type MotionValue } from "motion/react";
+import type { SlotFrameBuffer } from "../engine/types.js";
+import type { SlotWriter } from "./useSlotWriter.js";
+export interface SlotContextValue {
+    /** Position on the unbounded integer line. */
+    readonly index: number;
+    readonly ringIndex: number;
+    /** Index into the consumer's `items`, or null for a placeholder position. */
+    readonly itemIndex: number | null;
+    /** Signed, fractional slots from centre. 0 is dead centre. */
+    readonly distance: MotionValue<number>;
+    readonly writer: SlotWriter;
+}
+export declare const SlotContext: import("react").Context<SlotContextValue | null>;
+/**
+ * How open this card is: 0 … 1 for the open card, 0 for every other. A card
+ * can use it to load a bigger picture once it opens, or to show more detail.
+ */
+export declare function useSlotOpen(): MotionValue<number>;
+/**
+ * Read the slot a card is sitting in.
+ *
+ * Resolves to the NEAREST slot, which is what makes nesting work: a carousel
+ * rendered inside a card sees its own slots, while the card itself still sees
+ * the outer one.
+ */
+export declare function useSlotState(): SlotContextValue;
+/**
+ * A MotionValue for one RESOLVED layout output, rather than raw distance.
+ *
+ * Some card choreography keys off what the layout produced, not off distance:
+ * the 0.1.0 placeholder derived its text offset from the resolved `scaleY`.
+ * Without this, such a card has to re-derive the preset's own curve, which is
+ * exactly the coupling the layout layer exists to remove.
+ *
+ * Transform components (`x`, `scaleY`, `rotateY`, ...) have no standalone
+ * MotionValue by default -- they are folded into one transform string. Asking
+ * for one materialises it lazily, so a card that never asks pays nothing.
+ * The initial value is read straight from the already-resolved buffer, so
+ * there is no frame of wrong output before the subscription lands.
+ */
+export declare function useSlotValue<K extends keyof SlotFrameBuffer>(key: K): MotionValue<SlotFrameBuffer[K]>;

package/dist/carousel/slot/context.js

@@ -0,0 +1,69 @@
+"use client";
+import { createContext, useContext } from "react";
+import { useIsomorphicLayoutEffect, useMotionValue, useTransform, } from "motion/react";
+import { useCarouselMotion } from "../engine/handle.js";
+export const SlotContext = createContext(null);
+/**
+ * How open this card is: 0 … 1 for the open card, 0 for every other. A card
+ * can use it to load a bigger picture once it opens, or to show more detail.
+ */
+export function useSlotOpen() {
+    const { distance } = useSlotState();
+    const { openProgress } = useCarouselMotion();
+    return useTransform(() => openProgress.get() * Math.max(0, 1 - Math.abs(distance.get())));
+}
+/**
+ * Read the slot a card is sitting in.
+ *
+ * Resolves to the NEAREST slot, which is what makes nesting work: a carousel
+ * rendered inside a card sees its own slots, while the card itself still sees
+ * the outer one.
+ */
+export function useSlotState() {
+    const value = useContext(SlotContext);
+    if (!value) {
+        throw new Error("[@sharedex/ui] useSlotState must be called inside <Carousel.Slot>.");
+    }
+    return value;
+}
+/** The writer already keeps a dedicated MotionValue for these. */
+const DEDICATED = {
+    opacity: true,
+    zIndex: true,
+    filter: true,
+    pointerEvents: true,
+    originX: true,
+    originY: true,
+};
+const isDedicated = (k) => k in DEDICATED;
+/**
+ * A MotionValue for one RESOLVED layout output, rather than raw distance.
+ *
+ * Some card choreography keys off what the layout produced, not off distance:
+ * the 0.1.0 placeholder derived its text offset from the resolved `scaleY`.
+ * Without this, such a card has to re-derive the preset's own curve, which is
+ * exactly the coupling the layout layer exists to remove.
+ *
+ * Transform components (`x`, `scaleY`, `rotateY`, ...) have no standalone
+ * MotionValue by default -- they are folded into one transform string. Asking
+ * for one materialises it lazily, so a card that never asks pays nothing.
+ * The initial value is read straight from the already-resolved buffer, so
+ * there is no frame of wrong output before the subscription lands.
+ */
+export function useSlotValue(key) {
+    const { writer } = useSlotState();
+    // Hooks must run unconditionally, so materialise first and discard below.
+    const lazy = useMotionValue(writer.buffer[key]);
+    useIsomorphicLayoutEffect(() => {
+        if (isDedicated(key))
+            return;
+        return writer.register(key, lazy);
+    }, [writer, key, lazy]);
+    if (isDedicated(key)) {
+        // Safe by construction: DEDICATED's keys are exactly the writer fields
+        // whose MotionValue type already matches SlotFrameBuffer[key]. TypeScript
+        // cannot see that through the union because MotionValue is invariant.
+        return writer[key];
+    }
+    return lazy;
+}

package/dist/carousel/slot/useSlotWriter.d.ts

@@ -0,0 +1,65 @@
+import { type MotionValue } from "motion/react";
+import type { SlotFrameBuffer } from "../engine/types.js";
+import type { CarouselMotionSlice } from "../engine/handle.js";
+export interface SlotWriter {
+    /** ONE string. See the note below on why this beats a value per property. */
+    readonly transform: MotionValue<string>;
+    /** Published as `--sx-distance` so a card can choreograph in pure CSS. */
+    readonly distance: MotionValue<number>;
+    readonly opacity: MotionValue<number>;
+    readonly zIndex: MotionValue<number>;
+    readonly filter: MotionValue<string>;
+    readonly pointerEvents: MotionValue<"auto" | "none">;
+    readonly originX: MotionValue<number>;
+    readonly originY: MotionValue<number>;
+    /** Read-only view of the last resolved buffer, for useSlotValue. */
+    readonly buffer: SlotFrameBuffer;
+    /**
+     * Drive an extra MotionValue from one resolved buffer key.
+     *
+     * Transform components (x, scaleY, rotateY, ...) normally never exist as
+     * standalone values -- they are folded into the single transform string. A
+     * card that needs one materialises it here, and nothing pays for it until
+     * then. Returns an unsubscribe.
+     */
+    register<K extends keyof SlotFrameBuffer>(key: K, value: MotionValue<SlotFrameBuffer[K]>): () => void;
+}
+/**
+ * The per-slot write path. One layout evaluation and one transform string per
+ * slot per frame.
+ *
+ * ## Why a single 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 handing
+ * motion a ready-made transform string short-circuits its 18-property
+ * serialisation loop entirely.
+ *
+ * 0.1.0 ran five independent `useTransform` closures per slot -- five scheduler
+ * entries, five subscriptions, five function calls per frame, two of which
+ * (skewX/skewY) were computed and then never consumed by either card. Worse, the
+ * cost scaled *with* preset richness: a seven-term coverflow would have cost
+ * three times the two-term wave. Here it costs the same.
+ *
+ * ## Why this is not useMotionValueEvent
+ *
+ * The `update()` call in the render body is load-bearing and must not be
+ * "simplified" into an effect or a change subscription. This mirrors motion's
+ * own `useCombineMotionValues`, which calls `updateValue()` synchronously on
+ * every render for exactly this reason.
+ *
+ * At mount, metrics are all zero, so every card resolves to offset 0. The
+ * ResizeObserver then lands real numbers and React re-renders -- but `position`
+ * never moved, so no "change" event fires. A subscription-only writer would
+ * never re-run the layout, and every card would stay stacked on one edge until
+ * the user dragged, fading in as a pile.
+ *
+ * Typed to `CarouselMotionSlice`, not the full `CarouselEngine`, deliberately:
+ * everything read below (readFrame, readSlot, config, position, mode) lives in
+ * the motion slice, and the type constraint is what guarantees a future edit
+ * here can't reach for a data-slice field (`items`, `filter`, `metrics`, ...)
+ * without the compiler catching it. Slot passes it a `useCarouselMotion()`
+ * result specifically so a filter click never has a reason to run this again.
+ */
+export declare function useSlotWriter(handle: CarouselMotionSlice, index: number): SlotWriter;

package/dist/carousel/slot/useSlotWriter.js

@@ -0,0 +1,163 @@
+"use client";
+import { useRef } from "react";
+import { cancelFrame, frame as scheduler, useIsomorphicLayoutEffect, useMotionValue, } from "motion/react";
+import { createSlotFrameBuffer } from "../engine/types.js";
+import { applyLayout, serializeTransform } from "../layout/types.js";
+import { blendBuffers } from "../engine/morph.js";
+import { presenceProgress } from "../engine/presence.js";
+function useConstant(create) {
+    const ref = useRef(null);
+    if (ref.current === null)
+        ref.current = create();
+    return ref.current;
+}
+/**
+ * The per-slot write path. One layout evaluation and one transform string per
+ * slot per frame.
+ *
+ * ## Why a single 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 handing
+ * motion a ready-made transform string short-circuits its 18-property
+ * serialisation loop entirely.
+ *
+ * 0.1.0 ran five independent `useTransform` closures per slot -- five scheduler
+ * entries, five subscriptions, five function calls per frame, two of which
+ * (skewX/skewY) were computed and then never consumed by either card. Worse, the
+ * cost scaled *with* preset richness: a seven-term coverflow would have cost
+ * three times the two-term wave. Here it costs the same.
+ *
+ * ## Why this is not useMotionValueEvent
+ *
+ * The `update()` call in the render body is load-bearing and must not be
+ * "simplified" into an effect or a change subscription. This mirrors motion's
+ * own `useCombineMotionValues`, which calls `updateValue()` synchronously on
+ * every render for exactly this reason.
+ *
+ * At mount, metrics are all zero, so every card resolves to offset 0. The
+ * ResizeObserver then lands real numbers and React re-renders -- but `position`
+ * never moved, so no "change" event fires. A subscription-only writer would
+ * never re-run the layout, and every card would stay stacked on one edge until
+ * the user dragged, fading in as a pile.
+ *
+ * Typed to `CarouselMotionSlice`, not the full `CarouselEngine`, deliberately:
+ * everything read below (readFrame, readSlot, config, position, mode) lives in
+ * the motion slice, and the type constraint is what guarantees a future edit
+ * here can't reach for a data-slice field (`items`, `filter`, `metrics`, ...)
+ * without the compiler catching it. Slot passes it a `useCarouselMotion()`
+ * result specifically so a filter click never has a reason to run this again.
+ */
+export function useSlotWriter(handle, index) {
+    const buffer = useConstant(createSlotFrameBuffer);
+    // Layout morph: this slot's pose when the change happened, blended into the
+    // new layout's pose. `written` is false for a slot mounted mid-morph: it has
+    // no pose to start from and takes the new layout as it is.
+    const from = useConstant(createSlotFrameBuffer);
+    const morphSeen = useConstant(() => ({ gen: 0, snapshot: false, written: false }));
+    // Stays empty for every card that never asks, which is almost all of them.
+    // Stored as type-erased setters: MotionValue<T> is invariant in T, so a map
+    // keyed by the buffer's union of value types cannot be expressed directly.
+    const extras = useConstant(() => new Map());
+    const slotState = useConstant(() => ({
+        index: 0,
+        ringIndex: 0,
+        itemIndex: null,
+        distance: 0,
+    }));
+    const transform = useMotionValue("none");
+    const distance = useMotionValue(0);
+    const opacity = useMotionValue(1);
+    const zIndex = useMotionValue(0);
+    const filter = useMotionValue("none");
+    const pointerEvents = useMotionValue("auto");
+    const originX = useMotionValue(0.5);
+    const originY = useMotionValue(0.5);
+    const update = () => {
+        const frameState = handle.readFrame();
+        const slot = handle.readSlot(slotState, index);
+        // A layout may name a reduced-motion stand-in (stage looks use fade()).
+        // The flag is a ref, so the swap lands on the next write, not a re-render.
+        const { layout } = handle.config;
+        const active = layout.reduced && handle.reducedMotion.current && handle.config.a11y.respectReducedMotion
+            ? layout.reduced
+            : layout;
+        const morph = handle.morph.current;
+        if (morph.active && morphSeen.gen !== morph.gen) {
+            morphSeen.gen = morph.gen;
+            morphSeen.snapshot = morphSeen.written;
+            // the pose on screen right now, mid-morph included
+            if (morphSeen.written)
+                Object.assign(from, buffer);
+        }
+        applyLayout(active, buffer, slot, frameState);
+        morphSeen.written = true;
+        // The one exception to "one layout evaluation per frame" is free here: the
+        // old pose is a snapshot, so a morph costs one blend, not a second layout.
+        if (morph.active && morphSeen.snapshot) {
+            const t = morph.curve.at(handle.morphClock.get() - morph.stagger * Math.abs(slot.distance));
+            if (t !== 1)
+                blendBuffers(buffer, from, buffer, t);
+        }
+        // Enter / exit: the preset moves the resting pose to how it looks at p.
+        const presence = handle.presence.current;
+        if (presence.phase !== "shown" && presence.preset) {
+            const p = presenceProgress(presence, handle.presenceClock.get(), slot.distance);
+            if (p !== 1)
+                presence.preset.apply(buffer, slot, frameState, p);
+        }
+        // Every .set early-outs when the value is unchanged, so the near-static
+        // ones below cost nothing on a typical frame.
+        transform.set(serializeTransform(buffer));
+        const range = layout.distanceRange;
+        distance.set(range ? Math.min(range[1], Math.max(range[0], slot.distance)) : slot.distance);
+        opacity.set(buffer.opacity);
+        zIndex.set(buffer.zIndex);
+        filter.set(buffer.filter);
+        pointerEvents.set(buffer.pointerEvents);
+        originX.set(buffer.originX);
+        originY.set(buffer.originY);
+        for (const [key, sink] of extras)
+            sink(buffer[key]);
+    };
+    // Synchronous, every render. See the note above.
+    update();
+    // No dependency array, matching useCombineMotionValues: resubscribing each
+    // render is what keeps `update`'s closure over `index` and the current layout
+    // fresh. preRender(..., immediate=true) collapses a double-write in one frame.
+    useIsomorphicLayoutEffect(() => {
+        const schedule = () => scheduler.preRender(update, false, true);
+        const stopPosition = handle.position.on("change", schedule);
+        const stopMode = handle.mode.on("change", schedule);
+        const stopMorph = handle.morphClock.on("change", schedule);
+        const stopPresence = handle.presenceClock.on("change", schedule);
+        return () => {
+            stopPosition();
+            stopMode();
+            stopMorph();
+            stopPresence();
+            cancelFrame(update);
+        };
+    });
+    return {
+        transform,
+        distance,
+        opacity,
+        zIndex,
+        filter,
+        pointerEvents,
+        originX,
+        originY,
+        buffer,
+        register(key, value) {
+            const sink = (v) => value.set(v);
+            extras.set(key, sink);
+            return () => {
+                // Identity-checked so a re-register cannot be undone by a stale cleanup.
+                if (extras.get(key) === sink)
+                    extras.delete(key);
+            };
+        },
+    };
+}

package/dist/carousel/types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Public data types.
+ *
+ * 0.1.0 shipped a closed `TemplateCategory` union of four English literals,
+ * which type-blocked every site that wasn't folio. Items are now opaque to the
+ * engine: it stores indices, never records (see engine/ring.ts), so nothing
+ * here constrains what a card actually holds.
+ */
+/** A filter's value. Any string; "all" is conventional but not required. */
+export type FilterValue = string;
+export interface CarouselFilter<T = unknown> {
+    readonly label: string;
+    readonly value: FilterValue;
+    /**
+     * Which items this pill keeps. Omit it and the filter matches every item
+     * whose `category` field equals `value` -- the 0.1.0 behaviour, minus the
+     * closed union.
+     */
+    readonly predicate?: (item: T, index: number) => boolean;
+}
+/**
+ * The default match when a filter declares no predicate: keep everything for
+ * "all", otherwise compare a `category` field if the item happens to have one.
+ */
+export declare function defaultFilterPredicate(item: unknown, value: FilterValue): boolean;

package/dist/carousel/types.js

@@ -0,0 +1,20 @@
+/**
+ * Public data types.
+ *
+ * 0.1.0 shipped a closed `TemplateCategory` union of four English literals,
+ * which type-blocked every site that wasn't folio. Items are now opaque to the
+ * engine: it stores indices, never records (see engine/ring.ts), so nothing
+ * here constrains what a card actually holds.
+ */
+/**
+ * The default match when a filter declares no predicate: keep everything for
+ * "all", otherwise compare a `category` field if the item happens to have one.
+ */
+export function defaultFilterPredicate(item, value) {
+    if (value === "all")
+        return true;
+    if (typeof item !== "object" || item === null)
+        return false;
+    const category = item.category;
+    return category === value;
+}

package/dist/gpu/surface.d.ts

@@ -0,0 +1,46 @@
+import type { GpuContext } from "../backgrounds/types.js";
+/** How long a host may sit off screen before its context is handed back. */
+export declare const RELEASE_AFTER_MS = 3000;
+/** More context losses than this while on screen (within LOSS_WINDOW_MS) and the host settles on its fallback. */
+export declare const MAX_LOSSES = 3;
+export declare const LOSS_WINDOW_MS = 10000;
+export declare const CONTEXT_ATTRIBUTES: WebGLContextAttributes;
+export interface SurfaceHooks<S> {
+    readonly api: "webgl" | "webgl2";
+    /** Named in the console when a shader does not compile. */
+    readonly label: string;
+    /** Compile and allocate on a fresh context. Throw `WebglUnavailable` when the device cannot. */
+    init(gl: GpuContext): S;
+    dispose(gl: GpuContext, state: S): void;
+    /** Is the host on screen now? Asked again before a delayed release and after a loss. */
+    isVisible(): boolean;
+    /** The context is about to go: stop drawing. */
+    onRelease?(): void;
+    /** A fresh canvas is needed (the context was released or lost and the host is on screen again). */
+    renew(): void;
+    /** The device cannot run it: show the fallback. */
+    fail(): void;
+    /** Loss times, kept by the host across canvases (each renew is a new surface). */
+    readonly losses: {
+        current: number[];
+    };
+}
+export interface GpuSurface<S> {
+    /** The live context and its state, or null. */
+    readonly live: {
+        readonly gl: GpuContext;
+        readonly state: S;
+    } | null;
+    /** The live context, created on first call. Null when the device cannot (`fail` was called). */
+    ensure(): {
+        readonly gl: GpuContext;
+        readonly state: S;
+    } | null;
+    /** The host went off screen: release the context after RELEASE_AFTER_MS unless it comes back. */
+    hidden(): void;
+    /** The host is on screen. False when the context is gone and `renew` was called: stop, a new canvas is coming. */
+    shown(): boolean;
+    /** Unmount: free everything now. */
+    destroy(): void;
+}
+export declare function createGpuSurface<S>(canvas: HTMLCanvasElement, hooks: SurfaceHooks<S>): GpuSurface<S>;

package/dist/gpu/surface.js

@@ -0,0 +1,127 @@
+// ---------------------------------------------------------------------------
+// The WebGL context lifecycle, shared by every host that draws with WebGL
+// (backgrounds' WebglHost, transitions' ShaderStage). No React: the host keeps
+// the canvas generation and the "failed" flag in its own state and hands this
+// the callbacks that change them.
+//
+// A page gets only ~16 live WebGL contexts, so a surface:
+// - creates its context on first need (the host calls `ensure()` once it is on
+//   screen), not on mount;
+// - hands it back (`loseContext`) after RELEASE_AFTER_MS off screen; a released
+//   or lost context cannot be revived, so the host renders a fresh canvas
+//   (`renew`) when it returns;
+// - gives up (`fail`, the host shows its fallback) when WebGL, an extension or
+//   a compile is missing, or after MAX_LOSSES losses within LOSS_WINDOW_MS.
+// ---------------------------------------------------------------------------
+import { WebglUnavailable } from "../backgrounds/runtime/webgl.js";
+/** How long a host may sit off screen before its context is handed back. */
+export const RELEASE_AFTER_MS = 3000;
+/** More context losses than this while on screen (within LOSS_WINDOW_MS) and the host settles on its fallback. */
+export const MAX_LOSSES = 3;
+export const LOSS_WINDOW_MS = 10000;
+export const CONTEXT_ATTRIBUTES = {
+    alpha: true,
+    premultipliedAlpha: true,
+    antialias: false,
+    depth: false,
+    stencil: false,
+    preserveDrawingBuffer: false,
+    powerPreference: "low-power",
+};
+/**
+ * Canvases whose context a surface handed back. A host's effect can run again
+ * on the same canvas element (React StrictMode mounts twice; an option change
+ * re-runs the effect), and `getContext` then returns the dead context: Three.js
+ * throws on it, so the host must renew instead.
+ */
+const spent = new WeakSet();
+export function createGpuSurface(canvas, hooks) {
+    let live = null;
+    let released = false;
+    let timer;
+    const ensure = () => {
+        if (live)
+            return live;
+        if (spent.has(canvas)) {
+            released = true;
+            hooks.renew();
+            return null;
+        }
+        try {
+            const context = (hooks.api === "webgl2" ? canvas.getContext("webgl2", CONTEXT_ATTRIBUTES) : canvas.getContext("webgl", CONTEXT_ATTRIBUTES));
+            if (!context)
+                throw new WebglUnavailable(`${hooks.api === "webgl2" ? "WebGL2" : "WebGL"} is not available`);
+            live = { gl: context, state: hooks.init(context) };
+            return live;
+        }
+        catch (error) {
+            if (!(error instanceof WebglUnavailable)) {
+                console.warn(`[@sharedex/ui] ${hooks.label}: could not start (${String(error)}). Showing its fallback.`);
+            }
+            else if (/compile|link/.test(error.message)) {
+                console.warn(`[@sharedex/ui] ${hooks.label}: ${error.message} Showing its fallback.`);
+            }
+            hooks.fail();
+            return null;
+        }
+    };
+    /** Free the program and hand the context back now instead of waiting for garbage collection. */
+    const free = () => {
+        if (live && !live.gl.isContextLost()) {
+            hooks.dispose(live.gl, live.state);
+            live.gl.getExtension("WEBGL_lose_context")?.loseContext();
+            spent.add(canvas);
+        }
+        live = null;
+    };
+    const release = () => {
+        hooks.onRelease?.();
+        free();
+        released = true;
+    };
+    const lost = (event) => {
+        event.preventDefault();
+        // the late event of a context an earlier surface on this canvas handed back: not a loss of ours
+        if (!live)
+            return;
+        live = null; // its resources died with it
+        release();
+        if (!hooks.isVisible())
+            return;
+        const now = performance.now();
+        hooks.losses.current = [...hooks.losses.current.filter((t) => now - t < LOSS_WINDOW_MS), now];
+        if (hooks.losses.current.length > MAX_LOSSES)
+            hooks.fail();
+        else
+            hooks.renew();
+    };
+    canvas.addEventListener("webglcontextlost", lost);
+    return {
+        get live() {
+            return live;
+        },
+        ensure,
+        hidden() {
+            if (!live || timer !== undefined)
+                return;
+            timer = setTimeout(() => {
+                timer = undefined;
+                if (!hooks.isVisible())
+                    release();
+            }, RELEASE_AFTER_MS);
+        },
+        shown() {
+            clearTimeout(timer);
+            timer = undefined;
+            if (!released)
+                return true;
+            hooks.renew(); // back on screen: a fresh canvas and context
+            return false;
+        },
+        destroy() {
+            clearTimeout(timer);
+            canvas.removeEventListener("webglcontextlost", lost);
+            free();
+        },
+    };
+}

package/dist/grid/Grid.schema.d.ts

@@ -0,0 +1,6 @@
+import type { GridRootProps } from "./Root.js";
+/** `GridRootProps` for a form: `columns` is a number, unset meaning `"auto"`. */
+export interface GridSettings extends Omit<GridRootProps<unknown>, "columns"> {
+    readonly columns: number;
+}
+export declare const GRID_SCHEMA: import("../schema/types.js").Schema;