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

package/dist/glass/webgpu/residentPlanes.d.ts

@@ -0,0 +1,69 @@
+import type { CaptureWindow } from '../captureWindow.js';
+import type { CaptureBand } from './captureDemand.js';
+/** Backdrop captures kept resident in the glass worker after their plane left the set (a route
+ * covered by a push), so a pop back composes from them without a raster or upload, and the
+ * material contexts cached for plane sets. Bookkeeping only: the runtime posts the returned
+ * keys (`retain`/`unretain`) to the worker.
+ *
+ * Budget: every resident byte counts. A retained plane holds its ImageBitmap and its uploaded
+ * texture in the worker (2 x the image); its main-thread capture canvas is released when it is
+ * retained (a later context readback re-rasters it). Cached material contexts hold one ImageData
+ * each. Planes are validated against the page state they were captured in (host connected,
+ * appearance, text size, no damage since) before any reuse. */
+export type ResidentPlane = {
+    window?: CaptureWindow;
+    /** The only rows a banded capture holds (captureDemand.ts). */
+    bands?: readonly CaptureBand[];
+    signature: string;
+    key: string;
+    revision: number;
+    origin: {
+        x: number;
+        y: number;
+    };
+    width: number;
+    height: number;
+    resolution: number;
+    host: Element;
+    appearance: string;
+    text: string;
+    /** Image bytes of the capture (the worker holds this twice: image and texture). */
+    imageBytes: number;
+};
+export declare class ResidentPlanes<Context> {
+    private retained;
+    private contexts;
+    readonly budget: number;
+    constructor(budget: number);
+    get size(): number;
+    get(id: string): (ResidentPlane & {
+        stale?: boolean;
+    }) | undefined;
+    /** Resident bytes: retained images and textures plus cached context readbacks. */
+    get bytes(): number;
+    /** A retained plane usable as it is: same host still in the document, same appearance and text
+     * size, no damage inside it since it was captured. */
+    usable(id: string, appearance: string, text: string): (ResidentPlane & {
+        stale?: boolean;
+    }) | undefined;
+    /** The plane was captured anew: its old retained image (if any) is released in the worker. */
+    recaptured(id: string): string | undefined;
+    /** The plane returns to the set with its resident capture (the worker restores it). */
+    take(id: string): (ResidentPlane & {
+        stale?: boolean;
+    }) | undefined;
+    /** A plane left the set. Kept only when its host is still in the document (a popped route never
+     * returns) and it fits the budget on its own. Returns whether the worker should retain it. */
+    retain(id: string, entry: ResidentPlane): boolean;
+    /** DOM damage at `target`: retained planes containing it no longer match their capture. */
+    damage(target: Node): void;
+    context(key: string): Context | undefined;
+    storeContext(key: string, context: Context, bytes: number): void;
+    /** Drops stale and orphaned planes, then fits the budget: least recently used contexts first
+     * (the current one, `keep`, stays), then the oldest retained planes. Returns the worker keys to
+     * release. */
+    settle(keep?: string): string[];
+    /** Forget everything (appearance, text size or fonts changed; hidden; failure). Returns the
+     * worker keys to release. */
+    clear(): string[];
+}

package/dist/glass/webgpu/residentPlanes.js

