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

package/dist/presentation/model.d.ts

@@ -0,0 +1,108 @@
+import { type DisplayCornerMetrics } from '../safe-area/displayCorners.js';
+/** Native iOS 27 iPad sheet width (form sheet and detent sheet alike), 580 pt in both orientations. */
+export declare const SHEET_MAX_WIDTH = 580;
+export type SheetPlacement = Readonly<{
+    kind: 'edge';
+}> | Readonly<{
+    kind: 'fill';
+}> | Readonly<{
+    kind: 'form';
+    bottom: number;
+}> | Readonly<{
+    kind: 'floating';
+    bottom: number;
+}>;
+/** Native's preferred form height is independent of orientation. Constrain it only when the
+ * presenting viewport cannot hold it, rather than subtracting a device-specific margin. */
+export declare function formSheetHeight(viewportHeight: number): number;
+export declare function sheetPlacement(viewport: {
+    width: number;
+    height: number;
+}, bottomInset: number, onlyLarge: boolean, viewportTop?: number): SheetPlacement;
+export declare function sheetExpansion(height: number, medium: number, large: number): number;
+/** The same frame calculation serves React's resting layout and transient motion. */
+export declare function sheetFrame(viewportWidth: number, expansion: number, keyboardHeight: number, placement?: SheetPlacement): {
+    width: number;
+    left: number;
+    bottom: number;
+    contentScale: number;
+};
+/** Only an equally inset screen-edge card has the display's corner centre. A centred form,
+ * keyboard-raised card or narrow multitasking window keeps its own measured sheet corners. */
+export declare function sheetCornerShape(frame: ReturnType<typeof sheetFrame>, placement: SheetPlacement | undefined, viewport: {
+    width: number;
+    height: number;
+}, screen: {
+    width: number;
+    height: number;
+}, display: DisplayCornerMetrics): {
+    kind: 'roundedRectangle';
+    cornerRadius: number;
+    bottomCornerRadius?: number | undefined;
+    cornerStyle: 'continuous';
+};
+/** `PresentationDetent`: a sheet's supported resting height. */
+export type PresentationDetent = 'medium' | 'large' | Readonly<{
+    height: number;
+}> | Readonly<{
+    fraction: number;
+}>;
+export declare function detentHeight(detent: PresentationDetent, available: number): number;
+export declare function resolveDetents(detents: readonly PresentationDetent[], available: number): number[];
+/** Functional release policy. Velocity is points/ms. */
+export declare function releaseDetent(height: number, velocity: number, heights: readonly number[], dismissDisabled: boolean): number;
+export declare function rubberBandHeight(height: number, maximum: number): number;
+/** The painted drag position. Below its smallest detent a sheet keeps that size and slides down
+ * with the finger (native never shrinks a sheet to dismiss it); without interactive dismissal it
+ * resists there as it does above its largest detent. The result can be negative: off-screen. */
+export declare function sheetDragHeight(height: number, smallest: number, largest: number, dismissDisabled: boolean): number;
+/** How far a sheet painted at `height` has slid below its smallest detent, and its size there. */
+export declare function sheetTravel(height: number, smallest: number): {
+    size: number;
+    offset: number;
+};
+/** Native material changes at the midpoint of the medium-to-large drag.
+ * The recorded switch is bracketed by top edges 257.67 and 244.67 pt.
+ * Keep material choice separate from the final full-width frame geometry. */
+export declare function usesExpandedSheetMaterial(height: number, medium: number, large: number): boolean;
+/** Space kept between an alert's text field and the keyboard's top edge before the keyboard comes. */
+export declare const ALERT_FIELD_KEYBOARD_CLEARANCE = 8;
+/**
+ * Where an alert with a text field rests while no keyboard is reported.
+ *
+ * Measured on the iPad (1366 x 1024): the centred alert's field ends at 531 pt and the keyboard's
+ * top is at 526 pt. WebKit scrolls the document whenever a caret it could see is covered by the
+ * keyboard, for 300 ms, before any script can move the alert. An alert that already rests with
+ * its field above the keyboard to come gives WebKit nothing to reveal. On a phone the centred
+ * field is clear already and the centre is unchanged.
+ *
+ * `fieldReach` is how far the field's bottom edge lies below the alert's centre.
+ */
+export declare function alertRestingCenter(center: number, fieldReach: number, layoutHeight: number, expectedKeyboardHeight: number, keyboardCenter: number): number;
+export declare const CONFIRMATION_POPOVER_WIDTH = 240;
+export declare const CONFIRMATION_ARROW_HEIGHT = 14;
+export type PopoverAnchor = {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+};
+export type ConfirmationPopoverFrame = {
+    left: number;
+    top: number;
+    /** Where the arrow meets the body, in the popover's own x; absent when nothing points. */
+    arrow?: {
+        x: number;
+        edge: 'top' | 'bottom';
+    };
+    /** The point it grows from and shrinks into, in its own coordinates (arrow tip or button). */
+    origin?: {
+        x: number;
+        y: number;
+    };
+};
+export declare function confirmationPopoverFrame(anchor: PopoverAnchor | null, anchorInBar: boolean, height: number, viewport: {
+    width: number;
+    top: number;
+    bottom: number;
+}): ConfirmationPopoverFrame;

