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

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

@@ -0,0 +1,44 @@
+import { type CaptureBand, type SampleRect } from './captureBands.js';
+export type { CaptureBand, SampleRect } from './captureBands.js';
+/** Points of slack kept around each sample rectangle: press growth, sub-point layout and spring
+ * overshoot stay inside the capture without another preparation. */
+export declare const DEMAND_MARGIN_POINTS = 24;
+/** What a plane that does not scroll is captured for (see `demandWindow`). */
+export type PlaneDemand = {
+    /** Sample rectangles of every glass surface and region on screen. */
+    rects: readonly SampleRect[];
+    /** The plane is beneath an open presentation (a sheet, alert or confirmation): glass above it
+     * moves over all of it, so it is captured whole. */
+    covered: boolean;
+    /** The plane is captured again anyway (its content changed): a whole capture may shrink. */
+    damaged: boolean;
+};
+/** The sample rectangle of an app glass region: its box and its material's sampling halo. */
+export declare function regionSampleRect(element: Element, treatment?: string): SampleRect | undefined;
+/** Whether an open presentation (sheet, alert, confirmation) paints above `host`. Glass in it moves
+ * over the whole of `host` with the presentation, between preparations. */
+export declare function beneathPresentation(host: Element): boolean;
+type HostBox = {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+};
+/** The content rows of a plane that does not scroll which glass samples, or undefined for a
+ * capture of its whole content.
+ *
+ * Every sample rectangle that overlaps the host contributes its rows, widened by
+ * DEMAND_MARGIN_POINTS; overlapping or nearby rows merge into bands. Unrelated content outside
+ * them is never measured, rastered or read back, and a change to it is no change to the
+ * capture: capture cost follows the glass, not the page. Bands the plane already holds are kept
+ * while they cover the demand (no capture for glass that stays put), and a whole capture is kept
+ * until the content changes. Glass that later samples outside the bands makes the region bridge
+ * wait for a capture that covers it (`ProductionGlassRuntime.coverFor`); the renderer refuses any
+ * sample outside them (`uncoveredRows`). */
+export declare function demandBands(options: {
+    host: HostBox;
+    contentHeight: number;
+    resolution: number;
+    demand: PlaneDemand;
+    current?: readonly CaptureBand[] | 'full';
+}): CaptureBand[] | undefined;

package/dist/glass/webgpu/captureDemand.js