@@ -0,0 +1,104 @@
+export class ResidentPlanes {
+    retained = new Map();
+    contexts = new Map();
+    budget;
+    constructor(budget) {
+        this.budget = budget;
+    }
+    get size() {
+        return this.retained.size;
+    }
+    get(id) {
+        return this.retained.get(id);
+    }
+    /** Resident bytes: retained images and textures plus cached context readbacks. */
+    get bytes() {
+        return ([...this.retained.values()].reduce((n, e) => n + 2 * e.imageBytes, 0) +
+            [...this.contexts.values()].reduce((n, c) => n + c.bytes, 0));
+    }
+    /** A retained plane usable as it is: same host still in the document, same appearance and text
+     * size, no damage inside it since it was captured. */
+    usable(id, appearance, text) {
+        const entry = this.retained.get(id);
+        return entry &&
+            !entry.stale &&
+            entry.host.isConnected &&
+            entry.appearance === appearance &&
+            entry.text === text
+            ? entry
+            : undefined;
+    }
+    /** The plane was captured anew: its old retained image (if any) is released in the worker. */
+    recaptured(id) {
+        const entry = this.retained.get(id);
+        if (!entry)
+            return undefined;
+        this.retained.delete(id);
+        return entry.key;
+    }
+    /** The plane returns to the set with its resident capture (the worker restores it). */
+    take(id) {
+        const entry = this.retained.get(id);
+        this.retained.delete(id);
+        return entry;
+    }
+    /** A plane left the set. Kept only when its host is still in the document (a popped route never
+     * returns) and it fits the budget on its own. Returns whether the worker should retain it. */
+    retain(id, entry) {
+        if (!entry.host.isConnected || 2 * entry.imageBytes > this.budget)
+            return false;
+        this.retained.delete(id);
+        this.retained.set(id, entry);
+        return true;
+    }
+    /** DOM damage at `target`: retained planes containing it no longer match their capture. */
+    damage(target) {
+        for (const entry of this.retained.values())
+            if (entry.host.contains(target))
+                entry.stale = true;
+    }
+    context(key) {
+        const cached = this.contexts.get(key);
+        if (!cached)
+            return undefined;
+        this.contexts.delete(key);
+        this.contexts.set(key, cached);
+        return cached.context;
+    }
+    storeContext(key, context, bytes) {
+        this.contexts.delete(key);
+        this.contexts.set(key, { context, bytes });
+    }
+    /** Drops stale and orphaned planes, then fits the budget: least recently used contexts first
+     * (the current one, `keep`, stays), then the oldest retained planes. Returns the worker keys to
+     * release. */
+    settle(keep) {
+        const released = [];
+        for (const [id, entry] of this.retained)
+            if (entry.stale || !entry.host.isConnected) {
+                this.retained.delete(id);
+                released.push(entry.key);
+            }
+        for (const key of [...this.contexts.keys()]) {
+            if (this.bytes <= this.budget)
+                break;
+            if (key !== keep)
+                this.contexts.delete(key);
+        }
+        for (const [id, entry] of this.retained) {
+            if (this.bytes <= this.budget)
+                break;
+            this.retained.delete(id);
+            released.push(entry.key);
+        }
+        return released;
+    }
+    /** Forget everything (appearance, text size or fonts changed; hidden; failure). Returns the
+     * worker keys to release. */
+    clear() {
+        const keys = [...this.retained.values()].map(e => e.key);
+        this.retained.clear();
+        this.contexts.clear();
+        return keys;
+    }
+}

package/dist/glass/webgpu/restMaterial.d.ts

@@ -0,0 +1,6 @@
+import type { SurfaceRenderSpec } from '../renderSpecs.js';
+import type { Values } from './passes.js';
+/** Resting clear uses the frozen 7j operator. Interactive transmission remains
+ * blur-free and tint-free in sharedLift, regardless of the resting variant. */
+export declare function clearRestValues(spec: SurfaceRenderSpec): Values;
+export declare const tintFragment: string;

package/dist/glass/webgpu/restMaterial.js

