@vibecook/ice 0.11.0 → 0.15.0-desk.1

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

@@ -0,0 +1,120 @@
+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";
+import type { Ambient, AmbientState } from "./ambient";
+import type { DeskBuilder, DeskBuilderStats, DeskWakeReason, HoldPin } from "./builder";
+export interface DeskReflectorOptions {
+    readonly world: World;
+    readonly builder: DeskBuilder;
+    /** The kinds whose `theme()` makes a look — every object kind the ground registers. */
+    readonly kinds: readonly ObjectKind[];
+    readonly ambient: Ambient;
+    /** The ground once `Ground.create` resolved, null before and after the layer ends. */
+    readonly ground: () => Ground | null;
+    /** The host sizes its canvas to `width × height` DEVICE px (the swap chain follows). */
+    readonly attach: {
+        resize(width: number, height: number): void;
+    };
+    readonly theme: GroundTheme;
+    /** The host's palette — what each kind's `theme()` reads its look from. */
+    readonly palette: Palette;
+    /** The root's grid: the lattice's fade-in and the mat's config (its gobo, its rulers). */
+    readonly grid?: GridConfig;
+    /** The device pixel ratio the canvas is capped at (2). */
+    readonly maxDpr?: number;
+    readonly name?: string;
+    /** Called after every frame drawn — the layer publishes the selection menu's anchor from it (D4a). */
+    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.
+     */
+    readonly onWake?: (reason: string) => void;
+}
+/** What woke a frame, counted since the mount — the builder's reasons and the reflector's own. */
+export type DeskWakes = Readonly<Record<DeskWakeReason | "camera" | "viewport" | "nav" | "theme" | "grid" | "pin" | "ambient" | "live" | "ink" | "tray", number>>;
+export interface DeskReflectorStats extends DeskBuilderStats {
+    /** Whole-frame renders so far — the churn instrument (0 on an idle desk). */
+    readonly redraws: number;
+    /** The ground's stats for the last frame drawn (null before the first). */
+    readonly frame: GroundStats | null;
+    readonly ambient: AmbientState;
+}
+export interface DeskReflector {
+    /** The drawing reflector (`always: true`): register it where the ground layer goes. */
+    readonly reflector: ReflectorDef & {
+        available(): boolean;
+    };
+    /** The ground is here (or gone): the next tick paints. */
+    ready(): void;
+    /** The host's projection changed (a theme switch): the looks are remade, the next frame re-renders. */
+    setTheme(theme: GroundTheme, palette?: Palette): void;
+    /** The root's grid (the mat's config, the fade-in) as a whole. */
+    configureGrid(grid: GridConfig): void;
+    /** Wake a frame for a reason the world does not carry (a pin, an asset, the writing's flux — D2c's `ink`). */
+    wake(reason: "pin" | "ambient" | "ink"): void;
+    /**
+     * A harness's pins on the build (D2b): live insides on or off (the oracle's `portals: false`), a pinned root
+     * dressing (`lodZoom`), every spring and ghost held where it is (`freeze` — a still of a moving frame), the
+     * re-dressing ramp held at its start (`holdRedress`). Each present key is set; the next frame paints.
+     */
+    pinBuild(pins: {
+        readonly portals?: boolean;
+        readonly lodZoom?: number | null;
+        readonly freeze?: boolean;
+        readonly holdRedress?: boolean;
+        readonly hold?: HoldPin | null;
+    }): void;
+    /** The kinds whose own state moved this tick (their `local.tick` wanted a frame): the builder remakes their records this build (D6). */
+    restless(kinds: ReadonlySet<string>): void;
+    /** The frame dirty and not yet drawn (a rig's witness). */
+    dirty(): boolean;
+    /**
+     * WHEN THE REFLECTOR IS NEXT DUE (K7a — its registered wake): `now` while a frame is owed (dirt, a live spring or ghost, the
+     * drawer on its way) or the ambient still moves (the wind's clock is a frame); `Infinity` otherwise — and while it cannot
+     * draw (no ground yet, no viewport): the ground's arrival and the viewport's write wake it.
+     */
+    due(now: number): number;
+    redraws(): number;
+    stats(): DeskReflectorStats;
+    wakes(): DeskWakes;
+    /** The inputs of the last render, as handed to `Ground.render`. */
+    lastInputs(): GroundFrameInputs | null;
+    grid(): GridConfig;
+    theme(): GroundTheme;
+    /** A kind's look for the theme in force (its `theme()` of the palette) — the held bar's swatches read it (D3t-a). */
+    look(kind: string): unknown;
+    /** The pegboard drawer's flux (design-017 §3): its motion, the drawer as drawn (the pose seam's answer), the pins for a still. */
+    readonly tray: TrayFlux;
+    /** The tray's specimens as the last frame drew them (K5a) — a rig's witness; empty while the drawer is shut or bare. */
+    traySpecimens(): readonly TraySpecimenFrame[];
+    /**
+     * Did the last frame's TRAY draw `e` — a specimen, a lifted copy's key, an insert ghost it presented (K5b over K6b)? The frame raster
+     * queue's word on what shows is the builder's and this: an ask a specimen's writing made (its word, `tray.local`) is run, not let go.
+     */
+    trayShows(e: Entity): boolean;
+    /** The take's motion (K5b — tray/carry.ts): the lifted copy, the ghost's grow and its flight home. */
+    readonly carry: TrayCarry;
+    /** What the tray carried in the last frame drawn (K5b) — a rig's witness: each pose's slot, phase, ghost and rect on screen. */
+    trayCarried(): readonly TrayCarriedFrame[];
+    dispose(): void;
+}
+export declare function createDeskReflector(opts: DeskReflectorOptions): DeskReflector;
+/** Each kind's look for a theme, by kind name — what `ObjectContext.look` carries. */
+export declare function looksOf(kinds: readonly ObjectKind[], palette: Palette, theme: GroundTheme): Map<string, unknown>;

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

