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

package/dist/navigation/zoomGeometry.js

@@ -0,0 +1,94 @@
+/*
+ * The geometry of SwiftUI's zoom navigation transition, as pure functions of a rectangle.
+ *
+ * At every moment the pushed screen is shown inside a rounded "window" rectangle that moves between
+ * the source view's frame and the full screen. As natively, the screen's content is scaled so its
+ * width fills the window and is pinned to the window's top; whatever falls below the window's
+ * bottom edge is cut off.
+ *
+ * The cut is made by two nested boxes that only move, so the compositor draws it with the content:
+ * the screen container is scaled into place and shifted up until its bottom edge is the window's
+ * bottom; the motion layer inside it is shifted back down by the same amount, so the content's top
+ * stays at the window's top. Each box clips its overflow with the window's corner radius: the outer
+ * one makes the bottom corners, the inner one the top corners.
+ */
+import { ZOOM_EDGE_SCALE_LOSS, ZOOM_EDGE_SLOP, ZOOM_DRAG_BOTTOM_RISE, ZOOM_DRAG_HEIGHT_LOSS_PER_POINT, ZOOM_DRAG_SLOP, ZOOM_DRAG_WIDTH_LOSS_PER_POINT, } from './zoomMotion.js';
+/** The scale that makes the screen's width fill the window. */
+export function contentScale(screen, window) {
+    return window.rect.width / screen.width;
+}
+/**
+ * The styles that draw a screen laid out at `screen` inside `window`. Both boxes need
+ * `transform-origin: 0 0`, `overflow: hidden` and the screen's own layout frame.
+ */
+export function windowStyle(screen, window) {
+    const scale = contentScale(screen, window) || 1;
+    // The window's height in the content's own points, never taller than the content itself.
+    const visibleHeight = Math.min(window.rect.height / scale, screen.height);
+    const cut = screen.height - visibleHeight;
+    const x = window.rect.x - screen.x;
+    const y = window.rect.y - screen.y - cut * scale;
+    return {
+        containerTransform: `translate(${round(x)}px, ${round(y)}px) scale(${round(scale, 5)})`,
+        motionTransform: `translateY(${round(cut)}px)`,
+        borderRadius: `${round(window.radius / scale)}px`,
+    };
+}
+const lerp = (from, to, progress) => from + (to - from) * progress;
+/** The window `progress` of the way from `from` to `to`. Progress may overshoot 0…1 (springs). */
+export function interpolateWindow(from, to, progress) {
+    return {
+        rect: {
+            x: lerp(from.rect.x, to.rect.x, progress),
+            y: lerp(from.rect.y, to.rect.y, progress),
+            width: Math.max(0, lerp(from.rect.width, to.rect.width, progress)),
+            height: Math.max(0, lerp(from.rect.height, to.rect.height, progress)),
+        },
+        radius: Math.max(0, lerp(from.radius, to.radius, progress)),
+    };
+}
+/** How open a window is: 0 at the source's width, 1 at the screen's. */
+export function openness(screen, source, rect) {
+    const span = screen.width - source.width;
+    return span > 0 ? Math.min(1, Math.max(0, (rect.width - source.width) / span)) : 1;
+}
+/** The window's corner radius at an openness: from the source to the full page's clip. */
+export function windowRadius(open, sourceRadius, restingRadius) {
+    return lerp(sourceRadius, restingRadius, open);
+}
+/**
+ * The window under a dismissing finger, as natively measured: dragging down narrows it (centred on
+ * the finger's sideways travel), shortens it faster still, and lifts its bottom edge with the
+ * square of the drag. `translation` is the finger's travel since it went down.
+ */
+export function dragRect(screen, translation) {
+    const pulled = Math.max(0, translation.y - ZOOM_DRAG_SLOP);
+    const width = screen.width * Math.max(0.2, 1 - ZOOM_DRAG_WIDTH_LOSS_PER_POINT * pulled);
+    const height = Math.max(width, screen.height * (1 - ZOOM_DRAG_HEIGHT_LOSS_PER_POINT * pulled));
+    const bottom = screen.y + screen.height - ZOOM_DRAG_BOTTOM_RISE * pulled * pulled;
+    return {
+        x: screen.x + (screen.width - width) / 2 + translation.x,
+        y: bottom - height,
+        width,
+        height,
+    };
+}
+/**
+ * The window under the edge back swipe, as natively measured: it shrinks uniformly, its left edge
+ * follows the finger (less the recognizer's 18 pt) and it shrinks toward the screen's middle
+ * height. `progress` is the finger's travel over the screen's width.
+ */
+export function edgeRect(screen, progress) {
+    const pulled = Math.max(0, progress * screen.width - ZOOM_EDGE_SLOP);
+    const scale = Math.max(0.2, 1 - (ZOOM_EDGE_SCALE_LOSS * pulled) / screen.width);
+    return {
+        x: screen.x + pulled,
+        y: screen.y + (screen.height / 2) * (1 - scale),
+        width: screen.width * scale,
+        height: screen.height * scale,
+    };
+}
+function round(value, digits = 3) {
+    const factor = 10 ** digits;
+    return Math.round(value * factor) / factor;
+}

