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

package/dist/glass/rendererContract.d.ts

@@ -0,0 +1,205 @@
+import type { KeyboardTranslation } from '../keyboard/translation.js';
+import type { GlassShapeTrack } from './shapeTrack.js';
+import type { GlassMaterial, GlassRegion, GlassSceneSnapshot } from './regions.js';
+import type { AccessoryViewportTrack } from './webgpu/accessoryTrack.js';
+/** 12v owns execution. These messages never import the compatibility renderer. */
+export type GlassCanvas = OffscreenCanvas | HTMLCanvasElement;
+/** Canvas-local CSS points to the live backdrop plane coordinate space. */
+export type GlassViewport = Readonly<{
+    x: number;
+    y: number;
+    scaleX: number;
+    scaleY: number;
+}>;
+export declare const GLASS_RENDERER_PROTOCOL: 1;
+export type GlassInteraction = Readonly<{
+    regionId: string;
+    phase: 'rest' | 'pressed' | 'dragging' | 'releasing';
+    /** performance.timeOrigin + performance.now(), shared by document and worker. */
+    epoch: number;
+    /** Region-local CSS pixels; input samples do not resize foreground glyphs. */
+    contact?: Readonly<{
+        x: number;
+        y: number;
+    }>;
+}>;
+export type GlassPresenter = Readonly<{
+    id: string;
+    role?: 'material' | 'lift';
+    layerId: string;
+    /** One canvas can cover a layer, a container union, or an isolated DOM stacking slot. */
+    regionIds: readonly string[];
+    origin: Readonly<{
+        x: number;
+        y: number;
+    }>;
+    /** Container layout origin. Common translation moves the field without changing its local shapes. */
+    fieldOrigin?: Readonly<{
+        x: number;
+        y: number;
+    }>;
+    width: number;
+    height: number;
+    resolution: number;
+}>;
+export type GlassMaterialResponse = Readonly<{
+    rest: GlassMaterial;
+    lift: Readonly<{
+        variant: 'clear';
+        /** Sample the transmitted source, never the frosted rest output. */
+        source: 'transmitted-backdrop';
+        blurSigma: 0;
+        tintAlpha: 0;
+        rimProfile: 'measured-reference-native';
+        refractForeground: true;
+    }>;
+    liftMix: number;
+}>;
+/** A zero mix MUST take the original reference rest path without changed arithmetic. */
+export declare function glassMaterialResponse(material: GlassMaterial, liftMix: number): GlassMaterialResponse;
+export type GlassSource = Readonly<{
+    id: string;
+    revision: number;
+    layerId: string;
+    regionId?: string;
+    role: 'transmitted-backdrop' | 'rest-underlay' | 'foreground';
+    origin: Readonly<{
+        x: number;
+        y: number;
+    }>;
+    width: number;
+    height: number;
+    resolution: number;
+}>;
+export type GlassRendererRequest = GlassRendererOperation | {
+    type: 'transaction';
+    requests: readonly GlassRendererOperation[];
+};
+export type GlassRendererOperation = {
+    type: 'initialize';
+    protocol: typeof GLASS_RENDERER_PROTOCOL;
+    appearance: 'light' | 'dark';
+    reducedMotion: boolean;
+} | {
+    type: 'update-presenter';
+    presenter: GlassPresenter;
+} | {
+    type: 'presenter-viewport';
+    id: string;
+    viewport: GlassViewport;
+    keyboard?: KeyboardTranslation;
+}
+/** A region's glass changes size inside its still frame (shapeTrack.ts). Sent as soon as the
+ * run starts, ahead of the next scene, so the glass moves from its first frame. */
+ | {
+    type: 'region-shape-track';
+    regionId: string;
+    track: GlassShapeTrack | undefined;
+}
+/** A new trajectory inside the same admitted presentation source envelope. */
+ | {
+    type: 'region-presentation-track';
+    regionId: string;
+    contentEpoch: number;
+    track: AccessoryViewportTrack;
+} | {
+    type: 'attach-presenter';
+    presenter: GlassPresenter;
+    canvas: GlassCanvas;
+} | {
+    type: 'detach-presenter';
+    id: string;
+} | {
+    type: 'scene';
+    snapshot: GlassSceneSnapshot;
+} | {
+    type: 'source';
+    source: GlassSource;
+    bitmap: ImageBitmap;
+} | {
+    type: 'release-source';
+    id: string;
+} | {
+    type: 'interaction';
+    interaction: GlassInteraction;
+} | {
+    type: 'morph';
+    epoch: number;
+    namespace: string;
+    id: string;
+    from: GlassRegion;
+    to: GlassRegion;
+} | {
+    type: 'appearance';
+    value: 'light' | 'dark';
+    reducedMotion: boolean;
+} | {
+    type: 'visibility';
+    visible: boolean;
+} | {
+    type: 'purge';
+} | {
+    type: 'restore';
+} | {
+    type: 'diagnostics';
+} | {
+    type: 'dispose';
+};
+export type GlassRendererDiagnostics = Readonly<{
+    backend: 'webgpu';
+    devices: number;
+    contexts: number;
+    presenters: number;
+    regions: number;
+    scheduledFrames: number;
+    draws: number;
+    uploads: number;
+    copies: number;
+    allocatedBytes: number;
+    cpuMs: number;
+    gpuMs: number | null;
+}>;
+/** Worker failures must retain raw messages and device-loss reasons. */
+export type GlassRendererReply = {
+    type: 'error';
+    error: import('./errors.js').GlassError;
+} | {
+    type: 'diagnostics';
+    diagnostics: GlassRendererDiagnostics;
+} | {
+    type: 'ready';
+};
+/** Submitted emerge geometry, in the region's border-box coordinates. */
+export type GlassRegionEvent = {
+    type: 'accessory-ink';
+    regionId: string;
+    epoch: number;
+} | {
+    type: 'presentation-gate';
+    allowed: boolean;
+} | {
+    type: 'field-motion';
+    regionId: string;
+    start: number;
+    duration: number;
+    velocityX?: number;
+    velocityY?: number;
+    velocityScaleX?: number;
+    velocityScaleY?: number;
+    offsetX: number;
+    offsetY: number;
+    scaleX: number;
+    scaleY: number;
+} | {
+    type: 'emerge-settled';
+    regionId: string;
+    generation?: number;
+}
+/** A menu's rows moved between its glass ink and its live DOM: the glass draws them settled
+ * (`open-settled`: show the DOM rows) or has taken them into the close (`close-started`). */
+ | {
+    type: 'emerge-ink';
+    regionId: string;
+    generation?: number;
+    phase: 'open-settled' | 'close-started';
+};

