@satinhq/kit 0.0.0-stage → 0.1.0-beta.1

package/dist/presentation/dismiss.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Component, createContext, useContext } from 'react';
+/** The nearest dismissal: a pushed screen pops itself, a presentation's root dismisses it. */
+export const DismissContext = createContext(undefined);
+/**
+ * Closes the screen or presentation that contains the caller.
+ * In a pushed screen it pops that screen; at the root of a Sheet or FullScreenCover it dismisses the
+ * presentation, even when interactive dismissal is disabled. Elsewhere it does nothing.
+ */
+export function useDismiss() {
+    return useContext(DismissContext) ?? noDismissal;
+}
+function noDismissal() { }
+/**
+ * A render or effect error inside one presentation stays inside it. The app behind it keeps
+ * running and the presentation can still be dismissed. React still reports the caught error.
+ */
+export class PresentationBoundary extends Component {
+    state = { failure: null };
+    static getDerivedStateFromError(error) {
+        return { failure: { error } };
+    }
+    render() {
+        const failure = this.state.failure;
+        if (!failure)
+            return this.props.children;
+        const detail = failure.error instanceof Error ? failure.error.message : String(failure.error);
+        return (_jsxs("div", { role: "alert", className: "satin-presentation-failure", children: [_jsx("p", { className: "satin-presentation-failure-title", children: "This content couldn\u2019t be shown." }), _jsx("p", { className: "satin-presentation-failure-detail", children: detail })] }));
+    }
+}

package/dist/presentation/glassMotion.d.ts

@@ -0,0 +1,39 @@
+import type { AccessoryViewportTrack } from '../glass/webgpu/accessoryTrack.js';
+type Rect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/** The sheet's own material follows screen coordinates. Nested glass stays at rest. */
+export type PresentationGlassMotion = {
+    rect: Rect;
+    sampleRect: Rect;
+    track: AccessoryViewportTrack;
+    /** One retained-content submission per run, prepared before its clock starts. */
+    contentEpoch: number;
+    admitted: boolean;
+    ready: Promise<void>;
+    acknowledge: (track: AccessoryViewportTrack) => void;
+    current: () => boolean;
+    start: () => Promise<number>;
+    dispose: () => void;
+};
+/** Retarget an already admitted envelope without another capture or content fence. */
+export declare const PRESENTATION_TRACK_EVENT = "satin-presentation-track";
+/** Live finger writes remain imperative; the worker receives their matching held pose. */
+export declare function holdPresentationGlassMotion(layer: HTMLElement, offset: number): void;
+/** Returns the shared document epoch only when this run can start without waiting. */
+export declare function retargetPresentationGlassMotion(layer: HTMLElement, animation: Animation, now: number): number | undefined;
+export declare const presentationGlassMotion: (element: Element) => PresentationGlassMotion | undefined;
+export declare function disposePresentationGlassMotion(layer: HTMLElement): void;
+/** Nested materials keep their resting pixels, but must submit them for the new moving show
+ * before the outer clock is acknowledged. A cached draw from the clipped hold is not that handoff. */
+export declare function presentationGlassContentEpoch(element: Element): number | undefined;
+/** Once the renderer follows the run, neither outer nor nested canvases need DOM polling. */
+export declare function presentationGlassFollowing(element: Element): boolean;
+/** Reuse the actual WAAPI samples, including overshoot; never fit a second spring here. */
+export declare function preparePresentationGlassMotion(layer: HTMLElement, animation: Animation, { retain }?: {
+    retain?: boolean;
+}): PresentationGlassMotion | undefined;
+export {};

package/dist/presentation/glassMotion.js