package/dist/navigation/zoomGlass.d.ts

@@ -0,0 +1,27 @@
+import type { ZoomRect } from './zoomGeometry.js';
+/** The same viewport-space window that the compositor draws, sampled on its animation clock. */
+export type ZoomGlassPose = Readonly<{
+    x: number;
+    y: number;
+    scale: number;
+    origin: readonly [number, number];
+    clip: readonly [number, number, number, number];
+    radius: number;
+}>;
+type ZoomGlassMotion = {
+    layout: ZoomRect;
+    carriers: readonly HTMLElement[];
+    read: (at: number) => {
+        end: number;
+        sample: (time: number) => ZoomGlassPose;
+    };
+};
+export declare function registerZoomGlass(element: HTMLElement, motion: ZoomGlassMotion): () => void;
+export declare const zoomGlassMotion: (element: HTMLElement) => ZoomGlassMotion | undefined;
+/** Layout capture is synchronous. Important declarations override WAAPI only for these reads,
+ * and are restored before returning to WebKit; no animation clock or painted frame changes. */
+export declare function withZoomAtRest<T>(element: HTMLElement, read: () => T): T;
+/** In-content presenters travel inside the CSS window. Keep their material and allocation
+ * in the route's resting coordinates, rather than capturing Home through a scaled button. */
+export declare function zoomRestRect(element: HTMLElement): ZoomRect | undefined;
+export {};

package/dist/navigation/zoomGlass.js

@@ -0,0 +1,64 @@
+const motions = new WeakMap();
+export function registerZoomGlass(element, motion) {
+    motions.set(element, motion);
+    return () => {
+        if (motions.get(element) === motion)
+            motions.delete(element);
+    };
+}
+export const zoomGlassMotion = (element) => motions.get(element);
+/** Layout capture is synchronous. Important declarations override WAAPI only for these reads,
+ * and are restored before returning to WebKit; no animation clock or painted frame changes. */
+export function withZoomAtRest(element, read) {
+    const carriers = new Set();
+    for (let ancestor = element; ancestor; ancestor = ancestor.parentElement)
+        for (const carrier of motions.get(ancestor)?.carriers ?? [])
+            carriers.add(carrier);
+    const saved = [...carriers].map(carrier => ({
+        carrier,
+        value: carrier.style.getPropertyValue('transform'),
+        priority: carrier.style.getPropertyPriority('transform'),
+        visibility: carrier.style.getPropertyValue('visibility'),
+        visibilityPriority: carrier.style.getPropertyPriority('visibility'),
+    }));
+    for (const { carrier } of saved) {
+        carrier.style.setProperty('transform', 'none', 'important');
+        // The entrance remains hidden until its first glass submission. Capture its real
+        // content synchronously while that presentation barrier is still closed.
+        carrier.style.setProperty('visibility', 'visible', 'important');
+    }
+    try {
+        return read();
+    }
+    finally {
+        for (const { carrier, value, priority, visibility, visibilityPriority } of saved) {
+            if (value)
+                carrier.style.setProperty('transform', value, priority);
+            else
+                carrier.style.removeProperty('transform');
+            if (visibility)
+                carrier.style.setProperty('visibility', visibility, visibilityPriority);
+            else
+                carrier.style.removeProperty('visibility');
+        }
+    }
+}
+/** In-content presenters travel inside the CSS window. Keep their material and allocation
+ * in the route's resting coordinates, rather than capturing Home through a scaled button. */
+export function zoomRestRect(element) {
+    let ancestor = element;
+    while (ancestor && !motions.has(ancestor))
+        ancestor = ancestor.parentElement;
+    if (!ancestor)
+        return undefined;
+    const motion = motions.get(ancestor);
+    const at = performance.now();
+    const pose = motion.read(at).sample(at);
+    const rect = element.getBoundingClientRect();
+    return {
+        x: motion.layout.x + (rect.x - pose.x) / pose.scale,
+        y: motion.layout.y + (rect.y - pose.y) / pose.scale,
+        width: rect.width / pose.scale,
+        height: rect.height / pose.scale,
+    };
+}

