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

package/dist/glass/capability.js

@@ -0,0 +1,63 @@
+export function resolveGlassCapability({ forcedBaseline, reducedTransparency, renderTest, }) {
+    if (forcedBaseline)
+        return { reason: 'forced-baseline', state: 'baseline' };
+    if (reducedTransparency) {
+        return { reason: 'reduced-transparency', state: 'baseline' };
+    }
+    if (renderTest === 'pending') {
+        return { reason: 'render-test-pending', state: 'baseline' };
+    }
+    if (renderTest === 'failed') {
+        return { reason: 'render-test-failed', state: 'baseline' };
+    }
+    return { reason: 'raster-probe-passed', state: 'displacement' };
+}
+function loadImage(source) {
+    return new Promise((resolve, reject) => {
+        const image = new Image();
+        image.onload = () => resolve(image);
+        image.onerror = () => reject(new Error('The foreground SVG render probe did not load.'));
+        image.src = source;
+    });
+}
+/**
+ * Paints a deliberately displaced standalone SVG image into a readable canvas
+ * and verifies the resulting pixels. This is a raster-path prerequisite, not a
+ * live-compositor proof: WebKit can pass this Image -> canvas path while an SVG
+ * filter referenced by a live HTML element paints no displacement. JavaScript
+ * has no pixel-read API for the latter; installed-PWA capture and the lens-boost
+ * diagnostic remain the acceptance boundary.
+ */
+export async function runForegroundSvgRenderTest() {
+    if (typeof document === 'undefined' || typeof Image === 'undefined')
+        return false;
+    const svg = [
+        '<svg xmlns="http://www.w3.org/2000/svg" width="18" height="2" viewBox="0 0 18 2">',
+        '<defs><filter id="d" x="0" y="0" width="18" height="2" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">',
+        '<feFlood flood-color="rgb(255 128 128)" result="map"/>',
+        '<feDisplacementMap in="SourceGraphic" in2="map" scale="6" xChannelSelector="R" yChannelSelector="G"/>',
+        '</filter></defs>',
+        '<g id="source"><rect width="9" height="2" fill="black"/><rect x="9" width="9" height="2" fill="white"/></g>',
+        '<use href="#source" filter="url(#d)"/>',
+        '</svg>',
+    ].join('');
+    const source = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;
+    try {
+        const image = await loadImage(source);
+        const canvas = document.createElement('canvas');
+        canvas.width = 18;
+        canvas.height = 2;
+        const context = canvas.getContext('2d', { willReadFrequently: true });
+        if (!context)
+            return false;
+        context.drawImage(image, 0, 0);
+        // Without displacement x=7 is black. A +3 px foreground sample makes it
+        // white. Keep a wide threshold so color-management rounding cannot decide
+        // the gate.
+        const pixel = context.getImageData(7, 1, 1, 1).data;
+        return pixel[0] > 220 && pixel[1] > 220 && pixel[2] > 220 && pixel[3] > 220;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/glass/captureWindow.d.ts

@@ -0,0 +1,60 @@
+/** Renderer-independent content-space interval for a backdrop capture. */
+export type CaptureWindow = {
+    top: number;
+    bottom: number;
+    viewport: number;
+};
+export declare function filterCaptureNodes<Node extends {
+    y: number;
+    height: number;
+}>(nodes: readonly Node[], window: CaptureWindow, paintOverflow?: number): Node[];
+/** How far beyond the scrollport a glass surface samples its backdrop: the sample overscan of a
+ * surface (GLASS_OVERSCAN_Y_PX in lens/Scene.tsx, renderSpecs.ts `sampleInsetY`). A window covers
+ * the scrollport only when it holds this much content either side of it (or reaches the content's
+ * end): a lens at the scrollport's edge must never sample past the window. */
+export declare const LENS_REACH_POINTS = 128;
+/** Content either side of the scrollport in an entry window, beyond the lens reach, in
+ * scrollports: room to scroll before the first recentre (more than the recentre guard). */
+export declare const ENTRY_MARGIN_VIEWPORTS = 0.15;
+/** A Canvas2D taller than this is rasterized on the CPU in WebKit (device pixels). */
+export declare const ACCELERATED_CANVAS_PIXELS = 8192;
+/** Share of a recentred window's spare extent that lies ahead in the direction of travel. */
+export declare const RECENTRE_AHEAD_SHARE = 0.75;
+/** A recentre starts while the scrollport is still this far from the window's edge (scrollports)… */
+export declare const RECENTRE_GUARD_VIEWPORTS = 0.125;
+/** …or as far as the scroll travels in this many seconds, whichever is larger. */
+export declare const RECENTRE_LEAD_SECONDS = 0.2;
+export type CaptureWindowRequest = {
+    scrollTop: number;
+    viewport: number;
+    contentHeight: number;
+    resolution: number;
+    /** What the plane holds now: a window, the whole content ('full'), or nothing. */
+    current?: CaptureWindow | 'full';
+    /** The scene is idle: an entry window may grow. */
+    grow: boolean;
+    /** Signed scroll speed in points per second (positive: towards the end of the content). */
+    velocity: number;
+};
+/** Device pixels needed to cover `value` points. Window edges are texel multiples held in floating
+ * point, so a window of exactly 8192 px can measure 8192.000000004 px; that rounding error must not
+ * round up to another pixel (and past the accelerated-canvas limit). */
+export declare const texelCount: (value: number, resolution: number) => number;
+/** The largest extent a grown or recentred window takes, in points: one accelerated canvas.
+ * (A phone plane of that extent is 43 MB, more than the resident budget keeps for one plane, so
+ * a grown window is captured again, as an entry, when its tab comes back.) */
+export declare function grownExtent(request: Pick<CaptureWindowRequest, 'viewport' | 'resolution'>): number;
+/** How far ahead of the scrollport a window must still reach before a recentre starts. */
+export declare function recentreGuard(viewport: number, velocity: number): number;
+/** Whether `window` holds everything glass over a scrollport of `viewport` points at `scrollTop`
+ * can sample: the scrollport and the lens reach either side, up to the ends of the content.
+ * The scrollport is the one the host has NOW: a window captured while the keyboard was up, or in
+ * landscape, does not cover the taller scrollport that follows (`window.viewport` is only what
+ * the window was captured for). */
+export declare function windowCoversScrollport(window: CaptureWindow, scrollTop: number, viewport: number, contentHeight: number): boolean;
+/** Whether `window` no longer reaches far enough around the scrollport at `scrollTop`: it does
+ * not cover it (windowCoversScrollport), or its edge in a direction that has more content is
+ * inside the guard. `viewport` is the host's scrollport now. */
+export declare function captureWindowExhausted(window: CaptureWindow, scrollTop: number, contentHeight: number, velocity: number, viewport?: number): boolean;
+/** The capture window of a scrolling plane, or undefined for a capture of the whole content. */
+export declare function planCaptureWindow(request: CaptureWindowRequest): CaptureWindow | undefined;

package/dist/glass/captureWindow.js

@@ -0,0 +1,119 @@
+export function filterCaptureNodes(nodes, window, paintOverflow = 64) {
+    return nodes.filter(node => node.y + node.height >= window.top - paintOverflow && node.y <= window.bottom + paintOverflow);
+}
+// ---------------------------------------------------------------------------------------------
+// Bounded capture: a scrolling plane captures a window around its scrollport. Small sources
+// are captured whole; longer lists keep the capture within one accelerated canvas.
+//
+//   entry    the first capture of a visit: the scrollport, what a lens samples beyond it, and
+//            a small margin, either side.
+//   grown    once the scene has been idle, and at every recentre: as much content as one
+//            accelerated canvas holds (the whole content when it fits, and then the plane has
+//            no window and needs none again).
+//   recentre while scrolling, before the scrollport reaches the window's edge: the same extent,
+//            placed ahead in the direction of travel.
+//
+// A window the plane already holds is kept for as long as it covers the scrollport with the
+// guard to spare (a tab comes back to the capture it left with, and nothing is captured).
+/** How far beyond the scrollport a glass surface samples its backdrop: the sample overscan of a
+ * surface (GLASS_OVERSCAN_Y_PX in lens/Scene.tsx, renderSpecs.ts `sampleInsetY`). A window covers
+ * the scrollport only when it holds this much content either side of it (or reaches the content's
+ * end): a lens at the scrollport's edge must never sample past the window. */
+export const LENS_REACH_POINTS = 128;
+/** Content either side of the scrollport in an entry window, beyond the lens reach, in
+ * scrollports: room to scroll before the first recentre (more than the recentre guard). */
+export const ENTRY_MARGIN_VIEWPORTS = 0.15;
+/** A Canvas2D taller than this is rasterized on the CPU in WebKit (device pixels). */
+export const ACCELERATED_CANVAS_PIXELS = 8192;
+/** Share of a recentred window's spare extent that lies ahead in the direction of travel. */
+export const RECENTRE_AHEAD_SHARE = 0.75;
+/** A recentre starts while the scrollport is still this far from the window's edge (scrollports)… */
+export const RECENTRE_GUARD_VIEWPORTS = 0.125;
+/** …or as far as the scroll travels in this many seconds, whichever is larger. */
+export const RECENTRE_LEAD_SECONDS = 0.2;
+const texelFloor = (value, resolution) => Math.floor(value * resolution) / resolution;
+/** Device pixels needed to cover `value` points. Window edges are texel multiples held in floating
+ * point, so a window of exactly 8192 px can measure 8192.000000004 px; that rounding error must not
+ * round up to another pixel (and past the accelerated-canvas limit). */
+export const texelCount = (value, resolution) => Math.ceil(value * resolution - 1e-6);
+/** The largest extent a grown or recentred window takes, in points: one accelerated canvas.
+ * (A phone plane of that extent is 43 MB, more than the resident budget keeps for one plane, so
+ * a grown window is captured again, as an entry, when its tab comes back.) */
+export function grownExtent(request) {
+    return Math.max(request.viewport, ACCELERATED_CANVAS_PIXELS / request.resolution);
+}
+/** How far ahead of the scrollport a window must still reach before a recentre starts. */
+export function recentreGuard(viewport, velocity) {
+    return Math.max(viewport * RECENTRE_GUARD_VIEWPORTS, Math.abs(velocity) * RECENTRE_LEAD_SECONDS);
+}
+/** Whether `window` holds everything glass over a scrollport of `viewport` points at `scrollTop`
+ * can sample: the scrollport and the lens reach either side, up to the ends of the content.
+ * The scrollport is the one the host has NOW: a window captured while the keyboard was up, or in
+ * landscape, does not cover the taller scrollport that follows (`window.viewport` is only what
+ * the window was captured for). */
+export function windowCoversScrollport(window, scrollTop, viewport, contentHeight) {
+    const needTop = Math.max(0, scrollTop - LENS_REACH_POINTS);
+    const needBottom = Math.min(contentHeight, scrollTop + viewport + LENS_REACH_POINTS);
+    return window.top <= needTop + 1 / 64 && window.bottom >= needBottom - 1 / 64;
+}
+/** Whether `window` no longer reaches far enough around the scrollport at `scrollTop`: it does
+ * not cover it (windowCoversScrollport), or its edge in a direction that has more content is
+ * inside the guard. `viewport` is the host's scrollport now. */
+export function captureWindowExhausted(window, scrollTop, contentHeight, velocity, viewport = window.viewport) {
+    if (!windowCoversScrollport(window, scrollTop, viewport, contentHeight))
+        return true;
+    const guard = recentreGuard(viewport, velocity);
+    const before = scrollTop - LENS_REACH_POINTS - window.top;
+    const after = window.bottom - (scrollTop + viewport + LENS_REACH_POINTS);
+    // Only the direction of travel needs the lead; at rest both edges keep the small guard.
+    const rest = viewport * RECENTRE_GUARD_VIEWPORTS;
+    const beforeGuard = velocity < 0 ? guard : rest;
+    const afterGuard = velocity > 0 ? guard : rest;
+    return ((window.top > 0 && before < beforeGuard) ||
+        (window.bottom < contentHeight - 1 / 64 && after < afterGuard));
+}
+/** The capture window of a scrolling plane, or undefined for a capture of the whole content. */
+export function planCaptureWindow(request) {
+    const { scrollTop, viewport, contentHeight, resolution, current, grow, velocity } = request;
+    if (![scrollTop, viewport, contentHeight, resolution, velocity].every(Number.isFinite))
+        throw Error('Capture window geometry must be finite');
+    if (viewport <= 0 || resolution <= 0)
+        throw Error('Capture window geometry is invalid');
+    const largest = grownExtent(request);
+    // Overscan cannot turn content above the accelerated limit into a whole-content capture.
+    const entryExtent = Math.min(largest, viewport + 2 * (LENS_REACH_POINTS + viewport * ENTRY_MARGIN_VIEWPORTS));
+    // Content that an entry window would hold anyway is captured whole: no window to manage.
+    if (contentHeight <= entryExtent)
+        return undefined;
+    const fitsWhole = contentHeight <= largest;
+    if (current === 'full') {
+        if (fitsWhole)
+            return undefined;
+    }
+    else if (current) {
+        const exhausted = captureWindowExhausted(current, scrollTop, contentHeight, velocity, viewport);
+        const grown = current.bottom - current.top >= Math.min(contentHeight, largest) - 1 / 64;
+        // Kept with its pixels; it records the scrollport it serves now.
+        if (!exhausted && (grown || !grow))
+            return current.viewport === viewport ? current : { ...current, viewport };
+    }
+    const place = (extent, aheadShare) => {
+        const spare = extent - viewport;
+        const desired = scrollTop - spare * (1 - aheadShare);
+        const top = texelFloor(Math.max(0, Math.min(contentHeight - extent, desired)), resolution);
+        return { top, bottom: top + extent, viewport };
+    };
+    // A jump while at rest (a scroll-to-top tap, a scripted scroll) is an entry at the new place:
+    // the small window is installed soonest, and it grows when the scene is idle again.
+    const jumped = current !== undefined &&
+        current !== 'full' &&
+        velocity === 0 &&
+        !windowCoversScrollport(current, scrollTop, viewport, contentHeight);
+    const first = current === undefined || jumped;
+    if (first && !grow)
+        return place(texelFloor(entryExtent, resolution), 0.5);
+    if (fitsWhole)
+        return undefined;
+    const ahead = velocity > 0 ? RECENTRE_AHEAD_SHARE : velocity < 0 ? 1 - RECENTRE_AHEAD_SHARE : 0.5;
+    return place(texelFloor(largest, resolution), ahead);
+}

package/dist/glass/confusionSession.d.ts

@@ -0,0 +1,41 @@
+export type ConfusionPair = Readonly<{
+    id: string;
+    backdrop: string;
+    appearance: 'light' | 'dark';
+    state: string;
+    kind: 'still' | 'clip';
+    native: string;
+    pwa: string;
+    widthPt: number;
+    heightPt: number;
+    frames?: number;
+    fps?: number;
+    build: string;
+}>;
+export type ConfusionManifest = Readonly<{
+    version: string;
+    status: string;
+    pairs: readonly ConfusionPair[];
+    pending: readonly string[];
+}>;
+export type ConfusionTrial = {
+    pairId: string;
+    nativeLeft: boolean;
+    guess?: 'left' | 'right';
+    guessedAt?: string;
+    revealed: boolean;
+};
+export type ConfusionSession = {
+    id: string;
+    manifestVersion: string;
+    startedAt: string;
+    trials: ConfusionTrial[];
+};
+export declare function makeConfusionSession(manifest: ConfusionManifest): ConfusionSession;
+export declare function scoreConfusion(trials: readonly ConfusionTrial[]): {
+    count: number;
+    hits: number;
+    hitRate: number | null;
+    chance: number;
+    interval95: number[] | null;
+};

package/dist/glass/confusionSession.js

@@ -0,0 +1,44 @@
+function randomInt(max) {
+    const ceiling = Math.floor(4294967296 / max) * max;
+    let value;
+    do {
+        value = crypto.getRandomValues(new Uint32Array(1))[0];
+    } while (value >= ceiling);
+    return value % max;
+}
+export function makeConfusionSession(manifest) {
+    const trials = manifest.pairs.map(pair => ({
+        pairId: pair.id,
+        nativeLeft: randomInt(2) === 0,
+        revealed: false,
+    }));
+    for (let i = trials.length - 1; i > 0; i--) {
+        const j = randomInt(i + 1);
+        [trials[i], trials[j]] = [trials[j], trials[i]];
+    }
+    return {
+        id: Array.from(crypto.getRandomValues(new Uint32Array(4)), x => x.toString(16)).join('-'),
+        manifestVersion: manifest.version,
+        startedAt: new Date().toISOString(),
+        trials,
+    };
+}
+export function scoreConfusion(trials) {
+    const scored = trials.filter(t => t.guess !== undefined);
+    const hits = scored.filter(t => (t.guess === 'left') === t.nativeLeft).length;
+    const n = scored.length;
+    const rate = n ? hits / n : null;
+    // Wilson interval expresses sampling uncertainty. It is not an equivalence test.
+    const z = 1.959963984540054, denominator = 1 + (z * z) / Math.max(1, n);
+    const center = n ? (hits / n + (z * z) / (2 * n)) / denominator : null;
+    const half = n
+        ? (z * Math.sqrt(((hits / n) * (1 - hits / n)) / n + (z * z) / (4 * n * n))) / denominator
+        : null;
+    return {
+        count: n,
+        hits,
+        hitRate: rate,
+        chance: 0.5,
+        interval95: center === null || half === null ? null : [center - half, center + half],
+    };
+}

package/dist/glass/contactPhysics.d.ts

@@ -0,0 +1,130 @@
+export declare function menuPull(displacement: number, gain: number, range: number): number;
+export declare const MENU_RELEASE_SPRING: Readonly<{
+    stiffness: 111.73389187035956;
+    damping: 10.51444760548088;
+    delayMilliseconds: 4.941103419008078;
+}>;
+export declare function menuReturn(milliseconds: number): number;
+export declare const MENU_STRAIN_RESPONSE_MS = 109.7745877972179;
+export declare const MENU_TRIGGER_FOLLOW: Readonly<{
+    gainX: 0.028852199054395337;
+    gainY: 0.01683370428028321;
+    rangePt: 300;
+    responseMs: 211.1299624689032;
+}>;
+/** The menu panel's velocity strain, in seconds of finger velocity: the panel leads along the
+ * motion (x, y), stretches along it and narrows across it. */
+export declare const MENU_STRAIN: Readonly<{
+    leadXSeconds: 0.003524681648458459;
+    leadYSeconds: 0.0042655868076027946;
+    stretchSeconds: 0.004789086076060811;
+    narrowSeconds: 0.006870711203430614;
+}>;
+/**
+ * The kinds of interactive glass. Every interactive glass surface presses through the one contact
+ * (glassContact.ts in the document, InteractiveContact + InteractivePress in the glass worker);
+ * the kind only picks its parameters.
+ *
+ * - `button`: a glass Button in content (`.buttonStyle(.glass)`, `.glassProminent`, any shape).
+ * - `bar`: a toolbar or navigation-bar button, toolbar group, back/close/sidebar chrome buttons.
+ * - `menu`: a Menu's trigger (its glass becomes the menu).
+ * - `field`: interactive glass hosting one text editor (TextField, TextEditor, a composer).
+ * - `surface`: any other app `glassEffect(.regular.interactive())` shape: cards, the bottom
+ *   accessory, the mini player.
+ *
+ * Track thumbs (Toggle, Slider) take their finger through the same contact and respond as the
+ * thumb note at the end of this file describes. Contacts with their own measured engines use this table's laws
+ * through other entry points: the open menu panel (menuGesture: MENU_STRAIN, menuReturn, the menu
+ * touch light) and the tab bar's dragged selection (tabMotion).
+ */
+export type GlassContactKind = 'button' | 'bar' | 'menu' | 'field' | 'surface' | 'segmented';
+/** The kinds a framework control declares (`press`); `field` and `surface` follow from content. */
+export type GlassPressKind = 'button' | 'bar' | 'menu';
+/**
+ * OWNER DECISION PENDING (Oct 12): which kinds of interactive glass let a horizontal drag that
+ * starts on them start the navigation back swipe.
+ *
+ * - `[]` (current): every interactive glass owns its horizontal drag; it stretches toward the
+ *   finger and never navigates.
+ * - `['button']` (native, iPad catalog Oct 13): a rightward drag that starts on a content glass
+ *   button drives the back swipe while the button stays pressed and moves with the page; its tap
+ *   cancels. Add `'bar'` / `'menu'` to extend that to toolbar buttons and menu triggers.
+ *
+ * Fields always own their drag (a composer drag must not open the iPad split pane), as do
+ * surfaces, Toggles and Sliders.
+ */
+export declare const GLASS_BACK_SWIPE: {
+    yieldingKinds: readonly GlassPressKind[];
+};
+/** A highlight curve: [ms since touch-down, white amount over the glass]. */
+export type HighlightCurve = readonly (readonly [number, number])[];
+export type GlassContactParameters = Readonly<{
+    /** Uniform press growth: the shape grows this many points wide (INTERACTIVE_GLASS_PRESS). */
+    growthPt: number;
+    /** The held shape trailing the finger: menuPull gains per point over `rangePt`, approached
+     * with `responseMs`. */
+    follow: Readonly<{
+        gainX: number;
+        gainY: number;
+        rangePt: number;
+        responseMs: number;
+    }>;
+    /** Squish while the finger moves: the menu panel's velocity strain. */
+    strain: typeof MENU_STRAIN;
+    /** Pose limits in CSS px. They keep the pose inside the press growth's sampling margin. */
+    maxOffset: number;
+    maxSizeChange: number;
+    /**
+     * Light of the pressed glass. `whole`: a white curve across the whole shape (buttons, measured
+     * per appearance, released linearly over `releaseMs`). `finger`: the menu's touch light at the
+     * finger, scaled to the menu field, over a held floor across the shape (surfaces).
+     */
+    light: Readonly<{
+        kind: 'whole';
+        light: HighlightCurve;
+        dark: HighlightCurve;
+        releaseMs: Readonly<{
+            light: number;
+            dark: number;
+        }>;
+    }> | Readonly<{
+        kind: 'finger';
+        scale: number;
+        floor: number;
+        menuPeak: number;
+    }>;
+    /**
+     * The label above the glass (live DOM): `steady` keeps it at full strength; a curve gives its
+     * opacity [ms, opacity] while held, returning over the glass's release.
+     */
+    label: Readonly<{
+        light: HighlightCurve | 'steady';
+        dark: HighlightCurve | 'steady';
+    }>;
+}>;
+/** The contact kind of an interactive glass material. */
+export declare function glassContactKind(material: {
+    press?: GlassPressKind;
+    field?: true;
+}): GlassContactKind;
+export declare const GLASS_CONTACT_PHYSICS: Readonly<Record<GlassContactKind, GlassContactParameters>>;
+/**
+ * Track thumbs: a Toggle's or a Slider's thumb is a lens on a track. Its finger arrives through
+ * the same GlassContact as every interactive glass (glassContact.ts); its response differs from a
+ * free shape's in ways native shows, so it has its own rows:
+ *
+ * - Follow: the thumb follows the finger 1:1 along its track, clamped to the travel's ends (the
+ *   value moves with it), and never leaves the track. A free shape trails the finger by ~1% of the
+ *   drag (follow gains above). Native catalog `toggle-thumb-quiet` / `slider-thumb-quiet` (iPad,
+ *   cadence VALID): the held lens rides the finger to the ends; across the track it moves ≤1.4 pt.
+ * - Growth: the white thumb lifts into a clear lens after a stationary hold of `activationMs`, or
+ *   as soon as it drags, with the control's own springs (CONTROL_LIFT); a free shape grows at
+ *   touch-down.
+ * - Light: none. The lens is clear; the track shows through it.
+ * - A gesture that claims the touch before the thumb drags (a vertical scroll) cancels it; once it
+ *   drags the thumb keeps the finger (GlassContactOptions.yieldsTo).
+ *
+ * The page owns a thumb's value, so its response model runs in the document (toggleContact.ts,
+ * sliderContact.ts) and the renderer draws the lens it is sent (ControlLens). Values live in
+ * lens/controlLift.ts (CONTROL_LIFT, ControlLiftKind) beside the scope bar's selection lens.
+ */