@@ -0,0 +1,5 @@
+import { type Entity, type World } from "../../../core/src/index";
+export declare function tapHit(world: World, pid: string): {
+    readonly found: boolean;
+    readonly hit: Entity | undefined;
+};

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

@@ -0,0 +1,23 @@
+import { type CommitExtender, type DocSession } from "../../core/src/index";
+/** The document a driver writes into — the facade's `engine.docs` (its `current()` session: store + live writer + the gate's verdict). */
+export interface TypingDocs {
+    current(): Pick<DocSession, "store" | "liveWriter" | "readOnly" | "versionReport"> | undefined;
+    /** The facade's door into a gesture's own transaction (`docs.extendCommits`, D7 #2): a landing's writes in the gesture's undo step. Absent (a bare store), a driver has no such door. */
+    extendCommits?(extend: CommitExtender): () => void;
+    /** The facade's history doors (`docs.undo`/`docs.redo` — historyStep: the tween retarget, the read-only posture; D7 #9). Absent (a bare store), a driver moves no history. */
+    undo?(): boolean;
+    redo?(): boolean;
+}
+/** What a desk writer holds while it commits: the session's store and live writer. */
+export type WritableSession = Pick<DocSession, "store" | "liveWriter">;
+/**
+ * THE WRITER'S GATE (D7 #1): the session a desk gesture may commit into — none without a document, and none when the
+ * version gate's verdict is read-only (a doc a newer build wrote, a pack this build does not compile, a root that does not
+ * agree). `readOnly` is the verdict at open; the report is asked again because a peer's pack can move it after. This is
+ * the facade's `requireWritable` law at the desk's own write surfaces: strata's store has no read-only mode, and every desk
+ * writer commits through it directly (guardedTransaction, setWidgetProps), never through the doc kit's commit sink, so a
+ * gate that lived only in the sink never reached them. A refused writer does what "no document" means to it: nothing lands.
+ */
+export declare function writable(docs: TypingDocs): WritableSession | undefined;
+/** No document at all: the runtime is all there is (a desk without a facade, a catalog harness). */
+export declare const NO_DOCS: TypingDocs;

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