package/dist/glass/rendererContract.js

@@ -0,0 +1,18 @@
+export const GLASS_RENDERER_PROTOCOL = 1;
+/** A zero mix MUST take the original reference rest path without changed arithmetic. */
+export function glassMaterialResponse(material, liftMix) {
+    if (!Number.isFinite(liftMix) || liftMix < 0 || liftMix > 1)
+        throw new Error('Glass liftMix must be in 0...1.');
+    return {
+        rest: material,
+        lift: {
+            variant: 'clear',
+            source: 'transmitted-backdrop',
+            blurSigma: 0,
+            tintAlpha: 0,
+            rimProfile: 'measured-reference-native',
+            refractForeground: true,
+        },
+        liftMix: material.interactive ? liftMix : 0,
+    };
+}

package/dist/glass/shapeTrack.d.ts

@@ -0,0 +1,53 @@
+import type { SurfaceRenderSpec } from './renderSpecs.js';
+/**
+ * Glass that changes size without moving its canvas.
+ *
+ * A region's canvas fills its element. When the element's layout grows or shrinks, the canvas box
+ * changes in that same frame, but the worker only draws the new size a frame or more later. Until
+ * then the compositor stretches the old picture into the new box, so the page under the glass
+ * seems to slide and smear while nothing behind it moves (owner, Oct 13: "it looks like content is
+ * moving underneath as the menu grows").
+ *
+ * Native Liquid Glass keeps the content behind it in place: only the edge moves. A shape track
+ * does the same. The element keeps one layout box for the whole run (the envelope of every frame
+ * the glass passes through), so its canvas never resizes or moves and samples the page where it
+ * really is. The worker draws the glass at the track's frame for each frame's presentation time,
+ * and the page clips the element's content to the same frame from the same samples: one time
+ * function for both, as in the accessory morph (`webgpu/accessoryTrack.ts`, `held`).
+ */
+export type GlassShapeTrack = Readonly<{
+    /** When the run starts, on the normalized clock (`performance.timeOrigin + performance.now()`,
+     * the same instant in the page and the worker). `Number.MAX_VALUE` holds the first frame. */
+    epoch: number;
+    /** Milliseconds from the first frame to the last. */
+    duration: number;
+    /** The glass's frame at evenly spaced instants across the run, relative to the region's
+     * laid-out box (the envelope). The last frame holds after the run. */
+    frames: readonly ShapeFrame[];
+    /** Optional corner radii at the same instants as frames. Absent for existing submenu tracks. */
+    radii?: readonly number[];
+    /** Optional independent bottom corners, sampled at the same instants as frames. */
+    bottomRadii?: readonly number[];
+}>;
+export type ShapeFrame = Readonly<{
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}>;
+/** The normalized clock shared by the page and the glass worker. */
+export declare function shapeTrackClock(): number;
+/** The glass frame at `at`, interpolated between the track's samples. */
+export declare function shapeTrackFrame(track: GlassShapeTrack, at: number): ShapeFrame;
+/** Corners and geometry use one clock. Existing tracks keep their shape's radius rule. */
+export declare function shapeTrackRadius(track: GlassShapeTrack, at: number, fallback: number, edge?: 'top' | 'bottom'): number;
+/** Whether the track still moves at `at` (a held first frame does not). */
+export declare function shapeTrackRunning(track: GlassShapeTrack, at: number): boolean;
+/** The smallest box that holds every frame of the track (relative to the same origin). */
+export declare function shapeTrackEnvelope(frames: readonly ShapeFrame[]): ShapeFrame;
+/**
+ * A region's render spec with its glass drawn at the track's frame for `at`. The spec's frame and
+ * sampling rectangle stay the envelope's, so its canvas and textures keep their size: only the
+ * shape inside them changes. Corners keep the region's radius, capped by the smaller frame.
+ */
+export declare function trackedShapeSpec(spec: SurfaceRenderSpec, track: GlassShapeTrack, at: number, cornerRadius: (width: number, height: number) => number): SurfaceRenderSpec;