package/dist/presentation/model.js

@@ -0,0 +1,183 @@
+import { concentricRadius } from '../safe-area/displayCorners.js';
+import { createLayoutClassState } from '../layout/layoutClass.js';
+import { POPOVER_ARROW_HEIGHT } from '../glass/regions.js';
+/** Native iOS 27 iPad sheet width (form sheet and detent sheet alike), 580 pt in both orientations. */
+export const SHEET_MAX_WIDTH = 580;
+/** Native's preferred form height is independent of orientation. Constrain it only when the
+ * presenting viewport cannot hold it, rather than subtracting a device-specific margin. */
+export function formSheetHeight(viewportHeight) {
+    return Math.min(660, viewportHeight);
+}
+export function sheetPlacement(viewport, bottomInset, onlyLarge, viewportTop = 0) {
+    const layout = createLayoutClassState(viewport).layoutClass;
+    if (layout.vertical === 'compact')
+        return { kind: 'fill' };
+    if (layout.horizontal === 'compact')
+        return { kind: 'edge' };
+    if (onlyLarge) {
+        const freeHeight = viewport.height - formSheetHeight(viewport.height);
+        // Center in the full window while room permits. A constrained window must still
+        // contain the form inside its layout viewport, without moving above its origin.
+        return { kind: 'form', bottom: Math.min(freeHeight, (freeHeight + viewportTop) / 2) };
+    }
+    return { kind: 'floating', bottom: bottomInset };
+}
+export function sheetExpansion(height, medium, large) {
+    return large > medium
+        ? Math.max(0, Math.min(1, (height - medium) / (large - medium)))
+        : Number(height >= large);
+}
+/** The same frame calculation serves React's resting layout and transient motion. */
+export function sheetFrame(viewportWidth, expansion, keyboardHeight, placement = { kind: 'edge' }) {
+    if (placement.kind === 'fill')
+        return { width: viewportWidth, left: 0, bottom: 0, contentScale: 1 };
+    if (placement.kind === 'form') {
+        const width = Math.min(viewportWidth, SHEET_MAX_WIDTH);
+        return { width, left: (viewportWidth - width) / 2, bottom: placement.bottom, contentScale: 1 };
+    }
+    const width = Math.min(viewportWidth - 16 * (1 - expansion), SHEET_MAX_WIDTH);
+    const rest = placement.kind === 'floating' ? placement.bottom : 0;
+    return {
+        width,
+        left: (viewportWidth - width) / 2,
+        bottom: Math.max(rest + 8 * (1 - expansion), keyboardHeight),
+        contentScale: width / Math.min(viewportWidth, SHEET_MAX_WIDTH),
+    };
+}
+/** Only an equally inset screen-edge card has the display's corner centre. A centred form,
+ * keyboard-raised card or narrow multitasking window keeps its own measured sheet corners. */
+export function sheetCornerShape(frame, placement, viewport, screen, display) {
+    const cornerRadius = placement?.kind === 'form' ? 34 : 38;
+    const atDisplayEdge = placement?.kind === 'edge' &&
+        display.source !== 'fallback' &&
+        Math.abs(viewport.width - screen.width) < 1 &&
+        Math.abs(frame.left - frame.bottom) < 0.5;
+    return {
+        kind: 'roundedRectangle',
+        cornerRadius,
+        ...(atDisplayEdge ? { bottomCornerRadius: concentricRadius(display.radius, frame.left) } : {}),
+        cornerStyle: 'continuous',
+    };
+}
+export function detentHeight(detent, available) {
+    if (!Number.isFinite(available) || available <= 0)
+        throw new Error('Sheet requires a positive available height.');
+    if (detent === 'medium')
+        return available / 2;
+    if (detent === 'large')
+        return available;
+    const value = 'height' in detent ? detent.height : detent.fraction * available;
+    if (!Number.isFinite(value) || value <= 0 || ('fraction' in detent && detent.fraction > 1))
+        throw new Error('Sheet detents require positive heights or fractions in (0, 1].');
+    return Math.min(value, available);
+}
+export function resolveDetents(detents, available) {
+    if (!detents.length)
+        throw new Error('Sheet requires at least one detent.');
+    return [...new Set(detents.map(detent => detentHeight(detent, available)))].sort((a, b) => a - b);
+}
+/** Functional release policy. Velocity is points/ms. */
+export function releaseDetent(height, velocity, heights, dismissDisabled) {
+    const candidates = dismissDisabled ? heights : [0, ...heights];
+    // A directional flick advances one stop; slow releases choose the closest stop.
+    const directional = Math.abs(velocity) >= 0.5
+        ? candidates.filter(value => (velocity < 0 ? value > height : value < height))
+        : candidates;
+    const choices = directional.length ? directional : candidates;
+    return choices.reduce((best, value) => Math.abs(value - height) < Math.abs(best - height) ? value : best);
+}
+export function rubberBandHeight(height, maximum) {
+    return height <= maximum
+        ? Math.max(0, height)
+        : maximum + maximum * (1 - 1 / (1 + (height - maximum) / maximum));
+}
+/** The painted drag position. Below its smallest detent a sheet keeps that size and slides down
+ * with the finger (native never shrinks a sheet to dismiss it); without interactive dismissal it
+ * resists there as it does above its largest detent. The result can be negative: off-screen. */
+export function sheetDragHeight(height, smallest, largest, dismissDisabled) {
+    if (height > largest)
+        return rubberBandHeight(height, largest);
+    if (height >= smallest || !dismissDisabled)
+        return height;
+    const excess = smallest - height;
+    return smallest - smallest * (1 - 1 / (1 + excess / smallest));
+}
+/** How far a sheet painted at `height` has slid below its smallest detent, and its size there. */
+export function sheetTravel(height, smallest) {
+    return { size: Math.max(height, smallest), offset: Math.max(0, smallest - height) };
+}
+/** Native material changes at the midpoint of the medium-to-large drag.
+ * The recorded switch is bracketed by top edges 257.67 and 244.67 pt.
+ * Keep material choice separate from the final full-width frame geometry. */
+export function usesExpandedSheetMaterial(height, medium, large) {
+    return height >= (medium + large) / 2;
+}
+/** Space kept between an alert's text field and the keyboard's top edge before the keyboard comes. */
+export const ALERT_FIELD_KEYBOARD_CLEARANCE = 8;
+/**
+ * Where an alert with a text field rests while no keyboard is reported.
+ *
+ * Measured on the iPad (1366 x 1024): the centred alert's field ends at 531 pt and the keyboard's
+ * top is at 526 pt. WebKit scrolls the document whenever a caret it could see is covered by the
+ * keyboard, for 300 ms, before any script can move the alert. An alert that already rests with
+ * its field above the keyboard to come gives WebKit nothing to reveal. On a phone the centred
+ * field is clear already and the centre is unchanged.
+ *
+ * `fieldReach` is how far the field's bottom edge lies below the alert's centre.
+ */
+export function alertRestingCenter(center, fieldReach, layoutHeight, expectedKeyboardHeight, keyboardCenter) {
+    if (expectedKeyboardHeight <= 0)
+        return center;
+    const clearLine = layoutHeight - expectedKeyboardHeight - ALERT_FIELD_KEYBOARD_CLEARANCE;
+    // Never above where the keyboard itself would put the alert.
+    return Math.min(center, Math.max(keyboardCenter, clearLine - fieldReach));
+}
+/* Native iOS 27 `confirmationDialog` on iPhone is a popover from its source (native reference fixture reference,
+ * iPhone 17 Pro Max, 3x stills): 240 pt wide. From a list row it sits above the row, centred on it,
+ * with a 14 pt arrow whose tip lies 16.5 pt inside the row's top edge. From a toolbar button it grows
+ * out of the button: same top edge, 10 pt from the screen edge on the button's side, no arrow. */
+export const CONFIRMATION_POPOVER_WIDTH = 240;
+export const CONFIRMATION_ARROW_HEIGHT = POPOVER_ARROW_HEIGHT;
+const POPOVER_SCREEN_MARGIN = 10;
+const POPOVER_ARROW_OVERLAP = 16.5;
+const POPOVER_ARROW_HALF_BASE = 16;
+const POPOVER_ARROW_CORNER_CLEARANCE = 20;
+export function confirmationPopoverFrame(anchor, anchorInBar, height, viewport) {
+    const width = CONFIRMATION_POPOVER_WIDTH;
+    const margin = POPOVER_SCREEN_MARGIN;
+    if (!anchor) {
+        return {
+            left: (viewport.width - width) / 2,
+            top: (viewport.top + viewport.bottom) / 2 - height / 2,
+        };
+    }
+    const anchorCenter = (anchor.left + anchor.right) / 2;
+    if (anchorInBar) {
+        const trailing = anchorCenter > viewport.width / 2;
+        const left = trailing ? viewport.width - margin - width : margin;
+        return {
+            left,
+            top: anchor.top,
+            origin: { x: anchorCenter - left, y: (anchor.bottom - anchor.top) / 2 },
+        };
+    }
+    const center = Math.min(Math.max(anchorCenter, margin + width / 2), viewport.width - margin - width / 2);
+    const left = center - width / 2;
+    const arrowLimit = POPOVER_ARROW_HALF_BASE + POPOVER_ARROW_CORNER_CLEARANCE;
+    const arrowX = Math.min(Math.max(anchorCenter - left, arrowLimit), width - arrowLimit);
+    const overlap = Math.min(POPOVER_ARROW_OVERLAP, (anchor.bottom - anchor.top) / 2);
+    const above = anchor.top + overlap - CONFIRMATION_ARROW_HEIGHT - height;
+    if (above >= viewport.top + margin)
+        return {
+            left,
+            top: above,
+            arrow: { x: arrowX, edge: 'bottom' },
+            origin: { x: arrowX, y: height + CONFIRMATION_ARROW_HEIGHT },
+        };
+    return {
+        left,
+        top: anchor.bottom - overlap + CONFIRMATION_ARROW_HEIGHT,
+        arrow: { x: arrowX, edge: 'top' },
+        origin: { x: arrowX, y: -CONFIRMATION_ARROW_HEIGHT },
+    };
+}

