@vibecook/ice 0.10.0 → 0.14.0

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

@@ -0,0 +1,430 @@
+import { type Entity, type FramePickSlot, type HeldPoseSlot, type MarqueeBuffer, type NavFace, type NavGeometrySlot, type PresentationTransitionAdapter, type ReflectorDef, type TrayCategory, type TrayPoseSlot, type TrayScreenFrame, type WidgetType, type World } from "../../../core/src/index";
+import { type Ambient, type AmbientMode, type AmbientPin } from "../compose/ambient";
+import { type DeskBuilder, type HeldBuild, type HoldPin, type SpatialSource } from "../compose/builder";
+import { type BudgetStats } from "../engine/budget";
+import { type RasterQueueStats } from "../engine/rasters";
+import type { RecordStoreStats } from "../engine/records";
+import { type SelectionAnchor } from "../compose/marks";
+import { type DeskReflector, type DeskReflectorStats, type DeskWakes } from "../compose/reflector";
+import { Ground, type GroundFrameInputs } from "../ground";
+import type { KindProgram } from "../kind";
+import type { ObjectFlux } from "../kinds/world";
+import { type GridConfig } from "../mat/grid";
+import type { GlyphAtlasMeta, MatConfig, PlateName } from "../mat/layout";
+import type { ObjectSprings } from "../kit/springs";
+import type { KindDriver, KindLocal } from "../kinds/world";
+import { type BlobStore } from "../kit/blobs";
+import { type Lent } from "../kit/services";
+import { type TypingDocs } from "../docs";
+import { type TextRaster } from "../kit/raster";
+import type { DeskEditor } from "../kit/editor";
+import type { InsideView } from "../kit/inside";
+import { type MemoryLedger } from "../gpu-memory";
+import { type GpuProfiler } from "../gpu-profiler";
+import { type SubmitInstrument } from "../submit-instrument";
+import type { GroundTheme, Palette } from "../theme";
+import type { TrayFluxState, TrayPin } from "../tray/flux";
+import type { TrayLaid } from "../tray/pass";
+export interface DeskLayerOptions {
+    /** The theme in force at the mount (the app's `themeFrom(name, palette)`). */
+    readonly theme: GroundTheme;
+    /** The app's palette — what each kind's `theme()` reads its look from (`PaperPalette`, `MiniMatPalette`). */
+    readonly palette: Palette;
+    /**
+     * The OBJECT widget types this desk draws, beyond the engine catalog's own: their kinds are registered
+     * with the ground and join the builder's journal. The catalog's object types are always included.
+     */
+    readonly objects?: readonly WidgetType[];
+    /** Render-only kinds to register beside the objects' (a program with no world half yet). */
+    readonly kinds?: readonly KindProgram[];
+    /** The ambient policy (design-015 §4.6): `idle` by default. */
+    readonly ambient?: AmbientMode;
+    /** How long after the last touch the wind blows, ms (20 000). */
+    readonly ambientIdleMs?: number;
+    /** The root's grid at the mount: the mat's config (its gobo, its rulers) and the lattice's fade-in. */
+    readonly grid?: GridConfig;
+    /** The objects' springs (springs.ts `SPRINGS`): the builder reads these numbers every frame, so a host that keeps the object may tune them live (the dev panel — D5a). */
+    readonly springs?: ObjectSprings;
+    /** The device pixel ratio the canvas is capped at (2). */
+    readonly maxDpr?: number;
+    /** Where the layer acquires its OWN device when the engine has none (`engine.compositorDevice` — then it draws with that): `navigator.gpu` unless a host hands another. */
+    readonly gpu?: GPU;
+    /** Called once with the layer's OWN device, before anything submits. */
+    readonly onDevice?: (device: GPUDevice) => void;
+    /** The layer's name in the reflector roster. */
+    readonly name?: string;
+    /** The app's text raster (`inkRaster({ faces: penFaces({ … }) })`, D2c): absent, no note is written live — the pinned rasters only. */
+    readonly text?: TextRaster;
+    /** The document a note's typing session commits into — the facade's `engine.docs` (D2c); absent, typing stays runtime-only. */
+    readonly docs?: TypingDocs;
+    /** A typing session ends after this long without input, ms (1000). */
+    readonly idleMs?: number;
+    /** The app's byte store (D3w, D-D12): a print's picture by the hash its `blob` prop names; absent, prints draw their paper alone. */
+    readonly blobs?: BlobStore;
+    /**
+     * More SERVICES the host lends its kinds (K8a, kit/services.ts), each under its key — `service(KEY, value)` — beside the three it
+     * lends by name (`text` → `TEXT_RASTER`, `blobs` → `BLOB_STORE`, and `PICTURE_DECODER`, the desk's own decode). A plugin kind
+     * `use`s one by its key; a name lent twice (here, or by an object's DOM half) is a mount error.
+     */
+    readonly services?: readonly Lent[];
+    /**
+     * THE RASTER BUDGET (D6, design-015 §11.4), bytes: what every kind's raster caches may hold together — a board's ink (its strokes
+     * are the truth; evicted, it replays when next drawn), a notebook page's CPU raster, the calendar's tiles. The least recently used
+     * off-screen raster goes first. Default 192 MB.
+     */
+    readonly rasterBudget?: number;
+    /**
+     * THE FRAME'S RASTER BUDGET (K6b, design-016 §6), ms: what one frame spends making the rasters the kinds asked of the queue
+     * (engine/rasters.ts — a note's ink at a new band, a board's strokes on coming on screen); the rest wait their turn, their old
+     * raster standing. Default `RASTER_BUDGET_MS` (4).
+     */
+    readonly rasterMs?: number;
+    /**
+     * Keep the device's LIVE GPU MEMORY by label from the boot on (gpu-memory.ts, design-016 §4 — the profiler's memory table): a
+     * map entry per texture or buffer MADE, nothing per frame. Off by default (D-K2.2): a resource made before the ledger cannot be
+     * found after it (WebGPU has no enumeration), so it is the one instrument a host decides on at the mount.
+     */
+    readonly gpuLedger?: boolean;
+}
+/**
+ * The raster budget a host does not size: 256 MB — D6's 192 (about ten whiteboards' ink at the law's density, the notebook's
+ * eight page rasters and the calendar's tiles beside them) and 64 more since the PICTURES joined it (K6a, K-L4): their
+ * thumbnail array (1.4 MB a picture, always kept) and the details a frame binds — each its print's chain from the finest level
+ * it samples, so together at most about four texels a device pixel of the prints on screen (≈ 82 MB were prints to tile a
+ * 2400 × 1600 screen), where before every picture's whole chain stood outside any budget.
+ */
+export declare const DEFAULT_RASTER_BUDGET: number;
+/** The pinned still a parity scene states: the clocks, the plate and the gobo's opacity, the wind (0 = a still). */
+export interface MatPin extends AmbientPin {
+    readonly plate?: PlateName;
+    readonly opacity?: number;
+    readonly wind?: number;
+}
+/**
+ * The layer's honest state: `pending` until the device and the pipelines are here; `ready`; `degraded` — the device reported an error
+ * nobody captured (out of memory, a validation or an internal error): the desk still draws what it can, but a frame — or every frame,
+ * an attachment left invalid — may be lost, and the state never reads `ready` again on its own (D7); `failed` — no desk (refused, or
+ * the device lost). `message` names the cause.
+ */
+export interface DeskLayerStatus {
+    readonly state: "pending" | "ready" | "degraded" | "failed";
+    readonly message?: string;
+}
+/** The mount context — the fields of `@ice/dom`'s `LayerContext` this layer reads, mirrored structurally (dom never imports the desk). */
+export interface DeskLayerContext {
+    readonly host: {
+        readonly container: HTMLElement;
+    };
+    readonly world: World;
+    readonly framePick?: FramePickSlot;
+    /** The nav geometry seam (design-015 §9, D2b): the desk sets its word on its containers' drawn faces here, clears it at dispose. */
+    readonly navGeometry?: NavGeometrySlot;
+    /** The held pose seam (design-015 §8, D4b): the desk publishes where the object in hand is ON SCREEN as it drew it; core's held input maps every pointer through it. */
+    readonly heldPose?: HeldPoseSlot;
+    /** The tray pose seam (design-017 §4, K3): the desk publishes where the pegboard drawer is ON SCREEN as it drew it; core's tray input hit-tests through it. */
+    readonly trayPose?: TrayPoseSlot;
+    readonly transitions?: {
+        register(adapter: PresentationTransitionAdapter): () => void;
+    };
+    readonly catalog?: {
+        widgetTypes(): readonly WidgetType[];
+    };
+    /** The interaction stack's marquee preview (`stack.marqueeBuffer`, out of the ECS): the vellum the marks draw (D4a). */
+    readonly readMarquee?: () => MarqueeBuffer;
+    /** The engine's spatial index (`stack.index`; design-015 §2.5, D6): the cull's broad phase. Absent, every member is tested. */
+    readonly spatial?: SpatialSource;
+    /** The engine's device (`engine.compositorDevice`, D7): the layer draws with it and never acquires its own — ONE device per engine. */
+    readonly gpu?: {
+        readonly adapter: GPUAdapter;
+        readonly device: GPUDevice;
+    };
+    /**
+     * The engine's frame gate (K7a — the SLEEP, `@ice/core` frame-control.ts): the layer registers the desk's wake (when its reflector,
+     * its kinds and its drivers are next due), wakes a sleeping loop for what arrives outside a step, and on a step a registered time
+     * alone started (`settled`) asks only what is due. Absent (a headless host): every part is asked every step, as before.
+     */
+    readonly frame?: {
+        wake(reason: string): void;
+        wakeWhen(name: string, due: (now: number) => number): () => void;
+        settled(): boolean;
+    };
+}
+/** The selection menu's source (D4a): the marks' anchor as of the last frame, and a subscription that fires when it changes. */
+export interface SelectionSource {
+    anchor(): SelectionAnchor;
+    subscribe(listener: () => void): () => void;
+}
+/**
+ * The desk's MAIN-THREAD time (D6): every flush of the layer's reflector — the kinds' ticks, the pull, the build and the
+ * render when a frame is due — counted and timed since the mount; `frames` are the flushes that drew, `frameMs` their share.
+ * At rest a tick that draws nothing must cost next to nothing (design-015 §11.4: ≤ 0.1 ms of main thread per second).
+ */
+export interface DeskLayerPerf {
+    readonly ticks: number;
+    readonly ms: number;
+    readonly frames: number;
+    readonly frameMs: number;
+    /** Each kind's `tick`, asked (K7a): at rest a kind is asked only when it is due — the registered-wake witness. */
+    readonly kindTicks: Readonly<Record<string, number>>;
+    /** The drivers asked (`idle`, then `follow`): none on a step a registered time alone started (K7a). */
+    readonly driverAsks: number;
+}
+/**
+ * The pegboard tray's door (design-017; K3) — the app's `a` and a rig's hand: the facts through core's tray ops (the one writer beside
+ * the tray's input), the flux's pins and its state.
+ */
+/** A specimen as the last frame drew it (K5a — the tray door's witness): its type, kind, tag and accessory, its rect and pegs on screen (CSS px), the scale its kind drew it at. */
+export interface TraySpecimenSeen {
+    readonly type: string;
+    readonly kind: string;
+    readonly label: string;
+    readonly accessory: string;
+    readonly screen: {
+        readonly x0: number;
+        readonly y0: number;
+        readonly x1: number;
+        readonly y1: number;
+    };
+    readonly pegs: readonly (readonly [number, number])[];
+    readonly zoom: number;
+    /** K5b: its object as drawn on screen (the fit inside the hang). */
+    readonly object: {
+        readonly x0: number;
+        readonly y0: number;
+        readonly x1: number;
+        readonly y1: number;
+    };
+}
+/** What the tray carried in the last frame drawn (K5b — the door's witness): its type and phase, the ghost it presents (absent: the copy), its object's rect on screen, its scale. */
+export interface TrayCarriedSeen {
+    readonly type: string;
+    readonly phase: string;
+    readonly ghost?: number;
+    readonly screen: {
+        readonly x0: number;
+        readonly y0: number;
+        readonly x1: number;
+        readonly y1: number;
+    };
+    readonly zoom: number;
+}
+/**
+ * Where the tray's BAR is placed from (design-018 §5 — `<TrayBar>`, @ice/react, reads it structurally): the drawer as the last frame
+ * DREW it — its outline's top-left and width, its slide, its HEADER (R4) — the view, the hand, the category model its chips show, and
+ * the theme's night. A fact the bar follows is never a pixel it guesses: the pill rides `drawer.y` exactly, frame by frame, and the
+ * chips lie in the header as drawn.
+ */
+export interface TrayAnchor {
+    /** The drawer is out (the fact: its slide may still be on its way). */
+    readonly open: boolean;
+    /**
+     * The drawer's outline as drawn this frame (CSS px; its bottom runs on under the view) and its slide — null before its first frame, or
+     * while a pin hides it — and its HEADER (design-018 R4, `DRAWER.header`): the clear band under the edge's inside, from `y` for `h`,
+     * where nothing of the board's content shows and the bar lays its chips.
+     */
+    readonly drawer: {
+        readonly x: number;
+        readonly y: number;
+        readonly w: number;
+        readonly p: number;
+        readonly header: {
+            readonly y: number;
+            readonly h: number;
+        };
+    } | null;
+    readonly view: {
+        readonly width: number;
+        readonly height: number;
+    };
+    /** The theme's night, 0 day … 1 the Moon (`MatLight.night`): the bar's label tape steps back by it as the specimens' tags do (design-018 R4). */
+    readonly night: number;
+    /** An object is IN HAND (not flying home): the selection menu has the view's foot — the bar steps aside. */
+    readonly held: boolean;
+    /** How many entries the drawer's frame hangs, every category (0: nothing to offer here — the bar steps aside). */
+    readonly entries: number;
+    /** The category the drawer shows ("" all) and the categories its frame hangs, in the lay's order (design-018 §6). */
+    readonly category: string;
+    readonly categories: readonly TrayCategory[];
+}
+export interface DeskTrayDoor {
+    /** Open the drawer: refused (false) while an object is in hand; gestures in flight cancel. */
+    open(): boolean;
+    close(): void;
+    /** Open or close; returns whether it is open now. */
+    toggle(): boolean;
+    isOpen(): boolean;
+    /** The board's scroll, CSS px past its top — set when given (any value: a rig's 10⁶ rows down), and returned. */
+    scroll(px?: number): number;
+    /** The facts and the flux as of now, the drawer as last drawn (the pose seam's answer) and what the pass last laid. */
+    state(): TrayFluxState & {
+        readonly frame: TrayScreenFrame | undefined;
+        readonly laid: TrayLaid | null;
+        readonly specimens: readonly TraySpecimenSeen[];
+        readonly tags: number;
+        readonly slots: number;
+        readonly carried: readonly TrayCarriedSeen[];
+        readonly presented: readonly number[];
+    };
+    /** Pin the drawer for a still — the slide, the band, or hidden; `null` unpins. */
+    pin(pin: TrayPin | null): void;
+    /**
+     * design-018 §6 — the category the drawer shows ("" all): set when given (core's `setTrayCategory` — the lay lays only its
+     * entries, the board starts at its top, and it falls back to all when the frame hangs none of it), and returned.
+     */
+    category(id?: string): string;
+    /** design-018 §6 — the categories the drawer's frame hangs, in the lay's order: each its id, its label and its count (a host's chips). */
+    categories(): readonly TrayCategory[];
+    /** design-018 §5 — what the bar is placed from, as of the last frame drawn. */
+    anchor(): TrayAnchor;
+    /**
+     * design-018 §5 — tell `listener` after each frame that moved what `anchor()` says: the drawer as drawn (its slide, frame by frame),
+     * open or shut, the category or the categories, the hand, the entries, the view. Never at rest: no frame, no call.
+     */
+    subscribe(listener: () => void): () => void;
+}
+export interface DeskLayerHandle {
+    /** The drawing reflector — the facade registers it right after the plane transform, where the ground layer has always gone. */
+    readonly reflector: ReflectorDef & {
+        available(): boolean;
+    };
+    dispose(): void;
+    /** The canvas in the ground slot. */
+    readonly canvas: HTMLCanvasElement;
+    /** The device is acquired and `Ground.create` resolved. */
+    available(): boolean;
+    status(): DeskLayerStatus;
+    /**
+     * Told each time `status()` moves — the boot's end, an uncaptured error, the device lost after the boot (K9: a host says so on
+     * its page; a desk that just ended leaves no canvas behind). Returns the unsubscribe; `dispose` drops every listener.
+     */
+    onStatus(listener: (status: DeskLayerStatus) => void): () => void;
+    /** The device the layer draws with once it is here — the engine's when the context carries one (D7: one device per engine), else the layer's own. */
+    device(): GPUDevice | undefined;
+    /** The ground once made (a rig's door to a pass: `ground()?.pass("paper")`). */
+    ground(): Ground | null;
+    /** The theme changed (and, with it, the palette): the looks are remade, the next frame re-renders. */
+    setTheme(theme: GroundTheme, palette?: Palette): void;
+    /** The mat's config over the current one (the rulers, the gobo): the root's grid. */
+    configureMat(mat: Partial<MatConfig>): void;
+    /** The lattice's fade-in window. */
+    configureFadeIn(fadeIn: GridConfig["fadeIn"]): void;
+    /** A 512² rgba8 plate into slot `c` or `b` — the app's generated plates (never the study's). */
+    setPlate(name: PlateName, bytes: Uint8Array<ArrayBuffer>): void;
+    /** The 128² blue-noise tile; the desk's own is uploaded at the mount. */
+    setNoise(bytes: Uint8Array<ArrayBuffer>): void;
+    /** The rulers' and the mini mats' glyph atlas (RULER.md). */
+    setGlyphs(bytes: Uint8Array<ArrayBuffer>, meta: GlyphAtlasMeta): void;
+    /** Pin the mat for a still (a parity scene): the clocks, the plate, the gobo's opacity; `wind` > 0 unpins the clocks. `null` unpins everything. */
+    pinMat(pin: MatPin | null): void;
+    /**
+     * Pin a kind's own ASSET on an object for a still (K8a — generic: the kind reads it as `ctx.asset`, in a shape the KIND defines —
+     * the note's greeked writing is `{ greek }`, `PaperAsset`; the desk never knows it); `undefined` unpins. Until K8a this door was
+     * `pinGreek`, a note's writing stated by its shape (`GreekPin`) — the one kind-shaped door on the handle.
+     */
+    pinAsset(entity: Entity, asset: unknown): void;
+    /** Pin an object's spring targets for a still (a scene's `held` = `{ lift: 1 }`, never a `Grab`); `undefined` unpins. */
+    pinFlux(entity: Entity, targets: Partial<Pick<ObjectFlux, "lift" | "hover">> | undefined): void;
+    /** Every flux pin lifted. */
+    clearFlux(): void;
+    /** Live insides on or off (the oracle's `portals: false` — every face draws its far LOD alone). */
+    setPortals(on: boolean): void;
+    /**
+     * A kind's LAW, live (D5a — the dev panel's door): every object of `kind` resolves under `law` from the next build and the
+     * root's pass (its slots after it) draws with it; a kind with no live law ignores it. The host owns the law it hands in.
+     */
+    tuneLaw(kind: string, law: unknown): void;
+    /** Pin the root's dressing (the oracle's `lodZoom`); `null` unpins. */
+    pinLodZoom(zoom: number | null): void;
+    /** Hold every spring and ghost where it is — a still of a moving frame (a rig's flight pin). */
+    freeze(on: boolean): void;
+    /** Hold the re-dressing ramp at its start (the prototype harness's `redressPinned`). */
+    holdRedress(on: boolean): void;
+    /** THE HAND PINNED for a still (D4b): the carry amount at `e`, the kind's open motion snapped; `null` unpins. The object itself is picked up through `ops.open`. */
+    pinHold(pin: HoldPin | null): void;
+    /** The object in hand as of the last frame (D4b) — a rig's witness: its carry, its frame on screen, whether settled or flying home. */
+    hand(): HeldBuild | undefined;
+    /** THE SEAM's answer for a container under the camera (the live one unless given) — a rig's witness (`DeskBuilder.navFace`). */
+    navFace(entity: Entity, cam?: {
+        readonly x: number;
+        readonly y: number;
+        readonly zoom: number;
+    }): NavFace | undefined;
+    /** The last build's view of a container's inside (a rig's witness). */
+    insideViewOf(entity: Entity): InsideView | undefined;
+    /**
+     * The camera of the flight on now at progress `p` (the prototype's `flightAt`: the endpoints c0 and c1 themselves,
+     * `flightCamera` between) — what a rig's flight pin writes each tick; `undefined` when no flight drives.
+     */
+    flightCameraAt(p: number): {
+        readonly x: number;
+        readonly y: number;
+        readonly zoom: number;
+    } | undefined;
+    /** The ambient policy, live: the mode, the idle window. */
+    setAmbient(mode: AmbientMode, idleMs?: number): void;
+    ambient(): Ambient;
+    /** The submit instrument on the layer's device — installed the first time it is asked for (K2, D-K2.1: never asked, the queue carries no wrapper), counting from then; undefined before the device. */
+    submits(): SubmitInstrument | undefined;
+    /** The layer's own main-thread time since the mount (D6, design-015 §11.4's idle gate): a rig diffs two readings. */
+    perf(): DeskLayerPerf;
+    /** The raster budget's ledger (D6): what the kinds' caches hold, by owner, against the cap; the evictions so far. */
+    memory(): BudgetStats;
+    /** The frame's raster queue (K6b): the asks waiting and held, the runs, the turns, their ms and the most a turn spent. */
+    rasters(): RasterQueueStats;
+    /** The device's live GPU memory by label (K2) — kept only under `gpuLedger: true`, from the boot; undefined otherwise or before the device. */
+    gpuMemory(): MemoryLedger | undefined;
+    /**
+     * THE GPU PROFILER (K2, design-016 §4) on the layer's device — made on first ask, UNARMED (nothing installed) until `arm()`:
+     * each drawn frame's GPU span and passes, its draws by kind, pipelines, bind groups, uploads, and the ledger's memory; the
+     * layer's flush is its boundary. Undefined before the device.
+     */
+    profiler(): GpuProfiler | undefined;
+    /** The kinds' persistent record stores' counters by kind (D6, design-015 §4.3) — the root passes'; a rig diffs two readings. */
+    records(): Readonly<Record<string, RecordStoreStats>>;
+    redraws(): number;
+    stats(): DeskReflectorStats;
+    wakes(): DeskWakes;
+    /**
+     * The desk's registered wake taken apart (K7a — "why is the desk awake?"): when each part is next due, on `performance.now()`'s
+     * clock (`Infinity`: never on its own) — the reflector's, the drivers' (now while one follows), a kind woken, each kind's `due`,
+     * the tray's layers' let-go (`tray`, K7a over K5a) and the raster queue's waiting asks (`rasters`, K6b: now while any wait).
+     */
+    due(now: number): {
+        readonly at: number;
+        readonly reflector: number;
+        readonly drivers: number;
+        readonly following: readonly string[];
+        readonly woken: readonly string[];
+        readonly kinds: Readonly<Record<string, number>>;
+        readonly tray: number;
+        readonly rasters: number;
+    };
+    geometryOf(e: Entity): unknown | undefined;
+    fluxOf(e: Entity): ObjectFlux | undefined;
+    lastInputs(): GroundFrameInputs | null;
+    /** The frame dirty and not yet drawn, or a kind still moving on its own (a print in the air — D3w): a rig's settle witness. */
+    dirty(): boolean;
+    readonly builder: DeskBuilder;
+    /** A kind's own state on this desk by kind name (D3w: a print's body, a book's or a pad's pinned pose) — `undefined` when it keeps none. */
+    local(name: string): KindLocal | undefined;
+    /** The desk's ONE focused editor (D2c; the desk's since K8a — made at the mount whatever kinds are registered, leased by every kind that takes text). */
+    editor(): DeskEditor;
+    /**
+     * A kind's DRIVER on this desk by object type (D-D7-A.3) — what the object declared in `defineObject` (the note's typing, the
+     * board's pen, the notebook's hand, the print's carry, the calendar's writing + hand + DOM half), or undefined. A rig casts to
+     * the kind's own driver type (`PaperDriver`, `CalendarDriver`); the desk itself never names one.
+     */
+    driver(type: string): KindDriver | undefined;
+    /** Where the selection menu goes (D4a): the marks' box around the selection, published after each frame it moved. */
+    readonly selection: SelectionSource;
+    /** The pegboard tray's door (design-017; K3). */
+    readonly tray: DeskTrayDoor;
+    /**
+     * The DOM-free reflector behind `reflector` — named `desk`, never `compose`: react's retired
+     * `GroundLayerHandle.compose?` was the ground's COMPOSE handle (the composited profile read its
+     * `sourceCanvas` seam off it, until D5b), and the desk was never one. The slot stays absent.
+     */
+    readonly desk: DeskReflector;
+}
+export type DeskLayerFactory = (ctx: DeskLayerContext) => DeskLayerHandle;
+export declare function deskLayer(opts: DeskLayerOptions): DeskLayerFactory;

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