@@ -0,0 +1,65 @@
+import { MORPH_FIELD_GLSL, morphFieldUniforms } from '../morphField.js';
+import { REFERENCE_LENS_PRESETS, referenceAmplitudeScale } from '../lens/referenceProfiles.js';
+import { shaders } from './shaders.js';
+/** Resting clear uses the frozen 7j operator. Interactive transmission remains
+ * blur-free and tint-free in sharedLift, regardless of the resting variant. */
+export function clearRestValues(spec) {
+    const preset = REFERENCE_LENS_PRESETS.clear, first = spec.shape.first;
+    const shape = [
+        spec.sampleInsetX + first.centerX,
+        spec.sampleInsetY + first.centerY,
+        first.halfWidth,
+        first.halfHeight,
+    ];
+    const raw = Array.from({ length: 7 }, (_, i) => Math.exp(-0.5 * (i * 0.5) ** 2)), sum = raw[0] + 2 * raw.slice(1).reduce((a, b) => a + b, 0), weights = raw.map(v => v / sum);
+    return {
+        ...Object.fromEntries(shaders.clear.uniforms.map(name => [name, [0, 0, 0, 0]])),
+        ...morphFieldUniforms(spec),
+        uResolution: [spec.sampleWidth, spec.sampleHeight],
+        uSurfaceCenter: shape.slice(0, 2),
+        uHalfSize: shape.slice(2),
+        uRadius: first.radius,
+        uShapeA: shape,
+        uShapeB: shape,
+        uShapeRadii: [first.radius, first.radius],
+        uShapeParams: [1, 0, 0, spec.shape.rimAlpha],
+        uRimBand: spec.shape.rimBandCssPx ?? 0.75,
+        uCoverageWidth: 0.75,
+        uMotionMix: 1,
+        uProfile: [
+            preset.knotSpacingCssPx,
+            referenceAmplitudeScale(first.radius, preset),
+            0,
+            preset.bandBlurCssPx,
+        ],
+        uKnotsA: preset.knotsCssPx.slice(0, 4),
+        uKnotsB: preset.knotsCssPx.slice(4, 8),
+        uKnotsC: preset.knotsCssPx.slice(8, 12),
+        uKnotsD: preset.knotsCssPx.slice(12, 16),
+        uMaterialGain: 1.12,
+        uMaterialTint: spec.tint ?? [1, 1, 1, 0.075],
+        uSpacing: (spec.blurSigmaCssPx ?? preset.blurSigmaCssPx) * 0.5,
+        uCornerRadius: first.radius,
+        uWeightsA: weights.slice(0, 4),
+        uWeightsB: [...weights.slice(4), 0],
+    };
+}
+export const tintFragment = MORPH_FIELD_GLSL +
+    /* glsl */ `
+precision highp float;
+in vec2 vTextureCoord;
+in vec2 vFilterCoord;
+out vec4 finalColor;
+uniform sampler2D uTexture;
+uniform vec4 uTint;
+uniform vec2 uResolution;
+uniform vec4 uShape;
+uniform float uRadius;
+void main(){
+ vec4 source=texture(uTexture,vTextureCoord);
+ vec2 q=abs(vFilterCoord*uResolution-uShape.xy)-uShape.zw+uRadius;
+ float sd=min(max(q.x,q.y),0.0)+length(max(q,0.0))-uRadius;
+ if(uMorphParams.x>.5)sd=morphDistance(vFilterCoord*uResolution);
+ float amount=uTint.a*(1.0-step(0.0,sd));
+ finalColor=vec4(mix(source.rgb,uTint.rgb*source.a,amount),source.a);
+}`;

package/dist/glass/webgpu/resumeOverlay.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Resume diagnostics on screen, for device checks where no probe can attach (the owner's
+ * iPhone). Opt-in with `<html data-satin-debug-resume>`. It shows what the page and the
+ * renderer hold for the tab bar's minimize transaction and the bottom accessory's run, and
+ * marks STALE any run-owned state that outlives its run. One screenshot answers the question.
+ */
+export type ResumeReadout = {
+    lifecycle: {
+        hides: number;
+        resumes: number;
+        hidden: boolean;
+    };
+    compact: boolean;
+    minimize: {
+        active: boolean;
+        direction: string | null;
+        compactLayout: boolean;
+        accessoryRun: boolean;
+        timelineOffset: number;
+        accessory: {
+            run: boolean;
+            motion: boolean;
+            ink: string | null;
+            width: string | null;
+            readyInk: number | null;
+            reach: string | null;
+            animations: number;
+        } | null;
+    } | null;
+    renderer: {
+        visible: boolean | null;
+        tracks: unknown;
+        duplicatePresenters: [string, number][];
+        presenters: number;
+    };
+};
+export declare function resumeDebugEnabled(): boolean;
+/** Run-owned state still present while no run is (each entry names one). */
+export declare function staleResumeState(readout: ResumeReadout): string[];
+/**
+ * Shows the overlay for the rest of the page's life (once per document). It reads whichever
+ * runtime is current (`__SATIN_WEBGPU__`): a runtime is torn down and rebuilt on rebinds.
+ */
+export declare function showResumeOverlay(): void;

