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

package/dist/motion/springPath.d.ts

@@ -0,0 +1,27 @@
+import { type Animation } from './animationValue.js';
+/**
+ * One value moving to its target on a spring. The spring is linear, so the offset from the
+ * target at time t is `displacement · a(t) + velocity · b(t)`, where a is the response to a unit
+ * displacement at rest and b the response to a unit initial velocity with no displacement. That
+ * form lets an interrupted run hand its exact position and velocity to the next one, including
+ * a value that is already at its new target but still moving.
+ */
+export type SpringChannel = Readonly<{
+    displacement: number;
+    velocity: number;
+}>;
+/** Offset from the target and its velocity (per second) `ms` after the run started. */
+export declare function sampleChannel(animation: Animation, channel: SpringChannel, ms: number): {
+    offset: number;
+    velocity: number;
+};
+/** Progress from 0 to 1 of a run that starts at rest: what opacity follows. */
+export declare function sampleProgress(animation: Animation, ms: number): number;
+/**
+ * The 60 Hz frame times of a run, up to the frame after every channel has come within
+ * REST_TOLERANCE of its target. WAAPI interpolates linearly between these dense samples, which
+ * keeps the measured curve instead of approximating it with a cubic-bezier.
+ */
+export declare function runFrameTimes(animation: Animation, channels: readonly SpringChannel[], minimumMs?: number): number[];
+/** When a fade from 0 to 1 is within 1% of its end: opacity steps below that are invisible. */
+export declare function fadeSettleMs(animation: Animation): number;

package/dist/motion/springPath.js

@@ -0,0 +1,46 @@
+import { menuSpring } from '../glass/lens/menuSpring.js';
+import { unitSpring } from './animationValue.js';
+/** Offset from the target and its velocity (per second) `ms` after the run started. */
+export function sampleChannel(animation, channel, ms) {
+    const atRest = menuSpring(unitSpring(animation, 0), ms);
+    const pushed = menuSpring(unitSpring(animation, 1), ms);
+    const kickValue = pushed.value - atRest.value;
+    const kickVelocity = pushed.velocity - atRest.velocity;
+    return {
+        offset: channel.displacement * atRest.value + channel.velocity * kickValue,
+        velocity: channel.displacement * atRest.velocity + channel.velocity * kickVelocity,
+    };
+}
+/** Progress from 0 to 1 of a run that starts at rest: what opacity follows. */
+export function sampleProgress(animation, ms) {
+    return 1 - menuSpring(unitSpring(animation, 0), ms).value;
+}
+const FRAME_MS = 1000 / 60;
+const LONGEST_RUN_MS = 3000;
+/** Below a third of a point the remaining travel is invisible at 3× on a phone. */
+const REST_TOLERANCE = 0.3;
+/**
+ * The 60 Hz frame times of a run, up to the frame after every channel has come within
+ * REST_TOLERANCE of its target. WAAPI interpolates linearly between these dense samples, which
+ * keeps the measured curve instead of approximating it with a cubic-bezier.
+ */
+export function runFrameTimes(animation, channels, minimumMs = 0) {
+    let lastMoving = 0;
+    for (let ms = 0; ms <= LONGEST_RUN_MS; ms += FRAME_MS) {
+        const moving = channels.some(channel => Math.abs(sampleChannel(animation, channel, ms).offset) > REST_TOLERANCE);
+        if (moving)
+            lastMoving = ms;
+    }
+    // Opacity-only runs still need the spring's visible fade time.
+    const settleMs = Math.max(lastMoving + FRAME_MS, minimumMs);
+    const frames = Math.max(1, Math.ceil(settleMs / FRAME_MS));
+    return Array.from({ length: frames + 1 }, (_, frame) => frame * FRAME_MS);
+}
+/** When a fade from 0 to 1 is within 1% of its end: opacity steps below that are invisible. */
+export function fadeSettleMs(animation) {
+    for (let ms = 0; ms <= LONGEST_RUN_MS; ms += FRAME_MS) {
+        if (sampleProgress(animation, ms) >= 0.99)
+            return ms;
+    }
+    return LONGEST_RUN_MS;
+}