@@ -0,0 +1,2 @@
+import type { PictureDecoder } from "../kit/blobs";
+export declare const decodePicture: PictureDecoder;

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

@@ -0,0 +1,5 @@
+import type { Surface } from "../engine/device";
+export type { Surface } from "../engine/device";
+export declare function surface(device: GPUDevice, canvas: HTMLCanvasElement, opts?: {
+    alphaMode?: GPUCanvasAlphaMode;
+}): Surface;

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

@@ -0,0 +1,13 @@
+export * from "./ground";
+export * from "./tray/index";
+export * from "./host/index";
+export * from "./compose/index";
+export * from "./kit/index";
+export * from "./object";
+export { type DataChildren, FLUX_REST, type HeldContext, type HeldToolDef, type InsideContext, isObjectKind, type KindDriver, type KindDriverHost, type KindHost, type KindLocal, numberProp, type ObjectContext, type ObjectDomHost, type ObjectFlux, type ObjectHit, type ObjectHost, type ObjectKind, type ObjectRect, type OpenBinding, rectFrame, rectOf, type RungContext, type StratumName, stringProp } from "./kinds/world";
+export { carryOf, focusOf, HELD_USER_REST, type HeldPose, type HeldUser, type HeldViewport, heldCamera, heldFrame, heldPose, HOLD, type HomePose, homePose, isNarrow, type ReadingTarget, readingTarget } from "./hold/pose";
+export { NO_DOCS, type TypingDocs, type WritableSession, writable } from "./docs";
+export * from "./theme";
+export * from "./shaders";
+export { BLUE_NOISE_SIZE, blueNoise } from "./assets/blue-noise.gen";
+export { ZOOM_MAX, ZOOM_MIN } from "./lattice/lod";

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

