@vibecook/ice 0.11.0 → 0.15.0-desk.1

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

@@ -0,0 +1,536 @@
+import { type Entity, type FramePickSlot, type HeldPoseSlot, type MarqueeBuffer, type NavFace, type NavGeometrySlot, type PointPick, 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 HoldOptions } from "../hold/pose";
+import { type SelectionAnchor } from "../compose/marks";
+import { type DeskReflector, type DeskReflectorStats, type DeskWakes } from "../compose/reflector";
+import { type KindFault } from "../faults";
+import { type CaptureOptions, 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 TrayOptions } from "../tray/drawer";
+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 HAND as the host's chrome needs it (petition I20), read at the mount: the held object's reading fit keeps `top` CSS px under
+     * the view's top (`HOLD.top`, 56 — a phone keeps `HOLD.topPhone`) and `band` above its foot (`HOLD.band`, 72 — the held bar's band),
+     * and the held bar travels `travelMs` (M1; the bar is the host's — the anchor carries it, `HeldAnchor.travelMs`; absent, the bar's
+     * own). Each a finite number ≥ 0; absent, `HOLD`'s.
+     */
+    readonly hold?: HoldOptions;
+    /**
+     * THE DRAWER as the host's chrome needs it (petition I21), read at the mount: its `foot` inset, CSS px (0) — the pegboard's laid
+     * content ends this far above the board's bottom edge (the face's clip ends there, the veil lays the plain board over it and feathers
+     * out over `DRAWER.fade` above it — the header's mirror), where a host's line floats over the board; the scroll's range grows by it,
+     * so the last line is still reached; the board runs to its edge. A finite number ≥ 0; absent, 0.
+     */
+    readonly tray?: TrayOptions;
+    /**
+     * THE ROOM'S OTHER PEOPLE (petition I26), read at the mount: `false` — the host draws its peers itself (VibeField draws each by
+     * face, from `usePresencePeers`), so the host the layer is mounted in (`@ice/dom`'s `createDeskHost`, `<Desk>`) mounts no remote
+     * cursors — no plane, no reflector; the layer says so on its handle (`DeskLayerHandle.cursors`). The presence session,
+     * `usePresencePeers` and the local OS and open-hand cursors are untouched. Absent or `true`, the host draws them, as ever.
+     */
+    readonly cursors?: boolean;
+    /** 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.
+ *
+ * `faults` (petition I24) — the KINDS this desk draws as MISSING, each its name and why, in the order they went: refused at create (a
+ * pass that would not compile, a pipeline that failed validation) or quarantined at three strikes (a `resolve`, `record`, `chip`, `hit`,
+ * `tick` or `due` that threw — src/faults.ts). Absent while none is. One kind's fault is that kind's: the state does not move for it
+ * (`ready` stays `ready`), its objects wear the desk's missing face, nothing of it is called again. Each is said ONCE — the status
+ * moves when a kind goes missing (`onStatus` hears it; a kind refused at the boot rides the boot's own `ready`), never again for it.
+ */
+export interface DeskLayerStatus {
+    readonly state: "pending" | "ready" | "degraded" | "failed";
+    readonly message?: string;
+    readonly faults?: readonly KindFault[];
+}
+/** 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 interaction stack's exact pick out of the tick (`stack.pickAt`, petition I27 — what a press at a screen point would touch now,
+     * through `framePick` above): the handle's `pick` answers a host through it. Absent (a bare host), `pick` answers null.
+     */
+    readonly pickAt?: (sx: number, sy: number) => PointPick | undefined;
+    /** 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 object under a screen point as the desk's own pick resolves it (petition I27 — `DeskLayerHandle.pick`): what a press there
+ * touches, so what a primary click there selects — the host selects it through the engine's ops (`ops.setSelection([entity])`) and
+ * reads its acts off the selection's anchor.
+ */
+export interface PickResult {
+    readonly entity: Entity;
+    /** Its object type (its `PrefabId`) — what the host names it by and finds its type with (`engine.catalog.widget(type)`). */
+    readonly type: string;
+    /**
+     * The canvas it lies in — the frame the pick is made in: the board root on the root desk, the container entered (a mini mat whose
+     * desk is the view); `NO_ENTITY` in a world with no document.
+     */
+    readonly canvas: Entity;
+    /**
+     * Its kind's PART under the point (design-014): `""` the object itself — its body or its frame, which a click selects; a named part
+     * (the calendar's roll, corner and foot) is the kind's own — a click there works the part and selects nothing.
+     */
+    readonly part: string;
+}
+/**
+ * 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 mount's own cost as its boot went (petition I25). */
+    readonly boot: DeskLayerBoot;
+}
+/**
+ * THE MOUNT'S COST (petition I25 — a desk's kinds are compiled at its mount, so a host that changes them remounts, and may veil it):
+ * the boot's milestones, ms since the mount (the factory's call, on `performance.now()`'s clock), each absent until it happens — for
+ * good on a boot that failed. `device`: the device in hand (the adapter and the device asked for, or the engine's adopted); `compiled`:
+ * the passes compiled (`Ground.create` resolved — the status `ready`); `presented`: the first frame's GPU work done
+ * (`queue.onSubmittedWorkDone()` after its submit — the compositor's from then).
+ */
+export interface DeskLayerBoot {
+    readonly device?: number;
+    readonly compiled?: number;
+    readonly presented?: 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;
+    /**
+     * Whether the host mounts the room's other people's cursors (petition I26): `deskLayer({ cursors })` as read at the mount, `true`
+     * when absent — `@ice/dom`'s `createDeskHost` reads it off the handle (its structural `LayerHandle.cursors`) before it registers them.
+     */
+    readonly cursors: boolean;
+    /** 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 CAPTURE DOOR (petition I23 — the covers' still, the thumbnails, "Send to…"): the desk as the LAST PRESENTED frame showed
+     * it — the same camera, theme, selection marks, hand and tray (what to hide is the host's, by its own doors, before the call) —
+     * as an `ImageBitmap` of `rect` (CSS px of the view; the whole view when absent) at the view's dpr × `scale` (1; a thumbnail
+     * asks 0.25). Inside: that frame's inputs drawn ONCE MORE into a readable texture at the asked size and read back
+     * (`Ground.capture`) — never a copy kept of every frame, never a frame: the swap chain is not touched, the loop is not woken, no
+     * frame is counted (`redraws()`, `perf().frames`), and the memory ledger shows the still and its readback as a `capture` line of
+     * its own while they live and nothing after. Taken while the frame gate holds (`engine.frame.freeze`), it is the parked frame;
+     * live, the most recent. `undefined`, never a throw, while `status()` is `failed` or `degraded`, before the first frame has been
+     * presented, or when the device is lost mid-copy (a malformed option throws at the call). Captures serialize; one asked for the
+     * same picture (equal options, no frame since) while another is in flight resolves to that one's bitmap.
+     */
+    capture(opts?: CaptureOptions): Promise<ImageBitmap | undefined>;
+    /**
+     * THE DESK'S PICK (petition I27 — a host's right-click selects the object under the pointer before it grows the menu): the object
+     * at `point` (CSS px of the view, the container's top-left at 0, 0 — a pointer event's client point less the container's rect) as
+     * the desk's own pick resolves it. Inside: the interaction stack's exact pick (`stack.pickAt`, through the mount context) — the one
+     * body a press's `TouchesExact` is written by, never a second hit path — so the answer is what a primary click there selects: the
+     * topmost object by stratum and sibling order through its kind's mirror on the last frame's geometry, its PART reported; on a live
+     * mini mat's face the mini mat (its inside's objects are no members of this frame — entered, they pick with it as their canvas).
+     * Synchronous; reads the last frame's world — no redraw, no wake, no write; it never selects (the host decides). `null` over the
+     * bare mat and its rulers (printed on it), over what is not an object (a resize handle), while an object is in hand or the
+     * pegboard drawer is out (the desk inert to the pointer — D4b, design-017 §4), before the first frame, and while `status()` is
+     * `pending` or `failed` (`degraded` picks: the desk still draws, a click still selects). A point that is not two finite numbers throws.
+     */
+    pick(point: {
+        readonly x: number;
+        readonly y: number;
+    }): PickResult | null;
+    /** 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. And the boot's milestones (`boot`, petition I25). */
+    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). A
+     * MISSING kind (petition I24) is a row of `kinds` whatever it declares: `KIND_MISSING` (−1 — no time; it is never due, nothing of
+     * it runs), and `at` never counts it.
+     */
+    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,16 @@
+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 HeldReadoutContext, 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 HoldOptions, type HoldReserves, type HomePose, homePose, isNarrow, type ReadingTarget, readingTarget } from "./hold/pose";
+export { NO_DOCS, type TypingDocs, type WritableSession, writable } from "./docs";
+export { createKindFaults, faultText, KIND_MISSING, KIND_STRIKES, type KindFault, type KindFaults } from "./faults";
+export { MISSING_KIND, MISSING_OBJECT } from "./missing/object";
+export { isMissingRecord, missingFace, type MissingRecord } from "./missing/layout";
+export * from "./theme";
+export * from "./shaders";
+export { BLUE_NOISE_SIZE, blueNoise } from "./assets/blue-noise.gen";
+export { ZOOM_MAX, ZOOM_MIN } from "./lattice/lod";