@@ -0,0 +1,81 @@
+import { orderedTopLayerDialogs } from '../../modal/lifecycle.js';
+import { topLayerDialogOf } from '../topLayer.js';
+import { contextSampleInset } from './contextComposite.js';
+import { atRest, presentationTravel } from '../presentationFrame.js';
+import { bandsCover, snapCaptureBand } from './captureBands.js';
+/** Points of slack kept around each sample rectangle: press growth, sub-point layout and spring
+ * overshoot stay inside the capture without another preparation. */
+export const DEMAND_MARGIN_POINTS = 24;
+/** A demand window this close to the whole content captures the whole content instead. */
+const WHOLE_CONTENT_SHARE = 0.75;
+/** The sample rectangle of an app glass region: its box and its material's sampling halo. */
+export function regionSampleRect(element, treatment) {
+    // Nested sheet glass samples its resting content plane while CSS moves both.
+    // The sheet's own surface has zero nested travel and still samples the page.
+    const box = atRest(element.getBoundingClientRect(), presentationTravel(element));
+    if (box.width <= 0 || box.height <= 0)
+        return;
+    const inset = contextSampleInset(treatment);
+    return [box.x - inset, box.y - inset, box.width + 2 * inset, box.height + 2 * inset];
+}
+/** Whether an open presentation (sheet, alert, confirmation) paints above `host`. Glass in it moves
+ * over the whole of `host` with the presentation, between preparations. */
+export function beneathPresentation(host) {
+    const dialogs = orderedTopLayerDialogs(document);
+    const own = dialogs.indexOf(topLayerDialogOf(host));
+    return dialogs
+        .slice(own + 1)
+        .some(dialog => dialog.open && dialog.hasAttribute('data-satin-presentation'));
+}
+/** Bands closer than this merge into one: one raster and readback is cheaper than two that
+ * nearly touch. */
+const MERGE_GAP_POINTS = 2 * DEMAND_MARGIN_POINTS;
+/** The content rows of a plane that does not scroll which glass samples, or undefined for a
+ * capture of its whole content.
+ *
+ * Every sample rectangle that overlaps the host contributes its rows, widened by
+ * DEMAND_MARGIN_POINTS; overlapping or nearby rows merge into bands. Unrelated content outside
+ * them is never measured, rastered or read back, and a change to it is no change to the
+ * capture: capture cost follows the glass, not the page. Bands the plane already holds are kept
+ * while they cover the demand (no capture for glass that stays put), and a whole capture is kept
+ * until the content changes. Glass that later samples outside the bands makes the region bridge
+ * wait for a capture that covers it (`ProductionGlassRuntime.coverFor`); the renderer refuses any
+ * sample outside them (`uncoveredRows`). */
+export function demandBands(options) {
+    const { host, contentHeight, resolution, demand, current } = options;
+    if (demand.covered)
+        return undefined;
+    if (current === 'full' && !demand.damaged)
+        return undefined;
+    const rows = [];
+    for (const [x, y, width, height] of demand.rects) {
+        if (x + width <= host.left || x >= host.right)
+            continue;
+        if (y + height <= host.top || y >= host.bottom)
+            continue;
+        const top = Math.max(0, y - DEMAND_MARGIN_POINTS - host.top);
+        const bottom = Math.min(contentHeight, y + height + DEMAND_MARGIN_POINTS - host.top);
+        if (bottom > top)
+            rows.push([top, bottom]);
+    }
+    // No glass over the plane: nothing bounds it (a screen without glass keeps its whole capture).
+    if (!rows.length)
+        return undefined;
+    rows.sort((a, b) => a[0] - b[0]);
+    const bands = [];
+    for (const [top, bottom] of rows) {
+        const last = bands.at(-1);
+        if (last && top <= last.bottom + MERGE_GAP_POINTS)
+            last.bottom = Math.max(last.bottom, bottom);
+        else
+            bands.push({ top, bottom });
+    }
+    // Device-pixel rows: a band's edges are whole texels of the capture.
+    const snapped = bands.map(band => snapCaptureBand(band, resolution));
+    const captured = snapped.reduce((sum, band) => sum + band.bottom - band.top, 0);
+    if (captured >= WHOLE_CONTENT_SHARE * contentHeight)
+        return undefined;
+    if (current && current !== 'full' && bandsCover(current, snapped, resolution))
+        return [...current];
+    return snapped;
+}

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

@@ -0,0 +1,18 @@
+/** Release a throwaway capture canvas as soon as it has been consumed.
+ *
+ * WebKit keeps a GPU-process image for a canvas that was drawn into another canvas, and
+ * destroying that image is a synchronous round trip to the GPU process. Left to the garbage
+ * collector, the capture canvases of a preparation were swept together later, often in the
+ * first frames of the next navigation: a main-thread stall of about 200 ms (sampled in the
+ * Catalyst host: HTMLCanvasElement::~HTMLCanvasElement, ImageFrame::clearImage,
+ * RemoteNativeImageProxy::platformImage, IPC::Connection::waitForSyncReply). Emptying the
+ * canvas drops that image now, inside the preparation, which never runs during motion. */
+export declare function releaseCaptureCanvas(canvas: HTMLCanvasElement): void;
+/** Release every canvas of `canvases` and empty the list (so each is released exactly once,
+ * whichever of the normal path or a failure path gets to it first). */
+export declare function releaseCaptureCanvases(canvases: HTMLCanvasElement[]): void;
+/** A reply that never arrives must not keep capture canvases allocated for longer than this. */
+export declare const CAPTURE_RELEASE_FALLBACK_MS = 5000;
+/** Release `canvases` when `settled` settles, fulfilled or rejected, or after `fallbackMs` when it
+ * never does (a renderer that stopped answering). Whichever comes first releases them once. */
+export declare function releaseCaptureCanvasesAfter(settled: Promise<unknown>, canvases: HTMLCanvasElement[], fallbackMs?: number): void;