@@ -0,0 +1,43 @@
+export interface BudgetStats {
+    readonly cap: number;
+    /** Bytes charged across every owner — the resident arrays and the caches together. */
+    readonly used: number;
+    /** Bytes that reside (never evicted): the thumbnail arrays. */
+    readonly resident: number;
+    /** What the caches may hold beside what resides: `cap − resident`, never under the floor. */
+    readonly room: number;
+    readonly entries: number;
+    /** Evictions since the ledger was made. */
+    readonly evictions: number;
+    readonly byOwner: Readonly<Record<string, {
+        readonly bytes: number;
+        readonly entries: number;
+    }>>;
+}
+export interface RasterBudget {
+    readonly cap: number;
+    /** The caches' room this moment: `cap − resident`, never under the floor. */
+    room(): number;
+    /** An owner's raster `key` of `bytes`, and how to let it go; a second charge of the same key re-sizes it (the old bytes released). Touches it. */
+    charge(owner: string, key: string, bytes: number, evict: () => void): void;
+    /** An owner's `key` kept WHOLE (a thumbnail array): never evicted, outside the caches' room; a second call re-sizes it. */
+    reside(owner: string, key: string, bytes: number): void;
+    /** The raster was used (drawn, written): it is the most recently used now. */
+    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.
+     */
+    trim(keep?: (owner: string, key: string) => boolean): number;
+    stats(): BudgetStats;
+}
+/** The caches' floor as a share of the cap: what they may always hold, however much resides (D-K9-d.1). */
+export declare const BUDGET_FLOOR: number;
+export declare function createRasterBudget(cap: number, floor?: number): RasterBudget;

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

@@ -0,0 +1,54 @@
+export interface GpuOptions {
+    /** `navigator.gpu` in a browser; Dawn's `create([])` in Node. */
+    readonly gpu: GPU;
+    readonly label?: string;
+    readonly powerPreference?: GPUPowerPreference;
+    /** Features to enable where the adapter has them, beside `timestamp-query` — asked for whenever the adapter has it (the GPU profiler's clock, design-016 §4: a feature cannot be added to a device later, and one unused costs nothing). */
+    readonly requiredFeatures?: readonly GPUFeatureName[];
+    /** Device loss and uncaptured errors — the layer degrades, it does not throw. */
+    readonly onLost?: (info: GPUDeviceLostInfo) => void;
+    readonly onError?: (error: GPUError) => void;
+}
+export interface Gpu {
+    readonly adapter: GPUAdapter;
+    readonly device: GPUDevice;
+    readonly info: {
+        readonly vendor: string;
+        readonly architecture: string;
+        readonly description: string;
+    };
+}
+export declare function acquire(opts: GpuOptions): Promise<Gpu>;
+/**
+ * The one limit the desk asks above WebGPU's floor (K9 R1): the adapter's own `maxTextureArrayLayers` — a device asked for
+ * nothing gets the floor, 256, whatever the hardware holds (Apple 2048), and the kinds' shared thumbnail arrays (kit/arrays.ts
+ * `LayerArray`) stop there: the 257th picture has no layer, the 257th whiteboard no far-LOD thumbnail. On an adapter AT the floor
+ * this asks for 256 and changes nothing — the arrays' own reclaim and the boards' bare draw carry that cap honestly.
+ */
+export declare function arrayLayerLimit(adapter: Pick<GPUAdapter, "limits">): Record<string, number> | undefined;
+/**
+ * A device the host already HAS — the engine's (design-015 D7: ONE device per engine) — wired as `acquire` wires one it
+ * made: its loss and its uncaptured errors reach the handlers. The caller does not own it, so it never destroys it.
+ */
+export declare function adopt(adapter: GPUAdapter, device: GPUDevice, opts?: Pick<GpuOptions, "onLost" | "onError">): Gpu;
+/** A swap chain as the ground draws into it — made by `host/surface.ts` (a canvas) or a test's fake. */
+export interface Surface {
+    readonly context: GPUCanvasContext;
+    readonly format: GPUTextureFormat;
+    /** Size the drawing buffer to the CSS box × dpr (clamped). True when it changed. */
+    fit(maxDpr?: number): {
+        changed: boolean;
+        width: number;
+        height: number;
+        cssWidth: number;
+        cssHeight: number;
+        dpr: number;
+    };
+    /** The swap-chain texture view for this frame. */
+    view(): GPUTextureView;
+    /** The drawing buffer's size in device px — whatever sized the canvas, `fit()` or the host. */
+    size(): {
+        readonly w: number;
+        readonly h: number;
+    };
+}

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

