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

package/dist/glass/lens/mirrorExtents.js

@@ -0,0 +1,264 @@
+import { changesMirrorSource } from './mirrorInvalidation.js';
+import { GLASS_SOURCE_DAMAGE_EVENT } from '../sourceDamage.js';
+/** Bounded mirror scans.
+ *
+ * A windowed capture (a long list) keeps only elements whose own box reaches its window, but a
+ * whole-tree scan still read one rectangle per element: on a 1,200-message thread (~22,000
+ * elements) that read was half of the main thread while a reply streamed. A subtree can be skipped
+ * when no element in it reaches the window. Whether that holds is known from the last scan: each
+ * element records how far its subtree's boxes reach beyond its own box ("extent", relative to the
+ * element, so it survives the element moving). A later scan reads the element's box once and
+ * skips the subtree when box plus extent misses the window.
+ *
+ * Skipping is a superset filter: every visited element is still judged by its own box exactly as
+ * before, so a bounded scan returns the same nodes as a whole-tree scan whenever the recorded
+ * extents are current. They are dropped when they may not be:
+ * - a DOM change inside the subtree (children, text, attributes) drops the extents of its target
+ *   and every ancestor;
+ * - an attribute change can restyle descendants (selectors, inheritance), so it also drops every
+ *   extent recorded inside its target before the change (a generation stamp);
+ * - a nested scroller's scroll, an image load, and a running animation or transition do the same
+ *   for their element;
+ * - an element whose own size changed, or a host whose width changed, is measured again.
+ *
+ * Layout that moves without any of these (`position: fixed` content inside a scroller, `:hover`
+ * styles) is not tracked; MIRROR_EXTENT_SLACK keeps small movements in the window. The audit hook
+ * (`globalThis.__SATIN_MIRROR_AUDIT__`) compares every bounded scan with a whole-tree scan. */
+/** Extra reach (points) a recorded extent is given before its subtree is skipped. */
+export const MIRROR_EXTENT_SLACK = 32;
+/** Framework flags no style reads (the presentation hold, its glass receipts and its motion flag):
+ * a whole measurement survives them (mirrorReuse.ts). `data-satin-source-ready` is a navigation
+ * readiness flag (NavigatorHost.tsx). */
+const UNSTYLED_FLAGS = new Set([
+    'data-satin-glass-hold',
+    'data-satin-glass-source',
+    'data-satin-glass-show',
+    'data-satin-glass-presented',
+    'data-satin-glass-presented-show',
+    'data-satin-presentation-moving',
+    'data-satin-source-ready',
+    'inert',
+]);
+/** Attribute records of a batch whose attribute ends the batch with the value it had before it: a
+ * value written again, or React's radio-group detach on every controlled input update (`name` set
+ * to '' and back). */
+export function rewrittenAttributes(records) {
+    const before = new Map();
+    for (const record of records) {
+        if (record.type !== 'attributes')
+            continue;
+        const values = before.get(record.target) ?? new Map();
+        before.set(record.target, values);
+        if (!values.has(record.attributeName))
+            values.set(record.attributeName, record.oldValue);
+    }
+    return new Set(records.filter(record => record.type === 'attributes' &&
+        before.get(record.target).get(record.attributeName) ===
+            record.target.getAttribute(record.attributeName)));
+}
+export const isUnstyledFlag = (record) => record.type === 'attributes' && UNSTYLED_FLAGS.has(record.attributeName ?? '');
+/** The terminal inset is non-inherited and owned by ScrollSurface. It can resize
+ * the scroller, but cannot restyle each message. The walk still checks each cached
+ * subtree's width and height before reusing its relative extent. Other style
+ * changes retain the conservative descendant invalidation. */
+function terminalInsetChanged(record, target) {
+    if (record.type !== 'attributes' ||
+        record.attributeName !== 'style' ||
+        !target.hasAttribute('data-satin-scroll') ||
+        record.oldValue === null)
+        return false;
+    const before = document.createElement('div').style;
+    const after = document.createElement('div').style;
+    before.cssText = record.oldValue;
+    after.cssText = target.getAttribute('style') ?? '';
+    before.removeProperty('--satin-scroll-inset-bottom');
+    after.removeProperty('--satin-scroll-inset-bottom');
+    return before.cssText === after.cssText;
+}
+class ExtentTracker {
+    extents = new WeakMap();
+    stamps = new WeakMap();
+    generation = 0;
+    /** Counts every change the subtree's mirror could show (mirrorRevision). */
+    revision = 0;
+    /** An animation or transition inside the host ran at the last sync. */
+    animating = false;
+    /** Diagnostics (the mirror audit): the last change counted. */
+    lastChange = '';
+    hostWidth = -1;
+    observer;
+    host;
+    constructor(host) {
+        this.host = host;
+        this.observer = new MutationObserver(records => this.apply(records));
+        this.observer.observe(host, {
+            childList: true,
+            subtree: true,
+            characterData: true,
+            attributes: true,
+            attributeOldValue: true,
+        });
+        const touched = (event) => {
+            if (!(event.target instanceof Element))
+                return;
+            if (diagnosing())
+                this.lastChange = `${event.type} on ${describe(event.target)}`;
+            if (event.target !== host)
+                this.drop(event.target, true);
+            // The host's own scroll offset is part of a reused measurement's inputs (mirrorReuse.ts).
+            else if (event.type !== 'scroll')
+                this.revision++;
+        };
+        host.addEventListener('scroll', touched, { capture: true, passive: true });
+        host.addEventListener('load', touched, true);
+        host.addEventListener(GLASS_SOURCE_DAMAGE_EVENT, touched, true);
+    }
+    /** Drop the extents of `element` and its ancestors up to the host; `stamp` also drops every
+     * extent recorded inside `element` until now. */
+    drop(element, stamp, revise = true) {
+        if (revise)
+            this.revision++;
+        if (stamp)
+            this.stamps.set(element, ++this.generation);
+        for (let node = element; node; node = node.parentElement) {
+            this.extents.delete(node);
+            if (node === this.host)
+                break;
+        }
+    }
+    apply(records) {
+        const rewritten = rewrittenAttributes(records);
+        for (const record of records) {
+            if (!changesMirrorSource(record))
+                continue;
+            // Reuse already treats these records as unchanged source. Preserve the
+            // matching subtree extents too: stamping an unchanged ancestor turns the
+            // next composer update into a full transcript walk.
+            if (isUnstyledFlag(record) || rewritten.has(record))
+                continue;
+            const target = record.target instanceof Element ? record.target : record.target.parentElement;
+            if (!target)
+                continue;
+            this.drop(target, record.type === 'attributes' && !terminalInsetChanged(record, target));
+            if (diagnosing())
+                this.lastChange =
+                    `${record.type}:${record.attributeName ?? ''} on ${describe(target)} ${record.oldValue ?? ''} -> ${record.attributeName ? (target.getAttribute(record.attributeName) ?? '') : ''}`.slice(0, 200);
+        }
+    }
+    /** Bring the extents up to date before a scan. */
+    sync(width) {
+        this.apply(this.observer.takeRecords());
+        if (width !== this.hostWidth) {
+            this.hostWidth = width;
+            this.clear();
+        }
+        this.animating = false;
+        if (typeof document.getAnimations !== 'function')
+            return;
+        for (const animation of document.getAnimations()) {
+            const target = animation.effect?.target;
+            if (target && target !== this.host && this.host.contains(target)) {
+                this.drop(target, true);
+                this.animating = true;
+                if (diagnosing())
+                    this.lastChange = `animation on ${describe(target)}`;
+            }
+        }
+    }
+    clear() {
+        this.revision++;
+        this.stamps.set(this.host, ++this.generation);
+        this.extents.delete(this.host);
+    }
+}
+const diagnosing = () => '__SATIN_MIRROR_AUDIT__' in globalThis;
+const describe = (element) => `${element.tagName.toLowerCase()}${element.className && typeof element.className === 'string' ? `.${element.className.trim().split(/\s+/).join('.')}` : ''}`.slice(0, 80);
+/** Bounded scans need DOM change records (a browser document). */
+export const canTrackMirrorExtents = () => typeof MutationObserver !== 'undefined';
+const trackers = new WeakMap();
+const trackerFor = (host) => {
+    let tracker = trackers.get(host);
+    if (!tracker) {
+        tracker = new ExtentTracker(host);
+        trackers.set(host, tracker);
+    }
+    return tracker;
+};
+/** A counter of every change `host`'s mirror could show since the last call: DOM changes in its
+ * subtree (unstyled framework flags aside), a nested scroll, an image load, source damage, a running
+ * animation or transition inside it, a new host width. Equal counters mean no such change; a
+ * reading taken while something inside animates can be outdated as soon as it ends. */
+export function mirrorRevision(host) {
+    const tracker = trackerFor(host);
+    tracker.sync(host.getBoundingClientRect().width);
+    return {
+        revision: tracker.revision,
+        animating: tracker.animating,
+        lastChange: tracker.lastChange,
+    };
+}
+/** Forget every recorded extent of `host` (text size or appearance changed). */
+export function dropMirrorExtents(host) {
+    trackers.get(host)?.clear();
+}
+/** Visit `host` and its descendants in document order, reading each visited element's box once.
+ * `visit` returns whether the element's own box reaches the window. A subtree whose recorded
+ * extent misses `[top, bottom]` (viewport points, the window's paint margin included) is skipped
+ * when `bounded`; otherwise every element is visited, and the extents are recorded either way. */
+export function scanMirrorTree(host, window, bounded, visit) {
+    const tracker = trackerFor(host);
+    const hostRect = host.getBoundingClientRect();
+    tracker.sync(hostRect.width);
+    const open = [];
+    const close = (entry) => {
+        const { element, rect } = entry;
+        if (rect.width && rect.height)
+            tracker.extents.set(element, {
+                above: rect.top - entry.top,
+                below: entry.bottom - rect.bottom,
+                width: rect.width,
+                height: rect.height,
+                generation: tracker.generation,
+            });
+        const parent = open.at(-1);
+        if (parent) {
+            parent.top = Math.min(parent.top, entry.top);
+            parent.bottom = Math.max(parent.bottom, entry.bottom);
+        }
+    };
+    const reach = (rect) => rect.width && rect.height
+        ? { top: rect.top, bottom: rect.bottom }
+        : { top: Infinity, bottom: -Infinity };
+    const walk = (element, rect) => {
+        const stamp = Math.max(open.at(-1)?.stamp ?? 0, tracker.stamps.get(element) ?? 0);
+        visit(element, rect);
+        const own = reach(rect);
+        open.push({ element, rect, stamp, ...own });
+    };
+    walk(host, hostRect);
+    for (let next = host.firstElementChild; open.length;) {
+        if (!next) {
+            const done = open.pop();
+            close(done);
+            next = open.length ? done.element.nextElementSibling : null;
+            continue;
+        }
+        const rect = next.getBoundingClientRect();
+        const known = bounded ? tracker.extents.get(next) : undefined;
+        const parentStamp = open.at(-1).stamp;
+        if (known &&
+            rect.width === known.width &&
+            rect.height === known.height &&
+            known.generation >= Math.max(parentStamp, tracker.stamps.get(next) ?? 0) &&
+            (rect.bottom + known.below + MIRROR_EXTENT_SLACK < window.top ||
+                rect.top - known.above - MIRROR_EXTENT_SLACK > window.bottom)) {
+            const parent = open.at(-1);
+            parent.top = Math.min(parent.top, rect.top - known.above);
+            parent.bottom = Math.max(parent.bottom, rect.bottom + known.below);
+            next = next.nextElementSibling;
+            continue;
+        }
+        walk(next, rect);
+        next = next.firstElementChild ?? (close(open.pop()), next.nextElementSibling);
+    }
+}

