@vibecook/ice 0.11.0 → 0.15.0-desk.1

package/dist/types/packages/desk/src/ground.d.ts

@@ -0,0 +1,537 @@
+import type { Surface } from "./engine/device";
+import { CardPass } from "./card/card";
+import { type KindFault } from "./faults";
+import { type MissingFaces } from "./missing/pass";
+import { HoldPass } from "./hold/focus";
+import type { HoldShaders } from "./hold/shaders";
+import { type KindPass, type KindProgram, type RenderTarget, type StratumName } from "./kind";
+import { type View } from "./lattice/lod";
+import type { MatLight } from "./mat/night";
+import { type GridConfig, type GridStats, type SlotFrame } from "./mat/grid";
+import { CuttingMat } from "./mat/mat-pass";
+import type { MatShaders } from "./mat/shaders";
+import type { MarksInput } from "./marks/layout";
+import { MarksPass } from "./marks/pass";
+import type { MarksShaders } from "./marks/shaders";
+import { type TrayFrameInputs, TrayPass } from "./tray/pass";
+import type { TrayShaders } from "./tray/shaders";
+import { TraySlots } from "./tray/specimens";
+import { type Presentation } from "./nav/portal";
+import type { GroundTheme } from "./theme";
+export type { CardBinding, CardMaterial, KindExtra, KindPass, KindProgram, RenderTarget, SlotContext, StratumName } from "./kind";
+export { STRATA } from "./kind";
+export type { MarkBar, MarkBox, MarkFrame, MarkGuide, MarkMarquee, MarkObject, MarkRuler, MarksInput, MarkTape, MarkUnion } from "./marks/layout";
+export { MARKS_SHADER_FILES, marksShaders } from "./marks/shaders";
+export type { TrayFrameInputs } from "./tray/pass";
+export { TRAY_SHADER_FILES, trayShaders } from "./tray/shaders";
+export interface GroundOptions {
+    /**
+     * The device the HOST owns — the engine's (`acquireCompositorDevice()`, handed to the layer through its
+     * context) or the layer's own (`engine/device.ts` `acquire()`, as the oracle's is). The ground never
+     * makes one: every texture the compose pass samples must live on the same device.
+     */
+    readonly device: GPUDevice;
+    /**
+     * The swap chain the frames go into — the HOST makes it (`surface(device, canvas)` from
+     * `@ice/desk`'s src/host/, the one module that names a canvas; a test's fake), so this composition
+     * root never touches the DOM (design-015 §3 `desk-dom-free`, D2a-world).
+     */
+    readonly surface: Surface;
+    /** The cutting mat (mat/mat-pass.ts) — the ground's own: every slot draws it first. */
+    readonly mat: MatShaders;
+    /**
+     * The kinds this ground draws — its REGISTRY (kind.ts; the desk's own are `DESK_KINDS`, `@ice/desk/kinds`).
+     * Names are unique. Each kind's pass is made on the root's mat; the kinds prepare in this order and draw
+     * stratum by stratum, then in each slot's paint order.
+     */
+    readonly kinds: readonly KindProgram[];
+    /**
+     * The desk's chrome (marks/pass.ts; design-015 §7, D4a): the marks pass, drawn in the ROOT's pass after every
+     * stratum — the selection's brackets, the vellum, the laser, the tape — when a frame names its `marks`. Absent =
+     * a ground that draws no chrome.
+     */
+    readonly marks?: MarksShaders;
+    /**
+     * The hand (hold/focus.ts; design-015 §8, D4b): the focus behind an object in hand and the object over it, when a
+     * frame names its `held`. Absent = a ground that never picks anything up (a frame's `held` is then ignored).
+     */
+    readonly hold?: HoldShaders;
+    /**
+     * The pegboard tray (tray/pass.ts; design-017, K3): the drawer, drawn in the ROOT's pass after the marks when a frame names its
+     * `tray`. Absent = a ground with no tray.
+     */
+    readonly tray?: TrayShaders;
+    /**
+     * A GPU error the kinds' creation window caught that no kind raises alone (petition I24, `createKindPasses`): not a kind's — told
+     * here as the device would have told its uncaptured-error handler (the layer's `onError`: `degraded`). Absent: it is said on the console.
+     */
+    readonly onError?: (error: GPUError) => void;
+}
+/** A layer a host rendered first, laid on the mat inside the ground's pass (it sets its own scissor; the ground restores the slot's). */
+export interface Underlay {
+    draw(pass: GPURenderPassEncoder): void;
+}
+/**
+ * One object on a desk as the ground takes it: its kind's name (a registered one) and the record that kind's pass draws — and
+ * its KEY (D6, design-015 §4.3): stable across frames (the builder's entity; a ghost's negated), so the kind's persistent records
+ * keep the object's slot and write it only when the record object changed. Absent: the record is packed afresh every frame.
+ */
+export interface SlotObject {
+    readonly kind: string;
+    readonly record: unknown;
+    readonly key?: number | undefined;
+}
+/** One desk's ground: its camera, grid, objects and presentation — the root's, a departed desk's, or a mini mat's inside. */
+export interface SlotInputs extends SlotFrame {
+    /** The grid; the root may leave it unset and set `ground.grid` instead — every other slot names its own. */
+    readonly grid?: GridConfig;
+    /**
+     * Things drawn ON THE MAT by passes of their own, beneath everything else on the desk
+     * (CALENDAR.md: the desk calendar — the host renders its layer first, the ground lays it here).
+     */
+    readonly underlays?: readonly Underlay[];
+    /**
+     * The objects on this desk in PAINT ORDER, lowest first — the caller sorts: strata first (the ground draws
+     * stratum by stratum whatever the list says), then its own order within each. A kind's records are its
+     * objects, in this order; every kind named must be registered.
+     */
+    readonly objects?: readonly SlotObject[];
+    /** The live insides of this desk's sheets (MINIMAT.md §3): each drawn right after the object `at` names. */
+    readonly portals?: readonly PortalInputs[];
+}
+/**
+ * A mini mat's inside through its face (PORTAL.md §2.1, MINIMAT.md §3): `present` carries
+ * the presence (its opacity — the gate's answer) and the face (its clip); `view` may leave
+ * `box` unset — the ground sizes the slot's box from the clip.
+ */
+export interface PortalInputs extends SlotInputs {
+    readonly grid: GridConfig;
+    /** The mini mat's index in the parent's `objects` (paint order): the slot draws just AFTER it, over its face. */
+    readonly at: number;
+}
+/** The departed desk's ground for one flight frame: its own camera, grid, objects and presentation. */
+export interface OutgoingInputs extends SlotInputs {
+    readonly grid: GridConfig;
+    /** design-006's z-rule for a FROZEN flight: under on enter, over on exit. */
+    readonly order: "under" | "over";
+    /**
+     * ENTER through a live portal (PORTAL.md §2.4): the mini mat's index in the DEPARTED desk's
+     * `objects` — the two desks draw as one tree, the arriving one through the mini mat's face,
+     * so the objects over the mini mat stay over the inside and fade with their desk (a live
+     * portal of the departed desk at the same index is neither prepared nor drawn: the arriving
+     * desk is that face). Absent = two whole slots, `order` decides: a frozen flight, and every
+     * EXIT — the departed inside draws OVER the whole parent (whose own live portal shows the
+     * same pixels under it) and fades onto them at the landing.
+     */
+    readonly at?: number;
+}
+/**
+ * THE HAND for one frame (design-015 §8; D4b — the builder makes it, the ground draws it): the one object in hand as a slot
+ * of its own — its record, the pose's CAMERA (`view`) and its grid (no dapple in hand) — drawn by its kind's own pass over the
+ * desk out of focus. `e` is the carry amount (the focus follows it); `blur` the radius the ONE blur is made at (CSS px: 14, a
+ * phone's 10); `dim` the desk's dim behind (already by the carry); `filter` the reading light on the hand (1, 1 by day);
+ * `light` the hand's own light (the day's mixed in by night); `stamp` the desk copy's identity — while it stands, the blurred
+ * desk is reused (rendered ONCE per settled state, the held object alone redrawing).
+ */
+export interface HeldFrameInputs {
+    readonly object: SlotObject;
+    /** What rides with it (D3t-c — a calendar's stuck notes): drawn in the hand's slot after it, under the same camera. */
+    readonly riders?: readonly SlotObject[];
+    readonly view: View & {
+        readonly dpr: number;
+    };
+    readonly grid: GridConfig;
+    readonly e: number;
+    readonly blur: number;
+    readonly dim: number;
+    readonly filter: {
+        readonly saturate: number;
+        readonly brightness: number;
+    };
+    readonly light: MatLight;
+    readonly stamp: string;
+}
+export interface GroundFrameInputs extends SlotInputs {
+    /** The theme in force (`theme.ts`): the clear colour, the selection's colour and the mat's light (the Sun or the Moon) come from it. */
+    readonly theme: GroundTheme;
+    /** Present only while a nav flight is on. */
+    readonly outgoing?: OutgoingInputs;
+    /** The desk's marks this frame, in screen px (marks/layout.ts) — stratum 5, over everything; absent = none. */
+    readonly marks?: MarksInput;
+    /** The object in hand (design-015 §8, D4b) while one is held or flying home; absent = the desk as it is. At `e` 0 the frame is the rest frame, byte for byte. */
+    readonly held?: HeldFrameInputs;
+    /** The pegboard drawer this frame (design-017 — the renderer's flux: its slide, its shown scroll), over the marks; absent = none. Never drawn over the hand. */
+    readonly tray?: TrayFrameInputs;
+}
+export interface GroundStats extends GridStats {
+    /** The root's records drawn this frame, by kind name — every registered kind, 0 where it had none. */
+    readonly kinds: Readonly<Record<string, number>>;
+    /** The departed slot's grid while a flight is on. */
+    readonly outgoing: GridStats | null;
+    /** Live portals drawn this frame, the root's and the departed desk's together. */
+    readonly portals: number;
+    /** The records the kinds' CAPS turned away this frame, by kind name, every slot's (absent: none) — resolved and NOT drawn (D7). */
+    readonly dropped?: Readonly<Record<string, number>>;
+}
+/** One registered kind as a slot holds it: the registry's name and stratum, and the slot's own pass (and whether it lays a composite — `KindProgram.composite`). */
+export interface SlotKind {
+    readonly name: string;
+    readonly stratum: StratumName;
+    readonly pass: KindPass;
+    readonly composite?: boolean;
+}
+/** The passes one slot owns: the mat's, and every registered kind's by name, in registration order. The root's are the ground's; the pool spawns the rest on the same pipelines. */
+export interface SlotSet {
+    readonly mat: CuttingMat;
+    /**
+     * Every registered kind's entry — a MISSING kind's (petition I24) drawn by a spawn of the slot's missing face under the kind's own
+     * name and stratum — and, made on the first object that names it, `MISSING_KIND`'s (an object whose type has no kind). The ground
+     * swaps an entry when a kind goes missing (`Ground.quarantine`); nothing else writes the map.
+     */
+    readonly kinds: ReadonlyMap<string, SlotKind>;
+    /** The slot's FLAT-CARD pass (K7b, card/card.ts) over its kinds — absent when no registered kind declares a card material. */
+    readonly card?: CardPass;
+    /**
+     * The desk's MISSING FACES (petition I24, missing/ — the root's alone): what draws an object nothing can draw, spawned on a slot's
+     * mat into a kind's entry when the kind goes missing; nothing of them is made until the first is asked for. Absent on a slot set
+     * made by hand (a unit's): such an object is then refused as an unregistered kind is.
+     */
+    readonly missing?: MissingFaces;
+    /** The kinds REFUSED at create (the root's alone; petition I24): each its name and why — their entries draw the missing face from the start. */
+    readonly faults?: readonly KindFault[];
+}
+/** One slot's passes for `drawFrame` — the ground's own, or the oracle's. A parent carries its nested slots. */
+export interface DrawSlot {
+    readonly mat: CuttingMat;
+    readonly present?: Presentation | undefined;
+    /** BARE: no mat is drawn — the hand's slot (D4b) lays its one object over a frame that is already there. */
+    readonly bare?: boolean | undefined;
+    /** Layers laid on the mat before everything (the calendar's). */
+    readonly underlays?: readonly Underlay[] | undefined;
+    /** The slot's kinds, prepared (its `SlotSet.kinds`): an object's kind names its stratum and its pass. */
+    readonly kinds: ReadonlyMap<string, SlotKind>;
+    /** The slot's objects in paint order — only their kinds matter to the draw: each kind's records are counted along them. */
+    readonly objects?: readonly {
+        readonly kind: string;
+    }[] | undefined;
+    /**
+     * The FLAT CARDS (K7b): each object's card in the card pass's list this frame (`route[i]`, −1 = its kind draws it) — a run of cards
+     * is one draw whatever kinds it interleaves. Absent: every object is its kind's.
+     */
+    readonly card?: {
+        readonly pass: CardPass;
+        readonly route: Int32Array;
+    } | undefined;
+    /** Nested slots, each drawn right after the object `at` names (MINIMAT.md §3) — one that names no object here draws over them all. */
+    readonly children?: readonly {
+        readonly at: number;
+        readonly slot: DrawSlot;
+    }[] | undefined;
+    /** What the slot's grid did this frame. */
+    readonly stats: GridStats;
+}
+/** A slot at opacity 0 draws nothing: "source over" with alpha 0 leaves every pixel as it was. */
+export declare const visible: (p: Presentation | undefined) => boolean;
+/** What `createKindPasses` made: each program's root pass in registration order (undefined: refused), and the refusals. */
+export interface KindPasses {
+    readonly passes: readonly (KindPass | undefined)[];
+    readonly faults: readonly KindFault[];
+}
+/**
+ * EVERY KIND'S PASS, EACH IN ITS OWN ERROR SCOPE (petition I24 — one kind's create is that kind's): made in parallel on the root's mat,
+ * as before, each settled alone — a create that rejects (a WGSL that does not compile — the engine's `compile` throws — a pipeline the
+ * device refused) or whose own scope caught an error is REFUSED, and the rest stand. A kind's scope is pushed before its `create` is
+ * called and popped as it returns, so it holds what the kind does before its first await (its layouts, its shader modules — where a
+ * compile error is raised); a WINDOW scope around them all holds whatever any kind does after (a pipeline made synchronously after an
+ * await). When the window caught something, whose it was is found by making each kind that stood ALONE again, wholly in a scope of its
+ * own, one after another (its first pass let go) — a fault's cost; a desk with none pays three scopes a kind. An error the window
+ * caught that no kind raises alone is not a kind's: `onError` hears it (the device's handler would have — the layer's `degraded`).
+ * Nothing else may run on the device while the window is open: the card, the missing face and the chrome are made after it.
+ */
+export declare function createKindPasses(device: GPUDevice, format: GPUTextureFormat, mat: CuttingMat, programs: readonly KindProgram[], onError?: (error: GPUError) => void): Promise<KindPasses>;
+/**
+ * The root slot's passes: the mat's (made first — every kind's pass is made on it), every registered kind's — made in parallel on the
+ * root's mat, in registration order, each in its own error scope (`createKindPasses`: a kind refused there is MISSING, petition I24) —
+ * then the card over the kinds that stood, and the desk's missing faces (made only if a kind was refused). Names must be unique and
+ * strata known. Shared by the ground and the Node oracle (whose `onError` is its probe's: it watches the creation in scopes of its own).
+ */
+export declare function createSlotSet(device: GPUDevice, format: GPUTextureFormat, mat: CuttingMat, programs: readonly KindProgram[], onError?: (error: GPUError) => void): Promise<SlotSet>;
+/** Slots beyond the root, spawned on first use and reused every frame: `reset()` then `acquire()` per slot the frame needs. */
+export declare class SlotPool {
+    private readonly slots;
+    private used;
+    private readonly root;
+    /** False once a kind the card composes went missing (petition I24 — `Ground.quarantine`): every slot's card, spawned or yet to be, is off. */
+    cardOn: boolean;
+    constructor(root: SlotSet);
+    reset(): void;
+    /** The next slot: on first use its mat spawned from the root's, then every registered kind's pass on that mat, in registration order. */
+    acquire(): SlotSet;
+    /** Every slot spawned so far (a quarantine walks them). */
+    each(fn: (s: SlotSet) => void): void;
+    /** Slots spawned so far — the churn instrument. */
+    get size(): number;
+    dispose(): void;
+}
+/**
+ * Draw one slot into an open render pass: scissored to its portal (nothing
+ * outside it is shaded), skipped outright at opacity 0 — the mat, the layers on
+ * it, then the objects stratum by stratum: within a stratum in paint order, one
+ * `drawRange` per RUN of one kind (each kind counting its own records), the run
+ * cut after an object with a live inside — the inside over its face (restoring
+ * this slot's scissor), then that object's marks over the inside. Returns
+ * whether it drew.
+ */
+export declare function drawSlot(pass: GPURenderPassEncoder, size: {
+    readonly w: number;
+    readonly h: number;
+}, dpr: number, slot: DrawSlot): boolean;
+/**
+ * Record one frame into an open render pass: the root slot with its nested
+ * slots, and — while a flight is on — the departed slot: through the mini mat
+ * as one tree (`outgoing.at`), or whole, under or over, when the flight is
+ * frozen. Shared with the Node oracle so both hosts draw a frame through the
+ * same code. Returns each slot's grid stats (null = not drawn).
+ */
+export declare function drawFrame(pass: GPURenderPassEncoder, size: {
+    readonly w: number;
+    readonly h: number;
+}, dpr: number, incoming: DrawSlot, outgoing?: (DrawSlot & {
+    readonly order: "under" | "over";
+    readonly at?: number | undefined;
+}) | null): {
+    incoming: GridStats;
+    outgoing: GridStats | null;
+};
+/** What `prepareFrame` hands the draw: the two slots and the counts the stats report. */
+export interface PreparedFrame {
+    readonly incoming: DrawSlot;
+    readonly outgoing: (DrawSlot & {
+        readonly order: "under" | "over";
+        readonly at?: number | undefined;
+    }) | null;
+    readonly portals: number;
+    /** The root's records that will draw, by kind name — every registered kind. */
+    readonly kinds: Readonly<Record<string, number>>;
+    /** What the kinds' caps turned away, by kind name, every slot's (absent: nothing) — `GroundStats.dropped` (D7). */
+    readonly dropped?: Readonly<Record<string, number>>;
+    /** K5a: the tray's specimens, one slot each, prepared — drawn over the board, inside its edge (`drawTray`); absent = none. */
+    readonly tray?: readonly DrawSlot[];
+    /** K5b: what the tray carries, one slot each, prepared — drawn over the drawer, whole (`drawTray`); absent = none. */
+    readonly carried?: readonly DrawSlot[];
+}
+/** Where `prepareFrame` finds a specimen's slot (tray/specimens.ts `TraySlots`): undefined while its kind's pass is being made. */
+export interface TraySlotSource {
+    get(type: string, kind: string): SlotSet | undefined;
+}
+/**
+ * Upload one frame's records into its slots — the root's, each live portal's
+ * (from the pool), the departed desk's — run the mat's wind where its clock
+ * moved, and return the draw tree. Per slot, every registered kind prepares its
+ * own records (the slot's objects of that kind, in paint order), told which of
+ * them carries a live inside. Shared by the ground and the Node oracle. `grid`
+ * is the root's when its inputs name none.
+ */
+export declare function prepareFrame(encoder: GPUCommandEncoder, root: SlotSet, pool: SlotPool, inputs: GroundFrameInputs, grid?: GridConfig, target?: RenderTarget, traySlots?: TraySlotSource): PreparedFrame;
+/**
+ * THE TRAY, drawn (design-017 §5, §8; K5a) — shared by `Ground.render` and the Node oracle: the drawer UNDER its specimens (the dim, its
+ * shadows, the board to its edge, the accessories), each specimen by its own kind through the drawer's face (inside the edge — the rim
+ * laid over them all retired, design-018 §2), their name tags (the marks' pills), then the VEIL over them all at the top (design-018
+ * rev 5: the plain board, whole in the header and fading out over its ramp — what hangs there fades into the board, never see-through
+ * over a hole); then what the tray carries, whole. Shut (p 0) the drawer draws nothing (its pass laid no quad) and only a carried copy
+ * is drawn. Leaves the scissor on the whole view.
+ */
+export declare function drawTray(pass: GPURenderPassEncoder, size: {
+    readonly w: number;
+    readonly h: number;
+}, dpr: number, tray: TrayPass, slots: readonly DrawSlot[] | undefined, marks: MarksPass | null, carried?: readonly DrawSlot[]): void;
+/**
+ * The passes one frame draws with — a `Ground`'s own (it IS one), or the Node oracle's: the root slot and the pool, the root's
+ * grid, and the three chrome passes (null where a host made none). What `encodeFrame` and `captureFrame` take, so the swap chain's
+ * frame, a capture's still and the oracle's render go through ONE encoding of a frame (petition I23: the capture is the frame path
+ * drawn once more into another target — never a second copy of it).
+ */
+export interface FramePasses {
+    readonly root: SlotSet;
+    readonly pool: SlotPool;
+    readonly grid: GridConfig;
+    readonly marks: MarksPass | null;
+    readonly hold: HoldPass | null;
+    readonly tray: TrayPass | null;
+    readonly traySlots: TraySlotSource | null;
+}
+/** What `encodeFrame` recorded: the frame's stats (`Ground.render`'s answer), the prepared tree, and the marks it laid (0: none). */
+export interface EncodedFrame {
+    readonly stats: GroundStats;
+    readonly prepared: PreparedFrame;
+    readonly marked: number;
+}
+/**
+ * Record one REST frame (no object in hand — the held frame is `renderHeldFrame`'s) into `encoder`, drawn into `into` — the swap
+ * chain (`Ground.render`), a capture's readable still (`captureFrame`), the oracle's target: the drawer's prepare (shut, p 0, it
+ * lays no quad; what the tray carries draws whatever the slide — a ghost grows, or flies home, past it), the slot tree, the marks,
+ * then ONE render pass — the frame stratum by stratum, the marks over every slot and stratum (stratum 5; `drawFrame` left the
+ * scissor on the whole view), the pegboard drawer over them (design-017: the dim, its shadow, the board, the specimens — K5a).
+ * The caller submits. `target` marks what the slots are prepared for (D7, `RenderTarget`); absent, the frame's.
+ */
+export declare function encodeFrame(encoder: GPUCommandEncoder, passes: FramePasses, inputs: GroundFrameInputs, into: HeldInto, target?: RenderTarget): EncodedFrame;
+export declare class Ground {
+    readonly device: GPUDevice;
+    readonly surface: Surface;
+    /** The cutting mat — the root slot's; its plates, noise and glyph atlas are every slot's. */
+    readonly mat: CuttingMat;
+    /** The root slot's passes: the mat's and every registered kind's, by name (the registry, in registration order). */
+    readonly root: SlotSet;
+    /** Slots beyond the root — the departed desk's, the live insides of mini mats — spawned on first use. */
+    readonly pool: SlotPool;
+    /** The root's grid when a frame names none. */
+    grid: GridConfig;
+    /** The desk's chrome — stratum 5 (D4a); null when the options named no marks shaders. */
+    readonly marks: MarksPass | null;
+    /** The hand — the focus behind an object in hand and the object over it (D4b); null when the options named no hold shaders. */
+    readonly hold: HoldPass | null;
+    /** The pegboard drawer (design-017, K3); null when the options named no tray shaders. */
+    readonly tray: TrayPass | null;
+    /** The tray's specimens' slots (K5a) — one per specimen, made as the tray first shows each; null with no tray. */
+    readonly traySlots: TraySlots | null;
+    /** The desk copy's cache (D4b): the stamp it was made for and the stats of that frame. */
+    private readonly heldCache;
+    /** How many desk copies the hand has made so far (D4b) — a rig's witness that the blurred desk is made once per settled state. */
+    heldCopies(): number;
+    /** The drops last said, by kind (D7). */
+    private readonly dropSaid;
+    /** The kinds MISSING on this ground (petition I24): refused at create, or quarantined since — their entries draw the missing face. */
+    private readonly missing;
+    private constructor();
+    /**
+     * The mat first (every kind's pass is made on it), then every kind's pass in its own error scope (`createKindPasses` — a kind refused
+     * there is MISSING from the start: `faults()`, petition I24), then — once the kinds' window has closed, so nothing of theirs is taken
+     * for a kind's — the card over the kinds that stood, the marks, the hand and the tray, together. The missing faces are made only when
+     * one is asked for (a kind refused here, a quarantine, an object with no kind).
+     */
+    static create(opts: GroundOptions): Promise<Ground>;
+    /**
+     * The root's pass of the kind registered as `name` (undefined if none, or MISSING — petition I24: nothing of a missing kind is reached
+     * again) — a host reaches its kind's own API through it: the note's ink pages, the whiteboard's rasters.
+     */
+    pass(name: string): KindPass | undefined;
+    /** The kinds REFUSED when this ground was made (petition I24): each its name and why. Quarantines since are the layer's word. */
+    faults(): readonly KindFault[];
+    /**
+     * THE QUARANTINE (petition I24): kind `name` is MISSING from now on — its entry in every slot this ground holds (the root, the pool's,
+     * the tray's) becomes a spawn of that slot's missing face, under its name and in its stratum, and the passes it had are disposed (the
+     * pool's and the tray's first; the root's — whose shared resources go with it — last; a dispose that throws is said and passed). A
+     * kind the flat card composes turns the card off in every slot, for good (K7b's own A/B door: each material kind then draws its own
+     * runs — the card's pixels, more draws): its resources leave the card's bind group, and no draw may reach them. The next frame draws
+     * the kind's objects in the missing face (the builder makes their records so); one already made for its own pass is drawn as nothing.
+     * A kind already missing, or none of that name: nothing.
+     */
+    quarantine(name: string): void;
+    /** Size the canvas to its CSS box; returns the CSS size and dpr the frame should use. (A host may size the canvas itself instead.) */
+    fit(maxDpr?: number): {
+        changed: boolean;
+        width: number;
+        height: number;
+        cssWidth: number;
+        cssHeight: number;
+        dpr: number;
+    };
+    /** Render one frame now. Synchronous submit; the caller owns the cadence. */
+    render(inputs: GroundFrameInputs): GroundStats;
+    /**
+     * THE CAPTURE DOOR's GPU half (petition I23; `captureFrame`): `inputs` — the last frame's, as `render` took them — drawn once
+     * more into a readable texture at the view's dpr × `scale`, `rect` (CSS px of the view) read back. The swap chain is not touched,
+     * no frame is drawn, nothing is kept: the still and its readback buffer are made for the call and destroyed after it. Undefined
+     * when the device is lost mid-copy, or the rect lies off the view.
+     */
+    capture(inputs: GroundFrameInputs, opts?: CaptureOptions): Promise<CaptureBytes | undefined>;
+    /** A kind whose cap turns objects away is an ERROR on the host's console (D7): said when the drop begins and again if it grows. */
+    private said;
+    /** The pool's slots, then the root's kinds in reverse registration order (a missing kind's face among them), its missing face, then the mat. */
+    dispose(): void;
+    /** Make the passes the tray's composite specimens need (K5a — `TraySlots.warm`); `onReady` asks for the frame that shows them. */
+    warmTray(wanted: readonly (readonly [string, string])[], onReady: () => void): void;
+    /** The tray's slots let go of what they make again at their next draw once undrawn a while (D-K6a.3; `TraySlots.idle`) — every tick. */
+    idleTray(): void;
+    /** When `idleTray` next lets a tray layer go (K7a — a time the host registers; ∞ — nothing to let go). */
+    trayIdleAt(): number;
+}
+/** The specimens' name tags this frame (K5a): each label centred under its specimen — below a shelf's plank — in screen px. */
+export declare function tagsOf(tray: TrayFrameInputs | undefined): {
+    readonly label: string;
+    readonly x: number;
+    readonly y: number;
+}[];
+/** The desk copy's cache between held frames (D4b): the `stamp` it was made for (null: none yet), the stats of that frame, and how many copies were ever made (the "once per settled state" witness). */
+export interface HeldCache {
+    stamp: string | null;
+    stats: GroundStats | null;
+    copies: number;
+}
+/** Where a frame goes: the swap chain's view and size (the ground's surface), the oracle's target dressed as one, or a capture's still. */
+export interface HeldInto {
+    view(): GPUTextureView;
+    size(): {
+        readonly w: number;
+        readonly h: number;
+    };
+}
+/**
+ * A HELD FRAME (design-015 §8; D4b) — shared by `Ground.render` and the Node oracle so both hosts draw it through one code path:
+ *  1. the DESK COPY, only when its `stamp` moved: the frame WITHOUT the held object (the builder left it out), no marks, prepared
+ *     and drawn at half the dpr into the hold pass's half-size target, then blurred — its own encoder, SUBMITTED FIRST: the root's
+ *     passes are about to be prepared again for the hand, and a queue write lands before every later submit, never an earlier one;
+ *  2. the HAND: the one object under the pose's camera, its kind's own pass into a transparent full-size target (no mat — a bare
+ *     slot), the hand's light (the day's by night, as the carry rises);
+ *  3. the FRAME: the desk out of focus (the sharp copy mixed toward the blurred one by the carry, dimmed), then the hand over it
+ *     through the reading light. Two fullscreen draws; the marks stay quiet (the builder hands none).
+ * Returns the desk copy's stats (the frame's objects behind the hand). `label` names the encoders (`hold`; a capture's
+ * `capture` — the pass instrument closes a profiler frame at the `hold` encoder's submit, and a capture is not a frame).
+ */
+export declare function renderHeldFrame(device: GPUDevice, hold: HoldPass, root: SlotSet, pool: SlotPool, grid: GridConfig, into: HeldInto, inputs: GroundFrameInputs, held: HeldFrameInputs, cache: HeldCache, label?: string): GroundStats;
+/** A rect of the view, CSS px: `x`, `y` its top-left, `width` × `height` its size. */
+export interface CaptureRect {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+export interface CaptureOptions {
+    /** The part of the view to return, CSS px (the whole view when absent); what lies off the view is cut off. */
+    readonly rect?: CaptureRect;
+    /** A multiplier on the view's dpr (1 — the still at device pixels; a thumbnail asks 0.25). */
+    readonly scale?: number;
+}
+/**
+ * A captured still's bytes: `width` × `height` device px, rows tightly packed, four bytes a pixel in `format`'s own channel
+ * order and alpha AS DRAWN (`bgra8unorm` on most swap chains; `rgba8unorm` the oracle's) — the texture's texels, exactly:
+ * the host turns them into an `ImageBitmap` (host/layer.ts), the oracle hashes them beside its own render.
+ */
+export interface CaptureBytes {
+    readonly width: number;
+    readonly height: number;
+    readonly format: GPUTextureFormat;
+    readonly bytes: Uint8Array<ArrayBuffer>;
+}
+/** A malformed capture option is a THROW at the call (a programming error, never an honest undefined): the scale positive and finite, the rect's four numbers finite. */
+export declare function checkCapture(opts: CaptureOptions): void;
+/**
+ * The frame's inputs with EVERY view's dpr × `scale` — the root's, each live inside's (recursively: a nested slot carries a view of
+ * its own, and its mat prepares its lattice against it), the departed desk's and its insides', the hand's, the marks' (their
+ * hairlines are 1/dpr), the tray's specimens' and carried copies' — so every slot names the capture's attachment (kit/layer.ts
+ * `attachmentOf`), exactly as the reflector's inputs would at that dpr. At scale 1, the inputs themselves.
+ */
+export declare function scaledInputs(inputs: GroundFrameInputs, scale: number): GroundFrameInputs;
+/**
+ * THE CAPTURE (petition I23 — the covers' still, the thumbnails, "Send to…"): `inputs` — the last PRESENTED frame's, as
+ * `Ground.render` took them (the same camera, theme, marks, hand and tray) — drawn ONCE MORE, outside any frame, into a readable
+ * texture at the view's size × its dpr × `scale`, through the same encoding the swap chain's frame went through (`encodeFrame`;
+ * the held frame through `renderHeldFrame` — at the view's own size the standing desk copy is reused, the hand alone redrawn);
+ * then `rect` (CSS px of the view; the whole view when absent), in device px of the still, copied to a buffer and MAPPED. The
+ * slots are prepared for the `capture` target (D7, `RenderTarget`: a kind re-asks the residency the frame holds, as under the
+ * hand — a thumbnail's coarser asks evict nothing). The per-frame path gains nothing: no copy of any frame is kept, the swap chain
+ * is not touched, and the still and the readback buffer — `capture/still`, `capture/readback`, the ledger's own `capture` line
+ * while they live — are destroyed before the promise settles. Undefined, never a throw, when the device is lost before the bytes
+ * are mapped (the map rejects) or the rect lies wholly off the view; a malformed option throws at the call.
+ */
+export declare function captureFrame(device: GPUDevice, passes: FramePasses, format: GPUTextureFormat, inputs: GroundFrameInputs, cache: HeldCache, opts?: CaptureOptions): Promise<CaptureBytes | undefined>;

package/dist/types/packages/desk/src/hold/focus.d.ts

@@ -0,0 +1,53 @@
+import { Target } from "../engine/target";
+import type { HoldShaders } from "./shaders";
+/** The pass's knobs: `texel` = (1/w, 1/h of the SOURCE, the Kawase offset in half-texels, 0); `mix` = (the carry e, the dim, the saturate, the brightness). */
+export declare const HoldUniformsStruct: import("../engine").StructDef<"mix" | "texel">;
+/** The dual-Kawase chain's shape: two levels below the half-size copy; the offset per texel of radius. */
+export declare const KAWASE: {
+    readonly levels: 2;
+    readonly offsetPerTexel: 0.25;
+};
+export interface CompositeKnobs {
+    /** The carry amount: how far toward the blurred copy the background goes. */
+    readonly e: number;
+    /** The dim of the desk behind (already scaled by the carry). */
+    readonly dim: number;
+    /** The reading light on the hand (1, 1 by day; toward .62, .82 by night as the carry rises). */
+    readonly saturate: number;
+    readonly brightness: number;
+}
+export declare class HoldPass {
+    private readonly device;
+    private readonly layout;
+    private readonly sampler;
+    private readonly down;
+    private readonly up;
+    private readonly deskPipe;
+    private readonly handPipe;
+    /** The desk's half-size copy, the Kawase levels below it, the blurred copy back at half size, the hand at full size. */
+    readonly desk: Target;
+    readonly blurred: Target;
+    readonly hand: Target;
+    private readonly levels;
+    /** One uniform buffer per draw the chain records (each holds its own texel size and offset). */
+    private readonly knobs;
+    private readonly values;
+    private groups;
+    /** The size the groups were built for — rebuilt when a target resized. */
+    private built;
+    private constructor();
+    /** The four pipelines on `format` (the surface's — every target here is that format too, so one layout serves all). */
+    static create(device: GPUDevice, format: GPUTextureFormat, src: HoldShaders): Promise<HoldPass>;
+    /** Size the targets to the surface (device px): the copies at half, the hand at full. True when any target was remade (its contents gone). */
+    fit(w: number, h: number): boolean;
+    private rebind;
+    private knob;
+    /**
+     * The blur: from the desk copy through the levels and back into `blurred`, at `radiusTexels` (the radius in the copy's
+     * texels: the CSS radius × dpr / 2). Recorded into `encoder` after the copy was drawn; one chain per settled desk.
+     */
+    blur(encoder: GPUCommandEncoder, radiusTexels: number): void;
+    /** The frame: the desk out of focus, then the hand over it in its light — two fullscreen draws into the open pass. */
+    composite(pass: GPURenderPassEncoder, k: CompositeKnobs): void;
+    dispose(): void;
+}