package/dist/presentation/motion.d.ts

@@ -0,0 +1,56 @@
+export declare function sheetEntranceFrames(distance: number): Keyframe[];
+/** Native fullScreenCover entrance (r2, 11 clips, start pinned one screen below): power ease-out
+ * 1 - (1 - t / 0.963)^11.26, 6.3 pt RMS. It is the same curve in light and dark. */
+export declare const COVER_PRESENT_DURATION = 963;
+export declare function coverEntranceFrames(distance: number): Keyframe[];
+/** Native fullScreenCover dismissal (r2, 11 clips, travel pinned to one screen height): a
+ * mass-one spring from rest, 2.7 pt RMS over the visible part. Returns the travelled distance. */
+export declare function coverDismissalOffset(distance: number, seconds: number): number;
+/** Independently fitted native release tails; velocity is in points/second and seeds the spring.
+ * Below its smallest detent a released sheet translates at its detent size. `dismiss` and `return`
+ * are native-motion r2 fits (iPad, counter-qualified 60 Hz, light and dark together):
+ * - `dismiss`: slides off the screen, seeded with the release velocity; 0.77 pt RMS over 10 clips.
+ *   It replaces the 12e Simulator flick fit (637.3, 42.4), which no valid recording supports.
+ * - `return`: springs back to the detent; 0.23 pt RMS over 11 clips.
+ * `expand` and `collapse` remain the 12e phone fits. */
+export declare function sheetReleasePosition(from: number, to: number, velocity: number, seconds: number, phase: 'dismiss' | 'return' | 'expand' | 'collapse'): number;
+export declare function alertKeyboardState(from: number, to: number, velocity: number, seconds: number): {
+    position: number;
+    velocity: number;
+};
+/** Stock grabber taps are distinct from the velocity-bearing drag release fits. */
+export declare function sheetDetentPosition(from: number, to: number, seconds: number): number;
+export declare function dialogEntranceFrames(kind: 'alert' | 'confirmation'): Keyframe[];
+export declare const CONFIRMATION_DISMISS_DURATION = 210;
+export declare function confirmationDismissalFrames(): Keyframe[];
+/** Stock iOS 27 alert title-contrast fit (Sep 28); opening 2 is the holdout.
+ * Opacity RMS 0.0274, independently tracked from the scale/keyboard motion.
+ */
+export declare function alertEntranceOpacity(seconds: number): number;
+/** Native dismissal retains scale 1. Its last visible frame is at 193 ms;
+ * the first absent frame brackets removal at 210 ms. Samples use video PTS.
+ */
+export declare const ALERT_DISMISS_DURATION = 210;
+export declare function alertDismissalFrames(): Keyframe[];
+/** Sep 28 stock medium sheet + software keyboard: grabber 454 -> 65 pt,
+ * 120 accepted samples, RMS 1.689 pt. Selection itself remains unchanged.
+ */
+export declare function sheetKeyboardPosition(from: number, to: number, seconds: number): number;
+/** iOS 27 Done dismissal: medium 483 ms, large 494 ms, near-critical mass-one fits. */
+export declare function sheetDismissalPosition(distance: number, seconds: number, large: boolean): number;
+/** Submit the measured Done curve once. Ordinary linear interpolation between
+ * samples avoids depending on the engine's acceleration of CSS linear(). */
+export declare function presentationDismissalFrames(distance: number, from: number, opacity: number, kind: 'sheet' | 'cover', large: boolean, velocity?: number): {
+    transform: Keyframe[];
+    dim: Keyframe[];
+};
+/** Seed the existing sheet spring with the interrupted track's velocity.
+ * The cover is a power fit, not a spring: its correction matches initial
+ * velocity and vanishes at the original endpoint. Native parity is pending. */
+export declare function presentationReturnFrames(from: number, opacity: number, kind: 'sheet' | 'cover', velocity?: number): {
+    transform: Keyframe[];
+    dim: Keyframe[];
+};
+/** Velocity of the submitted linear keyframe segment in points/second.
+ * This reads the animation timeline, never main-thread callback spacing. */
+export declare function presentationAnimationVelocity(animation?: Animation): number;