package/dist/glass/webgpu/captureRelease.js

@@ -0,0 +1,39 @@
+import { traceStage, traceStageStart } from './profile.js';
+/** Release a throwaway capture canvas as soon as it has been consumed.
+ *
+ * WebKit keeps a GPU-process image for a canvas that was drawn into another canvas, and
+ * destroying that image is a synchronous round trip to the GPU process. Left to the garbage
+ * collector, the capture canvases of a preparation were swept together later, often in the
+ * first frames of the next navigation: a main-thread stall of about 200 ms (sampled in the
+ * Catalyst host: HTMLCanvasElement::~HTMLCanvasElement, ImageFrame::clearImage,
+ * RemoteNativeImageProxy::platformImage, IPC::Connection::waitForSyncReply). Emptying the
+ * canvas drops that image now, inside the preparation, which never runs during motion. */
+export function releaseCaptureCanvas(canvas) {
+    canvas.width = 0;
+    canvas.height = 0;
+}
+/** Release every canvas of `canvases` and empty the list (so each is released exactly once,
+ * whichever of the normal path or a failure path gets to it first). */
+export function releaseCaptureCanvases(canvases) {
+    if (!canvases.length)
+        return;
+    const started = traceStageStart();
+    const released = canvases.length;
+    for (const canvas of canvases.splice(0))
+        releaseCaptureCanvas(canvas);
+    traceStage('capture-release', started, () => `${released} canvases`);
+}
+/** A reply that never arrives must not keep capture canvases allocated for longer than this. */
+export const CAPTURE_RELEASE_FALLBACK_MS = 5000;
+/** Release `canvases` when `settled` settles, fulfilled or rejected, or after `fallbackMs` when it
+ * never does (a renderer that stopped answering). Whichever comes first releases them once. */
+export function releaseCaptureCanvasesAfter(settled, canvases, fallbackMs = CAPTURE_RELEASE_FALLBACK_MS) {
+    if (!canvases.length)
+        return;
+    const fallback = setTimeout(() => releaseCaptureCanvases(canvases), fallbackMs);
+    const release = () => {
+        clearTimeout(fallback);
+        releaseCaptureCanvases(canvases);
+    };
+    settled.then(release, release);
+}

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

@@ -0,0 +1,49 @@
+import type { GlassRegionEvent } from '../rendererContract.js';
+import type { GlassLayer } from './layers.js';
+import type { Request } from '../worker/protocol.js';
+export declare class WebGPUClient {
+    private transport?;
+    private local?;
+    get documentOwned(): boolean;
+    private nextId;
+    private pending;
+    private presentationAllowed;
+    /** Does not wait for the renderer queue, so a stalled request remains diagnosable. */
+    status(): {
+        execution: string;
+        presentationAllowed: boolean | undefined;
+        failed: string | undefined;
+        pending: {
+            id: number;
+            operation: string;
+            ageMs: number;
+        }[];
+    };
+    private adapterDeadline?;
+    private failed?;
+    private frames;
+    private webgpu;
+    private currentAppearance;
+    /** Production commits visibility only after remeasuring and replacing sources. */
+    deferResume: boolean;
+    /** Unsolicited worker events (a region's close morph ended). */
+    private eventListeners;
+    onEvent(listener: (event: GlassRegionEvent) => void): () => void;
+    backend: 'webgpu';
+    private visibility;
+    readonly work: {
+        at: number;
+        ms: number;
+    }[];
+    init(canvas: HTMLCanvasElement, resolution: number, worker: boolean, webgpu?: boolean, appearance?: () => 'light' | 'dark', execution?: 'worker' | 'document'): Promise<void>;
+    private initialize;
+    private failTransport;
+    attachLayer(canvas: HTMLCanvasElement, layer: GlassLayer): Promise<unknown>;
+    request(request: Request, transfer?: Transferable[], admitted?: () => void): Promise<unknown>;
+    pose(x: number, at: number): void;
+    private adapterVisibility;
+    private focus;
+    private bindLifecycle;
+    resume(): void;
+    park(): Promise<unknown>;
+}