@@ -0,0 +1,259 @@
+import { lagMark, lagTraceEnabled } from '../glass/webgpu/lagTrace.js';
+import { timelineStart } from '../motion/animate.js';
+const materials = new WeakMap();
+const layers = new WeakMap();
+let nextContentEpoch = 0;
+/** Retarget an already admitted envelope without another capture or content fence. */
+export const PRESENTATION_TRACK_EVENT = 'satin-presentation-track';
+function animationTrack(animation) {
+    const effect = animation.effect;
+    if (!effect?.getKeyframes)
+        return;
+    const frames = effect.getKeyframes();
+    const duration = Number(effect.getTiming().duration);
+    if (frames.length < 2 || !(duration > 0))
+        return;
+    if (frames.some((frame, index) => Math.abs(frame.computedOffset - index / (frames.length - 1)) > 1e-6))
+        return;
+    const offsets = frames.map(frame => {
+        const matrix = new DOMMatrixReadOnly(String(frame.transform ?? 'none'));
+        return { x: matrix.e, y: matrix.f };
+    });
+    return { duration, offsets };
+}
+function retarget(layer, track) {
+    const motion = layers.get(layer);
+    if (!motion?.current() || !motion.admitted)
+        return false;
+    const { rect, sampleRect } = motion;
+    // Reuse only source rows admitted for this same layout. A reflow retires the
+    // owner through ResizeObserver; a trajectory outside its envelope needs admission.
+    if (!track.offsets ||
+        track.offsets.some(offset => rect.x + offset.x < sampleRect.x - 0.5 ||
+            rect.y + offset.y < sampleRect.y - 0.5 ||
+            rect.x + offset.x + rect.width > sampleRect.x + sampleRect.width + 0.5 ||
+            rect.y + offset.y + rect.height > sampleRect.y + sampleRect.height + 0.5))
+        return false;
+    motion.track = track;
+    const material = layer.querySelector('.satin-presentation-surface');
+    window.dispatchEvent(new CustomEvent(PRESENTATION_TRACK_EVENT, { detail: material }));
+    return true;
+}
+/** Live finger writes remain imperative; the worker receives their matching held pose. */
+export function holdPresentationGlassMotion(layer, offset) {
+    const motion = layers.get(layer);
+    if (!motion)
+        return;
+    if (!retarget(layer, {
+        epoch: Number.MAX_VALUE,
+        duration: 1,
+        widths: [motion.rect.width, motion.rect.width],
+        offsets: [
+            { x: 0, y: offset },
+            { x: 0, y: offset },
+        ],
+    }))
+        motion.dispose();
+}
+/** Returns the shared document epoch only when this run can start without waiting. */
+export function retargetPresentationGlassMotion(layer, animation, now) {
+    const motion = layers.get(layer);
+    const samples = animationTrack(animation);
+    if (!motion || !samples)
+        return;
+    if (!retarget(layer, {
+        epoch: performance.timeOrigin + now,
+        duration: samples.duration,
+        widths: samples.offsets.map(() => motion.rect.width),
+        offsets: samples.offsets,
+    }))
+        return;
+    return timelineStart(now);
+}
+export const presentationGlassMotion = (element) => materials.get(element);
+export function disposePresentationGlassMotion(layer) {
+    layers.get(layer)?.dispose();
+}
+/** Nested materials keep their resting pixels, but must submit them for the new moving show
+ * before the outer clock is acknowledged. A cached draw from the clipped hold is not that handoff. */
+export function presentationGlassContentEpoch(element) {
+    const own = materials.get(element);
+    if (own)
+        return own.contentEpoch;
+    const layer = element.closest('[data-satin-glass-layer]');
+    const motion = layer ? layers.get(layer) : undefined;
+    return motion?.contentEpoch;
+}
+/** Once the renderer follows the run, neither outer nor nested canvases need DOM polling. */
+export function presentationGlassFollowing(element) {
+    const layer = element.closest('[data-satin-glass-layer]');
+    // Retaining coverage between gestures must not freeze nested scroll/toolbar
+    // presenters. Only active sheet travel replaces their DOM viewport sampling.
+    return (!!layer &&
+        layers.get(layer)?.admitted === true &&
+        !!layer.closest('dialog')?.hasAttribute('data-satin-presentation-moving'));
+}
+/** Reuse the actual WAAPI samples, including overshoot; never fit a second spring here. */
+export function preparePresentationGlassMotion(layer, animation, { retain = false } = {}) {
+    const material = layer.querySelector('.satin-presentation-surface');
+    if (!material)
+        return;
+    const usesFallback = () => !!material.querySelector(':scope > [data-satin-fallback-material]');
+    let ownsMaterial = material.hasAttribute('data-satin-glass-region-id') && !usesFallback();
+    const effect = animation.effect;
+    if (!effect?.getKeyframes)
+        return;
+    const frames = effect.getKeyframes();
+    const duration = Number(effect.getTiming().duration);
+    if (frames.length < 2 || !(duration > 0))
+        return;
+    // These framework tracks have evenly spaced translation samples and linear interpolation.
+    if (frames.some((frame, index) => Math.abs(frame.computedOffset - index / (frames.length - 1)) > 1e-6))
+        return;
+    const offsets = frames.map(frame => {
+        const matrix = new DOMMatrixReadOnly(String(frame.transform ?? 'none'));
+        return { x: matrix.e, y: matrix.f };
+    });
+    const transform = new DOMMatrixReadOnly(getComputedStyle(layer).transform || 'none');
+    const bounds = material.getBoundingClientRect();
+    const rect = {
+        x: bounds.x - transform.e,
+        y: bounds.y - transform.f,
+        width: bounds.width,
+        height: bounds.height,
+    };
+    const minX = Math.min(...offsets.map(offset => offset.x));
+    const maxX = Math.max(...offsets.map(offset => offset.x));
+    const minY = Math.min(...offsets.map(offset => offset.y));
+    const maxY = Math.max(...offsets.map(offset => offset.y));
+    const trace = (stage, values) => {
+        if (lagTraceEnabled())
+            lagMark({
+                stage: `sheet-motion-${stage}`,
+                at: performance.timeOrigin + performance.now(),
+                values,
+            });
+    };
+    trace('prepared', { width: rect.width, height: rect.height, ownsMaterial });
+    let started;
+    const running = new Promise(resolve => {
+        started = resolve;
+    });
+    let prepared;
+    const ready = new Promise(resolve => {
+        prepared = resolve;
+    });
+    let preparedReady = !ownsMaterial;
+    let startRequested = false;
+    let startFrame = 0;
+    let timelineEpoch = 0;
+    const motion = {
+        rect,
+        contentEpoch: ++nextContentEpoch,
+        sampleRect: {
+            x: rect.x + minX,
+            y: rect.y + minY,
+            width: rect.width + maxX - minX,
+            height: rect.height + maxY - minY,
+        },
+        // Prepare coverage and the first glass while WAAPI is held at sample zero.
+        track: { epoch: Number.MAX_VALUE, duration, widths: offsets.map(() => rect.width), offsets },
+        admitted: false,
+        ready,
+        current: () => layers.get(layer) === motion,
+        acknowledge(track) {
+            if (!motion.current() || motion.track !== track)
+                return;
+            preparedReady = true;
+            prepared();
+            if (track.epoch !== Number.MAX_VALUE) {
+                motion.admitted = true;
+                trace('admitted');
+                started(timelineEpoch);
+            }
+        },
+        start() {
+            if (!motion.current() || startRequested)
+                return running;
+            startRequested = true;
+            // Coverage, resource installation and the nested-content fence may take many frames.
+            // Keep sample zero throughout that work instead of spending the entrance behind the hold.
+            if (!preparedReady)
+                window.dispatchEvent(new Event('satin-presentation-motion'));
+            void ready.then(() => {
+                if (!motion.current())
+                    return;
+                // A long task can leave the document clock over a second behind. Acquire both
+                // clocks at a rendering update so a stall cannot look like suspension drift.
+                startFrame = requestAnimationFrame(() => {
+                    startFrame = 0;
+                    if (!motion.current())
+                        return;
+                    const start = performance.now();
+                    timelineEpoch = timelineStart(start);
+                    motion.track = { ...motion.track, epoch: performance.timeOrigin + start };
+                    motion.admitted = !ownsMaterial;
+                    if (!ownsMaterial)
+                        started(timelineEpoch);
+                    else
+                        window.dispatchEvent(new Event('satin-presentation-motion'));
+                });
+            });
+            return running;
+        },
+        dispose() {
+            if (layers.get(layer) !== motion)
+                return;
+            trace('retired');
+            cancelAnimationFrame(startFrame);
+            resize.disconnect();
+            fallback.disconnect();
+            window.removeEventListener('resize', motion.dispose);
+            window.visualViewport?.removeEventListener('resize', motion.dispose);
+            materials.delete(material);
+            layers.delete(layer);
+            // A reflow retires this sampled path. Resume the existing DOM-following path
+            // immediately instead of leaving a visible restoration paused until the watchdog.
+            motion.admitted = false;
+            prepared();
+            started(timelineStart(performance.now()));
+            window.dispatchEvent(new Event('satin-presentation-motion'));
+        },
+    };
+    const resize = new ResizeObserver(entries => {
+        const size = entries[0]?.borderBoxSize?.[0];
+        if (size &&
+            (Math.abs(size.inlineSize - rect.width) > 0.5 || Math.abs(size.blockSize - rect.height) > 0.5)) {
+            trace('reflow', { width: size.inlineSize, height: size.blockSize });
+            motion.dispose();
+        }
+    });
+    // CSS fallback samples its backdrop live. A demotion must release a pending
+    // GPU admission rather than leave a visible modal waiting for a retired worker.
+    const fallback = new MutationObserver(() => {
+        if (!ownsMaterial || !usesFallback() || !motion.current())
+            return;
+        ownsMaterial = false;
+        preparedReady = true;
+        prepared();
+        if (motion.track.epoch !== Number.MAX_VALUE) {
+            motion.admitted = true;
+            started(timelineEpoch);
+        }
+    });
+    layers.get(layer)?.dispose();
+    resize.observe(material);
+    fallback.observe(material, { childList: true });
+    window.addEventListener('resize', motion.dispose);
+    window.visualViewport?.addEventListener('resize', motion.dispose);
+    if (ownsMaterial)
+        materials.set(material, motion);
+    else
+        prepared();
+    layers.set(layer, motion);
+    // A sheet can retain its admitted full travel envelope between gestures. Its
+    // modal owner, resize or replacement retires it; a finished animation does not.
+    if (!retain)
+        void animation.finished.then(motion.dispose, motion.dispose);
+    return motion;
+}