package/dist/motion/springTrack.d.ts

@@ -0,0 +1,33 @@
+import { type MenuSpring } from '../glass/lens/menuSpring.js';
+/** A measured spring: SwiftUI's `.interpolatingSpring(stiffness:damping:)` with unit mass, released
+ * `delay` ms after the animation starts. */
+export type SpringParameters = Readonly<{
+    stiffness: number;
+    damping: number;
+    delay?: number;
+}>;
+/** The spring as a displacement from its target; `velocity` is normalised (travel per second). */
+export declare function springMotion(parameters: SpringParameters, velocity?: number): MenuSpring;
+/** Progress from 0 to 1 sampled once per 60 Hz frame until the spring settles. */
+export type SpringTrack = Readonly<{
+    duration: number;
+    progress: readonly number[];
+}>;
+export declare function springTrack(spring: MenuSpring): SpringTrack;
+/**
+ * Per-frame keyframes for WAAPI. WebKit runs keyframed transform and opacity animations on the
+ * compositor; a CSS `linear()` easing can fall back to the main thread (navigation/motion.ts).
+ */
+export declare function sampledKeyframes(track: SpringTrack, frame: (progress: number) => Keyframe): Keyframe[];
+/** An existing analytic motion fit sampled on one uniform time grid. Values may be
+ * points rather than normalized progress; no spring parameters are changed here. */
+export type SampledMotionTrack = Readonly<{
+    duration: number;
+    values: readonly number[];
+}>;
+export declare function sampledMotionTrack(duration: number, sample: (milliseconds: number) => number, tolerance?: number): SampledMotionTrack;
+/** Read the submitted segment, including its velocity, when a run is interrupted. */
+export declare function sampledMotionState(track: SampledMotionTrack, milliseconds: number): {
+    value: number;
+    velocity: number;
+};

package/dist/motion/springTrack.js

@@ -0,0 +1,69 @@
+import { menuSpring, menuSpringSettle } from '../glass/lens/menuSpring.js';
+const FRAME_MS = 1000 / 60;
+/** The spring as a displacement from its target; `velocity` is normalised (travel per second). */
+export function springMotion(parameters, velocity = 0) {
+    const omega = Math.sqrt(parameters.stiffness);
+    return {
+        delay: parameters.delay ?? 0,
+        omega,
+        zeta: parameters.damping / (2 * omega),
+        velocity,
+    };
+}
+export function springTrack(spring) {
+    const duration = Math.max(FRAME_MS, menuSpringSettle(spring));
+    const frames = Math.ceil(duration / FRAME_MS);
+    const progress = [];
+    for (let frame = 0; frame <= frames; frame++) {
+        progress.push(frame === frames ? 1 : 1 - menuSpring(spring, frame * FRAME_MS).value);
+    }
+    return { duration: frames * FRAME_MS, progress };
+}
+/**
+ * Per-frame keyframes for WAAPI. WebKit runs keyframed transform and opacity animations on the
+ * compositor; a CSS `linear()` easing can fall back to the main thread (navigation/motion.ts).
+ */
+export function sampledKeyframes(track, frame) {
+    const last = track.progress.length - 1;
+    return track.progress.map((progress, index) => ({ ...frame(progress), offset: index / last }));
+}
+export function sampledMotionTrack(duration, sample, tolerance = 0.2) {
+    if (!(duration > 0) || !Number.isFinite(duration) || !(tolerance > 0) || !Number.isFinite(tolerance))
+        throw Error('Motion tracks require a finite positive duration and tolerance');
+    let count = Math.max(1, Math.ceil(duration / (1000 / 120)));
+    // GPU and compositor consumers require even offsets. Refine the whole grid,
+    // rather than giving them independent adaptive sample positions.
+    while (count <= 4096) {
+        const values = Array.from({ length: count + 1 }, (_, index) => sample(duration * index / count));
+        if (!values.every(Number.isFinite))
+            throw Error('Motion track contains a non-finite value');
+        let accurate = true;
+        for (let index = 0; accurate && index < count; index++) {
+            for (const fraction of [0.25, 0.5, 0.75]) {
+                const exact = sample(duration * (index + fraction) / count);
+                const linear = values[index] + (values[index + 1] - values[index]) * fraction;
+                if (!Number.isFinite(exact))
+                    throw Error('Motion track contains a non-finite value');
+                if (Math.abs(exact - linear) > tolerance) {
+                    accurate = false;
+                    break;
+                }
+            }
+        }
+        if (accurate)
+            return { duration, values };
+        count *= 2;
+    }
+    throw Error('Motion track exceeds its sampling error budget');
+}
+/** Read the submitted segment, including its velocity, when a run is interrupted. */
+export function sampledMotionState(track, milliseconds) {
+    const last = track.values.length - 1;
+    const position = Math.max(0, Math.min(last, milliseconds / track.duration * last));
+    const index = Math.min(last - 1, Math.floor(position));
+    const from = track.values[index], to = track.values[index + 1];
+    return {
+        value: from + (to - from) * (position - index),
+        velocity: milliseconds < 0 || milliseconds >= track.duration ? 0 : (to - from) * last / track.duration * 1000,
+    };
+}