package/dist/glass/shapeTrack.js

@@ -0,0 +1,74 @@
+/** The normalized clock shared by the page and the glass worker. */
+export function shapeTrackClock() {
+    return performance.timeOrigin + performance.now();
+}
+/** The glass frame at `at`, interpolated between the track's samples. */
+export function shapeTrackFrame(track, at) {
+    const frames = track.frames;
+    if (frames.length === 0)
+        throw Error('A glass shape track needs at least one frame');
+    const progress = track.duration > 0 ? Math.max(0, Math.min(1, (at - track.epoch) / track.duration)) : 1;
+    const position = progress * (frames.length - 1);
+    const index = Math.floor(position);
+    const from = frames[index];
+    const to = frames[Math.min(index + 1, frames.length - 1)];
+    const mix = position - index;
+    return {
+        x: from.x + (to.x - from.x) * mix,
+        y: from.y + (to.y - from.y) * mix,
+        width: from.width + (to.width - from.width) * mix,
+        height: from.height + (to.height - from.height) * mix,
+    };
+}
+/** Corners and geometry use one clock. Existing tracks keep their shape's radius rule. */
+export function shapeTrackRadius(track, at, fallback, edge = 'top') {
+    const radii = edge === 'bottom' ? track.bottomRadii : track.radii;
+    if (!radii?.length)
+        return fallback;
+    const progress = track.duration > 0 ? Math.max(0, Math.min(1, (at - track.epoch) / track.duration)) : 1;
+    const position = progress * (radii.length - 1);
+    const index = Math.floor(position);
+    const from = radii[index];
+    return from + (radii[Math.min(index + 1, radii.length - 1)] - from) * (position - index);
+}
+/** Whether the track still moves at `at` (a held first frame does not). */
+export function shapeTrackRunning(track, at) {
+    return track.epoch !== Number.MAX_VALUE && at < track.epoch + track.duration;
+}
+/** The smallest box that holds every frame of the track (relative to the same origin). */
+export function shapeTrackEnvelope(frames) {
+    const left = Math.min(...frames.map(frame => frame.x));
+    const top = Math.min(...frames.map(frame => frame.y));
+    const right = Math.max(...frames.map(frame => frame.x + frame.width));
+    const bottom = Math.max(...frames.map(frame => frame.y + frame.height));
+    return { x: left, y: top, width: right - left, height: bottom - top };
+}
+/**
+ * A region's render spec with its glass drawn at the track's frame for `at`. The spec's frame and
+ * sampling rectangle stay the envelope's, so its canvas and textures keep their size: only the
+ * shape inside them changes. Corners keep the region's radius, capped by the smaller frame.
+ */
+export function trackedShapeSpec(spec, track, at, cornerRadius) {
+    const frame = shapeTrackFrame(track, at);
+    const radius = Math.max(0, Math.min(frame.width / 2, frame.height / 2, shapeTrackRadius(track, at, cornerRadius(frame.width, frame.height))));
+    const first = spec.shape.first;
+    const bottomRadius = first.bottomRadius === undefined && !track.bottomRadii?.length
+        ? undefined
+        : Math.max(0, Math.min(shapeTrackRadius(track, at, first.bottomRadius ?? radius, 'bottom'), frame.width / 2, frame.height / 2));
+    return {
+        ...spec,
+        radius,
+        shape: {
+            ...spec.shape,
+            first: {
+                ...first,
+                centerX: frame.x + frame.width / 2,
+                centerY: frame.y + frame.height / 2,
+                halfWidth: frame.width / 2,
+                halfHeight: frame.height / 2,
+                radius,
+                ...(bottomRadius === undefined ? {} : { bottomRadius }),
+            },
+        },
+    };
+}