package/dist/glass/webgpu/resumeOverlay.js

@@ -0,0 +1,82 @@
+export function resumeDebugEnabled() {
+    return document.documentElement.hasAttribute('data-satin-debug-resume');
+}
+/** Run-owned state still present while no run is (each entry names one). */
+export function staleResumeState(readout) {
+    const stale = [];
+    const minimize = readout.minimize;
+    const accessory = minimize?.accessory;
+    if (minimize && !minimize.active && accessory) {
+        if (minimize.accessoryRun || accessory.run)
+            stale.push('accessory run');
+        if (accessory.motion)
+            stale.push('accessory motion');
+        if (accessory.ink === 'true')
+            stale.push('ink hidden');
+        if (accessory.width)
+            stale.push(`width ${accessory.width}`);
+    }
+    // Within a frame or two the clocks normally agree; right after a resume the timeline can hold
+    // the last frame's time for a moment (Catalyst: -177 ms before the first frame).
+    if (minimize && Math.abs(minimize.timelineOffset) > 1000)
+        stale.push(`timeline ${minimize.timelineOffset} ms`);
+    if (readout.renderer.duplicatePresenters.length)
+        stale.push('duplicate presenters');
+    return stale;
+}
+let shown = false;
+/**
+ * Shows the overlay for the rest of the page's life (once per document). It reads whichever
+ * runtime is current (`__SATIN_WEBGPU__`): a runtime is torn down and rebuilt on rebinds.
+ */
+export function showResumeOverlay() {
+    if (shown)
+        return;
+    shown = true;
+    const read = () => globalThis
+        .__SATIN_WEBGPU__.resume();
+    const panel = document.createElement('pre');
+    panel.dataset.satinResumeOverlay = '';
+    Object.assign(panel.style, {
+        position: 'fixed',
+        zIndex: '2147483647',
+        top: 'calc(env(safe-area-inset-top) + 4px)',
+        left: '4px',
+        right: '4px',
+        margin: '0',
+        padding: '4px 6px',
+        font: '10px/1.25 ui-monospace, Menlo, monospace',
+        whiteSpace: 'pre-wrap',
+        color: '#fff',
+        background: 'rgba(0, 0, 0, 0.6)',
+        borderRadius: '6px',
+        pointerEvents: 'none',
+    });
+    document.body.append(panel);
+    let timer = 0;
+    const update = async () => {
+        clearTimeout(timer);
+        // React may replace the body's children; keep the panel attached.
+        if (!panel.isConnected)
+            document.body.append(panel);
+        try {
+            const readout = await read();
+            const stale = staleResumeState(readout);
+            const m = readout.minimize, a = m?.accessory;
+            panel.style.background = stale.length ? 'rgba(160, 0, 0, 0.75)' : 'rgba(0, 0, 0, 0.6)';
+            panel.textContent = [
+                `${stale.length ? 'STALE: ' + stale.join(', ') : 'ok'} · hides ${readout.lifecycle.hides} resumes ${readout.lifecycle.resumes}`,
+                `minimize ${m?.active ? 'running ' + m.direction : 'idle'} · compact ${readout.compact} layout ${m?.compactLayout} · timeline ${m?.timelineOffset ?? '?'} ms`,
+                `accessory run ${a?.run} motion ${a?.motion} ink ${a?.ink} width ${a?.width} ready ${a?.readyInk} anims ${a?.animations}`,
+                `renderer visible ${readout.renderer.visible} tracks ${JSON.stringify(readout.renderer.tracks)} presenters ${readout.renderer.presenters}`,
+            ].join('\n');
+        }
+        catch (error) {
+            panel.textContent = `resume readout failed: ${String(error)}`;
+        }
+        if (!document.hidden)
+            timer = setTimeout(update, 1000);
+    };
+    document.addEventListener('visibilitychange', () => void update());
+    void update();
+}