package/dist/motion/transition.d.ts

@@ -0,0 +1,48 @@
+/** The edge a view moves through, resolved against its own layout direction. */
+export type TransitionEdge = 'top' | 'bottom' | 'leading' | 'trailing';
+type Effect = Readonly<{
+    kind: 'opacity';
+} | {
+    kind: 'scale';
+    scale: number;
+} | {
+    kind: 'move';
+    edge: TransitionEdge;
+}>;
+/** Immutable insertion and removal effects. Timing belongs to withAnimation. */
+export type Transition = Readonly<{
+    insertion: readonly Effect[];
+    removal: readonly Effect[];
+}>;
+declare function move(edge: TransitionEdge): Transition;
+declare function scale(value?: number): Transition;
+declare function asymmetric(insertion: Transition, removal: Transition): Transition;
+declare function combined(...transitions: readonly Transition[]): Transition;
+export declare const Transition: Readonly<{
+    identity: Readonly<{
+        insertion: readonly Effect[];
+        removal: readonly Effect[];
+    }>;
+    opacity: Readonly<{
+        insertion: readonly Effect[];
+        removal: readonly Effect[];
+    }>;
+    move: typeof move;
+    scale: typeof scale;
+    slide: Readonly<{
+        insertion: readonly Effect[];
+        removal: readonly Effect[];
+    }>;
+    push: (edge: TransitionEdge) => Transition;
+    asymmetric: typeof asymmetric;
+    combined: typeof combined;
+}>;
+export type TransitionPose = Readonly<{
+    x: number;
+    y: number;
+    scale: number;
+    opacity: number;
+}>;
+export declare const identityPose: TransitionPose;
+export declare function transitionPose(transition: Transition, phase: 'insertion' | 'removal', width: number, height: number, rtl: boolean): TransitionPose;
+export {};

package/dist/motion/transition.js