@@ -0,0 +1,187 @@
+import type { BindKind } from "./engine/pipeline";
+import type { RecordStoreStats } from "./engine/records";
+import type { ComposeOptions } from "./engine/shader";
+import type { MatLight } from "./kit/light";
+import type { Presentation } from "./kit/nav";
+import type { FadeIn, MatConfig, MatFrame, MatPass, SlotLight, View } from "./kit/view";
+import type { GroundTheme, RGB } from "./theme";
+/** The strata of the desk a kind can lie in (design-015 §4.2): beneath everything, flat on the mat holding a desk, every other thing. */
+export type StratumName = "pads" | "sheets" | "things";
+/**
+ * The strata in paint order. The mat (stratum 0) is the ground's own and draws first; the held set and the
+ * marks (strata 4 and 5) are D4's. A kind's place in the registry never moves it out of its stratum.
+ */
+export declare const STRATA: readonly StratumName[];
+/**
+ * Everything a kind's pass is prepared with for one slot, one frame — what each object pass's `prepare`
+ * took as arguments before the registry, in one record. The ground fills it; a kind reads what it needs.
+ */
+/**
+ * What a slot is prepared FOR (D7): `frame` — the canvas (and the hand's own slot over it); `copy` — the held desk copy behind the
+ * hand, the desk at half the dpr (design-015 §8). A held frame prepares the root twice, once for each, so a pass that keeps state
+ * between its prepares keeps the copy's apart.
+ */
+/**
+ * The render a slot is prepared for (D7): the FRAME (the desk as it is), the COPY (the desk behind a carried object, made once
+ * per stamp and blurred), or the HAND (K9 R4 — the carried object alone, prepared EVERY frame of the carry while the copy
+ * stands). A pass that keeps state per render keeps the copy's apart; a pass whose residency asks are per prepare (the
+ * pictures' details, the boards' pool) re-asks what it has bound under the hand, else the tick's step — seeing only the hand's
+ * asks — would free every other detail on the desk behind it, a softness pop at every put-down.
+ */
+export type RenderTarget = "frame" | "copy" | "hand";
+export interface SlotContext {
+    /** The slot's camera and box (CSS px) and the device pixel ratio. */
+    readonly view: View & {
+        readonly dpr: number;
+    };
+    /** The slot's grid's fade-in window AS ITS GRID NAMES IT — `dressGrid` dresses the mat's lattice alone, never the objects. */
+    readonly fadeIn: FadeIn;
+    /** The slot's mat config (its gobo, its rulers, its vinyl). The block a pass draws with is the slot's (`MatPass.view`, K4a): read, never copied. */
+    readonly cfg: MatConfig;
+    /** The mat's clocks and tilt this frame; undefined = a still (a pass fills `STILL_MAT_FRAME`). */
+    readonly frame: MatFrame | undefined;
+    /** The OBJECTS' presentation: the slot's opacity times their own presence (`Presentation.objects`), and the slot's chain. */
+    readonly present: Presentation | undefined;
+    /** The Sun or the Moon (the theme's `matLight`). */
+    readonly light: MatLight;
+    /** The lamp the slot is lit by: undefined = its own camera's, exactly (the root at rest); else its host's (MINIMAT.md §4). */
+    readonly lit: SlotLight | undefined;
+    /** The selection ring's colour (the theme's `select`). */
+    readonly select: RGB;
+    /** The theme in force. */
+    readonly theme: GroundTheme;
+    /** The render this slot is prepared for; absent = the frame's (D7). */
+    readonly target?: RenderTarget;
+}
+/**
+ * What the ground knows of a kind's records beyond the slot, this frame. `live(i)`: record `i`'s live inside —
+ * its objects' presence over the record's face (0..1), or −1 where none is drawn — which the ground computes from
+ * the slot's portals, by the kind's OWN record index. A sheet that holds a desk lets its face's far LOD give way
+ * to it (the mini mat); every other kind ignores it.
+ */
+export interface KindExtra {
+    readonly live: (index: number) => number;
+    /**
+     * The records' KEYS, one per record in the same order (design-015 §4.3; D6) — the builder's entity (a ghost's negated), stable
+     * across frames, so a pass with persistent records keeps a record's slot and writes it only when the record object changed.
+     * Absent (the oracle, a bare host): every record is packed afresh this frame.
+     */
+    readonly keys?: readonly number[];
+}
+/**
+ * One slot's pass of one kind. The root's is made by the kind's program on the root's mat; every other slot's is
+ * `spawn`ed from it — its own buffers on the shared pipelines, reading its own mat's wind and light.
+ */
+export interface KindPass<R = unknown> {
+    /** A slot's own buffers on the shared pipelines, reading `mat`'s silhouette — a live inside's, a flight's departed desk's. */
+    spawn(mat: MatPass): KindPass<R>;
+    /** Take the root's laws (the prototype's `tune()` / `copy()`): a spawned slot's pass does, every frame, before it prepares. */
+    tune?(root: KindPass<R>): void;
+    /** Draw with a host's LIVE law (D5a — `handle.tuneLaw`): the root's pass takes it, and its slots follow through `tune`. */
+    setLaw?(law: unknown): void;
+    /**
+     * Upload this frame's records — the kind's objects in this slot, in paint order — for `slot`'s camera and light.
+     * `encoder` is the frame's: work that must precede the frame's pass may be recorded into it (or a pass may submit
+     * its own before the frame's, as the whiteboard's stamps and drying do). Returns the count that will draw.
+     */
+    prepare(encoder: GPUCommandEncoder, slot: SlotContext, records: readonly R[], extra?: KindExtra): number;
+    /** Draw records [first, end) — indices into this frame's `records` — in their order, into the open pass. */
+    drawRange(pass: GPURenderPassEncoder, first: number, end: number): void;
+    /**
+     * The kind's persistent record store's counters (design-015 §4.3; D6) — records packed and uploaded, draw lists rewritten — a
+     * rig's witness that a camera move writes no standing record. Absent for a kind that keeps none (the composites' layers).
+     */
+    records?(): RecordStoreStats;
+    /**
+     * The records this slot's last `prepare` turned away at the pass's CAP (its buffers' ceiling — the layered kinds' fixed tables,
+     * the record stores' most) — objects the builder resolved that will NOT draw. Never silent (D7): the ground sums them into the
+     * frame's `GroundStats.dropped` and the host says so.
+     */
+    dropped?(): number;
+    /** The hold is over (D7): a pass that kept the held desk copy's state apart (`SlotContext.target`) gives it back. */
+    endHold?(): void;
+    /**
+     * Let go of the device targets this slot's pass makes again at its next draw, when none of its objects was drawn within `ms`
+     * (K6a's D-K6a.3 — a layered kind's layer): asked each tick of the slots a host keeps beyond the root (the tray's, K5a).
+     */
+    idle?(ms: number): void;
+    /**
+     * When `idle(ms)` next lets something go (K7a): the host registers it as a TIME wake, so a desk asleep since the drawer shut
+     * still wakes to give the layer back. ∞, or absent: nothing to let go (a pass that says no time is let go at a tick taken anyway).
+     */
+    idleAt?(ms: number): number;
+    /** A sheet's marks over its live inside, drawn right after the inside (the mini mat's chips while the inside's objects come in). */
+    drawOver?(pass: GPURenderPassEncoder, index: number): void;
+    /**
+     * K7b: this slot's resources for the kind's CARD MATERIAL (`KindProgram.card`), in its `bindings` order, and a number that moves
+     * whenever one of them is replaced (a record store grown, a texture array grown) — the card's bind group is made again then.
+     */
+    cardResources?(): {
+        readonly version: number;
+        readonly resources: readonly (GPUBuffer | GPUTextureView | GPUSampler)[];
+    };
+    /**
+     * K7b: record `index` of the last `prepare` drawn by the desk's FLAT-CARD pipeline — its slot in the kind's records, which the
+     * material's functions read — or −1: this pass draws it itself (a print with its detail bound, a board with its raster).
+     */
+    cardSlot?(index: number): number;
+    /** This slot's buffers (the shared resources go with the last slot standing). */
+    dispose(): void;
+}
+/**
+ * A kind as the ground registers it: its name (unique in a ground), its stratum, and how its root pass is made on
+ * the root's mat — once per device; every other slot's pass is `spawn`ed from that one.
+ */
+export interface KindProgram<R = unknown> {
+    readonly name: string;
+    readonly stratum: StratumName;
+    /**
+     * A kind that lays a COMPOSITE (design-015 §4.2): its pass renders every one of its objects into a target of its own in `prepare`
+     * (depth, MSAA, shadow maps — the notebook's layer, the calendar's) and `drawRange` lays that target over the frame in one draw.
+     * The ground draws such a kind as ONE run, [0, count), after every other run of its stratum — its objects cannot interleave with
+     * another kind's without a target per run (D-D4's exception: a note laid on a notebook draws under it). Absent: the kind's objects
+     * are cut into runs in the slot's paint order.
+     */
+    readonly composite?: boolean;
+    /**
+     * K7b: the kind's CARD MATERIAL — its records drawn by the desk's ONE flat-card pipeline (card/card.ts), interleaved with every
+     * other material kind's objects in one run. Absent: the kind draws every record itself, a run of its own.
+     */
+    readonly card?: CardMaterial;
+    create(device: GPUDevice, format: GPUTextureFormat, mat: MatPass): Promise<KindPass<R>>;
+}
+/** A binding of a CARD MATERIAL (K7b): the WGSL the card declares after `@group(0) @binding(n)`, and its layout (the stages, what it is). */
+export interface CardBinding {
+    /** Whole, after the attribute: `var<uniform> paper_k: PaperUniforms` — its name UNIQUE across every kind's material (a kind prefixes its own). */
+    readonly wgsl: string;
+    readonly entry: BindKind;
+}
+/**
+ * A kind's CARD MATERIAL (K7b, design-016 §6 K7 — the run question). In mixed sibling order a run of one kind ends at the next
+ * object of another (rig:scale: draws ≈ 0.3 × the objects drawn, at every zoom); the kinds that declare a material are composed
+ * into ONE pipeline, so interleaved objects of every such kind are one run, one draw. Each object is drawn there by its OWN kind's
+ * functions over its own kind's records, uniforms and textures — the pixels its own pipeline makes. The card's module is the
+ * kit's pieces and every material's structs and modules (deduplicated by name and label), then its bindings, its `only`, its
+ * card functions (`shaders.entry` — the same text its own pass composes) and a dispatch on the card's material.
+ */
+export interface CardMaterial {
+    /**
+     * The kind's program as its own pass composes it — the kit's pieces, its structs, its pure modules — its `entry` the CARD FUNCTIONS
+     * over its bindings; asked when the card is composed (a host's text read then, as a pass reads it when it is made).
+     */
+    shaders(): ComposeOptions;
+    /** WGSL the card composes that the kind's own entry defines otherwise (a texel read from its thumbnails alone — the card binds no pool). */
+    readonly only?: string;
+    /** Its bindings beyond the slot's view block and mat (`u`, `gobo_tex`, `noise_tex` — the card's), in its pass's `cardResources` order. */
+    readonly bindings: readonly CardBinding[];
+    /** `fn <quad>(slot: u32, vid: u32) -> vec4f`: corner `vid`'s clip position; (2, 2, 2, 1) — the degenerate — collapses a culled one. */
+    readonly quad: string;
+    /** `fn <frag>(slot: u32, clip: vec4f) -> vec4f`: the fragment's premultiplied colour through the slot's presentation; alpha < 0 = discard. */
+    readonly frag?: string;
+    /**
+     * The fragment WRITTEN OUT instead of `frag`'s call: WGSL statements over `slot` and `in.clip` that set `c` (or discard) — the
+     * kind's own entry's fragment, statement for statement. For a kind whose shade reached through one more function compiles to
+     * other bits (the board's: one LSB on a pixel a scene — measured, K7b): the card then runs the very code its entry runs.
+     */
+    readonly fragInline?: string;
+}