package/dist/glass/lens/mirrorInvalidation.d.ts

@@ -0,0 +1,6 @@
+/** Press feedback belongs to the live DOM, not to the retained scene image.
+ * Do not turn one pointer's pressed/return state into a complete GPU rebuild.
+ * Content, class/style, geometry and accessibility visibility changes still
+ * invalidate the image. Navigation separately owns source handoff.
+ */
+export declare function changesMirrorSource(record: Pick<MutationRecord, 'type' | 'attributeName'>): boolean;

package/dist/glass/lens/mirrorInvalidation.js

@@ -0,0 +1,10 @@
+/** Press feedback belongs to the live DOM, not to the retained scene image.
+ * Do not turn one pointer's pressed/return state into a complete GPU rebuild.
+ * Content, class/style, geometry and accessibility visibility changes still
+ * invalidate the image. Navigation separately owns source handoff.
+ */
+export function changesMirrorSource(record) {
+    return (record.type !== 'attributes' ||
+        (record.attributeName !== 'data-satin-press-state' &&
+            record.attributeName !== 'data-satin-press-transition'));
+}

package/dist/glass/lens/mirrorReuse.d.ts

@@ -0,0 +1,20 @@
+import type { MirrorCaptureRange, MirrorLayout } from './Scene.js';
+/** Everything outside the subtree's DOM that a measurement of `host` reads. */
+export declare function mirrorInputs(host: HTMLElement, capture: 'viewport' | 'plane', range: MirrorCaptureRange | undefined): string;
+/** The previous measurement of `host`, when nothing it reads has changed since. */
+export declare function reusedMirrorLayout(host: HTMLElement, inputs: string, revision: number, lastChange?: string): Readonly<{
+    contentHeight: number;
+    measuredAt: number;
+    nodes: readonly import("./Scene.js").MirrorNode[];
+    screen: import("./Scene.js").ScreenId;
+    width: number;
+}> | undefined;
+/** Keep a fresh measurement of `host`, taken at `inputs` and subtree `revision`. */
+export declare function keepMirrorLayout(host: HTMLElement, inputs: string, revision: number, layout: MirrorLayout): void;
+/** Measure `host`, or return its previous measurement when nothing it reads has changed. */
+export declare function measureOrReuse(host: HTMLElement, capture: 'viewport' | 'plane', range: MirrorCaptureRange | undefined, measure: () => MirrorLayout | undefined): {
+    layout: MirrorLayout | undefined;
+    reused: boolean;
+};
+/** Tests: forget every kept measurement. */
+export declare function forgetMirrorLayouts(): void;