package/dist/glass/shapeTrackRegistry.d.ts

@@ -0,0 +1,40 @@
+import { type GlassShapeTrack } from './shapeTrack.js';
+/** The shape track a glass element is running, if any (read by the region bridge). */
+export declare function glassShapeTrack(element: Element): Readonly<{
+    epoch: number;
+    duration: number;
+    frames: readonly import("./shapeTrack.js").ShapeFrame[];
+    radii?: readonly number[];
+    bottomRadii?: readonly number[];
+}> | undefined;
+/** The visible aperture, not the canvas envelope, in viewport coordinates. Framework motion
+ * uses axis-aligned translation/scale. Layout dimensions undo that ancestor scale exactly once.
+ * Callers doing a multi-part handoff pass one timestamp for every sample. */
+export declare function glassAperture(element: HTMLElement, at?: number): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    radius: number;
+};
+/** The same aperture in a renderer's resting coordinate plane. */
+export declare function glassApertureInFrame(element: HTMLElement, box: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, at?: number): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    radius: number;
+};
+/**
+ * Run (or, with `undefined`, end) a shape track on a glass element. The caller keeps the
+ * element's layout at the track's envelope while it runs. The glass worker receives the track
+ * straight away, not with the next scene: a scene can wait behind captures for several frames.
+ */
+export declare function setGlassShapeTrack(element: Element, track: GlassShapeTrack | undefined): void;
+/** Tells the glass regions that an element's shape track changed (the bridge sends it at once). */
+export declare const GLASS_SHAPE_TRACK_EVENT = "satin-glass-shape-track";

package/dist/glass/shapeTrackRegistry.js