package/dist/presentation/glassReady.d.ts

@@ -0,0 +1,11 @@
+/** Keep the whole surface together until this show's scene has been submitted.
+ * Layout stays measurable while hidden; no replacement material is displayed. */
+export declare function holdPresentationForGlass(panel: HTMLElement, dimmer: HTMLElement | null, animations: readonly Animation[], invalidate: () => void, onReady?: () => void, canReveal?: () => boolean, 
+/** Native has no presented sheet before its presentation: nothing held is focusable or reachable
+ * by assistive technology (a menu keeps its own inert state, menuPresenter.tsx). */
+{ inert, revealStart, onFailure, }?: {
+    inert?: boolean;
+    revealStart?: () => Promise<number>;
+    /** Retire caller-owned visibility on failure instead of starting an unready entrance. */
+    onFailure?: () => void;
+}): () => void;

package/dist/presentation/glassReady.js

@@ -0,0 +1,246 @@
+import { VisibleDeadline } from '../glass/visibleDeadline.js';
+import { reportGlassError } from '../glass/errors.js';
+import { hold, releaseHold } from '../glass/presentationFrame.js';
+import { focusFromFramework } from '../focus/programmaticFocus.js';
+import { lagTraceEnabled } from '../glass/webgpu/lagTrace.js';
+import { glassNow, glassTiming } from '../glass/webgpu/profile.js';
+let nextShow = 0;
+/** Keep the whole surface together until this show's scene has been submitted.
+ * Layout stays measurable while hidden; no replacement material is displayed. */
+export function holdPresentationForGlass(panel, dimmer, animations, invalidate, onReady = () => { }, canReveal = () => true, 
+/** Native has no presented sheet before its presentation: nothing held is focusable or reachable
+ * by assistive technology (a menu keeps its own inert state, menuPresenter.tsx). */
+{ inert = false, revealStart, onFailure, } = {}) {
+    const generation = String(++nextShow);
+    const requestedAt = lagTraceEnabled() ? glassNow() : 0;
+    const trace = (stage) => {
+        if (lagTraceEnabled())
+            glassTiming(stage, requestedAt, generation);
+    };
+    trace('presentation-held');
+    // Only this presentation's own materials gate it: a canvas owned directly by a glass region in
+    // this dialog. A container's auxiliary canvas sits inside the sheet's region without being one,
+    // and a nested dialog holds its own show (reference readiness contract). Glass that mounts during the
+    // hold (a sheet's toolbar capsules are laid out after it opens) gates it too.
+    const dialog = panel.closest('dialog');
+    const gated = () => [
+        ...panel.querySelectorAll('canvas[data-satin-glass-region-canvas]:not([data-satin-glass-lift])'),
+    ].filter(canvas => canvas.parentElement?.hasAttribute('data-satin-glass-region-id') &&
+        canvas.closest('dialog') === dialog);
+    // Glass on a presentation samples the presentation's own content. Nothing may show until the
+    // renderer holds a backdrop measured during this hold (presentationFrame.ts) and the glass has
+    // been drawn over it, or the glass would show the screen below and change once content arrives.
+    let sourced = !panel.querySelector('[data-satin-presentation-content]');
+    let show = generation;
+    const arm = (canvas) => {
+        canvas.dataset.satinGlassShow = show;
+        delete canvas.dataset.satinGlassPresented;
+        delete canvas.dataset.satinGlassPresentedShow;
+    };
+    const targets = [panel, dimmer].filter((node) => node !== null);
+    // The hold is marked with its show generation, so source preparation can read through this
+    // framework hold while content an author hid stays hidden.
+    for (const node of targets)
+        hold(node, generation);
+    const releaseEditor = keepFocusedEditor(panel);
+    const releaseInert = inert ? holdInert(targets, panel) : (_refocus) => { };
+    for (const animation of animations) {
+        animation.pause();
+        animation.currentTime = 0;
+    }
+    gated().forEach(arm);
+    let stopped = false;
+    let preparingMotion = false;
+    const observer = new MutationObserver(check);
+    // The failure is reported loudly, then the presentation stops holding: an invisible modal would
+    // trap the app. The entrance settles at its resting pose without the motion sampling hook.
+    const deadline = new VisibleDeadline(10_000, () => {
+        if (stopped)
+            return;
+        trace('presentation-readiness-timeout');
+        reportGlassError('readiness-timeout', new Error('Presentation glass did not submit for the current show'), 'presentation-first-show');
+        stopped = true;
+        observer.disconnect();
+        if (!canReveal())
+            return;
+        if (onFailure) {
+            // Menu callers own a separate visibility state. Dismiss it before releasing this hold;
+            // treating failure as ready would start an entrance with no admitted glass.
+            onFailure();
+            reveal(true);
+        }
+        else {
+            reveal();
+            for (const animation of animations)
+                animation.finish();
+        }
+    });
+    deadline.start();
+    function reveal(closing = false) {
+        for (const node of targets)
+            releaseHold(node, generation);
+        releaseEditor();
+        releaseInert(!closing);
+    }
+    function check() {
+        if (stopped || preparingMotion)
+            return;
+        const canvases = gated();
+        if (!canvases.length)
+            return;
+        const late = canvases.filter(canvas => canvas.dataset.satinGlassShow !== show);
+        if (late.length) {
+            late.forEach(arm);
+            invalidate();
+            return;
+        }
+        if (!sourced) {
+            if (panel.getAttribute('data-satin-glass-source') !== generation)
+                return;
+            sourced = true;
+            trace('presentation-source-ready');
+            // Draws from scenes posted before this backdrop are not this show's: count only receipts
+            // for scenes that sample it.
+            show = `${generation}:source`;
+            canvases.forEach(arm);
+            invalidate();
+            return;
+        }
+        if (canvases.some(canvas => canvas.dataset.satinGlassPresentedShow !== show))
+            return;
+        const start = (epoch) => {
+            if (stopped)
+                return;
+            // Motion admission is asynchronous. A control can register or lose its scene while the
+            // outer material acquires its moving clock. Recheck the entire show before exposing it;
+            // a replacement admission must acquire a fresh clock after every material is ready again.
+            const current = gated();
+            if (!current.length ||
+                current.some(canvas => canvas.dataset.satinGlassShow !== show ||
+                    canvas.dataset.satinGlassPresentedShow !== show)) {
+                preparingMotion = false;
+                check();
+                return;
+            }
+            stopped = true;
+            observer.disconnect();
+            deadline.cancel();
+            // A retained dismissal can outlive its opening. Never revive its entrance.
+            if (!canReveal())
+                return;
+            reveal();
+            trace('presentation-shown');
+            // Rebase a pending pause, using the renderer's admitted clock when it follows this run.
+            for (const animation of animations) {
+                animation.play();
+                animation.startTime = epoch ?? document.timeline.currentTime;
+            }
+            onReady();
+        };
+        if (revealStart) {
+            preparingMotion = true;
+            void revealStart().then(start);
+        }
+        else
+            start();
+    }
+    observer.observe(panel, {
+        subtree: true,
+        childList: true,
+        attributes: true,
+        attributeFilter: ['data-satin-glass-presented-show', 'data-satin-glass-source'],
+    });
+    invalidate();
+    return () => {
+        stopped = true;
+        observer.disconnect();
+        deadline.cancel();
+        reveal(true);
+        for (const canvas of gated()) {
+            // Retire this generation before a pending scene can acknowledge it.
+            if (canvas.dataset.satinGlassShow === show) {
+                delete canvas.dataset.satinGlassShow;
+                delete canvas.dataset.satinGlassPresented;
+                delete canvas.dataset.satinGlassPresentedShow;
+            }
+        }
+    };
+}
+/**
+ * The held nodes are inert, so the hold is invisible to focus and assistive technology as well as
+ * to the eye. An editor the opening tap focused stays focusable (keepFocusedEditor): the nodes
+ * beside its path are inert instead. A visible focus inside the panel (a dialog's initial focus
+ * after a keyboard arrival) is given back at reveal. An `inert` the app set is left alone. The
+ * attribute is not read by glass source measurement (mirrorExtents.ts), so it changes no capture.
+ */
+function holdInert(targets, panel) {
+    const document = panel.ownerDocument;
+    const active = document.activeElement;
+    const focused = active instanceof HTMLElement && panel.contains(active) ? active : null;
+    const editor = focused?.matches('input, textarea, [contenteditable]:not([contenteditable="false"])')
+        ? focused
+        : null;
+    // A UA :focus-visible match may still be quieted after touch. Save the painted indicator
+    // before inertness blurs the target and clears that suppression.
+    const refocusable = focused !== editor && visibleFocus(focused) ? focused : null;
+    const inerted = [];
+    const makeInert = (node) => {
+        if (node.hasAttribute('inert'))
+            return;
+        node.setAttribute('inert', '');
+        inerted.push(node);
+    };
+    for (const node of targets) {
+        if (!editor || !node.contains(editor)) {
+            makeInert(node);
+            continue;
+        }
+        for (let path = editor; path !== node; path = path.parentElement)
+            for (const sibling of path.parentElement.children)
+                if (sibling !== path)
+                    makeInert(sibling);
+    }
+    let released = false;
+    return (refocus) => {
+        if (released)
+            return;
+        released = true;
+        for (const node of inerted)
+            node.removeAttribute('inert');
+        const now = document.activeElement;
+        if (refocus && refocusable?.isConnected && (!now || now === document.body))
+            focusFromFramework(refocusable, { preventScroll: true });
+    };
+}
+function visibleFocus(element) {
+    try {
+        return !!element?.matches(':focus-visible') && !element.hasAttribute('data-satin-focus-quiet');
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Measured on the iPad: an alert focuses its text field in the opening tap, the hold then hides
+ * the panel, and WebKit ends editing at the next rendering update because a hidden element cannot
+ * keep focus (focusout 3-12 ms after focusin, no keyboard). The focused editor stays focusable
+ * and unpainted for the hold instead, so the keyboard the tap asked for still comes.
+ */
+function keepFocusedEditor(panel) {
+    const editor = panel.ownerDocument.activeElement;
+    if (!(editor instanceof HTMLElement) || !panel.contains(editor))
+        return () => { };
+    if (!editor.matches('input, textarea, [contenteditable]:not([contenteditable="false"])'))
+        return () => { };
+    const { visibility, opacity } = editor.style;
+    editor.style.visibility = 'visible';
+    editor.style.opacity = '0';
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        editor.style.visibility = visibility;
+        editor.style.opacity = opacity;
+    };
+}