package/dist/navigation/zoomMotion.d.ts

@@ -0,0 +1,73 @@
+/** A spring as Core Animation runs it: natural frequency (rad/s) and damping ratio. */
+export type ZoomSpring = Readonly<{
+    omega: number;
+    zeta: number;
+}>;
+/** The window's centre and its size each follow their own spring. */
+export type ZoomSprings = Readonly<{
+    center: ZoomSpring;
+    size: ZoomSpring;
+}>;
+/**
+ * Push: the centre and the width move together, critically damped (half way at 88 ms; SwiftUI's
+ * duration 0.33 s); the height lags slightly. Native moves the width with the centre, so the
+ * width shares the centre's spring here and the height takes the size spring (rms 0.002, 51 ticks).
+ */
+export declare const ZOOM_PUSH: ZoomSprings & {
+    height: ZoomSpring;
+};
+/** Pop (the back button): centre and size, slightly underdamped (rms 0.005, 49 ticks). */
+export declare const ZOOM_POP: ZoomSprings;
+/** A released drag that dismisses: it bounces about 4% into the source (two drags, rms ≤ 0.01). */
+export declare const ZOOM_DISMISS: ZoomSprings;
+/** A released drag that returns to full screen (rms 0.005). */
+export declare const ZOOM_RETURN: ZoomSprings;
+/** The screen behind darkens to 15% black at full openness, in proportion to the openness
+ * (0.028 / 0.043 / 0.063 / 0.079 / 0.099 measured at openness 0.18 / 0.30 / 0.42 / 0.52 / 0.69). */
+export declare const ZOOM_DIM_OPACITY = 0.15;
+/** The screen behind shrinks about its centre to this scale at full openness (1 − 0.0788 × openness,
+ * exact over 17 ticks). It holds there while a finger drags the zoomed screen. */
+export declare const ZOOM_REAR_SCALE = 0.9212;
+/** The window's corner radius goes from the source's to the display's, in proportion to the
+ * openness (residual ≤ 3 pt over 9 frames). 58 pt is the iPhone 17 Pro Max display's; iPad
+ * displays are far squarer. */
+export declare const ZOOM_PHONE_DISPLAY_RADIUS = 58;
+export declare const ZOOM_PAD_DISPLAY_RADIUS = 18;
+/** The source tile is drawn over the window's top square and cross-fades with the page: on push it
+ * fades out linearly between these times (0.81 / 0.60 / 0.40 / 0.21 at 33 / 50 / 67 / 83 ms)… */
+export declare const ZOOM_PUSH_SOURCE_FADE_MS: {
+    readonly start: 17;
+    readonly end: 100;
+};
+/** …and on pop it fades in (0.49 / 0.70 / 0.87 / 0.98 at 67 / 84 / 100 / 117 ms). */
+export declare const ZOOM_POP_SOURCE_FADE_MS: {
+    readonly start: 25;
+    readonly end: 111;
+};
+/** Destination portal opacity during a native pop, independent of the source portal.
+ * Measured CADisplayLink presentation alpha, iOS 27 stock zoom fixture, October 13:
+ * zoom-return-zorder/native/{alpha.mp4,layers-alpha.log,alpha.json}. The page stays
+ * opaque through 67 ms, then fades while the already opaque tile continues its flight.
+ * These are rounded 60 Hz samples of that channel, not a newly chosen spring. */
+export declare const ZOOM_POP_PAGE_ALPHA: readonly (readonly [number, number])[];
+/** The bar's items (the back button's glass, the title) fade in over the push on a smoothstep… */
+export declare const ZOOM_PUSH_CHROME_FADE_MS = 250;
+/** …and out over the pop, linearly from this window (1 → 0, measured 0.91 at 50 ms, 0.07 at 217 ms). */
+export declare const ZOOM_POP_CHROME_FADE_MS: {
+    readonly start: 33;
+    readonly end: 240;
+};
+export declare const ZOOM_DRAG_SLOP = 12;
+export declare const ZOOM_DRAG_WIDTH_LOSS_PER_POINT = 0.000698;
+export declare const ZOOM_DRAG_HEIGHT_LOSS_PER_POINT: number;
+export declare const ZOOM_DRAG_BOTTOM_RISE = 0.000294;
+/** The edge back swipe zooms too (dark run, 3 swipes): the window shrinks uniformly by 0.66 of the
+ * finger's travel over the screen's width (0.0015 per point on a 440 pt screen), counted from the
+ * recognizer's 18 pt; its left edge follows the finger. 88 pt returned; 298 and 398 pt dismissed. */
+export declare const ZOOM_EDGE_SLOP = 18;
+export declare const ZOOM_EDGE_SCALE_LOSS = 0.66;
+/** A released drag dismisses past this distance down (native: 50 and 80 pt returned, 140 pt
+ * dismissed; an 80 pt flick at 849 pt/s still returned, so speed alone does not dismiss). */
+export declare const ZOOM_DISMISS_DISTANCE = 110;
+/** A drag starts once the finger has moved this far, mostly downward, from where it went down. */
+export declare const ZOOM_DRAG_START_DISTANCE = 10;