@@ -0,0 +1,5 @@
+export { defineStruct, type StructDef, type StructBuffer, type FieldSlot, type FieldType, type FieldValue, type StructValues } from "./struct";
+export { compose, compile, type ComposedShader, type ComposeOptions, type ShaderPart } from "./shader";
+export { acquire, adopt, type Gpu, type GpuOptions, type Surface } from "./device";
+export { bindLayout, bindGroup, renderPipeline, uniformBuffer, storageBuffer, BLEND_OVER, type BindEntry, type BindKind, type RenderPipelineOptions, type Visibility, } from "./pipeline";
+export { Target, beginPass, readback, type Clear, type TargetOptions } from "./target";

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

@@ -0,0 +1,36 @@
+export type Visibility = "vertex" | "fragment" | "compute";
+export type BindEntry = {
+    readonly binding: number;
+    readonly stages: readonly Visibility[];
+    readonly buffer: GPUBufferBindingType;
+} | {
+    readonly binding: number;
+    readonly stages: readonly Visibility[];
+    readonly texture: GPUTextureSampleType;
+    readonly dimension?: GPUTextureViewDimension;
+} | {
+    readonly binding: number;
+    readonly stages: readonly Visibility[];
+    readonly sampler: GPUSamplerBindingType;
+};
+/** A binding's layout without its number — what a card material declares (K7b), the card deals the numbers. */
+export type BindKind = BindEntry extends infer E ? (E extends BindEntry ? Omit<E, "binding"> : never) : never;
+export declare function bindLayout(device: GPUDevice, entries: readonly BindEntry[], label?: string): GPUBindGroupLayout;
+export declare function bindGroup(device: GPUDevice, layout: GPUBindGroupLayout, resources: ReadonlyArray<GPUBuffer | GPUTextureView | GPUSampler>, label?: string): GPUBindGroup;
+/** Straight-alpha "source over": colour by src-alpha, alpha accumulates. */
+export declare const BLEND_OVER: GPUBlendState;
+export interface RenderPipelineOptions {
+    readonly label?: string;
+    readonly layout: GPUPipelineLayout;
+    readonly module: GPUShaderModule;
+    readonly vertex?: string;
+    readonly fragment?: string;
+    readonly format: GPUTextureFormat;
+    readonly blend?: GPUBlendState;
+    /** WGSL `override` values, fixed at creation — how one file becomes N specialised pipelines. */
+    readonly constants?: Record<string, number>;
+    readonly topology?: GPUPrimitiveTopology;
+}
+export declare function renderPipeline(device: GPUDevice, o: RenderPipelineOptions): Promise<GPURenderPipeline>;
+export declare function uniformBuffer(device: GPUDevice, size: number, label?: string): GPUBuffer;
+export declare function storageBuffer(device: GPUDevice, size: number, label?: string): GPUBuffer;

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

