@vibecook/ice 0.14.0 → 0.15.0-desk.2

package/dist/types/packages/core/src/index.d.ts

@@ -74,7 +74,7 @@ export { createPresentationTransitionCoordinator, type FrameSwitchDescriptor, ty
 export { canvasRuntimeExtensions, defineCanvasRuntimeExtension, defineFrameBehavior, frameBehaviorPackId, frameBehaviors, type CanvasReadFacet, type CanvasRuntimeChanges, type CanvasRuntimeExtension, type CanvasRuntimeExtensionContext, type CanvasRuntimeExtensionDef, type CanvasScopedReader, type CanvasSemanticMigration, type CanvasSemanticMigrationContext, type ExistingPlacementPosture, type FrameBehavior, type FrameBehaviorDef, type FrameBehaviorWriteContext, } from "./canvas/extensions";
 export { createWidgetEquipSystem } from "./widget/equip";
 export { attachSpawnBehaviors, attachSpawnParent, spawnWidget, widgetSpawnInits, type SpawnWidgetOpts } from "./widget/spawn";
-export type { FramePickSlot, FramePickSource } from "./systems/l1-pick";
+export type { FramePickSlot, FramePickSource, PointPick } from "./systems/l1-pick";
 export { setWidgetProps } from "./widget/set-props";
 export { createWidgetRuntime, installWidgetRuntime, type WidgetRuntime } from "./widget/mount-store";
 export * from "./settings/defaults";

package/dist/types/packages/core/src/interaction/install.d.ts

@@ -17,7 +17,7 @@ import { SpatialIndex } from "../../../kernel/src/index";
 import { type CommitSink } from "../engine/commit-sink";
 import type { Engine } from "../engine/engine";
 import type { InputQueue } from "../input/queue";
-import { type FramePickSlot } from "../systems/l1-pick";
+import { type FramePickSlot, type PointPick } from "../systems/l1-pick";
 import { type SpawnProfiles } from "../systems/l2-recognize";
 import { type WirePreviewBuffer } from "../systems/l3-connect";
 import { type DropPlacementPolicy } from "../systems/l3-drop";
@@ -55,6 +55,12 @@ export interface InteractionStack extends InteractionCore {
     readonly wirePreview: WirePreviewBuffer;
     /** The frame pick source's slot (design-014, B3b): the ground layer sets `current` at mount, clears it at dispose. */
     readonly framePick: FramePickSlot;
+    /**
+     * The exact pick OUT of the tick (petition I27; l1-pick `pickAt`): what a press at a SCREEN point (CSS px of the view) would touch
+     * now — `picking`'s own `TouchesExact` body on the world as the last tick left it, through the frame source above; `undefined` over
+     * the bare canvas and while the pegboard drawer is out. Read-only. The desk's `handle.pick` reaches it through its mount context.
+     */
+    pickAt(sx: number, sy: number): PointPick | undefined;
     /**
      * The nav geometry seam (design-015 §9; D2b) beside `framePick`: the renderer's word on a
      * container's DRAWN face, the inside's arrival and the exact cut camera — core's nav, the

package/dist/types/packages/core/src/systems/held.d.ts

@@ -26,7 +26,9 @@
  *    drawing surface with a mode in hand (D3t-a): that press is the TOOL's (`HeldPress` `tool` — the
  *    board's stroke; a double-click there is two dots, never a way back) — or on one of the kind's named
  *    PARTS (D3t-b: any part but `content` and `frame`, the object itself): that press is the KIND's
- *    (`HeldPress` `part`, with the part it began on — a notebook's turn: two clicks there turn two pages).
+ *    (`HeldPress` `part`, with the part it began on — a notebook's turn: two clicks there turn two pages);
+ *  - every route above is the PRIMARY button's (petition I28, press-button.ts): a secondary press — and a middle one with nothing
+ *    to pan — is a point in the hand as on the desk: it keeps no `HeldPress`, so it puts nothing down, works no part, lays no stroke.
  * The ways back are OPS (`ops.putDown`, structural) and a system may not run them mid-tick: it writes
  * the one-tick `HeldIntent` and the facade applies it after the step (D2b's `NavIntent`, same shape).
  * Nothing here reads a kind: the seam gives a frame and (D3t-a) the part under a point; the tool in

package/dist/types/packages/core/src/systems/l1-pick.d.ts

@@ -42,6 +42,11 @@
  * pickTopAt, so pick can never diverge from paint), then the CanvasSurface
  * entity as the guaranteed fallback (design-001 §4). Relations are written
  * change-only (design-002 §4 hygiene). Wires/ports are M8 — skipped.
+ *
+ * `pickAt` is the exact pick OUT of the tick (petition I27 — the desk's
+ * `handle.pick`, a host's right-click): the `TouchesExact` body above run on
+ * the world as the last tick left it, read-only — one body, so a host's pick
+ * and a press can never disagree.
  */
 import type { Entity, System, TickSystem, World } from "@vibecook/strata-ecs";
 import { SpatialIndex } from "../../../kernel/src/index";
@@ -82,11 +87,22 @@ export interface FramePickSource {
 export interface FramePickSlot {
     current: FramePickSource | null;
 }
+/** What a press at a point would touch (`TouchesExact`): the entity, and the PART under it (`""` the thing itself — design-014). */
+export interface PointPick {
+    readonly entity: Entity;
+    readonly part: string;
+}
 export interface PickingSystems {
     spatialSync: TickSystem;
     picking: System;
     /** The shared spatial index — snap/drop/marquee consume the SAME instance. */
     index: SpatialIndex<Entity>;
+    /**
+     * The exact pick OUT of the tick (petition I27): what a press at a SCREEN point (CSS px of the view) would touch now — the
+     * `TouchesExact` body `picking` runs, on the world as the last tick left it and the camera as it stands; `undefined` over the bare
+     * canvas, and everywhere while the pegboard drawer is out (the desk inert, design-017 §4). Read-only: no relation, no tag, no stamp.
+     */
+    pickAt(sx: number, sy: number): PointPick | undefined;
     /** Nav-op seam (design-004 §7): forget every last-known AABB so the next
      *  spatialSync pass repopulates the cleared index from the new Active set. */
     clearCaches(): void;

package/dist/types/packages/core/src/systems/l2-recognize.d.ts

@@ -3,7 +3,9 @@
  *
  * `ctl:spawn`  — cancelSweep (consumes the one-tick CancelRequest) →
  *                recognizerSpawn (tool profiles; pinch on 2nd touch suspends
- *                singles; wheel recognizers are `Simultaneous`) →
+ *                singles; wheel recognizers are `Simultaneous`; a primary
+ *                press only — a secondary one is a point, a middle one its
+ *                pan's drag: petition I28, press-button.ts) →
  *                recognizerIntegrity (requiredWatches counts, capture death,
  *                suspension lift). Newborns are identity-only until the
  *                ctl:spawn flush, so integrity naturally skips them until the

package/dist/types/packages/core/src/systems/press-button.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The button a press began with (petition I28) — read off the pointer's `PointerButtons.buttons` on its `WentDown` tick, which is
+ * the down fact's own PointerEvent `buttons` mask (ingest's fold ends at the transition, l0-input.ts). A pointerdown carries the
+ * one button that pressed: a second button joining a held press arrives as a pointermove (the Pointer Events spec's chorded
+ * buttons), never as a down.
+ *
+ *   - PRIMARY — bit 1 (a mouse's left button, a touch, a pen's tip) or 32 (a pen's eraser end: the board's eraser reads it), or
+ *     no bit at all (a synthetic down that names no button — every press, as before I28). The recognizers take it, and the hand.
+ *   - MIDDLE — bit 4: a drag only where its drag pans — `dragRoute`'s device convention on the bare canvas (design-003 §4.4), the
+ *     hand's pan brought close (held.ts) — and never a tap, a long press, or a grab of what is under it.
+ *   - SECONDARY — anything else (2: the right button, a pen's barrel; 8/16: back and forward): a POINT. Its point, its pick and
+ *     its hover move with it (ingest, `picking`); nothing selects, drags, enters or works a part. Its `contextmenu` is the host's.
+ *
+ * Pure over the ctx: no writes.
+ */
+import type { Entity, SystemCtx } from "@vibecook/strata-ecs";
+export type PressButton = "primary" | "middle" | "secondary";
+/** The button a press began with, from the `buttons` mask its down carried. */
+export declare function pressButton(buttons: number): PressButton;
+/**
+ * Whether a MIDDLE press on `captured` is a drag: where `dragRoute` sends a drag to its CANVAS branch, whose device convention pans
+ * — the bare canvas, or a capture that is no handle, no port and no object (a wire). Over a handle, a port or an object it is a
+ * point: before I28 it resized, connected or MOVED what it landed on.
+ */
+export declare function middlePans(ctx: Pick<SystemCtx, "has" | "hasTag">, captured: Entity | undefined): boolean;

package/dist/types/packages/core/src/systems/tray.d.ts

@@ -44,6 +44,8 @@ import { type WidgetType } from "../widget/define-widget";
  * `trayScrollMax`), so the lay can clamp the scroll in the tick a new foot or face moves the range; absent, nothing clamps it.
  * design-018 R4: the `head`, how far under its top nothing of the board's content shows (the renderer's clear HEADER, where a host lays
  * the category chips) — a specimen scrolled under it is never hovered or taken there: a press there is the board's; absent, 0.
+ * Petition I21: the `foot`, how far above its bottom edge nothing of the content shows (a host's foot inset — its line floats over the
+ * board there): the same at the foot, and the range is the content's foot plus a pitch less the face ABOVE it; absent, 0.
  */
 export interface TrayScreenFrame {
     readonly x: number;
@@ -56,6 +58,7 @@ export interface TrayScreenFrame {
     readonly scroll: number;
     readonly face?: number;
     readonly head?: number;
+    readonly foot?: number;
 }
 /** The pose seam: the renderer's word on where the drawer is — `undefined` before its first frame. */
 export interface TrayPoseSource {

package/dist/types/packages/desk/src/compose/builder.d.ts

@@ -1,5 +1,7 @@
 import { type MarqueeBuffer, type NavFace, type Entity, type WidgetType, type World } from "../../../core/src/index";
+import type { KindFaults } from "../faults";
 import type { HeldFrameInputs, OutgoingInputs, PortalInputs, SlotObject } from "../ground";
+import { type HoldReserves } from "../hold/pose";
 import { FLUX_REST, type KindLocal, type ObjectFlux, type ObjectKind } from "../kinds/world";
 import type { MarksInput } from "../marks/layout";
 import { type SelectionAnchor } from "./marks";
@@ -20,7 +22,9 @@ export interface DeskBuilderOptions {
     /**
      * The OBJECT widget types this desk may hold: their prop groups join the change journal and
      * their kinds' `reach` the pick pad. An object of a type not listed still draws (its kind is found
-     * off the widget type) but its props are refreshed only on a Position/Size/tag change.
+     * off the widget type) but its props are refreshed only on a Position/Size/tag change — unless the
+     * boundary is on (`faults`, the layer's): then its kind must be one the listed types name, the set
+     * the desk was MOUNTED with and its ground compiled (petition I25), or it wears the missing face.
      */
     readonly objects: readonly WidgetType[];
     /** The objects' springs (springs.ts `SPRINGS`). */
@@ -45,6 +49,17 @@ export interface DeskBuilderOptions {
      * host), every member is tested.
      */
     readonly spatial?: SpatialSource;
+    /** The hand's reserves (petition I20 — `deskLayer({ hold })`): where the reading fit keeps clear of the host's chrome; `HOLD`'s by default. */
+    readonly hold?: HoldReserves;
+    /**
+     * THE KIND BOUNDARY (petition I24, faults.ts): every call into a kind's world half — `resolve`, `record` (and what a remake asks with
+     * them: `face`, `frame`, `rung`, its desk state's `landed`), `chip`, `hit`, the hand's, a ghost's, `lifted` and `veils` — is caught at the
+     * kind: the throw is a strike, the object it was made for is left out of this frame (its record reset, made afresh next time), and
+     * the frame goes on. A MISSING kind's objects — and an object whose type has no kind — are drawn by the missing face
+     * (`MISSING_OBJECT`) under their kind's name; nothing of a missing kind is called again. Absent (a unit, a bare host): as before — a
+     * throw is the caller's, and an object whose type has no kind is not drawn.
+     */
+    readonly faults?: KindFaults;
 }
 /**
  * What the builder asks of the spatial index: the entries whose rects meet a world AABB (kernel's `SpatialIndex.search`), and how
@@ -258,6 +273,12 @@ export interface DeskBuilder {
     heldPoint(e: Entity, wx: number, wy: number): readonly [number, number] | undefined;
     /** The held kind's part under such a point — its `hit` on the geometry it was drawn with in hand; null over nothing (the pose seam's `part`, D3t-a). */
     heldPart(e: Entity, x: number, y: number): string | null;
+    /**
+     * What is under a world point of `e` as the last build drew it (the pick source's mirror, design-015 §4.5): its kind's `hit` on that
+     * geometry — or, drawn as the MISSING face (petition I24), its box. `null`: a miss (a kind whose `hit` throws takes a strike and misses
+     * — the pick goes on to the next object down); `undefined`: not drawn (unseen, culled, its kind gone missing since).
+     */
+    hitAt(e: Entity, wx: number, wy: number): string | null | undefined;
     /** The objects the last build painted LIFTED by their kind's own state (D3t-a — a print carried or in the air): above their siblings, asked first by the pick. */
     lifted(): readonly Entity[];
     /** An entity a kind's state veiled in the last build (D3t-c — a note gone with its month): not drawn, never picked. */

package/dist/types/packages/desk/src/compose/marks.d.ts

@@ -55,6 +55,13 @@ export interface HeldAnchor {
     readonly active: string;
     readonly landing: boolean;
     readonly settled: boolean;
+    /**
+     * The held bar's TRAVEL (M1), ms, as the host set it (`deskLayer({ hold: { travelMs } })`, petition I20): the bar travels to the
+     * foot over it and back. Absent — the host set none — the bar keeps its own.
+     */
+    readonly travelMs?: number;
+    /** The kind's WORD in hand (petition I22 — its `open.readout`): "Page 2", "September". Absent — the kind says none (or none now). */
+    readonly readout?: string;
 }
 /** A kind's act as the selection menu shows it (K8a): plain data — the op stays on the widget type (`ops.runMenuAction`). */
 export interface MenuSlot {

package/dist/types/packages/desk/src/compose/pick.d.ts

@@ -1,5 +1,5 @@
 import type { FramePickSource } from "../../../core/src/index";
 import type { DeskBuilder } from "./builder";
-export declare function createPickSource(builder: Pick<DeskBuilder, "geometryOf" | "kindOf" | "live" | "reach" | "lifted"> & Partial<Pick<DeskBuilder, "veiled" | "heldPoint" | "hand">>, opts?: {
+export declare function createPickSource(builder: Pick<DeskBuilder, "geometryOf" | "kindOf" | "live" | "reach" | "lifted"> & Partial<Pick<DeskBuilder, "veiled" | "heldPoint" | "hand" | "hitAt">>, opts?: {
     readonly moving?: () => boolean;
 }): FramePickSource;

package/dist/types/packages/desk/src/compose/reflector.d.ts

@@ -1,8 +1,10 @@
 import { type Entity, type ReflectorDef, type World } from "../../../core/src/index";
+import type { KindFaults } from "../faults";
 import type { Ground, GroundFrameInputs, GroundStats } from "../ground";
 import { type KindLocal, type ObjectKind } from "../kinds/world";
 import { type GridConfig } from "../mat/grid";
 import type { GroundTheme, Palette } from "../theme";
+import { type TrayOptions } from "../tray/drawer";
 import { type TrayFlux } from "../tray/flux";
 import { type TrayCarry } from "../tray/carry";
 import { type TrayCarriedFrame, type TraySpecimenFrame } from "../tray/specimens";
@@ -32,6 +34,13 @@ export interface DeskReflectorOptions {
     readonly onFrame?: () => void;
     /** The kinds' own state on this desk (`KindLocal`, by kind name): what the tray's carried objects are drawn with, as the builder's are (K5b). */
     readonly locals?: ReadonlyMap<string, KindLocal>;
+    /** The drawer as the host set it (petition I21 — `deskLayer({ tray })`): its foot inset. */
+    readonly tray?: TrayOptions;
+    /**
+     * THE KIND BOUNDARY (petition I24, faults.ts): the tray's specimens and carried copies are recorded through it (a missing kind's are the
+     * missing face; a throw is a strike), and a missing kind is never asked for its look again.
+     */
+    readonly faults?: KindFaults;
     /**
      * Called when a frame is asked for from OUTSIDE the flush — a wake (a pin, an ink landing, the ambient's policy), the ground
      * arriving, a theme, a grid, a harness's pin (K7a): the host wakes a sleeping loop with it.

package/dist/types/packages/desk/src/engine/budget.d.ts

@@ -26,6 +26,11 @@ export interface RasterBudget {
     touch(owner: string, key: string): void;
     /** The owner let the raster (or the resident array) go itself (no eviction). */
     release(owner: string, key: string): void;
+    /**
+     * Every raster `owner` holds, let go WITHOUT its eviction (petition I24 — a kind gone MISSING: its caches went with its passes,
+     * and nothing of it is called again). Returns the bytes forgotten.
+     */
+    forget(owner: string): number;
     /**
      * Evict least-recently-used caches until they are within their room — never one `keep` says to hold (an owner's word on
      * what is on screen this frame; absent, every cache may go), never a resident charge. Returns the bytes freed.

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

@@ -0,0 +1,38 @@
+import type { Entity } from "../../core/src/index";
+/** A kind the desk draws as MISSING, and why — what `DeskLayerStatus.faults` lists, in the order the kinds went missing. */
+export interface KindFault {
+    readonly kind: string;
+    readonly reason: string;
+}
+/** The strikes a kind is allowed: the third throw makes it missing (design-009 §16's ladder — three strikes, then quarantine). */
+export declare const KIND_STRIKES = 3;
+/**
+ * A missing kind's row in the layer's `due().kinds` (host/layer.ts): no time — a time there is ≥ 0, `Infinity` never on its own —
+ * so −1 reads as what it is: this kind is never due again, nothing of it runs.
+ */
+export declare const KIND_MISSING = -1;
+export interface KindFaults {
+    /** How many kinds are missing — 0 while none is (every call site's first and, then, only test). */
+    readonly size: number;
+    /** Is `kind` missing (refused at create, or quarantined)? Nothing of it is called again. */
+    missing(kind: string): boolean;
+    /** `kind` was REFUSED at create (ground.ts — `reason` says so): missing from the start. Said once; a second word for it is ignored. */
+    refuse(kind: string, reason: string): void;
+    /**
+     * One of `kind`'s calls threw: a strike, said on the console with the call and the entity. The third makes it MISSING (said once,
+     * the listeners told) — returns true then. A strike for a kind already missing is ignored (its last call's throw, still unwinding).
+     */
+    strike(kind: string, call: string, err: unknown, entity?: Entity): boolean;
+    /** The strikes `kind` has taken (0 … `KIND_STRIKES`). */
+    strikes(kind: string): number;
+    /** The missing kinds, in the order they went — one array until the next goes (a host may hold it). */
+    list(): readonly KindFault[];
+    /** Told once for each kind that goes missing, after it is in `list()`. Returns the unsubscribe. */
+    subscribe(listener: (fault: KindFault) => void): () => void;
+}
+/**
+ * The first line of a fault worth a host's reading: an error's message, its first non-blank line — for the engine's WGSL refusal
+ * (`WGSL <label>:` then the compiler's lines, engine/shader.ts `compile`) the compiler's first, with its place.
+ */
+export declare function faultText(err: unknown): string;
+export declare function createKindFaults(): KindFaults;

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

@@ -1,5 +1,7 @@
 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";
@@ -59,6 +61,11 @@ export interface GroundOptions {
      * `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 {
@@ -176,9 +183,22 @@ export interface SlotKind {
 /** 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 {
@@ -212,21 +232,43 @@ export interface DrawSlot {
 }
 /** 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[];
+}
 /**
- * The root slot's passes: the mat's (made first — every kind's pass is made on it) and every registered
- * kind's, made in parallel on the root's mat, in registration order. Names must be unique and strata known.
- * Shared by the ground and the Node oracle.
+ * 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 createSlotSet(device: GPUDevice, format: GPUTextureFormat, mat: CuttingMat, programs: readonly KindProgram[]): Promise<SlotSet>;
+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;
@@ -303,6 +345,36 @@ 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;
@@ -328,10 +400,33 @@ export declare class Ground {
     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) — a host reaches its kind's own API through it: the note's ink pages, the whiteboard's rasters. */
+    /**
+     * 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;
@@ -343,9 +438,16 @@ export declare class Ground {
     };
     /** 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, then the mat. */
+    /** 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;
@@ -366,7 +468,7 @@ export interface HeldCache {
     stats: GroundStats | null;
     copies: number;
 }
-/** Where a held frame goes: the swap chain's view and size (the ground's surface, or the oracle's target dressed as one). */
+/** 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(): {
@@ -383,6 +485,53 @@ export interface HeldInto {
  *     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).
+ * 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 renderHeldFrame(device: GPUDevice, hold: HoldPass, root: SlotSet, pool: SlotPool, grid: GridConfig, into: HeldInto, inputs: GroundFrameInputs, held: HeldFrameInputs, cache: HeldCache): GroundStats;
+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

@@ -1,7 +1,7 @@
 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<"texel" | "mix">;
+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;

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

@@ -29,12 +29,30 @@ export declare const HOLD: {
         readonly hz: 1.4;
         readonly zeta: 0.78;
     };
-    /** The held bar's travel (M1 morph) and its return after the landing. */
+    /** The held bar's travel (M1 morph) and its return after the landing — `travelMs` the default of a host's `hold.travelMs` (I20). */
     readonly bar: {
         readonly travelMs: 340;
         readonly backMs: 200;
     };
 };
+/**
+ * THE HAND'S RESERVES (petition I20): how far the reading fit keeps from the view's top (`top`) and from its foot (`band` — the held
+ * bar's band), CSS px. `HOLD`'s are the default; a host's chrome moves them (`deskLayer({ hold })`). A phone keeps its own top.
+ */
+export interface HoldReserves {
+    readonly top: number;
+    readonly band: number;
+}
+/**
+ * The hand as a HOST sets it (petition I20 — `deskLayer({ hold })`, read at the mount): the reserves above and below the reading fit,
+ * CSS px, and the held bar's travel (M1), ms — each `HOLD`'s when absent (`top` 56, `band` 72, `travelMs` 340). The bar is the host's:
+ * the desk publishes the travel on the selection's anchor (`HeldAnchor.travelMs`) for whichever bar draws it.
+ */
+export interface HoldOptions {
+    readonly top?: number;
+    readonly band?: number;
+    readonly travelMs?: number;
+}
 export interface HeldViewport {
     readonly width: number;
     readonly height: number;
@@ -49,13 +67,15 @@ export interface ReadingTarget {
 /** A phone's width (desk.js `narrow`). */
 export declare const isNarrow: (vp: HeldViewport) => boolean;
 /**
- * The reading size (desk.js `heldTarget`): the extent fits the view inside the margins and above the bar's band, never past 3×.
- * `spread`: the extent is a two-page spread that may open one page at a time — on a portrait phone (W < 0.85·H) it does when
- * one page reads at least 1.3× larger than the whole spread would; then the RIGHT page is centred (the extent's centre sits a
- * quarter of its width left of the middle) — or, `face` → 1, the LEFT (D3t-b: the notebook reads page by page; between, the view
- * glides).
+ * The reading size (desk.js `heldTarget`): the extent fits the view inside the margins, `reserves.top` under its top and the bar's
+ * band (`reserves.band`) above its foot, never past 3× — the host's reserves (I20), `HOLD`'s by default; a phone keeps its own top
+ * and margins. `spread`: the extent is a two-page spread that may open one page at a time — on a portrait phone (W < 0.85·H) it
+ * does when one page reads at least 1.3× larger than the whole spread would; then the RIGHT page is centred (the extent's centre sits
+ * a quarter of its width left of the middle) — or, `face` → 1, the LEFT (D3t-b: the notebook reads page by page; between, the view
+ * glides). That decision is the PHONE'S, on `HOLD`'s band whatever the host reserves, so a kind that asks it alone
+ * (`readingTarget(extent, vp, true).single`) agrees with the hand; the reserves size the page it shows.
  */
-export declare function readingTarget(extent: ObjectRect, vp: HeldViewport, spread?: boolean, face?: number): ReadingTarget;
+export declare function readingTarget(extent: ObjectRect, vp: HeldViewport, spread?: boolean, face?: number, reserves?: HoldReserves): ReadingTarget;
 /** Where the extent lies on screen at rest, under the desk's camera: its centre (CSS px), the scale (the zoom) and the object's turn. */
 export interface HomePose {
     readonly cx: number;

package/dist/types/packages/desk/src/host/index.d.ts

@@ -1,4 +1,4 @@
-export { deskLayer, type DeskLayerContext, type DeskLayerFactory, type DeskLayerHandle, type DeskLayerOptions, type DeskLayerPerf, type DeskLayerStatus, type DeskTrayDoor, type MatPin, type SelectionSource, type TrayAnchor } from "./layer";
+export { deskLayer, type DeskLayerBoot, type DeskLayerContext, type DeskLayerFactory, type DeskLayerHandle, type DeskLayerOptions, type DeskLayerPerf, type DeskLayerStatus, type DeskTrayDoor, type MatPin, type PickResult, type SelectionSource, type TrayAnchor } from "./layer";
 export type { SelectionAnchor } from "../compose/marks";
 export { surface, type Surface } from "./surface";
 export { createDeskEditor, type DeskEditorOptions, EDITOR_ATTR, KEYBOARD_CLAIM_ATTR } from "./editor";