package/dist/glass/lens/mirrorReuse.js

@@ -0,0 +1,166 @@
+import { imageCaptureRevision } from '../../image/resource.js';
+import { reportGlassError } from '../errors.js';
+import { isUnstyledFlag, mirrorRevision, rewrittenAttributes } from './mirrorExtents.js';
+const kept = new Map();
+let fontRevision = 0;
+let fontsWatched = false;
+function watchFonts() {
+    if (fontsWatched || typeof document === 'undefined' || !document.fonts)
+        return;
+    fontsWatched = true;
+    document.fonts.addEventListener('loadingdone', () => fontRevision++);
+}
+/** Style properties that move or fade a subtree as one, without changing any box inside it. */
+const MOTION = ['transform', 'translate', 'opacity', 'will-change'];
+let scratch;
+function withoutMotion(style) {
+    scratch ??= document.createElement('div');
+    scratch.setAttribute('style', style ?? '');
+    for (const property of MOTION)
+        scratch.style.removeProperty(property);
+    return scratch.style.cssText;
+}
+/** What changed on an ancestor in this batch of records, if anything a descendant could show. */
+function ancestorChanged(records) {
+    const rewritten = rewrittenAttributes(records);
+    for (const record of records) {
+        const change = !rewritten.has(record) && ancestorRecordChanged(record);
+        if (change)
+            return change;
+    }
+    return false;
+}
+function ancestorRecordChanged(record) {
+    if (isUnstyledFlag(record))
+        return false;
+    const target = record.target;
+    const now = target.getAttribute(record.attributeName);
+    if (record.attributeName === 'style' && withoutMotion(record.oldValue) === withoutMotion(now))
+        return false;
+    return `${target.tagName.toLowerCase()}[${record.attributeName}] ${record.oldValue ?? ''} -> ${now ?? ''}`.slice(0, 160);
+}
+const ancestorsOf = (host) => {
+    const chain = [];
+    for (let node = host.parentElement; node; node = node.parentElement)
+        chain.push(node);
+    return chain;
+};
+const focusIn = (host) => {
+    const active = host.ownerDocument.activeElement;
+    return active && host.contains(active) ? active : null;
+};
+/** Everything outside the subtree's DOM that a measurement of `host` reads. */
+export function mirrorInputs(host, capture, range) {
+    watchFonts();
+    const rect = host.getBoundingClientRect();
+    const media = (query) => matchMedia?.(query).matches ?? false;
+    return JSON.stringify([
+        capture,
+        range?.top,
+        range?.bottom,
+        range?.bands,
+        rect.width,
+        rect.height,
+        host.scrollTop,
+        host.scrollLeft,
+        host.scrollHeight,
+        innerWidth,
+        innerHeight,
+        devicePixelRatio,
+        media('(prefers-color-scheme: dark)'),
+        media('(prefers-contrast: more)'),
+        getComputedStyle(host).fontSize,
+        fontRevision,
+        imageCaptureRevision(),
+        document.styleSheets.length,
+    ]);
+}
+/** The previous measurement of `host`, when nothing it reads has changed since. */
+export function reusedMirrorLayout(host, inputs, revision, lastChange = '') {
+    const entry = kept.get(host);
+    if (!entry)
+        return;
+    entry.changed ||= ancestorChanged(entry.watch.takeRecords());
+    const ancestors = ancestorsOf(host);
+    const miss = entry.changed
+        ? `ancestor ${entry.changed}`
+        : entry.inputs !== inputs
+            ? `inputs ${entry.inputs} -> ${inputs}`
+            : entry.revision !== revision
+                ? `subtree ${lastChange}`
+                : entry.active !== focusIn(host)
+                    ? 'focus'
+                    : ancestors.length !== entry.ancestors.length ||
+                        ancestors.some((node, index) => node !== entry.ancestors[index])
+                        ? 'moved'
+                        : undefined;
+    if (!miss)
+        return entry.layout;
+    const hook = auditHook();
+    if (hook)
+        (hook.misses ??= []).push(`${host.dataset.satinScroll ?? host.tagName}: ${miss}`);
+}
+/** Keep a fresh measurement of `host`, taken at `inputs` and subtree `revision`. */
+export function keepMirrorLayout(host, inputs, revision, layout) {
+    for (const [other, entry] of kept)
+        if (other === host || !other.isConnected) {
+            entry.watch.disconnect();
+            kept.delete(other);
+        }
+    const ancestors = ancestorsOf(host);
+    const entry = {
+        inputs,
+        revision,
+        active: focusIn(host),
+        ancestors,
+        layout,
+        changed: false,
+        watch: new MutationObserver(records => {
+            entry.changed ||= ancestorChanged(records);
+        }),
+    };
+    for (const node of ancestors)
+        entry.watch.observe(node, { attributes: true, attributeOldValue: true });
+    kept.set(host, entry);
+}
+/** Measure `host`, or return its previous measurement when nothing it reads has changed. */
+export function measureOrReuse(host, capture, range, measure) {
+    const { revision, animating, lastChange } = mirrorRevision(host);
+    const inputs = mirrorInputs(host, capture, range);
+    const previous = reusedMirrorLayout(host, inputs, revision, lastChange);
+    if (previous) {
+        audit(host, previous, measure);
+        return { layout: previous, reused: true };
+    }
+    const layout = measure();
+    // A reading mid-animation is not kept: the animation can end without any other change.
+    if (layout && !animating)
+        keepMirrorLayout(host, inputs, revision, layout);
+    else
+        forgetMirrorLayout(host);
+    return { layout, reused: false };
+}
+const auditHook = () => globalThis.__SATIN_MIRROR_AUDIT__;
+const content = (layout) => JSON.stringify([layout.width, layout.contentHeight, layout.nodes]);
+function audit(host, previous, measure) {
+    const hook = auditHook();
+    if (!hook)
+        return;
+    hook.reuses = (hook.reuses ?? 0) + 1;
+    const fresh = measure();
+    if (!fresh || content(fresh) === content(previous))
+        return;
+    const detail = `${host.dataset.satinScroll ?? host.tagName}: reused ${previous.nodes.length} nodes, fresh ${fresh.nodes.length}`;
+    hook.mismatches.push(detail);
+    reportGlassError('presentation', Error(detail), 'backdrop capture', 'stale-mirror-reuse');
+}
+function forgetMirrorLayout(host) {
+    kept.get(host)?.watch.disconnect();
+    kept.delete(host);
+}
+/** Tests: forget every kept measurement. */
+export function forgetMirrorLayouts() {
+    for (const entry of kept.values())
+        entry.watch.disconnect();
+    kept.clear();
+}