package/dist/glass/webgpu/sampleTrace.d.ts

@@ -0,0 +1,11 @@
+export declare function traceCapture(source: object): number;
+/** Exact float32 shader inputs, before material refraction/blur. These are encoded samples,
+ * not scanout evidence. Atlas poses cannot be summarized as one source rectangle. */
+export declare function traceSourcePlane(source: object, identity: {
+    raster: number | string;
+    region: string;
+    plane: string;
+    key: string;
+}, uniforms: Float32Array, scissor: readonly number[], geometry: Record<string, number | string | boolean | null>): void;
+export declare function traceResult(result: object, source: object | null): void;
+export declare function traceSubmitted(result: object, values: Record<string, number | string | boolean | null>): void;

package/dist/glass/webgpu/sampleTrace.js

@@ -0,0 +1,50 @@
+import { lagMark, lagTraceEnabled, lagTraceHasRoom } from './lagTrace.js';
+import { glassNow } from './profile.js';
+// Diagnostic capture identities follow textures, including shared graph results. A result
+// keeps the capture it encoded from even after the scratch source texture is overwritten.
+const captures = new WeakMap();
+const results = new WeakMap();
+let nextCapture = 0;
+export function traceCapture(source) {
+    const capture = ++nextCapture;
+    captures.set(source, capture);
+    return capture;
+}
+/** Exact float32 shader inputs, before material refraction/blur. These are encoded samples,
+ * not scanout evidence. Atlas poses cannot be summarized as one source rectangle. */
+export function traceSourcePlane(source, identity, uniforms, scissor, geometry) {
+    if (!lagTraceEnabled() || !lagTraceHasRoom())
+        return;
+    const u = uniforms;
+    const atlas = u[52] > 0;
+    lagMark({
+        stage: 'worker-source-plane',
+        at: glassNow(),
+        values: {
+            ...identity,
+            ...geometry,
+            capture: captures.get(source) ?? null,
+            uniforms: JSON.stringify(Array.from(u)),
+            scissor: JSON.stringify(scissor),
+            // Bounds of the scissored front-plane footprint in logical source pixels. Pixel
+            // centres lie half a destination pixel inside; sampler clamping/open fill apply later.
+            sourceX: atlas ? null : (scissor[0] / u[2]) * u[56] + u[4] - u[16],
+            sourceY: atlas ? null : (scissor[1] / u[2]) * u[57] + u[5] + u[14],
+            sourceWidth: atlas ? null : (scissor[2] / u[2]) * u[56],
+            sourceHeight: atlas ? null : (scissor[3] / u[2]) * u[57],
+            atlas,
+        },
+    });
+}
+export function traceResult(result, source) {
+    results.set(result, source ? (captures.get(source) ?? null) : null);
+}
+export function traceSubmitted(result, values) {
+    if (!lagTraceEnabled() || !lagTraceHasRoom())
+        return;
+    lagMark({
+        stage: 'worker-source-submit',
+        at: glassNow(),
+        values: { ...values, capture: results.get(result) ?? null },
+    });
+}

package/dist/glass/webgpu/scrollEdgeBackdrop.d.ts