package/dist/navigation/zoomMotion.js

@@ -0,0 +1,104 @@
+/*
+ * Measured values of SwiftUI's `.navigationTransition(.zoom(sourceID:in:))` on iOS 27.
+ *
+ * native reference: a stock native fixture (a 180 pt tile with a 10 pt corner in a
+ * NavigationStack grid, pushed to a full-screen page), iPhone 17 Pro Max Simulator, iOS 27.0.
+ * Core Animation presentation layers were logged on every display tick (the zoom draws through an
+ * SDF "window" layer and two portals: the source tile and the page), and idb drove real Simulator
+ * touches. Appearance (cross-fade, dim, corner) comes from frames of the same runs, matched to the
+ * logged ticks by the window's rectangle. Fits and plots: native measurements
+ * (the measured reference, October 11).
+ */
+/**
+ * Push: the centre and the width move together, critically damped (half way at 88 ms; SwiftUI's
+ * duration 0.33 s); the height lags slightly. Native moves the width with the centre, so the
+ * width shares the centre's spring here and the height takes the size spring (rms 0.002, 51 ticks).
+ */
+export const ZOOM_PUSH = {
+    center: { omega: 19.1, zeta: 1 },
+    size: { omega: 19.1, zeta: 1 },
+    height: { omega: 16.3, zeta: 0.95 },
+};
+/** Pop (the back button): centre and size, slightly underdamped (rms 0.005, 49 ticks). */
+export const ZOOM_POP = {
+    center: { omega: 18.9, zeta: 0.93 },
+    size: { omega: 16.4, zeta: 0.9 },
+};
+/** A released drag that dismisses: it bounces about 4% into the source (two drags, rms ≤ 0.01). */
+export const ZOOM_DISMISS = {
+    center: { omega: 13.75, zeta: 0.82 },
+    size: { omega: 13.75, zeta: 0.7 },
+};
+/** A released drag that returns to full screen (rms 0.005). */
+export const ZOOM_RETURN = {
+    center: { omega: 22.6, zeta: 0.94 },
+    size: { omega: 22.6, zeta: 0.94 },
+};
+/** The screen behind darkens to 15% black at full openness, in proportion to the openness
+ * (0.028 / 0.043 / 0.063 / 0.079 / 0.099 measured at openness 0.18 / 0.30 / 0.42 / 0.52 / 0.69). */
+export const ZOOM_DIM_OPACITY = 0.15;
+/** The screen behind shrinks about its centre to this scale at full openness (1 − 0.0788 × openness,
+ * exact over 17 ticks). It holds there while a finger drags the zoomed screen. */
+export const ZOOM_REAR_SCALE = 0.9212;
+/** The window's corner radius goes from the source's to the display's, in proportion to the
+ * openness (residual ≤ 3 pt over 9 frames). 58 pt is the iPhone 17 Pro Max display's; iPad
+ * displays are far squarer. */
+export const ZOOM_PHONE_DISPLAY_RADIUS = 58;
+export const ZOOM_PAD_DISPLAY_RADIUS = 18;
+/** The source tile is drawn over the window's top square and cross-fades with the page: on push it
+ * fades out linearly between these times (0.81 / 0.60 / 0.40 / 0.21 at 33 / 50 / 67 / 83 ms)… */
+export const ZOOM_PUSH_SOURCE_FADE_MS = { start: 17, end: 100 };
+/** …and on pop it fades in (0.49 / 0.70 / 0.87 / 0.98 at 67 / 84 / 100 / 117 ms). */
+export const ZOOM_POP_SOURCE_FADE_MS = { start: 25, end: 111 };
+/** Destination portal opacity during a native pop, independent of the source portal.
+ * Measured CADisplayLink presentation alpha, iOS 27 stock zoom fixture, October 13:
+ * zoom-return-zorder/native/{alpha.mp4,layers-alpha.log,alpha.json}. The page stays
+ * opaque through 67 ms, then fades while the already opaque tile continues its flight.
+ * These are rounded 60 Hz samples of that channel, not a newly chosen spring. */
+export const ZOOM_POP_PAGE_ALPHA = [
+    [0, 1],
+    [67, 1],
+    [83, 0.86253],
+    [100, 0.6992],
+    [117, 0.55629],
+    [133, 0.43524],
+    [150, 0.33528],
+    [167, 0.25448],
+    [183, 0.19035],
+    [200, 0.14029],
+    [217, 0.10181],
+    [233, 0.07266],
+    [250, 0.0509],
+    [267, 0.03489],
+    [283, 0.02331],
+    [300, 0.01506],
+    [317, 0.0093],
+    [333, 0.00536],
+    [350, 0.00274],
+    [367, 0.00106],
+    [383, 0.00003],
+    [400, 0],
+];
+/** The bar's items (the back button's glass, the title) fade in over the push on a smoothstep… */
+export const ZOOM_PUSH_CHROME_FADE_MS = 250;
+/** …and out over the pop, linearly from this window (1 → 0, measured 0.91 at 50 ms, 0.07 at 217 ms). */
+export const ZOOM_POP_CHROME_FADE_MS = { start: 33, end: 240 };
+/*
+ * The interactive dismissal (a slow 540 pt drag, 70 ticks, linear throughout): the window's width
+ * shrinks 0.000698 of the screen per point dragged and its height 1.223 points per point, both
+ * counted from the 12 pt the recognizer needs. Its bottom edge rises with the square of the drag.
+ */
+export const ZOOM_DRAG_SLOP = 12;
+export const ZOOM_DRAG_WIDTH_LOSS_PER_POINT = 0.000698;
+export const ZOOM_DRAG_HEIGHT_LOSS_PER_POINT = 1.223 / 956;
+export const ZOOM_DRAG_BOTTOM_RISE = 2.94e-4;
+/** The edge back swipe zooms too (dark run, 3 swipes): the window shrinks uniformly by 0.66 of the
+ * finger's travel over the screen's width (0.0015 per point on a 440 pt screen), counted from the
+ * recognizer's 18 pt; its left edge follows the finger. 88 pt returned; 298 and 398 pt dismissed. */
+export const ZOOM_EDGE_SLOP = 18;
+export const ZOOM_EDGE_SCALE_LOSS = 0.66;
+/** A released drag dismisses past this distance down (native: 50 and 80 pt returned, 140 pt
+ * dismissed; an 80 pt flick at 849 pt/s still returned, so speed alone does not dismiss). */
+export const ZOOM_DISMISS_DISTANCE = 110;
+/** A drag starts once the finger has moved this far, mostly downward, from where it went down. */
+export const ZOOM_DRAG_START_DISTANCE = 10;

