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

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

@@ -0,0 +1,294 @@
+import { type MenuCornerPose } from '../lens/menuCornerMotion.js';
+import { type MenuMorphPose } from '../lens/menuMorphMotion.js';
+import type { GlassRegionEvent } from '../rendererContract.js';
+import { type GraphLease } from './frameGraph.js';
+import { type InteractivePressKind } from '../lens/interactivePress.js';
+import { type GlassContactPose } from '../lens/interactiveContact.js';
+import { type GlassPresenter, type GlassRendererRequest, type GlassSource } from '../rendererContract.js';
+import { type GlassRegion, type GlassSceneSnapshot } from '../regions.js';
+import type { SurfaceRenderSpec } from '../renderSpecs.js';
+import type { NavigationPose } from './productionTracks.js';
+import type { Appearance } from '../lens/theme.js';
+import { LayerDevice } from './layers.js';
+import { type ControlLiftKind } from '../lens/controlLift.js';
+import { WebGPURaster } from './raster.js';
+/** A presenter is a DOM stacking slot. Its shader coordinates remain local. */
+export declare function regionSpec(region: GlassRegion, presenter: GlassPresenter, scene: GlassSceneSnapshot): SurfaceRenderSpec;
+/** The selection's labels as ink: the region's whole foreground atlas, captured in the region's
+ * sample space (regionBridge), drawn over the pill (rasterMaterial encodeTabSelection). */
+export declare function selectionInk(spec: SurfaceRenderSpec, foreground: {
+    width: number;
+    height: number;
+} | undefined): SurfaceRenderSpec;
+export declare function fieldRegionSpec(regions: readonly GlassRegion[], presenter: GlassPresenter, scene: GlassSceneSnapshot): SurfaceRenderSpec;
+export { menuMotionProfile as emergeProfile } from '../lens/menuMorphMotion.js';
+/** Shared measured mass 1, stiffness 186.57, damping 25.13. */
+export declare function fieldSpringProgress(ms: number): number;
+/** An emerging region samples over its trigger and panel (the presenter bounds). Its glass is one
+ * field of two members (lens/menuField.ts): the panel member moves from the trigger's seed (its
+ * round part at the menu's own button: the whole trigger when it is a circle; progress 0) to the
+ * panel (1) inside that fixed envelope, and the trigger member holds, is absorbed on open and
+ * grows back on close. `field` gives the time since the morph's first frame; without it the pose
+ * alone decides (the trigger member is present only at progress 0). */
+export declare function emergeRegionSpec(spec: SurfaceRenderSpec, region: GlassRegion, presenter: GlassPresenter, progress: number | MenuMorphPose, corner?: MenuCornerPose, liveSource?: NonNullable<GlassRegion['emerge']>['from'], field?: {
+    direction: 'open' | 'close';
+    ms: number;
+    pressHighlight: number;
+    settled: boolean;
+    recipeMix?: number;
+}, appearance?: Appearance): SurfaceRenderSpec;
+/** The shared native press growth (INTERACTIVE_GLASS_PRESS): a surface's 160pt circle becomes
+ * 164pt while held, a button grows 16pt wide. Preserve the material and expand its actual
+ * aperture; never cover it with the unfiltered page. `amount` is the press spring (it
+ * overshoots on press and undershoots on release). `pose` is the contact's follow and squish
+ * (InteractiveContact): it moves the grown shape and changes its width and height, keeping a
+ * capsule's ends round.
+ */
+export declare function pressedRegionSpec(spec: SurfaceRenderSpec, amount: number, kind?: InteractivePressKind, memberIndex?: number, pose?: GlassContactPose): SurfaceRenderSpec;
+/** A Toggle or Slider thumb lens inside its control's frame: a capsule of the lifted size at the
+ * contact's lens centre (frame-local CSS px). At rest it is prepared but transparent; the page's
+ * opaque white thumb covers the hand-off while the lens grows. */
+export declare function controlLensSpec(spec: SurfaceRenderSpec, kind: ControlLiftKind, amount: number, centerX: number): SurfaceRenderSpec;
+/** Implements the public scene/source protocol on the page's existing GPU owner. */
+export declare class RegionScene {
+    private samplePixels;
+    private scene;
+    private presenters;
+    private sources;
+    private emptyForeground?;
+    private drop;
+    /** Install the chrome's shared capture (already retained in the frame graph under
+     * `key`) as the root backdrop: one transfer and one upload serve chrome and regions. */
+    shareSource(descriptor: GlassSource, bitmap: ImageBitmap, key: string, ordered?: boolean): Promise<void>;
+    get sharedRevision(): number | undefined;
+    get navigationActive(): boolean;
+    private motions;
+    private touchLights;
+    /** Scope thumbs in flight (GlassRegion.selection): segment index from → to since `start`. */
+    /** The thumbs of segmented regions (the search scope bar), by region id. */
+    private thumbs;
+    private reducedMotion;
+    /** Emerging regions (glass Menus): direction, start (epoch ms) and the progress it starts from. */
+    private emerges;
+    private fields;
+    private appearance;
+    /** Presenters whose backdrop only moved (scroll under a fixed region): redrawn once
+     * in the next worker frame instead of reinstalled and fenced per scroll event. */
+    private moved;
+    /** A pressed interactive region is being dragged or held (its motion is live). */
+    get pressing(): boolean;
+    /** The press highlight still changes (held: its first 600 ms; released: its fade). */
+    private highlighting;
+    /** A backdrop plane scrolled or the plane set changed: redraw only presenters whose
+     * composed backdrop differs (scroll-attached glass over its own plane does not). */
+    backdropMoved(): void;
+    /** The plane set is about to be replaced by another tab's (a source preparation committed).
+     * `regionIds` are the regions of tabs that are not selected. Called BEFORE the new planes are
+     * installed, so each of those presenters is drawn one last time over its own tab's backdrop (a
+     * press still animating is settled at rest first) and then parked: from here on its canvas keeps
+     * those pixels, and nothing can draw another tab's backdrop into it. */
+    holdForBackdropChange(regionIds: readonly string[]): void;
+    /** The new plane set is installed. Every region that is not in `heldIds` belongs to the selected
+     * tab: it resumes now (the next install redraws it over its own backdrop), at the same point of
+     * the batch where an unheld region is redrawn. */
+    resumeForBackdropChange(heldIds: readonly string[]): void;
+    /** Install what the last resume left pending: a parked presenter whose region is no longer held.
+     * Nothing is pending in a scene that held nothing, so a renderer without regions (or one that has
+     * not been given its appearance yet) is never installed from here. */
+    installPending(): Promise<void>;
+    private motionLive;
+    private park;
+    /** Marks parked presenters whose region is not held for a repaint; true when there is one. */
+    private repaintVisibleParked;
+    private keyboardSampledAt;
+    get active(): boolean;
+    private emergeRunning;
+    private emergeSample;
+    private presentEmerge;
+    /** A navigation in progress: presenters over the settled chrome backdrop compose its route atlas
+     * (the moving routes, the destination included) in place of the content plane, at the pose of
+     * every worker frame, as native glass shows the page moving under it. The next settled backdrop
+     * (the capture after the navigation) ends it. */
+    private navigation?;
+    navigationSource(navigation: {
+        key: string;
+        lease: GraphLease<ImageBitmap>;
+        routes: number;
+        contentLayer: string;
+        width: number;
+        height: number;
+        pose?: NavigationPose;
+        deferPresent?: boolean;
+        rows?: readonly {
+            top: number;
+            bottom: number;
+        }[];
+    }): Promise<void>;
+    setNavigation(pose: NavigationPose, key?: string, draw?: boolean): void;
+    private presenterNavigationPose;
+    /** Glass changing size inside a still canvas: draw each frame's shape at its presentation time. */
+    private presentShapeTracks;
+    private shapeAt;
+    private presentTrackedViewport;
+    /** Whether a region's press or contact still moves (or lights) its glass at `at`. */
+    private interactionMoving;
+    /**
+     * `spec` (a region's scene spec in `presenter`) posed by its shape track and by the bottom
+     * accessory's run at `at` when one is live: the run's capsule width and ink and, for a held-still canvas, its travel
+     * inside the canvas. Without a run (or before its ink arrives) it is `spec` unchanged.
+     *
+     * The run and a press both draw the accessory, and a press builds on this pose. A press that
+     * rebuilt from the scene spec drew the run's whole envelope, without ink, at the committed
+     * row, until the run's next frame: the owner's smudge recording (a finger on the mini player
+     * while the bar collapsed) showed that empty capsule running past the Search circle.
+     */
+    private posedRegionSpec;
+    /** Where a region's glass frame sits in its presenter at the region's laid-out position. */
+    private restingFrame;
+    /**
+     * The time the last frame sampled the tracks at. A draw between frames (an install or a
+     * scroll update) poses accessory tracks at that time too: the other surfaces of the frame,
+     * such as the tab bar on its minimize track, stay where that frame sampled them, and a pose
+     * taken at the draw's own time put the moving accessory a frame ahead of the bar.
+     */
+    private sampledAt?;
+    private trackClock;
+    sample(at: number, presentationAt?: number): void;
+    /** A selection the page changed slides its thumb from wherever it is now (SelectionThumb). */
+    private retargetSelections;
+    /** The finger on a segmented region's thumb. */
+    private selectionInput;
+    /** The bar draws its pill where the thumb is; its lift overlay draws the lens over the bar. */
+    private presentSelection;
+    private illuminate;
+    /** A segmented region with its thumb where the motion has it, and its bar grown and lit while
+     * a finger presses it (the segmented row of GLASS_CONTACT_PHYSICS). */
+    private posedSelection;
+    private presentMotion;
+    /**
+     * The light of a pressed interactive shape: the menu's touch light at the finger
+     * (InteractiveContact). Each kind's light is a row of GLASS_CONTACT_PHYSICS: a button-like
+     * glass whitens across its shape on its measured curve; a surface's light is the menu field
+     * scaled to native, over a held floor across the whole shape. In a field of several members the light stays inside the
+     * pressed member's aperture (one member's light never spills onto its neighbours).
+     */
+    private pressLight;
+    setLensDebug(view: import('./lensDebug.js').LensDebugView): void;
+    private deferred;
+    private visible;
+    private sourceRevision?;
+    private sourcePending;
+    private topologyPending;
+    /** A capture cannot draw retained geometry from the previous root/layout. Keep its
+     * last submitted pixels until the matching scene arrives; do not reset any motion. */
+    beginSourceChange(revision: number): void;
+    private submissionAllowed;
+    private owner;
+    /** Worker-to-page events (a close morph that ended, so its panel can be torn down). */
+    private notify;
+    constructor(owner: LayerDevice, notify?: (event: GlassRegionEvent) => void, submissionAllowed?: () => boolean);
+    request(request: GlassRendererRequest): Promise<unknown>;
+    /** New source images (uploads) since the last install: only those need a completion fence. */
+    private presentationReceipt;
+    private sourcesChanged;
+    private install;
+    prepareResume(): Promise<void>;
+    present(): void;
+    navigationRasters(): WebGPURaster[];
+    snapshot(id: string): Promise<{
+        width: number;
+        height: number;
+        pixels: Uint8Array<ArrayBuffer>;
+    }>;
+    diagnostics(): {
+        navigation: {
+            key: string;
+            pose: NavigationPose | undefined;
+        } | undefined;
+        drawableCosts: {
+            submittedPixels: number;
+            submittedCommandBuffers: number;
+            pixels: number;
+            waitMs: number;
+            count: number;
+        };
+        samplePixels: number;
+        presenterCosts: {
+            id: string;
+            regions: readonly string[];
+            role: "lift" | "material" | undefined;
+            zoomRoute: number | undefined;
+            width: number;
+            height: number;
+            stats: {
+                sourceInstalls: number;
+                sourceBytes: number;
+                draws: number;
+                submissions: number;
+                presentPixels: number;
+                presentAttachmentPixels: number;
+            } | null;
+            presentation: {
+                id: import("../renderSpecs.js").SurfaceId;
+                restHidden: boolean;
+                opacity: number;
+                empty: boolean;
+                covered: boolean;
+                lift: number;
+                centre: number[] | null;
+                radius: number | null;
+            } | null;
+        }[];
+        presenterOrigins: any[][];
+        regionPoses: {
+            region: string;
+            accessoryTrack: {
+                epoch: number;
+                held: boolean;
+            } | null;
+            foreground: boolean;
+            interaction: boolean;
+            role: "lift" | "material" | undefined;
+            canvas: {
+                x: number;
+                y: number;
+                width: number;
+            };
+            frame: {
+                x: number;
+                y: number;
+            } | null;
+            capsuleWidth: number | null;
+            inkLayers: number;
+            covered: boolean | undefined;
+            parked: boolean;
+        }[];
+        interactions: {
+            id: string;
+            epoch: number;
+            active: boolean;
+            pending: boolean;
+            amount: number;
+            press: number;
+            model: string;
+        }[];
+        backend: string;
+        canvasContexts: number;
+        devices: number;
+        draws: number;
+        submissions: number;
+        presenters: number;
+        regions: number;
+        sources: number;
+        retainedSourceBytes: number;
+        visible: boolean;
+        scene: Readonly<{
+            revision: number;
+            sourceRevision?: number;
+            backdropOwners?: readonly string[];
+            layers: readonly import("./layers.js").GlassLayer[];
+            scrolls: readonly import("../regions.js").GlassScrollSnapshot[];
+            regions: readonly GlassRegion[];
+        }>;
+    };
+}