package/dist/presentation/motion.js

@@ -0,0 +1,263 @@
+/** Native iOS 27 iPad large-sheet entrance (native-motion r2), one spring for light and dark.
+ * Joint fit over 11 counter-retimed clips with the start pinned below the screen: 1.38 pt RMS.
+ */
+const SHEET_PRESENT_SPRING = [331.98, 36.378];
+/** A mass-one spring released at rest, sampled into WAAPI translateY keyframes over 0.7 s. */
+function springEntranceFrames(distance, [stiffness, damping]) {
+    return Array.from({ length: 85 }, (_, index) => {
+        const remaining = springState(distance, 0, 0, (index / 84) * 0.7, stiffness, damping).position;
+        return {
+            offset: index / 84,
+            transform: `translateY(${index === 84 ? 0 : remaining}px)`,
+        };
+    });
+}
+export function sheetEntranceFrames(distance) {
+    return springEntranceFrames(distance, SHEET_PRESENT_SPRING);
+}
+/** Native fullScreenCover entrance (r2, 11 clips, start pinned one screen below): power ease-out
+ * 1 - (1 - t / 0.963)^11.26, 6.3 pt RMS. It is the same curve in light and dark. */
+export const COVER_PRESENT_DURATION = 963;
+export function coverEntranceFrames(distance) {
+    return Array.from({ length: 97 }, (_, index) => ({
+        offset: index / 96,
+        transform: `translateY(${index === 96 ? 0 : distance * (1 - index / 96) ** 11.257}px)`,
+    }));
+}
+/** Native fullScreenCover dismissal (r2, 11 clips, travel pinned to one screen height): a
+ * mass-one spring from rest, 2.7 pt RMS over the visible part. Returns the travelled distance. */
+export function coverDismissalOffset(distance, seconds) {
+    return distance - springState(distance, 0, 0, seconds, 330.544, 35.996).position;
+}
+/** Independently fitted native release tails; velocity is in points/second and seeds the spring.
+ * Below its smallest detent a released sheet translates at its detent size. `dismiss` and `return`
+ * are native-motion r2 fits (iPad, counter-qualified 60 Hz, light and dark together):
+ * - `dismiss`: slides off the screen, seeded with the release velocity; 0.77 pt RMS over 10 clips.
+ *   It replaces the 12e Simulator flick fit (637.3, 42.4), which no valid recording supports.
+ * - `return`: springs back to the detent; 0.23 pt RMS over 11 clips.
+ * `expand` and `collapse` remain the 12e phone fits. */
+export function sheetReleasePosition(from, to, velocity, seconds, phase) {
+    const [stiffness, damping] = {
+        dismiss: [305.97, 34.33],
+        return: [321.912, 35.09],
+        collapse: [326.5080212050766, 36.13545200303523],
+        expand: [136.04264454717745, 21.643366602174066],
+    }[phase];
+    const w = Math.sqrt(stiffness), z = damping / (2 * w), d = Math.sqrt(1 - z * z);
+    const displacement = from - to;
+    return (to +
+        Math.exp(-z * w * seconds) *
+            (displacement * Math.cos(w * d * seconds) +
+                ((velocity + z * w * displacement) / (w * d)) * Math.sin(w * d * seconds)));
+}
+/** Mass-one spring, including critical/overdamped native detent taps. */
+function springState(from, to, velocity, seconds, stiffness, damping) {
+    const t = Math.max(0, seconds), x = from - to, a = damping / 2, discriminant = a * a - stiffness;
+    let displacement, speed;
+    if (Math.abs(discriminant) < 1e-6) {
+        const b = velocity + a * x, decay = Math.exp(-a * t);
+        displacement = decay * (x + b * t);
+        speed = decay * (b - a * (x + b * t));
+    }
+    else if (discriminant > 0) {
+        const root = Math.sqrt(discriminant), r1 = -a + root, r2 = -a - root;
+        const c1 = (velocity - r2 * x) / (r1 - r2), c2 = x - c1;
+        displacement = c1 * Math.exp(r1 * t) + c2 * Math.exp(r2 * t);
+        speed = r1 * c1 * Math.exp(r1 * t) + r2 * c2 * Math.exp(r2 * t);
+    }
+    else {
+        const w = Math.sqrt(-discriminant), b = (velocity + a * x) / w, decay = Math.exp(-a * t);
+        displacement = decay * (x * Math.cos(w * t) + b * Math.sin(w * t));
+        speed = -a * displacement + decay * w * (-x * Math.sin(w * t) + b * Math.cos(w * t));
+    }
+    return { position: to + displacement, velocity: speed };
+}
+/* Sep 27 iOS 27 stock alert + TextField, warmed run 1; run 2 is the holdout.
+ * Native centre 492 -> 335.5 pt. See measured-reference notes for captures and residuals.
+ */
+export function alertKeyboardState(from, to, velocity, seconds) {
+    return springState(from, to, velocity, seconds, 480.14579454093644, 41.79219798805168);
+}
+/** Stock grabber taps are distinct from the velocity-bearing drag release fits. */
+export function sheetDetentPosition(from, to, seconds) {
+    return to > from
+        ? springState(from, to, 0, seconds, 316.1544205988269, 35.57406510593182).position
+        : springState(from, to, 0, seconds, 346.32375968752916, 37.49481475190611).position;
+}
+/* Native visible scale tails, with the Sep 28 software-keyboard alert opacity fit. The
+ * confirmation popover grows from its arrow tip (native reference reference, Oct 10, 60 Hz Simulator recording,
+ * fit-only): popover width 0.23 -> 1, RMS 0.006, with the dark-run opacity samples below. */
+export function dialogEntranceFrames(kind) {
+    const [from, velocity, w, z] = kind === 'alert'
+        ? [1.1818181818181819, -1.7709405499714581, 20.045876104162325, 0.9515937909832228]
+        : [0.23, 0, 20, 0.8];
+    const d = Math.sqrt(1 - z * z), x = from - 1;
+    return Array.from({ length: 85 }, (_, index) => {
+        const t = (index / 84) * 0.7;
+        const scale = 1 +
+            Math.exp(-z * w * t) *
+                (x * Math.cos(w * d * t) + ((velocity + z * w * x) / (w * d)) * Math.sin(w * d * t));
+        return {
+            offset: index / 84,
+            transform: `scale(${index === 84 ? 1 : scale})`,
+            opacity: index === 84 ? 1 : kind === 'alert' ? alertEntranceOpacity(t) : confirmationOpacity(t),
+        };
+    });
+}
+/** Popover body level over a black list relative to rest (dark run), ms after the first frame. */
+const CONFIRMATION_ENTRANCE_OPACITY = [
+    [0, 0],
+    [17, 0.2],
+    [34, 0.36],
+    [44, 0.43],
+    [62, 0.57],
+    [79, 0.64],
+    [97, 0.7],
+    [112, 0.77],
+    [130, 0.86],
+    [147, 0.91],
+    [164, 0.93],
+    [182, 0.95],
+    [195, 1],
+];
+function confirmationOpacity(seconds) {
+    const ms = seconds * 1000;
+    const next = CONFIRMATION_ENTRANCE_OPACITY.findIndex(([time]) => time >= ms);
+    if (next <= 0)
+        return next === 0 ? 0 : 1;
+    const [t0, v0] = CONFIRMATION_ENTRANCE_OPACITY[next - 1], [t1, v1] = CONFIRMATION_ENTRANCE_OPACITY[next];
+    return v0 + ((v1 - v0) * (ms - t0)) / (t1 - t0);
+}
+/* The popover shrinks back into its arrow tip as it fades (native reference reference, video PTS): scale from
+ * the light run's width, opacity from the dark run. The first absent frame is at 200-220 ms. */
+export const CONFIRMATION_DISMISS_DURATION = 210;
+export function confirmationDismissalFrames() {
+    const samples = [
+        [0, 1, 1],
+        [16, 0.97, 0.93],
+        [35, 0.875, 0.83],
+        [50, 0.751, 0.7],
+        [66, 0.615, 0.64],
+        [83, 0.502, 0.54],
+        [101, 0.419, 0.41],
+        [120, 0.34, 0.29],
+        [136, 0.302, 0.2],
+        [153, 0.275, 0.13],
+        [170, 0.234, 0.09],
+        [188, 0.215, 0.06],
+        [210, 0.2, 0],
+    ];
+    return samples.map(([time, scale, opacity]) => ({
+        offset: time / CONFIRMATION_DISMISS_DURATION,
+        transform: `scale(${scale})`,
+        opacity,
+    }));
+}
+/** Stock iOS 27 alert title-contrast fit (Sep 28); opening 2 is the holdout.
+ * Opacity RMS 0.0274, independently tracked from the scale/keyboard motion.
+ */
+export function alertEntranceOpacity(seconds) {
+    return Math.max(0, Math.min(1, springState(0, 1, 0, seconds, 1396.659532456193, 117.75600163364518).position));
+}
+/** Native dismissal retains scale 1. Its last visible frame is at 193 ms;
+ * the first absent frame brackets removal at 210 ms. Samples use video PTS.
+ */
+export const ALERT_DISMISS_DURATION = 210;
+export function alertDismissalFrames() {
+    const samples = [
+        [0, 1],
+        [11, 0.987],
+        [18, 0.934],
+        [35, 0.813],
+        [56, 0.675],
+        [70, 0.538],
+        [85, 0.42],
+        [103, 0.307],
+        [120, 0.242],
+        [135, 0.175],
+        [142, 0.143],
+        [161, 0.116],
+        [175, 0.084],
+        [193, 0.058],
+        [210, 0],
+    ];
+    return samples.map(([time, opacity]) => ({ offset: time / ALERT_DISMISS_DURATION, opacity }));
+}
+/** Sep 28 stock medium sheet + software keyboard: grabber 454 -> 65 pt,
+ * 120 accepted samples, RMS 1.689 pt. Selection itself remains unchanged.
+ */
+export function sheetKeyboardPosition(from, to, seconds) {
+    // Return-key dismissal: 100 samples, RMS 1.306 pt, same native session.
+    return to > from
+        ? springState(from, to, 0, seconds, 479.14469035648204, 42.67259323369546).position
+        : springState(from, to, 0, seconds, 677.3440899114729, 54.3445148299905).position;
+}
+/** iOS 27 Done dismissal: medium 483 ms, large 494 ms, near-critical mass-one fits. */
+export function sheetDismissalPosition(distance, seconds, large) {
+    if (seconds >= 0.5)
+        return 0;
+    const stiffness = large ? 431 : 361.5;
+    const damping = large ? 41.5 : 38;
+    return Math.max(0, springState(distance, 0, 0, seconds, stiffness, damping).position);
+}
+/** Submit the measured Done curve once. Ordinary linear interpolation between
+ * samples avoids depending on the engine's acceleration of CSS linear(). */
+export function presentationDismissalFrames(distance, from, opacity, kind, large, velocity = 0) {
+    const transform = [];
+    const dim = [];
+    for (let index = 0; index <= 120; index++) {
+        const offset = index / 120;
+        const remaining = velocity === 0
+            ? kind === 'cover'
+                ? distance - coverDismissalOffset(distance, offset * 0.5)
+                : sheetDismissalPosition(distance, offset * 0.5, large)
+            : springState(distance, 0, -velocity, offset * 0.5, kind === 'cover' ? 330.544 : large ? 431 : 361.5, kind === 'cover' ? 35.996 : large ? 41.5 : 38).position;
+        transform.push({ offset, transform: `translateY(${from + distance - remaining}px)` });
+        dim.push({ offset, opacity: opacity * Math.max(0, remaining / distance) });
+    }
+    return { transform, dim };
+}
+/** Seed the existing sheet spring with the interrupted track's velocity.
+ * The cover is a power fit, not a spring: its correction matches initial
+ * velocity and vanishes at the original endpoint. Native parity is pending. */
+export function presentationReturnFrames(from, opacity, kind, velocity = 0) {
+    const normalized = kind === 'cover' ? coverEntranceFrames(1) : sheetEntranceFrames(1);
+    const transform = [];
+    const dim = [];
+    for (const frame of normalized) {
+        const remaining = Number(String(frame.transform).slice(11, -3));
+        const phase = Number(frame.offset);
+        const seconds = phase * (kind === 'cover' ? COVER_PRESENT_DURATION / 1000 : 0.7);
+        const position = phase === 1
+            ? 0
+            : kind === 'sheet'
+                ? springState(from, 0, velocity, seconds, ...SHEET_PRESENT_SPRING).position
+                : from * remaining +
+                    (velocity + (from * 11.257) / 0.963) * seconds * (1 - phase) ** 11.257;
+        transform.push({ offset: frame.offset, transform: `translateY(${position}px)` });
+        dim.push({ offset: frame.offset, opacity: 1 - (1 - opacity) * remaining });
+    }
+    return { transform, dim };
+}
+/** Velocity of the submitted linear keyframe segment in points/second.
+ * This reads the animation timeline, never main-thread callback spacing. */
+export function presentationAnimationVelocity(animation) {
+    const effect = animation?.effect;
+    if (!effect || !(effect instanceof KeyframeEffect) || typeof animation?.currentTime !== 'number')
+        return 0;
+    const duration = Number(effect.getComputedTiming().duration);
+    if (!(duration > 0))
+        return 0;
+    const phase = animation.currentTime / duration;
+    const frames = effect.getKeyframes();
+    for (let index = 1; index < frames.length; index++) {
+        const before = frames[index - 1];
+        const after = frames[index];
+        if (phase < before.computedOffset || phase >= after.computedOffset)
+            continue;
+        const start = new DOMMatrixReadOnly(String(before.transform)).m42;
+        const end = new DOMMatrixReadOnly(String(after.transform)).m42;
+        return ((end - start) * 1000) / ((after.computedOffset - before.computedOffset) * duration);
+    }
+    return 0;
+}

package/dist/presentation/presentationMotion.d.ts

@@ -0,0 +1,10 @@
+/** One admission, clock and cancellation contract for programmatic and gesture sheet tails. */
+export declare function runPresentationMotion({ layer, movement, dimming, tracksGlass, phase, invalidate, complete, }: {
+    layer: HTMLElement;
+    movement: Animation;
+    dimming: Animation;
+    tracksGlass: boolean;
+    phase: 'entrance' | 'dismissal' | 'drag';
+    invalidate: () => void;
+    complete: () => void;
+}): () => void;