@@ -0,0 +1,66 @@
+import type { Entity } from "../../../core/src/index";
+/** What a run says: `done` — the raster is laid (or no longer owed); `wait` — no room for it now: held until its owner `wake`s. */
+export type RasterRun = () => "done" | "wait";
+export interface RasterQueueStats {
+    /** The frame's budget, ms. */
+    readonly budgetMs: number;
+    /** Asks waiting for their turn, and those held for room. */
+    readonly waiting: number;
+    readonly held: number;
+    /** Runs since the queue was made, the turns that ran any, and their ms. */
+    readonly ran: number;
+    readonly turns: number;
+    readonly ms: number;
+    /** Asks let go unrun: their object was not drawn when their turn came. */
+    readonly dropped: number;
+    /** The most runs one turn made, the most ms one turn spent, and the most one run took — a turn overshoots its budget by at most its last run. */
+    readonly peakRuns: number;
+    readonly peakMs: number;
+    readonly dearest: number;
+}
+export interface RasterQueue {
+    /** The frame's budget, ms (the turn's first run excepted). */
+    readonly budgetMs: number;
+    /**
+     * Ask for `owner`'s raster of `key` (a kind and its object): `priority` orders the turn (lower first — a kind puts what shows
+     * nothing before what shows a stand-in, and the nearest the view's centre first); `run` lays it when its turn comes. A second ask
+     * for the same key replaces the first — its priority and its run, and a held ask is waiting again.
+     */
+    ask(owner: string, key: Entity, priority: number, run: RasterRun): void;
+    /** The ask is withdrawn: the object's need went away before its turn (the zoom came back to the band it holds), or it left. */
+    drop(owner: string, key: Entity): void;
+    has(owner: string, key: Entity): boolean;
+    /** Room may have been made — `owner` let a raster go, or (no owner) the host drew a frame: the held asks wait for their turn again. */
+    wake(owner?: string): void;
+    /** Every ask of `owner` withdrawn (its state reset), or every ask. */
+    clear(owner?: string): void;
+    /** The host's turn, once a tick before the build: the runs, lowest priority first, while the budget lasts. Returns how many ran. */
+    drain(): number;
+    /** Asks waiting for their turn — the host keeps the desk awake while there are any (held asks are not counted). */
+    readonly size: number;
+    stats(): RasterQueueStats;
+}
+export interface RasterQueueOptions {
+    /** The frame's budget, ms (default `RASTER_BUDGET_MS`). */
+    readonly budgetMs?: number;
+    /** The clock the budget is kept on (default `performance.now`). */
+    readonly clock?: () => number;
+    /** Was the object drawn in the last build (the builder's word, `DeskBuilder.shows`)? Absent: every ask is run. */
+    readonly shows?: (key: Entity) => boolean;
+}
+/**
+ * The frame's raster budget, ms: a zoom's frame keeps its other work (≈ 1 ms of JS on the stress desk) inside design-016 §6's
+ * 8 ms with a raster's worth to spare — a note's ink at band 2 costs ≈ 2 ms on this Mac, and the turn's first always runs.
+ */
+export declare const RASTER_BUDGET_MS = 4;
+/**
+ * What an object shows while its raster waits its turn (K6b): NOTHING (a blank sheet, a bare board), its old raster MAGNIFIED (a
+ * band or a density short of the screen's — soft), or its old raster MINIFIED (past it — only the pages' room is at stake).
+ */
+export type RasterWait = "nothing" | "magnified" | "minified";
+/**
+ * The priority every kind asks with, so one turn orders them all alike (K6b): what shows nothing first, then a stand-in magnified,
+ * then one minified — the nearest the view's centre (`px`, screen px) first within each.
+ */
+export declare function rasterPriority(shows: RasterWait, px: number): number;
+export declare function createRasterQueue(opts?: RasterQueueOptions): RasterQueue;

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

@@ -0,0 +1,56 @@
+import type { StructBuffer, StructDef } from "./struct";
+/** How the pass packs one record into its slot; `blocks` (when the store has them) and `blockBase` name the slot's block. Returns the block records used (0 without blocks). */
+export type RecordPacker<R, F extends string, B extends string> = (record: R, aux: number, into: StructBuffer<F>, slot: number, blocks: StructBuffer<B> | null, blockBase: number) => number;
+export interface RecordStoreOptions<R, F extends string, B extends string = never> {
+    readonly device: GPUDevice;
+    readonly def: StructDef<F>;
+    /** Slots at the start; grown by doubling up to `max` (65,536). */
+    readonly capacity: number;
+    readonly max?: number;
+    /** The records buffer's label (`paper/notes`); the draw list is `<label> order`, the blocks `blocks.label`. */
+    readonly label: string;
+    readonly pack: RecordPacker<R, F, B>;
+    /** A fixed block of `per` sub-records of `def` a slot (the mini mat's chips). */
+    readonly blocks?: {
+        readonly def: StructDef<B>;
+        readonly per: number;
+        readonly label: string;
+    };
+}
+export interface RecordStoreStats {
+    /** Records packed and uploaded since the store was made. */
+    readonly written: number;
+    /** Bytes those uploads carried (records and blocks). */
+    readonly bytes: number;
+    /** Draw-list uploads. */
+    readonly orderWrites: number;
+    /** Slots in use, the capacity, how many times the buffers were remade. */
+    readonly slots: number;
+    readonly capacity: number;
+    readonly grown: number;
+}
+export interface RecordStore<R> {
+    /** The records buffer, the draw list and (with blocks) the blocks buffer — bind them; their identity moves on growth, `version` says when. */
+    readonly records: GPUBuffer;
+    readonly order: GPUBuffer;
+    readonly blocks: GPUBuffer | null;
+    readonly version: number;
+    /**
+     * One frame's records in paint order. `keys`: one per record, stable across frames (absent = transient: slots dealt from 0,
+     * everything packed). `aux(i)`: a number per record folded into the change test and handed to the pack. Returns the count
+     * that will draw — `order[0 … count)` names each paint index's slot.
+     */
+    prepare(records: readonly R[], keys: readonly number[] | undefined, aux?: (index: number) => number): number;
+    /** The slot drawn at paint index `i` this frame. */
+    slotAt(i: number): number;
+    /** What the pack folded in at paint index `i`: its aux and the block records it used. */
+    entryAt(i: number): {
+        readonly aux: number;
+        readonly blockN: number;
+    };
+    /** Every live record repacked at the next `prepare` (a law changed under them). */
+    invalidate(): void;
+    stats(): RecordStoreStats;
+    dispose(): void;
+}
+export declare function createRecordStore<R, F extends string, B extends string = never>(opts: RecordStoreOptions<R, F, B>): RecordStore<R>;

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