package/dist/glass/lens/motion.d.ts

@@ -0,0 +1,62 @@
+export type ScriptedScrollMode = 'constant' | 'flick';
+export type ScriptedMotionMode = ScriptedScrollMode | 'drag-scripted';
+export type MotionSample = Readonly<{
+    elapsedMs: number;
+    offsetCssPx: number;
+    progress?: number;
+    timestampMs: number;
+}>;
+export type MotionRun = Readonly<{
+    completed: boolean;
+    durationMs: number;
+    endedAtMs: number;
+    mode: ScriptedMotionMode;
+    samples: readonly MotionSample[];
+    startedAtMs: number;
+}>;
+export declare const MOTION_SPEC: {
+    delayMs: number;
+    durationMs: number;
+    settleMs: number;
+    flickTravelPt: number;
+    flickDecay: number;
+    constantVelocityPtPerSecond: number;
+    dragDurationMs: number;
+    dragCapsuleStart: number[];
+    dragCapsuleEnd: number[];
+    dragCircleStart: number[];
+    dragCircleEnd: number[];
+};
+export declare const NATIVE_WIDGET_Y_REGISTRATION_PX = 14;
+export declare function scriptedScrollOffset(mode: ScriptedScrollMode, elapsedMs: number): number;
+export declare function scriptedDragProgress(elapsedMs: number): number;
+export declare function scriptedDragFrames(progress: number, physicalTopInset: number): {
+    capsule: {
+        height: number;
+        width: number;
+        x: number;
+        y: number;
+    };
+    circle: {
+        height: number;
+        width: number;
+        x: number;
+        y: number;
+    };
+};
+export declare function runScriptedScroll(mode: ScriptedScrollMode, writeOffset: (offset: number) => void, signal?: AbortSignal): Promise<Readonly<{
+    completed: boolean;
+    durationMs: number;
+    endedAtMs: number;
+    mode: ScriptedMotionMode;
+    samples: readonly MotionSample[];
+    startedAtMs: number;
+}>>;
+export declare function runScriptedDrag(writeProgress: (progress: number) => void, signal?: AbortSignal): Promise<Readonly<{
+    completed: boolean;
+    durationMs: number;
+    endedAtMs: number;
+    mode: ScriptedMotionMode;
+    samples: readonly MotionSample[];
+    startedAtMs: number;
+}>>;