@@ -0,0 +1,89 @@
+import type { NavigationGlassRoute } from '../../navigation/glassTransition.js';
+/** The navigation bar's scroll-edge material as the glass renderer sees it.
+ * Natively, bar buttons sit above the scroll-edge effect and refract the already
+ * blurred, tinted backdrop. Satin paints that effect with CSS for DOM content, which
+ * a canvas cannot sample, so the renderer composes the same treatment into the
+ * backdrop under every glass surface it overlaps. Values mirror styles.css
+ * ([data-satin-scroll-edge]); scrollEdgeBackdrop.test.ts keeps them in step. */
+export type ScrollEdge = {
+    zoomClip?: {
+        rect: readonly [number, number, number, number];
+        radius: number;
+    };
+    zoomOcclusions?: readonly {
+        rect: readonly [number, number, number, number];
+        radius: number;
+    }[];
+    /** Viewport rectangle of the edge element [x,y,w,h]. */
+    rect: readonly [number, number, number, number];
+    /** Page-local horizontal geometry, posed in the worker by the same navigation track as content. */
+    navigation?: {
+        route: number;
+        clip: readonly [number, number];
+        covers: readonly number[];
+        origins: readonly number[];
+    };
+    /** Viewport y where the mask starts fading (fully applied above it). */
+    solid: number;
+    /** Optional measured vertical mask stops, in viewport points and normalized alpha. */
+    mask?: readonly (readonly [number, number])[];
+    /** Gaussian standard deviation, points (CSS blur()). */
+    sigma: number;
+    /** Straight tint colour and alpha painted over the blurred backdrop. */
+    tint: readonly [number, number, number, number];
+    /** Element opacity: 0 at rest, ramping to 1 as content scrolls under the bar. */
+    strength: number;
+    /** The search header's edge (readSearchEdges), which the search field does not diffuse through. */
+    search?: true;
+    /** Opaque top fill, separately composited above the scroll-driven material. */
+    cap?: {
+        color: readonly [number, number, number, number];
+        solid: number;
+        end: number;
+    };
+};
+export declare const SCROLL_EDGE_MATERIAL: {
+    readonly light: {
+        readonly sigma: 4.5;
+        readonly tint: readonly [1, 1, 1, 0.55];
+    };
+    readonly dark: {
+        readonly sigma: 4.5;
+        readonly tint: readonly [0, 0, 0, 0.59];
+    };
+};
+export declare const SCROLL_EDGE_FADE_PT = 2;
+/** The cap (styles.css [data-satin-scroll-edge-cap]) keeps the band colour through the status band,
+ * then fades out over the resting seam's 28 pt. The renderer approximates that eased fade linearly. */
+export declare const SCROLL_EDGE_CAP_FADE_PT = 28;
+/** Native searchable header fit, iOS 27.0 24A434, dark-glass/native-visible-edge-fit*.json.
+ * These are search-specific; the bar material above does not apply to them. */
+export declare const SEARCH_HEADER_MATERIAL: {
+    readonly light: {
+        readonly sigma: 1.75;
+        readonly tint: readonly [1, 1, 1, 0.55];
+    };
+    readonly dark: {
+        readonly sigma: 1.5;
+        readonly tint: readonly [0, 0, 0, 0.64];
+    };
+};
+/** Native field RGB against the material bar face matrix, three avatar colors through the rendered operator.
+ * Attenuate the input before the bar operator so its neutral floor remains intact
+ * and saturated channels are not clipped before attenuation. Empirical fit RMS 2.58 / 255; see the implementation contract */
+export declare const SEARCH_FIELD_DARK_TRANSMISSION = 0.8456002308235339;
+/** A pinned plain-list header's hard-edged material (styles.css,
+ * [data-satin-section-header-pinned]). Light's brightness(1.2) has no tint equivalent; 56% white
+ * reproduces its result on mid-tone content. */
+export declare const PINNED_HEADER_MATERIAL: {
+    readonly light: {
+        readonly sigma: 6;
+        readonly tint: readonly [1, 1, 1, 0.56];
+    };
+    readonly dark: {
+        readonly sigma: 6;
+        readonly tint: readonly [0, 0, 0, 0.55];
+    };
+};
+/** Visible scroll-edge layers in `root`, in viewport coordinates. */
+export declare function readScrollEdges(root: ParentNode, dark: boolean, routes?: readonly NavigationGlassRoute[]): ScrollEdge[];