@@ -0,0 +1,22 @@
+import type { StructDef } from "./struct";
+export interface ShaderPart {
+    readonly label: string;
+    readonly text: string;
+}
+export interface ComposeOptions {
+    /** Structs whose WGSL text is prepended, in order. */
+    readonly structs?: ReadonlyArray<StructDef<string>>;
+    /** Pure modules, in dependency order. */
+    readonly modules?: ReadonlyArray<ShaderPart>;
+    /** The entry: bindings + @vertex/@fragment/@compute. */
+    readonly entry: ShaderPart;
+}
+export interface ComposedShader {
+    readonly code: string;
+    readonly label: string;
+    /** Map a line of the composed code back to `<part>:<line>`. */
+    locate(line: number): string;
+}
+export declare function compose(opts: ComposeOptions): ComposedShader;
+/** Create the module and surface compilation errors with mapped locations. */
+export declare function compile(device: GPUDevice, shader: ComposedShader): Promise<GPUShaderModule>;

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

@@ -0,0 +1,39 @@
+/** The scalar and vector types, and a fixed array of vec4f (`array<vec4f, N>`: stride 16, legal in a uniform block) — the portal chain's. */
+export type FieldType = "f32" | "i32" | "u32" | "vec2f" | "vec3f" | "vec4f" | "mat4x4f" | `array<vec4f, ${number}>`;
+interface TypeInfo {
+    readonly align: number;
+    readonly size: number;
+    readonly n: number;
+    readonly scalar: "f" | "i" | "u";
+}
+/** A field type's layout: the table's, or a vec4f array's — N × 16 bytes, 4N floats, written as one flat list. */
+export declare function typeInfo(type: FieldType): TypeInfo | undefined;
+export interface FieldSlot {
+    readonly byte: number;
+    readonly type: FieldType;
+    readonly n: number;
+}
+export type FieldValue = number | boolean | ArrayLike<number>;
+export type StructValues<F extends string> = Partial<Record<F, FieldValue>>;
+export interface StructDef<F extends string> {
+    readonly name: string;
+    readonly fields: ReadonlyArray<readonly [F, FieldType]>;
+    /** Padded size in bytes; also the array stride. */
+    readonly size: number;
+    readonly slots: Readonly<Record<F, FieldSlot>>;
+    /** `struct <name> { ... }` — prepend to any shader that binds this. */
+    readonly wgsl: string;
+    /** Backing storage for `count` elements. */
+    alloc(count?: number): StructBuffer<F>;
+}
+export interface StructBuffer<F extends string> {
+    readonly def: StructDef<F>;
+    readonly count: number;
+    readonly bytes: ArrayBuffer;
+    /** Write fields by name into element `index`. Unknown names and wrong arity throw. */
+    set(values: StructValues<F>, index?: number): void;
+    /** The byte view to upload; `elements` trims to a prefix of the array. */
+    view(elements?: number): Uint8Array<ArrayBuffer>;
+}
+export declare function defineStruct<F extends string>(name: string, fields: ReadonlyArray<readonly [F, FieldType]>): StructDef<F>;
+export {};

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