@@ -0,0 +1,56 @@
+function effects(insertion, removal = insertion) {
+    return Object.freeze({
+        insertion: Object.freeze(insertion.map(effect => Object.freeze({ ...effect }))),
+        removal: Object.freeze(removal.map(effect => Object.freeze({ ...effect }))),
+    });
+}
+function move(edge) {
+    return effects([{ kind: 'move', edge }]);
+}
+function scale(value = 0) {
+    if (!Number.isFinite(value) || value < 0)
+        throw new Error('Transition scale must be finite and non-negative.');
+    return effects([{ kind: 'scale', scale: value }]);
+}
+function asymmetric(insertion, removal) {
+    return effects(insertion.insertion, removal.removal);
+}
+function combined(...transitions) {
+    return effects(transitions.flatMap(value => value.insertion), transitions.flatMap(value => value.removal));
+}
+const opacity = effects([{ kind: 'opacity' }]);
+export const Transition = Object.freeze({
+    identity: effects([]),
+    opacity,
+    move,
+    scale,
+    slide: asymmetric(move('leading'), move('trailing')),
+    push: (edge) => {
+        const opposite = {
+            top: 'bottom',
+            bottom: 'top',
+            leading: 'trailing',
+            trailing: 'leading',
+        };
+        return combined(opacity, asymmetric(move(edge), move(opposite[edge])));
+    },
+    asymmetric,
+    combined,
+});
+export const identityPose = { x: 0, y: 0, scale: 1, opacity: 1 };
+export function transitionPose(transition, phase, width, height, rtl) {
+    let x = 0, y = 0, scale = 1, opacity = 1;
+    for (const effect of transition[phase]) {
+        if (effect.kind === 'opacity')
+            opacity = 0;
+        else if (effect.kind === 'scale')
+            scale *= effect.scale;
+        else if (effect.edge === 'top')
+            y -= height;
+        else if (effect.edge === 'bottom')
+            y += height;
+        else
+            x += (effect.edge === 'leading' ? -1 : 1) * (rtl ? -1 : 1) * width;
+    }
+    return { x, y, scale, opacity };
+}

package/dist/motion/transitionImages.d.ts

@@ -0,0 +1,7 @@
+/** A DOM clone is a new image consumer in WebKit, even when its URL is already cached.
+ * Freeze responsive selection to the displayed resource and decode each copied node before
+ * showing it. Keep the original nodes in their React tree throughout the transition. */
+export declare function prepareClonedImages(source: HTMLElement, clone: HTMLElement): Promise<void> | undefined;
+/** Covered routes may have lost their decoded pixels without changing URLs. Revalidate
+ * the displayed nodes before a pop reveals them; a retained cache promise is insufficient. */
+export declare function prepareRevealedImages(root: HTMLElement): Promise<void>;

package/dist/motion/transitionImages.js

@@ -0,0 +1,49 @@
+import { imageCapture, paintedImage, settleContentImage, emptyImageSource, } from '../image/resource.js';
+/** A DOM clone is a new image consumer in WebKit, even when its URL is already cached.
+ * Freeze responsive selection to the displayed resource and decode each copied node before
+ * showing it. Keep the original nodes in their React tree throughout the transition. */
+export function prepareClonedImages(source, clone) {
+    const images = (root) => [
+        ...(root instanceof HTMLImageElement ? [root] : []),
+        ...root.querySelectorAll('img'),
+    ];
+    const originals = images(source);
+    const copies = images(clone);
+    if (!copies.length)
+        return undefined;
+    return Promise.all(copies.map(async (copy, index) => {
+        const original = originals[index];
+        const pixels = await paintedImage(original);
+        copy.removeAttribute('srcset');
+        copy.removeAttribute('sizes');
+        copy.loading = 'eager';
+        copy.decoding = 'sync';
+        copy.src = pixels ? original.currentSrc || original.src : emptyImageSource;
+        const decoded = await settleContentImage(copy.decode().then(() => copy));
+        if (!decoded)
+            copy.src = emptyImageSource;
+    })).then(() => { });
+}
+/** Covered routes may have lost their decoded pixels without changing URLs. Revalidate
+ * the displayed nodes before a pop reveals them; a retained cache promise is insufficient. */
+export async function prepareRevealedImages(root) {
+    const images = [
+        ...(root instanceof HTMLImageElement ? [root] : []),
+        ...root.querySelectorAll('img'),
+    ];
+    await Promise.all(images.map(async (image) => {
+        // Hidden prewarm descendants do not contribute to the revealed route. Their
+        // removal must not cancel its preparation. Stop at the route root: a covered
+        // route itself may be hidden while its displayed images still need decode.
+        for (let ancestor = image; ancestor && ancestor !== root; ancestor = ancestor.parentElement) {
+            if (ancestor.hidden || getComputedStyle(ancestor).display === 'none')
+                return;
+        }
+        const capture = imageCapture(image);
+        if (!capture)
+            return;
+        const pixels = await settleContentImage(capture.ready);
+        if (pixels)
+            await settleContentImage(image.decode().then(() => image));
+    }));
+}