package/dist/glass/webgpu/client.js

@@ -0,0 +1,336 @@
+import { glassNow, glassTiming, receiveGlassFrames, receiveGlassTiming, setGlassTimingSink, } from './profile.js';
+import { motionPreparationEnabled, recordMotionPreparation } from '../../motionProbe.js';
+import { installGlassErrorAlert } from '../errorAlert.js';
+import { glassFailureCode } from '../webgpu/errorCode.js';
+import { reportGlassError, setGlassAdapterRecovery } from '../errors.js';
+import { GLASS_READINESS_BUDGET_MS, VisibleDeadline } from '../visibleDeadline.js';
+import { PageFrameHost } from './frameClock.js';
+import { readDarkAppearance } from '../../app/appearance.js';
+export class WebGPUClient {
+    transport;
+    local;
+    get documentOwned() {
+        return !!this.local;
+    }
+    nextId = 0;
+    pending = new Map();
+    presentationAllowed;
+    /** Does not wait for the renderer queue, so a stalled request remains diagnosable. */
+    status() {
+        return {
+            execution: this.documentOwned ? 'document' : 'worker',
+            presentationAllowed: this.presentationAllowed,
+            failed: this.failed?.message,
+            pending: [...this.pending].map(([id, request]) => ({
+                id,
+                operation: request.operation,
+                ageMs: glassNow() - request.at,
+            })),
+        };
+    }
+    adapterDeadline;
+    failed;
+    frames = new PageFrameHost();
+    webgpu = false;
+    currentAppearance = () => readDarkAppearance() ? 'dark' : 'light';
+    /** Production commits visibility only after remeasuring and replacing sources. */
+    deferResume = false;
+    /** Unsolicited worker events (a region's close morph ended). */
+    eventListeners = new Set();
+    onEvent(listener) {
+        this.eventListeners.add(listener);
+        return () => {
+            this.eventListeners.delete(listener);
+        };
+    }
+    backend = 'webgpu';
+    visibility = (event) => {
+        const visible = event?.type !== 'pagehide' && document.visibilityState === 'visible';
+        if (visible)
+            void this.request({ type: 'retry-adapter' }).catch(() => {
+                // The device owner reports an exhausted burst once, with its history.
+            });
+        if (!visible || !this.deferResume)
+            void this.request({ type: 'visible', visible }).catch(error => {
+                reportGlassError(glassFailureCode('worker control', error), error, 'worker control');
+            });
+        if (!visible)
+            this.frames.cancel();
+    };
+    work = [];
+    async init(canvas, resolution, worker, webgpu = false, appearance = () => (readDarkAppearance() ? 'dark' : 'light'), execution = 'worker') {
+        installGlassErrorAlert();
+        setGlassTimingSink(event => recordMotionPreparation(() => ({
+            kind: 'webgpu-timing',
+            ...event,
+            epoch: event.at,
+            at: event.at - performance.timeOrigin,
+        })), motionPreparationEnabled);
+        glassTiming('client-start');
+        try {
+            await this.initialize(canvas, resolution, worker, webgpu, appearance, execution);
+        }
+        catch (error) {
+            reportGlassError(glassFailureCode('renderer initialization', error), error, 'renderer initialization');
+            throw error;
+        }
+    }
+    async initialize(canvas, resolution, worker, webgpu, appearance, execution) {
+        this.currentAppearance = appearance;
+        // 7b: do not create the page context before visibility plus one frame.
+        if (document.visibilityState !== 'visible')
+            await new Promise(resolve => {
+                const listener = () => {
+                    if (document.visibilityState === 'visible') {
+                        document.removeEventListener('visibilitychange', listener);
+                        resolve();
+                    }
+                };
+                document.addEventListener('visibilitychange', listener);
+            });
+        await new Promise(resolve => requestAnimationFrame(() => resolve()));
+        this.webgpu = webgpu;
+        if (worker) {
+            const receive = (event) => {
+                if (this.frames.receive(event.data, data => this.transport.postMessage(data)))
+                    return;
+                const { id, value, error, glassError, glassProfile, glassFrames, glassEvent, appearanceRefresh, appearanceRevision, } = event.data;
+                if (typeof event.data.adapterRecovery === 'boolean') {
+                    const pending = event.data.adapterRecovery;
+                    setGlassAdapterRecovery(pending);
+                    if (pending && !this.adapterDeadline) {
+                        // Settled regions may have cancelled their own deadlines before loss.
+                        // Retain one budget through duplicate loss signals and hidden time.
+                        this.adapterDeadline = new VisibleDeadline(GLASS_READINESS_BUDGET_MS, () => {
+                            reportGlassError('readiness-timeout', 'Glass device was not reconstructed within 10 s of visible time', 'device recovery');
+                        });
+                        this.adapterDeadline.start();
+                    }
+                    else if (!pending) {
+                        this.adapterDeadline?.cancel();
+                        this.adapterDeadline = undefined;
+                    }
+                    return;
+                }
+                if (appearanceRefresh) {
+                    void this.request({
+                        type: 'canonical',
+                        appearanceRevision,
+                        request: {
+                            type: 'appearance',
+                            value: appearance(),
+                            reducedMotion: matchMedia('(prefers-reduced-motion: reduce)').matches,
+                        },
+                    }).catch(error => {
+                        reportGlassError(glassFailureCode('appearance restoration', error), error, 'appearance restoration');
+                    });
+                    return;
+                }
+                if (glassEvent) {
+                    if (glassEvent.type === 'presentation-gate')
+                        this.presentationAllowed = glassEvent.allowed;
+                    for (const listener of this.eventListeners)
+                        listener(glassEvent);
+                    return;
+                }
+                if (glassFrames) {
+                    receiveGlassFrames(glassFrames);
+                    recordMotionPreparation(() => ({
+                        kind: 'webgpu-frames',
+                        at: performance.now(),
+                        summaries: glassFrames,
+                    }));
+                    return;
+                }
+                if (glassProfile) {
+                    receiveGlassTiming(glassProfile);
+                    recordMotionPreparation(() => ({
+                        kind: 'webgpu-timing',
+                        ...glassProfile,
+                        epoch: glassProfile.at,
+                        at: glassProfile.at - performance.timeOrigin,
+                    }));
+                    return;
+                }
+                if (glassError) {
+                    reportGlassError(glassError.code, glassError.message, glassError.stage, glassError.reason);
+                    return;
+                }
+                const request = this.pending.get(id);
+                this.pending.delete(id);
+                if (error)
+                    request?.reject(new Error(error));
+                else
+                    request?.resolve(value);
+            };
+            glassTiming(execution === 'document' ? 'renderer-create' : 'worker-create');
+            if (execution === 'document') {
+                const { createWebGPURenderer } = await import('./renderer.js');
+                const renderer = createWebGPURenderer(data => queueMicrotask(() => receive(new MessageEvent('message', { data }))));
+                this.local = renderer;
+                this.transport = {
+                    postMessage: data => renderer.receive({ data }),
+                    terminate: () => renderer.stop(),
+                };
+            }
+            else {
+                const transport = new Worker(new URL('./entry.worker.js', import.meta.url), {
+                    type: 'module',
+                    name: 'satin-glass-webgpu',
+                });
+                transport.onmessage = receive;
+                transport.onerror = event => this.failTransport(new Error(event.message || 'Glass worker failed'), 'worker startup/runtime');
+                transport.onmessageerror = () => this.failTransport(Error('Glass worker message could not be deserialized'), 'worker transport');
+                this.transport = {
+                    postMessage: (data, transfer = []) => transport.postMessage(data, transfer),
+                    terminate: () => transport.terminate(),
+                };
+            }
+            // The transport is page-lived, including while release fallback is presented.
+            // Keep availability signals bound when presentation is parked.
+            document.addEventListener('visibilitychange', this.adapterVisibility, true);
+            window.addEventListener('pagehide', this.adapterVisibility, true);
+            window.addEventListener('pageshow', this.adapterVisibility);
+            window.addEventListener('focus', this.adapterVisibility);
+            if (webgpu) {
+                let timeout;
+                try {
+                    await Promise.race([
+                        this.request({ type: 'capability' }),
+                        new Promise((_, reject) => {
+                            timeout = setTimeout(() => reject(Error('WebGPU startup exceeded 2.5 seconds')), 2500);
+                        }),
+                    ]);
+                    this.backend = 'webgpu';
+                }
+                catch (error) {
+                    this.failed = error instanceof Error ? error : Error(String(error));
+                    reportGlassError(glassFailureCode('WebGPU startup', this.failed), this.failed, 'WebGPU startup');
+                    this.transport?.terminate();
+                    for (const pending of this.pending.values())
+                        pending.reject(this.failed);
+                    this.pending.clear();
+                    throw this.failed;
+                }
+                finally {
+                    clearTimeout(timeout);
+                }
+            }
+            const offscreen = this.local ? canvas : canvas.transferControlToOffscreen();
+            await this.request({
+                type: 'init',
+                canvas: offscreen,
+                resolution,
+                appearance: appearance(),
+                presentationLeadMs: Number(document.documentElement.getAttribute('data-satin-experimental-glass-lead-ms') ?? 0),
+            }, this.local ? [] : [offscreen]);
+        }
+        else {
+            throw Error('WebGPU requires an owned renderer transport');
+        }
+        this.bindLifecycle();
+    }
+    failTransport(error, stage) {
+        this.adapterDeadline?.cancel();
+        this.failed = error;
+        reportGlassError(glassFailureCode(stage, error), error, stage);
+        for (const pending of this.pending.values())
+            pending.reject(error);
+        this.pending.clear();
+    }
+    async attachLayer(canvas, layer) {
+        if (!this.webgpu)
+            throw Error('Additional presentation canvases require WebGPU');
+        canvas.style.position = 'absolute';
+        canvas.style.pointerEvents = 'none';
+        canvas.style.zIndex = String(layer.depth);
+        canvas.dataset.satinGlassLayer = layer.id;
+        canvas.dataset.satinGlassAttachment = layer.attachment.kind;
+        if (layer.attachment.kind === 'scroll') {
+            const container = canvas.closest('[data-satin-scroll-container]');
+            if (container?.getAttribute('data-satin-scroll-container') !== layer.attachment.scrollId)
+                throw Error('Scroll glass canvas must be mounted inside its declared scroll container');
+        }
+        const offscreen = this.local ? canvas : canvas.transferControlToOffscreen();
+        return this.request({ type: 'attach-layer', layer, canvas: offscreen }, this.local ? [] : [offscreen]);
+    }
+    request(request, transfer = [], admitted) {
+        if (this.failed)
+            return Promise.reject(this.failed);
+        if (request.type === 'visible' && request.visible) {
+            // Read at dispatch, after the appearance store's visibility handler. Never
+            // infer a resume material from the hidden-time media query or worker state.
+            request = {
+                ...request,
+                appearance: this.currentAppearance(),
+                reducedMotion: matchMedia('(prefers-reduced-motion: reduce)').matches,
+            };
+        }
+        const id = ++this.nextId, at = glassNow();
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, {
+                at,
+                operation: request.type === 'canonical' ? `canonical:${request.request.type}` : request.type,
+                resolve: value => {
+                    glassTiming('rpc', at, () => request.type === 'canonical' ? 'canonical:' + request.request.type : request.type);
+                    resolve(value);
+                },
+                reject: error => {
+                    glassTiming('rpc', at, request.type, error);
+                    reject(error);
+                },
+            });
+            try {
+                this.transport.postMessage({ id, request, postedAt: glassNow() }, transfer);
+                admitted?.();
+            }
+            catch (error) {
+                this.pending.delete(id);
+                reportGlassError(glassFailureCode('worker transport', error), error, 'worker transport');
+                reject(error);
+            }
+        });
+    }
+    pose(x, at) {
+        const start = performance.now(), request = { type: 'pose', x, at };
+        this.transport.postMessage({ id: 0, request });
+        this.work.push({ at, ms: performance.now() - start });
+        if (this.work.length > 2400)
+            this.work.shift();
+    }
+    adapterVisibility = (event) => {
+        if (this.failed)
+            return;
+        const visible = event.type !== 'pagehide' && document.visibilityState === 'visible';
+        this.adapterDeadline?.setVisible(visible);
+        void this.request({ type: 'adapter-visibility', visible }).catch(() => {
+            // Transport failures already enter the terminal diagnostic channel.
+        });
+    };
+    focus = () => {
+        if (document.visibilityState === 'visible')
+            void this.request({ type: 'retry-adapter' }).catch(() => {
+                // The device owner reports terminal acquisition failures.
+            });
+    };
+    bindLifecycle() {
+        // Capture hide before the appearance store's bubble listener can publish.
+        document.addEventListener('visibilitychange', this.visibility, true);
+        window.addEventListener('pagehide', this.visibility, true);
+        window.addEventListener('pageshow', this.visibility);
+        window.addEventListener('focus', this.focus);
+    }
+    resume() {
+        this.bindLifecycle();
+        this.visibility();
+    }
+    park() {
+        this.frames.cancel();
+        document.removeEventListener('visibilitychange', this.visibility, true);
+        window.removeEventListener('pagehide', this.visibility, true);
+        window.removeEventListener('pageshow', this.visibility);
+        window.removeEventListener('focus', this.focus);
+        return this.request({ type: 'visible', visible: false });
+        // Preserve the page-lifetime worker and device.
+    }
+}

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

