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

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

@@ -0,0 +1,73 @@
+import type { SurfaceRenderSpec } from '../renderSpecs.js';
+import type { ZoomGlassPose } from '../../navigation/zoomGlass.js';
+export type RegionTrack = {
+    id: string;
+    epoch: number;
+    duration: number;
+    specs: readonly SurfaceRenderSpec[];
+};
+/** Uniformly sampled measured geometry. Only numeric leaves interpolate. */
+export declare function interpolateValue<T>(a: T, b: T, t: number): T;
+export declare function sampleRegion(track: RegionTrack, at: number): Readonly<{
+    touchLight?: import("../renderSpecs.js").GlassTouchLight;
+    excludeRegionIds?: readonly string[];
+    restHidden?: boolean;
+    opacity?: number;
+    occluder?: import("../renderSpecs.js").CapsuleShape;
+    prewarmTransparent?: boolean;
+    recipeMix?: number;
+    sheetOpaqueMix?: number;
+    popoverArrow?: import("../regions.js").PopoverArrow;
+    variant?: import("../lens/referenceProfiles.js").ReferenceVariant;
+    treatment?: 'sheet' | 'expandedSheet' | 'alert' | 'confirmation' | 'contextBackdrop' | 'contextPreview' | 'contextMenu';
+    tint?: import("../regions.js").GlassTint;
+    memberHighlight?: Readonly<{
+        member: number;
+        amount: number;
+        light?: import("../renderSpecs.js").GlassTouchLight;
+    }>;
+    backdropExclusions?: readonly string[];
+    backdropMenuOverlay?: boolean;
+    blurSigmaCssPx?: number;
+    frameHeight: number;
+    frameWidth: number;
+    frameX: number;
+    frameY: number;
+    id: import("../renderSpecs.js").SurfaceId;
+    materialMix: number;
+    materialProfile: 'chrome' | 'searchField' | 'menu';
+    menuTintMix?: number;
+    returningTrigger?: import("../renderSpecs.js").ReturningMenuTrigger;
+    radius: number;
+    sampleHeight: number;
+    sampleInsetX: number;
+    sampleInsetY: number;
+    sampleWidth: number;
+    shaderAperture: boolean;
+    shape: import("../renderSpecs.js").SurfaceShape;
+    tabSelection?: import("../renderSpecs.js").TabSelectionShape;
+    ink?: Readonly<{
+        atlas: Readonly<{
+            width: number;
+            height: number;
+        }>;
+        layers: readonly import("../lens/menuField.js").MenuInkLayer[];
+    }>;
+}>;
+export type NavigationPose = {
+    routes?: readonly {
+        x: number;
+        dim: number;
+        zoom?: ZoomGlassPose;
+    }[];
+    frontX: number;
+    rearX: number;
+    frontDim: number;
+    rearDim: number;
+};
+export type NavigationTrack = {
+    epoch: number;
+    duration: number;
+    poses: readonly NavigationPose[];
+};
+export declare function sampleNavigation(track: NavigationTrack, at: number): NavigationPose;

package/dist/glass/webgpu/productionTracks.js

@@ -0,0 +1,22 @@
+/** Uniformly sampled measured geometry. Only numeric leaves interpolate. */
+export function interpolateValue(a, b, t) {
+    if (typeof a === 'number' && typeof b === 'number')
+        return (a + (b - a) * t);
+    if (Array.isArray(a) && Array.isArray(b))
+        return a.map((v, i) => interpolateValue(v, b[i], t));
+    if (a && b && typeof a === 'object' && typeof b === 'object') {
+        const result = { ...a };
+        for (const key of Object.keys(a))
+            result[key] = interpolateValue(a[key], b[key], t);
+        return result;
+    }
+    return t < 1 ? a : b;
+}
+export function sampleRegion(track, at) {
+    const index = Math.max(0, Math.min(1, (at - track.epoch) / track.duration)) * (track.specs.length - 1);
+    return interpolateValue(track.specs[Math.floor(index)], track.specs[Math.ceil(index)], index % 1);
+}
+export function sampleNavigation(track, at) {
+    const index = Math.max(0, Math.min(1, (at - track.epoch) / track.duration)) * (track.poses.length - 1);
+    return interpolateValue(track.poses[Math.floor(index)], track.poses[Math.ceil(index)], index % 1);
+}

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