package/dist/navigation/zoomTransition.d.ts

@@ -0,0 +1,82 @@
+import type { NamespaceID } from '../motion/matchedGeometry.js';
+import type { TransitionBinding, TransitionController, TransitionControllerFactory } from './types.js';
+import { type ZoomRect } from './zoomGeometry.js';
+import { type ZoomSpring, type ZoomSprings } from './zoomMotion.js';
+type TransitionSource = Readonly<{
+    namespace: NamespaceID;
+    id: string;
+    wrapper: HTMLElement;
+}>;
+type ZoomRequest = Readonly<{
+    namespace: NamespaceID;
+    sourceID: string;
+}>;
+/** Registers a `MatchedTransitionSource`; returns its removal. */
+export declare function registerTransitionSource(source: TransitionSource): () => void;
+/** Registers a screen's `.navigationTransition(.zoom)`; returns its removal. */
+export declare function registerZoomRequest(entryKey: string, request: ZoomRequest): () => void;
+/**
+ * The source view a zoom of `entryKey` starts from or returns to, if it is on screen inside `rear`
+ * (and not inside `excluded`, the zoomed screen itself).
+ */
+export declare function visibleZoomSource(entryKey: string, rear: HTMLElement, excluded?: HTMLElement): HTMLElement | undefined;
+/** What a zoom-dismissing drag needs from its transition. */
+export type ZoomDragHandle = Readonly<{
+    /** Moves the screen with the finger: translation in points since the finger went down. */
+    track(translation: Readonly<{
+        x: number;
+        y: number;
+    }>): void;
+    /** Lets go: dismisses into the source or returns to full screen. Velocity in points/second. */
+    release(velocity: Readonly<{
+        x: number;
+        y: number;
+    }>): void;
+}>;
+/**
+ * Whether `controller` runs as a zoom once bound to `binding`. Deciding is idempotent and can
+ * happen before the binding is handed over (the navigator prepares glass first).
+ */
+export declare function decideZoomTransition(controller: TransitionController, binding: TransitionBinding): boolean;
+/** The drag handle of an interactive pop that a zoom drag started, once the pop is a zoom. */
+export declare function zoomDragHandleOf(controller: TransitionController | undefined): Readonly<{
+    /** Moves the screen with the finger: translation in points since the finger went down. */
+    track(translation: Readonly<{
+        x: number;
+        y: number;
+    }>): void;
+    /** Lets go: dismisses into the source or returns to full screen. Velocity in points/second. */
+    release(velocity: Readonly<{
+        x: number;
+        y: number;
+    }>): void;
+}> | undefined;
+/**
+ * Marks the next interactive pop of `entryKey` as a zoom drag (not the edge back swipe). The touch
+ * position is where the finger went down, which stays under the finger as the screen shrinks.
+ */
+export declare function beginZoomDrag(entryKey: string, touchDown: Readonly<{
+    x: number;
+    y: number;
+}>): void;
+/**
+ * Wraps the slide controller factory: each transition binds first, then runs as a zoom when its
+ * screens asked for one, and as the unchanged slide otherwise.
+ */
+export declare function withZoomTransitions(createSlide: TransitionControllerFactory): TransitionControllerFactory;
+type WindowFrame = Readonly<{
+    ms: number;
+    rect: ZoomRect;
+}>;
+/**
+ * The 60 Hz frames of one window run, as native moves it: the window's centre follows one spring
+ * and its size another (a push moves the width with the centre and the height on its own spring).
+ * The finger's velocity starts the centre moving.
+ */
+export declare function windowKeyframes(from: ZoomRect, to: ZoomRect, springs: ZoomSprings & {
+    height?: ZoomSpring;
+}, velocity: Readonly<{
+    x: number;
+    y: number;
+}>): WindowFrame[];
+export {};