@@ -0,0 +1,6 @@
+/** Prepare the dim before revealing a context menu, including speculative hold preparation.
+ * Only menu rasters sample this overlay; the displayed popover dims the other controls. */
+export declare function contextBackdrop(document: Document): {
+    owner: string | undefined;
+    alpha: number;
+} | undefined;

package/dist/glass/webgpu/contextBackdrop.js

@@ -0,0 +1,13 @@
+import { backdropOwner } from './backdropLayers.js';
+/** Prepare the dim before revealing a context menu, including speculative hold preparation.
+ * Only menu rasters sample this overlay; the displayed popover dims the other controls. */
+export function contextBackdrop(document) {
+    const hosts = document.querySelectorAll('[data-satin-context-backdrop-active]');
+    const host = hosts[hosts.length - 1];
+    if (!host)
+        return undefined;
+    return {
+        owner: backdropOwner(host),
+        alpha: document.documentElement.dataset.satinAppearance === 'dark' ? 0.48 : 0.2,
+    };
+}

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

@@ -0,0 +1,64 @@
+/** Native light exterior fit, review-2/measurements/context-shadow-fit.json.
+ * Dark uses the same geometric shadow candidate; its near-black signal did not identify a fit. */
+export declare const contextPreviewShadow: readonly [19.544682868986335, 0.29743200247189167, 0.24465397829558655];
+export declare const contextMenuShadow: readonly [17.05975989117854, 0.12642226441997836, 7.75094276443249];
+export declare const contextSampleInset: (treatment?: string) => 20 | 48 | 80;
+export declare const contextBackdropFit: {
+    readonly light: {
+        readonly sigma: 0.031692773778513594;
+        readonly gain: 0.8010016469847555;
+        readonly bias: number;
+    };
+    readonly dark: {
+        readonly sigma: 0.034251656122903235;
+        readonly gain: 0.5188529641684325;
+        readonly bias: number;
+    };
+};
+export declare const contextComposite: {
+    readonly uniforms: readonly ['uResolution', 'uShape', 'uRadius', 'uFilter', 'uAxis', 'uShadow'];
+    readonly textures: readonly ['uTexture'];
+    readonly wgsl: `
+struct P { resolution:vec4f, shape:vec4f, radius:vec4f, response:vec4f, axis:vec4f, shadow:vec4f }
+@group(0) @binding(0) var<uniform> p:P;
+@group(0) @binding(1) var s:sampler;
+@group(0) @binding(2) var source:texture_2d<f32>;
+// Gaussian integral of a rounded rectangle. Integrate horizontal CDF slices
+// through the true rounded aperture, rather than a distance-only halo.
+fn cdf(v:f32)->f32 {
+ let z=abs(v)/sqrt(2.0);let t=1.0/(1.0+.3275911*z);
+ let erf=1.0-(((((1.061405429*t-1.453152027)*t)+1.421413741)*t-.284496736)*t+.254829592)*t*exp(-z*z);
+ return .5*(1.0+sign(v)*erf);
+}
+fn shadowAt(point:vec2f)->f32 {
+ let sigma=p.shadow.x;if(sigma<=0.0){return 0.0;}
+ let local=point-p.shape.xy-vec2f(0,p.shadow.z);var total=0.0;
+ let step=2*p.shape.w/64.0;let exponent=select(2.0,2.900378259,p.radius.y>0.0);
+ for(var i=0;i<64;i++){
+  let yy=-p.shape.w+(f32(i)+.5)*step;let dy=(yy-local.y)/sigma;
+  let corner=max(0.0,abs(yy)-(p.shape.w-p.radius.x));
+  let halfWidth=p.shape.z-p.radius.x+p.radius.x*pow(max(0.0,1.0-pow(corner/p.radius.x,exponent)),1.0/exponent);
+  total+=(cdf((halfWidth-local.x)/sigma)-cdf((-halfWidth-local.x)/sigma))*exp(-.5*dy*dy)*step/(sigma*sqrt(6.283185307));
+ }
+ return total*p.shadow.y;
+}
+@fragment fn main(@location(0) uv:vec2f,@location(1) coord:vec2f)->@location(0) vec4f {
+ var colour=textureSampleLevel(source,s,uv,0);
+ if(p.response.x>0.001){
+  var total=1.0;
+  for(var i=1;i<=6;i++){
+   let w=exp(-.5*pow(f32(i)*.5,2));
+   let delta=p.axis.xy*f32(i)*.5*p.response.x/p.resolution.xy;
+   colour+=(textureSampleLevel(source,s,uv+delta,0)+textureSampleLevel(source,s,uv-delta,0))*w;
+   total+=2*w;
+  }
+  colour/=total;
+ }
+ let point=coord*p.resolution.xy;
+ let q=abs(point-p.shape.xy)-p.shape.zw+p.radius.x;
+ let distance=length(max(q,vec2f(0)))+min(max(q.x,q.y),0)-p.radius.x;
+ let coverage=1-smoothstep(-.5,.5,distance);
+ let face=vec4f(clamp(colour.rgb*p.response.y+vec3f(p.response.z)*colour.a,vec3f(0),vec3f(1)),colour.a)*select(coverage,1.0,p.radius.y>0.0);
+ return face+vec4f(0,0,0,shadowAt(point))*(1-face.a);
+}`;
+};