@@ -0,0 +1,20 @@
+import type { RuntimeGeometry, SurfaceRenderSpec } from '../renderSpecs.js';
+import type { WebGPURequest as Request } from '../worker/protocol.js';
+/** [left, top, width, height] in CSS px. */
+export type CanvasViewport = readonly [number, number, number, number];
+/** The chrome and lift canvases a runtime presents on. */
+export type SurfaceCanvases = {
+    chrome: HTMLCanvasElement;
+    menu: HTMLCanvasElement;
+    chromeLift: HTMLCanvasElement;
+    menuLift: HTMLCanvasElement;
+};
+/** Place a canvas element on its band of the layer. */
+export declare function placeCanvas(canvas: HTMLCanvasElement, [left, top, width, height]: CanvasViewport): void;
+/** The band a surface's canvas covers. A surface draws only inside its sample rectangle. The
+ * dock's band spans the full width from its highest sample row to the bottom (minimized pills
+ * stay inside); the menu's is its envelope (open and closed). */
+export declare function surfaceViewport(spec: SurfaceRenderSpec, geometry: RuntimeGeometry): CanvasViewport;
+/** Move each surface's canvas (and its lift canvas) onto the band it reaches. Returns the
+ * `layer-viewport` requests for the bands that changed; `installed` holds each layer's band key. */
+export declare function placeSurfaceCanvases(specs: readonly SurfaceRenderSpec[], geometry: RuntimeGeometry, canvases: SurfaceCanvases, liftAttached: boolean, installed: Map<string, string>): Request[];

package/dist/glass/webgpu/productionViewport.js

@@ -0,0 +1,52 @@
+/** Place a canvas element on its band of the layer. */
+export function placeCanvas(canvas, [left, top, width, height]) {
+    Object.assign(canvas.style, {
+        left: `${left}px`,
+        top: `${top}px`,
+        width: `${width}px`,
+        height: `${height}px`,
+    });
+}
+/** The band a surface's canvas covers. A surface draws only inside its sample rectangle. The
+ * dock's band spans the full width from its highest sample row to the bottom (minimized pills
+ * stay inside); the menu's is its envelope (open and closed). */
+export function surfaceViewport(spec, geometry) {
+    const top = Math.max(0, Math.floor(spec.frameY - spec.sampleInsetY));
+    if (spec.id !== 'right')
+        return [0, top, Math.ceil(geometry.width), Math.ceil(geometry.height) - top];
+    const left = Math.max(0, Math.floor(spec.frameX - spec.sampleInsetX));
+    const right = Math.min(Math.ceil(geometry.width), Math.ceil(spec.frameX - spec.sampleInsetX + spec.sampleWidth));
+    const bottom = Math.min(Math.ceil(geometry.height), Math.ceil(spec.frameY - spec.sampleInsetY + spec.sampleHeight));
+    return [left, top, right - left, bottom - top];
+}
+/** Move each surface's canvas (and its lift canvas) onto the band it reaches. Returns the
+ * `layer-viewport` requests for the bands that changed; `installed` holds each layer's band key. */
+export function placeSurfaceCanvases(specs, geometry, canvases, liftAttached, installed) {
+    const requests = [];
+    const placements = specs.flatMap(spec => [
+        {
+            spec,
+            layerId: spec.id === 'right' ? 'menu' : 'chrome',
+            canvas: spec.id === 'right' ? canvases.menu : canvases.chrome,
+        },
+        ...(liftAttached
+            ? [
+                {
+                    spec,
+                    layerId: spec.id === 'right' ? 'menu-lift' : 'chrome-lift',
+                    canvas: spec.id === 'right' ? canvases.menuLift : canvases.chromeLift,
+                },
+            ]
+            : []),
+    ]);
+    for (const { spec, layerId, canvas } of placements) {
+        const viewport = surfaceViewport(spec, geometry);
+        const key = JSON.stringify(viewport);
+        if (installed.get(layerId) === key || viewport[2] <= 0 || viewport[3] <= 0)
+            continue;
+        installed.set(layerId, key);
+        placeCanvas(canvas, viewport);
+        requests.push({ type: 'layer-viewport', layerId, viewport });
+    }
+    return requests;
+}

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