@@ -0,0 +1,26 @@
+export interface TargetOptions {
+    readonly format: GPUTextureFormat;
+    readonly label?: string;
+    /** Add COPY_SRC when a host wants to read the pixels back (the oracle does). */
+    readonly readable?: boolean;
+}
+export declare class Target {
+    texture: GPUTexture;
+    view: GPUTextureView;
+    width: number;
+    height: number;
+    readonly format: GPUTextureFormat;
+    private readonly usage;
+    private readonly device;
+    private readonly opts;
+    constructor(device: GPUDevice, opts: TargetOptions, width?: number, height?: number);
+    private make;
+    /** True when the texture was recreated (and therefore holds nothing). */
+    resize(w0: number, h0: number): boolean;
+    dispose(): void;
+}
+export type Clear = readonly [number, number, number, number];
+/** Begin a colour-only render pass; `clear` omitted loads the existing contents. */
+export declare function beginPass(encoder: GPUCommandEncoder, view: GPUTextureView, clear?: Clear, label?: string): GPURenderPassEncoder;
+/** Read a texture back as raw bytes with row padding removed (oracle / tests). */
+export declare function readback(device: GPUDevice, texture: GPUTexture, bytesPerTexel: number): Promise<Uint8Array>;

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/gpu-ablation.d.ts

@@ -0,0 +1,61 @@
+import type { GroundFrameInputs } from "./ground";
+export interface KindCostOptions {
+    /** Rounds (7). */
+    readonly rounds?: number;
+    /** The batch's target GPU time, ms (25). */
+    readonly targetMs?: number;
+    /** The probe's frames (4). */
+    readonly probeFrames?: number;
+    /** The batch's bounds (3 … 300 frames). */
+    readonly minFrames?: number;
+    readonly maxFrames?: number;
+    /** The kinds to leave out (default: every kind with an object in the frame). */
+    readonly kinds?: readonly string[];
+}
+export interface Sampled {
+    readonly median: number;
+    readonly min: number;
+}
+export interface KindCost {
+    /** ms per frame the frame loses without the kind: the median of the paired base − without-k over rounds. */
+    readonly ms: number;
+    /** …as a share of the base frame. */
+    readonly share: number;
+    /** The frame without the kind, ms per frame. */
+    readonly without: Sampled;
+    /** The kind's objects in the frame (every slot's). */
+    readonly objects: number;
+    /** The cost clears the noise floor. */
+    readonly clears: boolean;
+}
+export interface KindCostReport {
+    /** Frames a batch, rounds, and every round's batches in the order drawn. */
+    readonly frames: number;
+    readonly rounds: number;
+    /** The frame as it is, ms per frame. */
+    readonly base: Sampled;
+    /** The A/A control: the same frame as a variant of its own. */
+    readonly control: Sampled;
+    /** median(control) − median(base): the A/A offset. */
+    readonly aa: number;
+    /** The noise floor: the median over rounds of |control − base| within a round. */
+    readonly noise: number;
+    readonly kinds: Readonly<Record<string, KindCost>>;
+    /** Every batch, ms per frame, by variant (`base`, `control`, each kind), in round order — round r drew variant i at position (i − r) mod n. */
+    readonly samples: Readonly<Record<string, readonly number[]>>;
+}
+export interface Ablation {
+    /** The frame to measure (the last one drawn). */
+    readonly inputs: GroundFrameInputs;
+    /** Draw one frame of these inputs, synchronously (`Ground.render`). */
+    render(inputs: GroundFrameInputs): void;
+    /** Resolve once the GPU finished everything submitted (`queue.onSubmittedWorkDone`). */
+    drain(): Promise<unknown>;
+    now(): number;
+}
+/** Every kind with an object in the frame, and how many — the root's, the insides', the departed desk's. */
+export declare function kindsIn(inputs: GroundFrameInputs): Record<string, number>;
+/** The frame with `kind`'s objects left out of every slot (its insides with them); `null` kind: the frame as it is. The held object is always left out (the rest frame). */
+export declare function withoutKind(inputs: GroundFrameInputs, kind: string | null): GroundFrameInputs;
+/** Measure what each kind costs the frame (the header's method). */
+export declare function ablateKinds(a: Ablation, opts?: KindCostOptions): Promise<KindCostReport>;