@@ -0,0 +1,49 @@
+import { shapeTrackClock, shapeTrackFrame, shapeTrackRadius, } from './shapeTrack.js';
+/** Page side of shape tracks (shapeTrack.ts): which glass element runs which track. The glass
+ * worker never imports this module; it receives tracks in requests and scene snapshots. */
+const tracks = new WeakMap();
+/** The shape track a glass element is running, if any (read by the region bridge). */
+export function glassShapeTrack(element) {
+    return tracks.get(element);
+}
+/** The visible aperture, not the canvas envelope, in viewport coordinates. Framework motion
+ * uses axis-aligned translation/scale. Layout dimensions undo that ancestor scale exactly once.
+ * Callers doing a multi-part handoff pass one timestamp for every sample. */
+export function glassAperture(element, at = shapeTrackClock()) {
+    return glassApertureInFrame(element, element.getBoundingClientRect(), at);
+}
+/** The same aperture in a renderer's resting coordinate plane. */
+export function glassApertureInFrame(element, box, at = shapeTrackClock()) {
+    const style = getComputedStyle(element);
+    const radius = parseFloat(style.borderTopLeftRadius) || 0;
+    const track = tracks.get(element);
+    if (!track)
+        return { x: box.x, y: box.y, width: box.width, height: box.height, radius };
+    const width = parseFloat(style.width) || element.offsetWidth;
+    const height = parseFloat(style.height) || element.offsetHeight;
+    const scaleX = width > 0 ? box.width / width : 1;
+    const scaleY = height > 0 ? box.height / height : 1;
+    const frame = shapeTrackFrame(track, at);
+    return {
+        x: box.x + frame.x * scaleX,
+        y: box.y + frame.y * scaleY,
+        width: frame.width * scaleX,
+        height: frame.height * scaleY,
+        radius: Math.min(frame.width / 2, frame.height / 2, shapeTrackRadius(track, at, radius)) *
+            Math.min(scaleX, scaleY),
+    };
+}
+/**
+ * Run (or, with `undefined`, end) a shape track on a glass element. The caller keeps the
+ * element's layout at the track's envelope while it runs. The glass worker receives the track
+ * straight away, not with the next scene: a scene can wait behind captures for several frames.
+ */
+export function setGlassShapeTrack(element, track) {
+    if (track)
+        tracks.set(element, track);
+    else
+        tracks.delete(element);
+    window.dispatchEvent(new CustomEvent(GLASS_SHAPE_TRACK_EVENT, { detail: element }));
+}
+/** Tells the glass regions that an element's shape track changed (the bridge sends it at once). */
+export const GLASS_SHAPE_TRACK_EVENT = 'satin-glass-shape-track';

package/dist/glass/sourceDamage.d.ts

@@ -0,0 +1,6 @@
+/** Mutations inside framework chrome (controls, bars) never damage the glass source: their
+ * feedback is presentation (webgpu/production.ts). A control whose painted look changed, such as a
+ * Toggle track's colour, asks for that one recapture so glass sampling it does not keep the old
+ * paint. Dispatch after the change has finished painting, not per animation frame. */
+export declare const GLASS_SOURCE_DAMAGE_EVENT = "satin-glass-source-damage";
+export declare function requestGlassSourceDamage(element: Element): void;

package/dist/glass/sourceDamage.js

@@ -0,0 +1,8 @@
+/** Mutations inside framework chrome (controls, bars) never damage the glass source: their
+ * feedback is presentation (webgpu/production.ts). A control whose painted look changed, such as a
+ * Toggle track's colour, asks for that one recapture so glass sampling it does not keep the old
+ * paint. Dispatch after the change has finished painting, not per animation frame. */
+export const GLASS_SOURCE_DAMAGE_EVENT = 'satin-glass-source-damage';
+export function requestGlassSourceDamage(element) {
+    element.dispatchEvent(new Event(GLASS_SOURCE_DAMAGE_EVENT, { bubbles: true }));
+}

package/dist/glass/submenuMotion.d.ts