@@ -0,0 +1,37 @@
+/** Wall-time evidence, in a common epoch across the main thread and worker.
+ * Queue completion is not compositor presentation or scanout. No idle sampler. */
+export type GlassTiming = {
+    stage: string;
+    realm: 'main' | 'worker';
+    at: number;
+    ms: number;
+    detail?: string;
+    error?: string;
+};
+export declare const glassNow: () => number;
+export declare function receiveGlassTiming(event: GlassTiming): void;
+/** Worker frame summaries (per interaction kind), newest last; see frameProbe.ts. */
+export declare function receiveGlassFrames(summaries: readonly unknown[]): void;
+export declare function setGlassTimingSink(next: ((event: GlassTiming) => void) | undefined, enabled?: () => boolean): void;
+export declare function glassTiming(stage: string, at?: number, detail?: string | (() => string), error?: unknown): void;
+/** Start of a stage that is timed only for the lag trace: no clock read when the trace is off. */
+export declare const traceStageStart: () => number;
+/** Record a lag-trace-only stage started with `traceStageStart`. Nothing is built or kept when the trace is off. */
+export declare function traceStage(stage: string, started: number, detail?: () => string): void;
+export declare function glassTimed<T>(stage: string, work: () => T, detail?: string | (() => string)): T;
+export declare function glassTimedAsync<T>(stage: string, work: () => Promise<T>, detail?: string | (() => string)): Promise<T>;
+export declare function glassProfile(): {
+    firstPresent: GlassTiming | undefined;
+    firstReady: GlassTiming | undefined;
+    startup: GlassTiming[];
+    events: GlassTiming[];
+    frames: unknown[];
+    totals: {
+        [k: string]: {
+            count: number;
+            ms: number;
+            maxMs: number;
+        };
+    };
+    boundary: string;
+};

package/dist/glass/webgpu/profile.js

@@ -0,0 +1,101 @@
+import { lagMark, lagTraceEnabled } from './lagTrace.js';
+const events = [], startup = [];
+const totals = new Map();
+let firstPresent, firstReady;
+let presented = false, sink;
+let sinkEnabled = () => true;
+export const glassNow = () => performance.timeOrigin + performance.now();
+export function receiveGlassTiming(event) {
+    // The page's lag trace keeps every timing event of both realms (worker events arrive here too).
+    if (lagTraceEnabled() && typeof document !== 'undefined')
+        lagMark({
+            stage: `${event.realm}:${event.stage}`,
+            at: event.at,
+            ms: event.ms,
+            values: { detail: event.detail, error: event.error },
+        });
+    events.push(event);
+    if (events.length > 240)
+        events.shift();
+    if (!presented && startup.length < 160)
+        startup.push(event);
+    if (event.stage === 'first-present-complete') {
+        presented = true;
+        firstPresent ??= event;
+    }
+    if (event.stage === 'production-prepared')
+        firstReady ??= event;
+    const key = event.realm + ':' + event.stage, t = totals.get(key) ?? { count: 0, ms: 0, maxMs: 0 };
+    t.count++;
+    t.ms += event.ms;
+    t.maxMs = Math.max(t.maxMs, event.ms);
+    totals.set(key, t);
+}
+const frameSummaries = [];
+/** Worker frame summaries (per interaction kind), newest last; see frameProbe.ts. */
+export function receiveGlassFrames(summaries) {
+    frameSummaries.push(...summaries);
+    if (frameSummaries.length > 40)
+        frameSummaries.splice(0, frameSummaries.length - 40);
+}
+export function setGlassTimingSink(next, enabled = () => true) {
+    sink = next;
+    sinkEnabled = enabled;
+}
+export function glassTiming(stage, at = glassNow(), detail, error) {
+    const send = !!sink && sinkEnabled();
+    const detailed = send || lagTraceEnabled();
+    const event = {
+        stage,
+        at,
+        ms: glassNow() - at,
+        realm: typeof document === 'undefined' ? 'worker' : 'main',
+        detail: typeof detail === 'function' ? (detailed ? detail() : undefined) : detail,
+        error: error === undefined ? undefined : String(error),
+    };
+    receiveGlassTiming(event);
+    if (send)
+        sink?.(event);
+}
+/** Start of a stage that is timed only for the lag trace: no clock read when the trace is off. */
+export const traceStageStart = () => (lagTraceEnabled() ? glassNow() : 0);
+/** Record a lag-trace-only stage started with `traceStageStart`. Nothing is built or kept when the trace is off. */
+export function traceStage(stage, started, detail) {
+    if (lagTraceEnabled())
+        glassTiming(stage, started, detail);
+}
+export function glassTimed(stage, work, detail) {
+    const at = glassNow();
+    try {
+        const value = work();
+        glassTiming(stage, at, detail);
+        return value;
+    }
+    catch (error) {
+        glassTiming(stage, at, detail, error);
+        throw error;
+    }
+}
+export async function glassTimedAsync(stage, work, detail) {
+    const at = glassNow();
+    try {
+        const value = await work();
+        glassTiming(stage, at, detail);
+        return value;
+    }
+    catch (error) {
+        glassTiming(stage, at, detail, error);
+        throw error;
+    }
+}
+export function glassProfile() {
+    return {
+        firstPresent,
+        firstReady,
+        startup,
+        events,
+        frames: frameSummaries,
+        totals: Object.fromEntries(totals),
+        boundary: 'Wall time; RPC includes queueing, upload is CPU enqueue, GPU completion excludes compositor/scanout.',
+    };
+}

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