package/dist/glass/lens/motion.js

@@ -0,0 +1,93 @@
+import backgroundDescription from './backgrounds.json';
+export const MOTION_SPEC = backgroundDescription.motion;
+export const NATIVE_WIDGET_Y_REGISTRATION_PX = 14;
+const clamp = (value, low, high) => Math.max(low, Math.min(high, value));
+export function scriptedScrollOffset(mode, elapsedMs) {
+    const activeMs = clamp(elapsedMs - MOTION_SPEC.delayMs, 0, MOTION_SPEC.durationMs);
+    if (mode === 'constant')
+        return (activeMs / 1000) * MOTION_SPEC.constantVelocityPtPerSecond;
+    const progress = activeMs / MOTION_SPEC.durationMs;
+    const numerator = 1 - Math.exp(-MOTION_SPEC.flickDecay * progress);
+    const denominator = 1 - Math.exp(-MOTION_SPEC.flickDecay);
+    return (MOTION_SPEC.flickTravelPt * numerator) / denominator;
+}
+export function scriptedDragProgress(elapsedMs) {
+    const activeMs = clamp(elapsedMs - MOTION_SPEC.delayMs, 0, MOTION_SPEC.dragDurationMs);
+    const linear = activeMs / MOTION_SPEC.dragDurationMs;
+    return linear * linear * (3 - 2 * linear);
+}
+export function scriptedDragFrames(progress, physicalTopInset) {
+    const clamped = clamp(progress, 0, 1);
+    const interpolate = (start, end) => start.map((value, index) => value + (end[index] - value) * clamped);
+    const capsuleCenter = interpolate(MOTION_SPEC.dragCapsuleStart, MOTION_SPEC.dragCapsuleEnd);
+    const circleCenter = interpolate(MOTION_SPEC.dragCircleStart, MOTION_SPEC.dragCircleEnd);
+    const layoutY = (physicalY) => physicalY + NATIVE_WIDGET_Y_REGISTRATION_PX - physicalTopInset;
+    return {
+        capsule: {
+            height: 120,
+            width: 300,
+            x: capsuleCenter[0] - 150,
+            y: layoutY(capsuleCenter[1]) - 60,
+        },
+        circle: {
+            height: 160,
+            width: 160,
+            x: circleCenter[0] - 80,
+            y: layoutY(circleCenter[1]) - 80,
+        },
+    };
+}
+export function runScriptedScroll(mode, writeOffset, signal) {
+    const startedAtMs = performance.now();
+    const samples = [];
+    const totalMs = MOTION_SPEC.delayMs + MOTION_SPEC.durationMs + MOTION_SPEC.settleMs;
+    writeOffset(0);
+    return new Promise(resolve => {
+        const tick = (timestampMs) => {
+            const elapsedMs = timestampMs - startedAtMs;
+            const offsetCssPx = scriptedScrollOffset(mode, elapsedMs);
+            writeOffset(offsetCssPx);
+            samples.push({ elapsedMs, offsetCssPx, timestampMs });
+            if (!signal?.aborted && elapsedMs < totalMs) {
+                requestAnimationFrame(tick);
+                return;
+            }
+            resolve({
+                completed: !signal?.aborted,
+                durationMs: elapsedMs,
+                endedAtMs: timestampMs,
+                mode,
+                samples,
+                startedAtMs,
+            });
+        };
+        requestAnimationFrame(tick);
+    });
+}
+export function runScriptedDrag(writeProgress, signal) {
+    const startedAtMs = performance.now();
+    const samples = [];
+    const totalMs = MOTION_SPEC.delayMs + MOTION_SPEC.dragDurationMs + MOTION_SPEC.settleMs;
+    writeProgress(0);
+    return new Promise(resolve => {
+        const tick = (timestampMs) => {
+            const elapsedMs = timestampMs - startedAtMs;
+            const progress = scriptedDragProgress(elapsedMs);
+            writeProgress(progress);
+            samples.push({ elapsedMs, offsetCssPx: 0, progress, timestampMs });
+            if (!signal?.aborted && elapsedMs < totalMs) {
+                requestAnimationFrame(tick);
+                return;
+            }
+            resolve({
+                completed: !signal?.aborted,
+                durationMs: elapsedMs,
+                endedAtMs: timestampMs,
+                mode: 'drag-scripted',
+                samples,
+                startedAtMs,
+            });
+        };
+        requestAnimationFrame(tick);
+    });
+}