@@ -0,0 +1,205 @@
+import { type SpringParameters } from '../motion/springTrack.js';
+/**
+ * Nested menus, measured from stock SwiftUI on iOS 27.0 (submenus/SPEC.md).
+ *
+ * iPhone stacks each submenu over its parent: the parent shrinks to 0.97 about its top edge and
+ * its rows dim to half ink, and the child grows out of the row that opened it into a full-width
+ * platter whose title row sits 12 pt above where that row now is. iPad opens a cascade beside the
+ * parent instead: the child overlaps the parent's edge by 12 pt and its first row lines up with
+ * the row that opened it, while the parent stays as it was.
+ *
+ * Springs are fitted per track from a 60 Hz presentation-layer trace of the native Simulator
+ * (submenus-impl/fit-open-child.json and fit-back.json; RMS residuals under 0.2 pt / 0.004 ink).
+ * Forward and back are fitted separately: the child opens slightly underdamped (zeta 0.85) and
+ * collapses critically damped (zeta 1.0). The iPad cascade's motion is unmeasured; it uses the
+ * same child springs until an iPad trace exists.
+ *
+ * Only the glass changes size. The same trace shows the child's rows keeping their full size
+ * throughout: on the way back the glass shrinks around the title row while the rows drift 3.6 pt,
+ * so the title lands exactly on the row that opened it, and the title's chevron turns from down to
+ * forward on its own spring (measured Oct 13: the content and chevron fits).
+ */
+export declare const SUBMENU_GEOMETRY: {
+    /** Each ancestor level below the top submenu shrinks by this much more (0.97, 0.94, ...). */
+    parentScaleStep: number;
+    /** Ink of an ancestor's rows while a submenu covers it. */
+    parentInk: number;
+    /** The child's top sits this far above the (scaled) top of the row that opened it. */
+    phoneTitleLift: number;
+    /** The iPad child overlaps the parent's edge by this much. */
+    padEdgeOverlap: number;
+    /** The iPad child's first row starts this far above the row that opened it. */
+    padRowLift: number;
+};
+export declare const SUBMENU_SPRINGS: {
+    open: {
+        /** Width, height and x of the child's glass: one spring. */
+        frame: {
+            stiffness: number;
+            damping: number;
+        };
+        /** The glass's top settles faster than its size (overdamped). */
+        top: {
+            stiffness: number;
+            damping: number;
+        };
+        /** The child's rows keep their size and move only from the opening row to their place. */
+        content: {
+            stiffness: number;
+            damping: number;
+        };
+        /** The title's chevron turns from pointing forward to pointing down. */
+        chevron: {
+            stiffness: number;
+            damping: number;
+        };
+        parentScale: {
+            stiffness: number;
+            damping: number;
+        };
+        /** The parent's rows start dimming 50 ms after the child starts to grow. */
+        parentInk: {
+            stiffness: number;
+            damping: number;
+            delay: number;
+        };
+    };
+    back: {
+        frame: {
+            stiffness: number;
+            damping: number;
+        };
+        top: {
+            stiffness: number;
+            damping: number;
+        };
+        parentScale: {
+            stiffness: number;
+            damping: number;
+        };
+        parentInk: {
+            stiffness: number;
+            damping: number;
+        };
+        /** The child's rows fade out as it collapses into its row. */
+        fade: {
+            stiffness: number;
+            damping: number;
+        };
+        /** The rows keep their size and move only until the title sits on the row that opened it. */
+        content: {
+            stiffness: number;
+            damping: number;
+        };
+        /** The title's chevron turns back from pointing down to pointing forward. */
+        chevron: {
+            stiffness: number;
+            damping: number;
+        };
+    };
+};
+export type Frame = Readonly<{
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}>;
+/** Progress (0 to 1) of a measured spring `ms` after it starts. */
+export declare function springProgress(parameters: SpringParameters, ms: number): number;
+/** Compositor keyframes for one measured spring, from `from` to `to`. */
+export declare function springKeyframes(parameters: SpringParameters, frame: (progress: number) => Keyframe): {
+    keyframes: Keyframe[];
+    duration: number;
+};
+/** Scale of a level that has `covering` submenu levels open above it. */
+export declare function ancestorScale(covering: number): number;
+/**
+ * Where a phone submenu settles, in the root platter's coordinates. `parent` is the parent
+ * platter's resting frame and `row` the opening row's resting frame; the parent then shrinks to
+ * `parentScale` about its top edge.
+ */
+export declare function phoneSubmenuFrame(parent: Frame, row: Frame, parentScale: number, child: {
+    width: number;
+    height: number;
+}, bounds: Frame): Frame;
+/**
+ * Where an iPad submenu settles: beside the parent, overlapping its trailing edge, with its first
+ * row level with the opening row. It flips to the leading side when the trailing side has no room.
+ */
+export declare function padSubmenuFrame(parent: Frame, row: Frame, child: {
+    width: number;
+    height: number;
+    firstRowOffset: number;
+}, bounds: Frame): Frame;
+/** Where the child's content sits, in the same coordinates as its frame. */
+export type Point = Readonly<{
+    x: number;
+    y: number;
+}>;
+/**
+ * The child's glass frame from `from` to `to`, sampled from the measured springs until it settles:
+ * x, width and height share one spring and the top has its own.
+ */
+export declare function submenuGlassFrames(from: Frame, to: Frame, direction: 'open' | 'back'): {
+    frames: Readonly<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }>[];
+    duration: number;
+};
+/**
+ * Where a phone child's content must sit for its title row to cover the row that opened it:
+ * `titleOffset` is the title row's position inside the content. The child grows out of that place
+ * and collapses back into it, so the title never jumps when the platter appears or leaves.
+ */
+export declare function titleOnRow(row: Frame, titleOffset: Point): Point;
+/** The content's position `ms` into a transition from `from` to `to`. */
+export declare function submenuContentAt(from: Point, to: Point, direction: 'open' | 'back', ms: number): Point;
+/** Compositor keyframes that turn the title's chevron: forward is a quarter turn back from down. */
+export declare function chevronKeyframes(direction: 'open' | 'back', fromDegrees?: number): {
+    keyframes: Keyframe[];
+    duration: number;
+};
+/** The parts of a platter a transition moves. */
+export type SubmenuParts = Readonly<{
+    /** The positioned frame element; its layout box holds still for the whole transition. */
+    platter: HTMLElement;
+    /** The glass element inside it, which carries the shape track. */
+    glass: HTMLElement;
+    /** Clips the content to the glass's current frame. */
+    clip: HTMLElement;
+    /** The rows, at their full size. */
+    content: HTMLElement;
+    /** The glass's corner radius. */
+    cornerRadius: number;
+}>;
+/** Where a platter's glass is now (not its layout box, which may be larger while it moves). */
+export declare function submenuVisibleFrame(platter: HTMLElement): Readonly<{
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}> | undefined;
+/**
+ * Move a child platter's glass from `from` to `to` on the measured springs, and its content from
+ * `contentFrom` to `contentTo` on its own spring.
+ *
+ * The platter's layout box holds the envelope of every frame of the run, so its glass canvas never
+ * resizes or moves: the backdrop stays where it is on screen and only the glass's edge moves
+ * (shapeTrack.ts). The glass is drawn from a shape track, and the content is clipped to the same
+ * frames, read from the same track. Returns a function that stops the motion where it is.
+ */
+export declare function animateSubmenuFrame(parts: SubmenuParts, from: Frame, to: Frame, contentFrom: Point, contentTo: Point, direction: 'open' | 'back', done?: () => void): () => void;
+/**
+ * Lay a platter out for a run that has not started: its box is already the run's envelope and its
+ * glass holds the first frame, so the glass the platter first appears with is drawn in the canvas
+ * the whole run keeps.
+ */
+export declare function holdSubmenuFrame(parts: SubmenuParts, from: Frame, to: Frame, contentFrom: Point, direction: 'open' | 'back'): void;
+/** Where a platter's content sits now, if a transition has placed it. */
+export declare function submenuContentPlace(platter: HTMLElement): Readonly<{
+    x: number;
+    y: number;
+}> | undefined;