@@ -0,0 +1,337 @@
+import type { GlassCanvas, GlassViewport } from '../rendererContract.js';
+import { type LensDebugView } from './lensDebug.js';
+import { type GraphLease } from './frameGraph.js';
+import type { NavigationPose } from './productionTracks.js';
+import { LayerDevice, type GlassLayer } from './layers.js';
+import type { RasterSetup } from '../worker/protocol.js';
+import type { SurfaceRenderSpec } from '../renderSpecs.js';
+export declare const drawableCosts: () => {
+    submittedPixels: number;
+    submittedCommandBuffers: number;
+    pixels: number;
+    waitMs: number;
+    count: number;
+};
+export declare function takePresentedCanvases(): string;
+/** Thin WebGPU reference candidate. No Pixi imports, contexts, tickers, or DOM reads. */
+/** A retained spec's material at a new appearance. The tab bar's material blur follows the
+ * appearance; any other selection (the scope bar's thumb) keeps its region's own material. */
+export declare function retainedAppearanceSpec(spec: SurfaceRenderSpec, appearance: RasterSetup['appearance']): SurfaceRenderSpec;
+export declare class WebGPURaster {
+    private submissionAllowed;
+    setSubmissionGate(allowed: () => boolean): void;
+    private resultOwner;
+    private device;
+    private context;
+    private canvas;
+    private passes;
+    private setup?;
+    private lensDebug;
+    setLensDebug(view: LensDebugView): void;
+    private targets;
+    private graph;
+    private textureLeases;
+    private imageLeases;
+    private bitmaps?;
+    private compositePipeline;
+    private overlayPipeline;
+    private presentPipeline;
+    private format;
+    private lost;
+    private suspended;
+    private covered;
+    private initialized;
+    onLoss: () => void;
+    onRestore: () => void;
+    /** `presentPixels` counts fragments the layer-sized result/present passes shade; `presentAttachmentPixels` what they would shade unscissored. */
+    readonly stats: {
+        sourceInstalls: number;
+        sourceBytes: number;
+        draws: number;
+        submissions: number;
+        presentPixels: number;
+        presentAttachmentPixels: number;
+    };
+    private owner;
+    private unsubscribe?;
+    init(canvas: GlassCanvas, owner: LayerDevice, layer: GlassLayer, presenter?: import('../rendererContract.js').GlassPresenter): Promise<void>;
+    private bindDevice;
+    /** Update retained chrome material before unsuspending its first resume frame. */
+    setAppearance(appearance: RasterSetup['appearance']): void;
+    dispose(): void;
+    /** Keep only the pixels this surface last presented on its canvas: drop its setup and every
+     * image and texture lease (a hidden tab's region must not pin a capture that has left the
+     * resident budget). A parked surface cannot draw by any path (motion, device restore, app
+     * resume): nothing encodes without a setup. It draws again once it is installed again. */
+    park(): void;
+    forkRegion(): WebGPURaster;
+    private useDevice;
+    private useDeviceScoped;
+    loseDevice(): void;
+    private release;
+    private allocate;
+    private allocateScoped;
+    private upload;
+    /** `present:false` prepares storage and uploads without drawing; a batch's final render presents every surface together. */
+    install(setup: RasterSetup, front: ImageBitmap, rear: ImageBitmap, glyphs: ImageBitmap, present?: boolean): void;
+    /** The scene retains canonical images; each presenter acquires its own leases. */
+    installRetained(setup: RasterSetup, source: GraphLease<ImageBitmap>, foreground: GraphLease<ImageBitmap>, present?: boolean): boolean;
+    private installLeases;
+    clear(): void;
+    setCovered(covered: boolean): void;
+    get isCovered(): boolean;
+    setVisible(visible: boolean, deferDraw?: boolean): void;
+    /** `scissor` ([x,y,w,h] device pixels, clamped to `size`) bounds fragment work to the
+     * pixels a pass can change; the clear load op still covers the whole attachment. */
+    private custom;
+    private timing?;
+    benchmark(count?: number): Promise<{
+        samples: {
+            cpuMs: number;
+            gpuMs: number | null;
+        }[];
+        timestampQuery: boolean;
+        boundary: string;
+    }>;
+    get spec(): Readonly<{
+        touchLight?: import("../renderSpecs.js").GlassTouchLight;
+        excludeRegionIds?: readonly string[];
+        restHidden?: boolean;
+        opacity?: number;
+        occluder?: import("../renderSpecs.js").CapsuleShape;
+        prewarmTransparent?: boolean;
+        recipeMix?: number;
+        sheetOpaqueMix?: number;
+        popoverArrow?: import("../regions.js").PopoverArrow;
+        variant?: import("../lens/referenceProfiles.js").ReferenceVariant;
+        treatment?: 'sheet' | 'expandedSheet' | 'alert' | 'confirmation' | 'contextBackdrop' | 'contextPreview' | 'contextMenu';
+        tint?: import("../regions.js").GlassTint;
+        memberHighlight?: Readonly<{
+            member: number;
+            amount: number;
+            light?: import("../renderSpecs.js").GlassTouchLight;
+        }>;
+        backdropExclusions?: readonly string[];
+        backdropMenuOverlay?: boolean;
+        blurSigmaCssPx?: number;
+        frameHeight: number;
+        frameWidth: number;
+        frameX: number;
+        frameY: number;
+        id: import("../renderSpecs.js").SurfaceId;
+        materialMix: number;
+        materialProfile: 'chrome' | 'searchField' | 'menu';
+        menuTintMix?: number;
+        returningTrigger?: import("../renderSpecs.js").ReturningMenuTrigger;
+        radius: number;
+        sampleHeight: number;
+        sampleInsetX: number;
+        sampleInsetY: number;
+        sampleWidth: number;
+        shaderAperture: boolean;
+        shape: import("../renderSpecs.js").SurfaceShape;
+        tabSelection?: import("../renderSpecs.js").TabSelectionShape;
+        ink?: Readonly<{
+            atlas: Readonly<{
+                width: number;
+                height: number;
+            }>;
+            layers: readonly import("../lens/menuField.js").MenuInkLayer[];
+        }>;
+    }> | undefined;
+    private navigation?;
+    setNavigation(pose: NavigationPose): void;
+    /** Route cells in its installed navigation atlas (0 when it composes a settled capture). */
+    get navigationRoutes(): number;
+    private scrollY;
+    setTrigger(trigger: RasterSetup['trigger']): void;
+    setScroll(y: number): void;
+    /** A fixed region's backdrop moved under it: same storage and uploads, new sampling origin. */
+    setSourceOrigin(origin: {
+        x: number;
+        y: number;
+    }): void;
+    /** A region presenter moved in the viewport (its canvas scrolled or relaid out). */
+    setViewportOrigin(origin: {
+        x: number;
+        y: number;
+    }): void;
+    private liveViewport?;
+    /** Moving the canvas changes where it looks, never its retained source or target storage. */
+    setViewport(viewport: GlassViewport): void;
+    updateSpec(spec: RasterSetup['spec']): void;
+    setLift(lift: RasterSetup['lift']): void;
+    private lastX;
+    draw(x: number, clear?: boolean): void;
+    private drawScoped;
+    submitted(): void;
+    private presentRect?;
+    /** Layer-space device-pixel origin of the result texture (integer, so presents are 1:1). */
+    private resultOrigin;
+    /** Chrome surfaces (a bar or menu on a full-screen layer) keep a local result; a
+     * region presenter's layer already is its sample rectangle and keeps layer space. */
+    private localResult;
+    /** Device-pixel offset of this layer's canvas within its layer. */
+    private canvasOffset;
+    private canvasSize;
+    /** Size the shared layer canvas to a band of its layer (the element is placed there by
+     * the page): a lift overlay presents a strip, not a second full-screen canvas. */
+    setCanvasViewport(viewport: readonly [number, number, number, number] | undefined): void;
+    /** Surface opacity on its layer canvas (spec.opacity; 1 when absent). */
+    private presentAlpha;
+    /** `spec.occluder` on the layer canvas: [radius, centre x, centre y, half width, half height]
+     * in canvas pixels, or zeros. */
+    private presentOccluder;
+    /** The present uniform for this surface's layer canvas: placement, opacity and occluder. */
+    private presentUniform;
+    private presentScissor;
+    /** Present uniform: where the result texture lands on the layer canvas. */
+    private presentOrigin;
+    private resultSize;
+    /** Result holds nothing (a lift overlay at rest): presenting it would only clear. */
+    private resultEmpty;
+    /** Counts every re-encode of the result: an unchanged count means unchanged result pixels. */
+    private resultRevision;
+    /** The next layer present of this raster's canvas is never skipped (its content, size or
+     * device changed outside `presentLayer`). */
+    private forgetPresent;
+    /** Present every surface of one canvas layer in a single render pass: one clear, one
+     * store of the canvas per frame instead of a load+store per surface. Results are
+     * per-raster storage, so presenting after every surface has encoded is safe.
+     * Returns false, drawing nothing, when the canvas already shows exactly this (see
+     * `presentedLayers`): the same results at the same places, or nothing at all. */
+    static presentLayer(encoder: GPUCommandEncoder, rasters: readonly WebGPURaster[]): boolean;
+    private presentDraw;
+    /** Scroll-attached glass is part of the scrolling content, and the navigation bar's scroll-edge
+     * effect is painted over that content (CSS, a layer above the scroll container). Its own
+     * backdrop is the content behind it, without the edge: composing the edge in as well applied
+     * the effect twice where such glass passes under the bar, and redrew it in every scroll frame
+     * while it was there. Bar glass sits above the edge and keeps refracting the treated backdrop. */
+    private belowScrollEdges;
+    private lastBackdropKey;
+    /** Diagnostics: the backdrop key the last composite used. */
+    get composedBackdropKey(): string;
+    /** This surface's sample rectangle in viewport coordinates. */
+    private backdropRect;
+    /** Whether the backdrop under this surface changed since its last encode (a plane scrolled or moved). */
+    backdropStale(): boolean;
+    /** Sample-sized scratch for the scroll-edge blur, acquired only by surfaces under a bar edge. */
+    private edgeScratch;
+    /** Compose the screen-space backdrop under this surface into its source target: the
+     * page background, then each plane clipped to its viewport rectangle. The content
+     * plane keeps the navigation composite (pose, route atlas) on the raster's own capture. */
+    private composeBackdrop;
+    /** Encode this surface's passes up to its result; false when it cannot draw now. */
+    encodeResult(encoder: GPUCommandEncoder, x: number): boolean;
+    /** Outside a surface's sample rectangle its result is exactly transparent (every pass clears,
+     * then writes only inside its output frame), so only that rectangle needs shading. A menu's
+     * material frame is its padded pyramid extent. Device px on the layer. */
+    private sampleRectangle;
+    /** The whole layer, placed relative to this surface's sample rectangle (device px). */
+    private layerPresentOrigin;
+    /** The backdrop capture, the material (or presentation treatment), the tab selection and the
+     * lift, each re-encoded only when its inputs changed. */
+    private encodeVisibleResult;
+    /** The composited backdrop under the surface (source target) and its blur pyramid, re-encoded
+     * only when the capture, pose, scroll or backdrop under it changed. */
+    private encodeCapture;
+    /** The material into the result: a menu copies its padded material; any other surface presents
+     * it inside its sample rectangle (the present shader is zero outside it, which the clear wrote). */
+    private encodeResultPresent;
+    /** A pressed control's lift: with fitted optics, the shared-lift lens over the unchanged
+     * result underneath (optionally diffused); without, the plain lens kernel. */
+    private encodeLift;
+    settled(): Promise<void>;
+    stageSnapshot(stage: 'source' | 'pyramid' | 'material' | 'composed' | 'vertical', level: number): Promise<{
+        width: number;
+        height: number;
+        pixels: Uint8Array<ArrayBuffer>;
+        unavailable: string;
+    } | {
+        unavailable?: undefined;
+        width: number;
+        height: number;
+        pixels: Uint8Array<ArrayBuffer>;
+    }>;
+    snapshot(): Promise<{
+        width: number;
+        height: number;
+        pixels: Uint8Array<ArrayBuffer>;
+    }>;
+    /** What this surface currently presents (diagnostics and the menu-close regression check). */
+    presentation(): {
+        id: import("../renderSpecs.js").SurfaceId;
+        restHidden: boolean;
+        opacity: number;
+        empty: boolean;
+        covered: boolean;
+        lift: number;
+        centre: number[] | null;
+        radius: number | null;
+    } | null;
+    report(): {
+        deviceRequests: number;
+        deviceLosses: number;
+        restores: number;
+        canvasContexts: number;
+        nullAdapters: number;
+        forcedNullAdapters: number;
+        adapterRecoveryPending: boolean;
+        adapterVisible: boolean;
+        lastLoss: {
+            reason: string;
+            message: string;
+        } | undefined;
+        activeCanvases: number;
+        presentationBackingBytes: number;
+        layers: Readonly<{
+            id: string;
+            depth: number;
+            attachment: Readonly<{
+                kind: 'fixed';
+            }> | Readonly<{
+                kind: 'scroll';
+                scrollId: string;
+            }>;
+        }>[];
+        presenters: (Readonly<{
+            id: string;
+            role?: 'material' | 'lift';
+            layerId: string;
+            regionIds: readonly string[];
+            origin: Readonly<{
+                x: number;
+                y: number;
+            }>;
+            fieldOrigin?: Readonly<{
+                x: number;
+                y: number;
+            }>;
+            width: number;
+            height: number;
+            resolution: number;
+        }> | {
+            id: string;
+            layerId: string;
+        })[];
+        errors: string[];
+        sourceInstalls: number;
+        sourceBytes: number;
+        draws: number;
+        submissions: number;
+        presentPixels: number;
+        presentAttachmentPixels: number;
+        appearance: import("../testing.js").Appearance | null;
+        gpuBackingBytes: number;
+        sharedGraph: {
+            gpuBytes: number;
+            retainedBitmapBytes: number;
+            textures: number;
+            images: number;
+            generation: number;
+        };
+        lost: boolean;
+        suspended: boolean;
+        covered: boolean;
+    };
+}