package/dist/motionProbe.d.ts

@@ -0,0 +1,227 @@
+/** Opt-in CPU/API telemetry. Never interprets rAF timestamps as display scanout. */
+export type MotionKind = 'push' | 'pop-scrub' | 'pop-release' | 'pop' | 'minimize' | 'restore' | 'tab-switch' | 'menu-open' | 'menu-close' | 'menu-drag';
+type Frame = {
+    at: number;
+    delta: number;
+    callbackMs: number;
+    callbacks: number;
+    input: number;
+    styleWrites: number;
+    otherStyleWrites: number;
+    gl: number;
+    uploads: number;
+    mirrorRebuilds: number;
+};
+type MotionWindow = {
+    inputStart?: number;
+    contactFrames?: Frame[];
+    id: number;
+    kind: MotionKind;
+    owner: string;
+    start: number;
+    end?: number;
+    interrupted?: boolean;
+    frames: Frame[];
+    inputTimes: number[];
+    styles: Record<string, number>;
+};
+export declare function recordMotionEventCost(kind: string, start: number, end: number): void;
+export declare function recordNavigationGlassFrame(value: unknown): void;
+export declare function recordMotionPreparation(value: unknown): void;
+/** Opt-in swipe trace (scripts/test-support/recorder.js): a diagnostic sink the page installs on
+ * `globalThis.__SATIN_SWIPE_TRACE__` before the app bundle loads. Normal builds never install
+ * it, so every hook below is one test of a module constant. The sink receives the same records
+ * as the motion probe's preparations plus the live navigation tracks, which it samples itself. */
+export type SwipeTraceTrack = {
+    animation: Animation;
+    /** outgoing, incoming, outgoing-title, incoming-title, title-clip, title-content, dim, back-button, chrome */
+    role: string;
+    /** Layer width in CSS pixels: translate3d percentages resolve against it. */
+    width: number;
+};
+export declare const swipeTraceEnabled: () => boolean;
+/** Hand a navigation phase's tracks to the swipe trace. Call only when `swipeTraceEnabled()`. */
+export declare function traceNavigationTracks(phase: string, tracks: SwipeTraceTrack[]): void;
+export declare function motionPreparationEnabled(): boolean;
+export declare function beginMotionProbe(kind: MotionKind, owner: string): () => void;
+export declare function countMotionProbe(name: 'gl' | 'uploads' | 'mirrorRebuilds', amount?: number): void;
+export declare function motionPercentile(values: readonly number[], p: number): number | null;
+export declare function summarizeMotionWindow(window: MotionWindow): {
+    id: number;
+    kind: MotionKind;
+    owner: string;
+    start: number;
+    end: number | undefined;
+    inputStart: number | undefined;
+    inputToSettlement: {
+        callbackMax: number | null;
+        maximumObservedGap: number | null;
+        uploads: number;
+        boundary: string;
+    } | undefined;
+    precedingFrame: Frame | undefined;
+    boundaryCallbackMax: number | null;
+    maximumObservedGap: number | null;
+    frames: number;
+    rafHz: number | null;
+    inputHz: number | null;
+    deltaP95: number | null;
+    callbackP95: number | null;
+    histogram: {
+        upper: string | number;
+        count: number;
+    }[];
+    totals: {
+        [k: string]: number;
+    };
+    glMax: number;
+    uploadsMax: number;
+    styles: Record<string, number>;
+};
+/** Install once before app mount; dispose restores the original rAF function. */
+export declare function installMotionProbe({ build, endpoint, sampleNavigationFrames, graphicsMode, }: {
+    build: string;
+    endpoint?: string;
+    sampleNavigationFrames?: boolean;
+    graphicsMode?: 'off' | 'submissions';
+}): {
+    report: (completed?: MotionWindow[]) => {
+        version: number;
+        glassProfile: {
+            firstPresent: import("./glass/webgpu/profile.js").GlassTiming | undefined;
+            firstReady: import("./glass/webgpu/profile.js").GlassTiming | undefined;
+            startup: import("./glass/webgpu/profile.js").GlassTiming[];
+            events: import("./glass/webgpu/profile.js").GlassTiming[];
+            frames: unknown[];
+            totals: {
+                [k: string]: {
+                    count: number;
+                    ms: number;
+                    maxMs: number;
+                };
+            };
+            boundary: string;
+        };
+        sampling: {
+            observerPending: boolean;
+            observerCallbacks: number;
+            uploadTimerPending: boolean;
+            idlePolicy: string;
+        };
+        navigationGlassFrames: unknown[];
+        graphicsMode: "off" | "submissions";
+        graphics: {
+            events: {
+                [key: string]: unknown;
+                at: number;
+                kind: string;
+            }[];
+            frames: unknown[];
+            droppedEvents: number;
+            droppedFrames: number;
+            boundary: string;
+        } | undefined;
+        pointerSamples: unknown[];
+        navigationFrames: unknown[];
+        sampleNavigationFrames: boolean;
+        navigationFrameBoundary: string;
+        touchSamples: unknown[];
+        eventCosts: {
+            kind: string;
+            start: number;
+            end: number;
+        }[];
+        preparations: unknown[];
+        svgApertureUpdates: number[];
+        scrollSamples: unknown[];
+        contacts: unknown[];
+        uploadsAvailable: boolean;
+        client: string;
+        build: string;
+        timeOrigin: number;
+        at: number;
+        url: string;
+        userAgent: string;
+        standalone: boolean;
+        navigation: {
+            historyLength: number;
+            screens: {
+                screen: string | undefined;
+                covered: string | undefined;
+                phase: string | undefined;
+                rect: any;
+            }[];
+            scroll: {
+                id: string | undefined;
+                x: number;
+                y: number;
+            }[];
+        };
+        nativeNavigation: {
+            ready: boolean;
+            x: number;
+            width: number;
+            scrollWidth: number;
+            host: any;
+            source: any;
+        } | undefined;
+        visibility: DocumentVisibilityState;
+        inputType: string;
+        supportedEntryTypes: readonly string[];
+        limitations: {
+            cpu: string;
+            longTasks: string;
+            uploads: string;
+            gl: string;
+            styleWrites: string;
+            cap: string;
+        };
+        longTasks: {
+            start: number;
+            duration: number;
+        }[];
+        inputTiming: unknown[];
+        experiments: unknown[];
+        idleFrames: Frame[];
+        windows: MotionWindow[];
+        summaries: {
+            id: number;
+            kind: MotionKind;
+            owner: string;
+            start: number;
+            end: number | undefined;
+            inputStart: number | undefined;
+            inputToSettlement: {
+                callbackMax: number | null;
+                maximumObservedGap: number | null;
+                uploads: number;
+                boundary: string;
+            } | undefined;
+            precedingFrame: Frame | undefined;
+            boundaryCallbackMax: number | null;
+            maximumObservedGap: number | null;
+            frames: number;
+            rafHz: number | null;
+            inputHz: number | null;
+            deltaP95: number | null;
+            callbackP95: number | null;
+            histogram: {
+                upper: string | number;
+                count: number;
+            }[];
+            totals: {
+                [k: string]: number;
+            };
+            glMax: number;
+            uploadsMax: number;
+            styles: Record<string, number>;
+        }[];
+        posted: number;
+        postedThrough: number;
+    };
+    post: () => Promise<boolean>;
+    createControls: () => HTMLElement;
+    readonly active: boolean;
+    dispose(): void;
+};
+export {};