package/dist/glass/lens/recordedMotion.d.ts

@@ -0,0 +1,6 @@
+import type { MenuMorphDirection } from './menuMorphMotion.js';
+/** Shape-preserving interpolation with a C1 correction for an interrupted run. */
+export declare function recordedMotion<K extends string>(axes: readonly K[], fit: Record<MenuMorphDirection, number[][]>): (direction: MenuMorphDirection, ms: number, from?: Record<K, number>, velocity?: Record<K, number>) => {
+    pose: Record<K, number>;
+    velocity: Record<K, number>;
+};

package/dist/glass/lens/recordedMotion.js

@@ -0,0 +1,44 @@
+/** Shape-preserving interpolation with a C1 correction for an interrupted run. */
+export function recordedMotion(axes, fit) {
+    const zero = () => Object.fromEntries(axes.map(k => [k, 0]));
+    const value = (row) => Object.fromEntries(axes.map((k, i) => [k, row[i + 1]]));
+    const slopes = (knots, column) => {
+        const h = knots.slice(1).map((k, i) => (k[0] - knots[i][0]) / 1000), d = h.map((v, i) => (knots[i + 1][column] - knots[i][column]) / v);
+        return knots.map((_, i) => {
+            if (i === 0 || i === knots.length - 1 || d[i - 1] * d[i] <= 0)
+                return 0;
+            const a = 2 * h[i] + h[i - 1], b = h[i] + 2 * h[i - 1];
+            return (a + b) / (a / d[i - 1] + b / d[i]);
+        });
+    };
+    const tangents = {
+        open: axes.map((_, i) => slopes(fit.open, i + 1)),
+        close: axes.map((_, i) => slopes(fit.close, i + 1)),
+    };
+    return (direction, ms, from = value(fit[direction][0]), velocity = zero()) => {
+        const knots = fit[direction], duration = knots.at(-1)[0] / 1000;
+        if (ms >= duration * 1000)
+            return { pose: value(knots.at(-1)), velocity: zero() };
+        const elapsed = Math.max(0, ms), right = Math.max(1, knots.findIndex(k => k[0] >= elapsed)), a = knots[right - 1], b = knots[right];
+        const span = (b[0] - a[0]) / 1000, t = (elapsed - a[0]) / (b[0] - a[0]), t2 = t * t, t3 = t2 * t, u = elapsed / (duration * 1000), pose = zero(), speed = zero();
+        axes.forEach((axis, index) => {
+            const v0 = a[index + 1], v1 = b[index + 1], m0 = tangents[direction][index][right - 1], m1 = tangents[direction][index][right], correction = from[axis] - knots[0][index + 1];
+            pose[axis] =
+                (2 * t3 - 3 * t2 + 1) * v0 +
+                    (t3 - 2 * t2 + t) * span * m0 +
+                    (-2 * t3 + 3 * t2) * v1 +
+                    (t3 - t2) * span * m1 +
+                    correction * (1 - 3 * u * u + 2 * u * u * u) +
+                    velocity[axis] * duration * u * (1 - u) * (1 - u);
+            speed[axis] =
+                ((6 * t2 - 6 * t) * v0 +
+                    (3 * t2 - 4 * t + 1) * span * m0 +
+                    (-6 * t2 + 6 * t) * v1 +
+                    (3 * t2 - 2 * t) * span * m1) /
+                    span +
+                    (correction * (-6 * u + 6 * u * u)) / duration +
+                    velocity[axis] * (1 - 4 * u + 3 * u * u);
+        });
+        return { pose, velocity: speed };
+    };
+}