@vibecook/ice 0.11.0 → 0.15.0-desk.1

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

@@ -0,0 +1,103 @@
+import { type BindEntry } from "../engine/pipeline";
+import { type ComposeOptions } from "../engine/shader";
+import type { CardMaterial, KindPass, KindProgram, SlotContext } from "../kind";
+import type { MatPass } from "../kit/view";
+/** A card's slot in its kind's records: the low 24 bits; the high byte its material. */
+export declare const CARD_SLOT_BITS = 24;
+/** A kind composed into the card: its name (the ground's key), its material, and its program (the material's `shaders()`, asked once). */
+export interface CardKind {
+    readonly name: string;
+    readonly material: CardMaterial;
+    readonly shaders: ComposeOptions;
+}
+/** What one card pipeline composes: its kinds by material index, and what it could not (a limit it would pass — they draw themselves). */
+export interface CardPlan {
+    readonly kinds: readonly CardKind[];
+    readonly left: readonly {
+        readonly name: string;
+        readonly why: string;
+    }[];
+}
+type Limits = Pick<GPUSupportedLimits, "maxSampledTexturesPerShaderStage" | "maxSamplersPerShaderStage" | "maxStorageBuffersPerShaderStage" | "maxUniformBuffersPerShaderStage" | "maxBindingsPerBindGroup">;
+/** A binding's name from its WGSL (`var<uniform> paper_k: PaperUniforms` → `paper_k`); null when it declares none the card can read. */
+export declare const bindingName: (wgsl: string) => string | null;
+/**
+ * The kinds one card pipeline composes, in registration order — a material kind is left out (and draws itself) when it is a
+ * composite (its objects are one target's), when adding it would pass one of the device's per-stage limits, or (K9 R3) when a
+ * name of its would collide with the card's own or an earlier kind's.
+ */
+export declare function planCards(programs: readonly KindProgram[], limits: Limits): CardPlan;
+/** The card's own entry: its bindings, every material's, their `only` and card functions, and the dispatch on the card's material. */
+export declare function cardEntry(kinds: readonly CardKind[]): string;
+/** The card's program: every material's structs (by name) and modules (by label) once, in order, then the card's entry. */
+export declare function cardShaders(kinds: readonly CardKind[]): ComposeOptions;
+/** The layout: the card's own four, then every material's bindings in order. */
+export declare function cardLayoutEntries(kinds: readonly CardKind[]): BindEntry[];
+/** The pipelines every slot's card draws with (once per device). */
+export interface CardShared {
+    /** The kinds composed, by material index. */
+    readonly kinds: readonly string[];
+    readonly material: ReadonlyMap<string, number>;
+    readonly layout: GPUBindGroupLayout;
+    readonly pipeline: GPURenderPipeline;
+    /** The same, for a slot lit from elsewhere (MINIMAT.md §4) — the materials' `LIT_ELSEWHERE`. */
+    readonly litPipeline: GPURenderPipeline;
+    /** What was left out, and why. */
+    readonly left: CardPlan["left"];
+}
+/**
+ * The card's pipelines for the registered programs; null when none declares a material the device can compose. A material the
+ * device REFUSES (K9 R3 — a plugin's WGSL error, a binding whose type its layout belies) takes only its own kind out of the card:
+ * each material is then compiled alone and the ones that fail are left with their error; if what remains still fails together (a
+ * collision the plan did not see), the last registered goes until the card compiles (a plugin registers after the built-ins).
+ * Every kind left out draws itself, as one past the device's limits does, and is said once (`console.error`, and `left`).
+ */
+export declare function createCardShared(device: GPUDevice, format: GPUTextureFormat, programs: readonly KindProgram[]): Promise<CardShared | null>;
+/**
+ * One slot's card: its draw list (the ground pushes a card for every object a material kind's pass lets go, in the order its
+ * runs walk them) and the bind group over the slot's view block and mat and ITS kinds' resources — made again only when one of
+ * them was replaced. The list is uploaded only when it changed (a camera move over a settled desk writes nothing).
+ */
+export declare class CardPass {
+    readonly name = "card";
+    /** Off: the ground routes nothing here — every object is drawn by its kind's own pass (a witness's second draw, a rig's A/B). */
+    on: boolean;
+    private list;
+    private sent;
+    private n;
+    private sentN;
+    private buffer;
+    private group;
+    /** What the group was made over: the mat's assets, the list's buffer, and each material's version. */
+    private boundOver;
+    private litElsewhere;
+    /** Each object's card this frame (−1: none) — a slot's route, reused frame to frame (`route`). */
+    private routes;
+    private readonly device;
+    private readonly shared;
+    private readonly mat;
+    private readonly kinds;
+    private bufferVersion;
+    constructor(device: GPUDevice, shared: CardShared, mat: MatPass, kinds: ReadonlyMap<string, {
+        readonly pass: KindPass;
+    }>);
+    /** A slot's card on the same pipelines, over ITS mat and kinds. */
+    spawn(mat: MatPass, kinds: ReadonlyMap<string, {
+        readonly pass: KindPass;
+    }>): CardPass;
+    /** The material index of kind `name`, or undefined when the card does not draw it. */
+    materialOf(name: string): number | undefined;
+    /** A frame's list begins, and a route for `n` objects, every one −1 (drawn by its kind). */
+    begin(n: number): Int32Array;
+    /** A card for record `slot` of material `m`: its index in this frame's list (the ground's run counts it). */
+    push(m: number, slot: number): number;
+    /** The list uploaded when it changed, the group made again when anything under it moved, the pipeline for the slot's light. */
+    prepare(slot: SlotContext): number;
+    private rebind;
+    /** Cards [first, end) of this frame's list — interleaved objects of every material kind — as ONE instanced draw. */
+    drawRange(pass: GPURenderPassEncoder, first: number, end: number): void;
+    /** The cards this frame. */
+    get count(): number;
+    dispose(): void;
+}
+export {};

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

@@ -0,0 +1,59 @@
+import { type MatFrame } from "../mat/layout";
+export type AmbientMode = "live" | "idle" | "still";
+export interface AmbientOptions {
+    /** `idle` by default (design-015 D-D9). */
+    readonly mode?: AmbientMode;
+    /** How long after the last touch the wind keeps blowing, ms (20 000). */
+    readonly idleMs?: number;
+    /** How long the wind takes to ease to still once idle, ms (2 000). */
+    readonly settleMs?: number;
+    /** Seconds of gobo time per second at full speed (theme.ts `MAT_GRID.gobo.wind`). */
+    readonly wind?: number;
+    /** Radians of projector tilt per unit of smoothed pointer NDC (theme.ts `MAT_GRID.gobo.tilt`). */
+    readonly tilt?: number;
+    /** The OS asked for reduced motion: the mode is `still` whatever was set. */
+    readonly reducedMotion?: boolean;
+    /** The blue noise's re-roll (Math.random); a test's fake. */
+    readonly random?: () => number;
+}
+export type AmbientPhase = "live" | "easing" | "still" | "pinned";
+export interface AmbientState {
+    readonly mode: AmbientMode;
+    readonly phase: AmbientPhase;
+    /** The wind's speed, 0 … 1 of full. */
+    readonly speed: number;
+    readonly reducedMotion: boolean;
+    readonly pinned: boolean;
+}
+/** A pinned still's clocks (a parity scene): whatever is absent keeps the engine's still values. */
+export interface AmbientPin {
+    readonly time?: number;
+    readonly goboTime?: number;
+    readonly noise?: readonly [number, number];
+}
+export interface Ambient {
+    /** The pointer moved, a gesture or a flight ran: the wind (re)starts its `idleMs`. */
+    touch(now: number): void;
+    /** Advance the clocks by `dt` seconds at `now` ms, the tilt following `pointer` (NDC, or null before the pointer was seen); `live` = another frame is wanted. */
+    step(dt: number, now: number, pointer: readonly [number, number] | null): {
+        readonly frame: MatFrame;
+        readonly live: boolean;
+    };
+    /** The frame as the clocks stand, NOT advanced (the pinned one while pinned) — the desk behind the hand stands still (§8, D7). */
+    frame(): MatFrame;
+    /** Pin the clocks (a still) or unpin (`null`). Pinned, `step` returns the pinned frame and wants no frame. */
+    pin(frame: AmbientPin | null): void;
+    configure(opts: Pick<AmbientOptions, "mode" | "idleMs" | "settleMs" | "reducedMotion">): void;
+    state(): AmbientState;
+    /** The clocks as they stand (a rig's witness). */
+    clocks(): {
+        readonly time: number;
+        readonly goboTime: number;
+    };
+}
+export declare const AMBIENT_DEFAULTS: {
+    readonly mode: AmbientMode;
+    readonly idleMs: 20000;
+    readonly settleMs: 2000;
+};
+export declare function createAmbient(opts?: AmbientOptions): Ambient;

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

@@ -0,0 +1,306 @@
+import { type MarqueeBuffer, type NavFace, type Entity, type WidgetType, type World } from "../../../core/src/index";
+import type { KindFaults } from "../faults";
+import type { HeldFrameInputs, OutgoingInputs, PortalInputs, SlotObject } from "../ground";
+import { type HoldReserves } from "../hold/pose";
+import { FLUX_REST, type KindLocal, type ObjectFlux, type ObjectKind } from "../kinds/world";
+import type { MarksInput } from "../marks/layout";
+import { type SelectionAnchor } from "./marks";
+import type { GridConfig } from "../mat/grid";
+import type { MatFrame, SlotLight } from "../mat/layout";
+import { type InsideView } from "../kit/inside";
+import { type CameraState } from "../nav/flight";
+import { type Presentation } from "../nav/portal";
+import { type ObjectSprings } from "../kit/springs";
+import type { GroundTheme } from "../theme";
+/** The view a frame is built for: CSS px and the dpr the canvas is at. */
+export interface BuildViewport {
+    readonly width: number;
+    readonly height: number;
+    readonly dpr: number;
+}
+export interface DeskBuilderOptions {
+    /**
+     * The OBJECT widget types this desk may hold: their prop groups join the change journal and
+     * their kinds' `reach` the pick pad. An object of a type not listed still draws (its kind is found
+     * off the widget type) but its props are refreshed only on a Position/Size/tag change — unless the
+     * boundary is on (`faults`, the layer's): then its kind must be one the listed types name, the set
+     * the desk was MOUNTED with and its ground compiled (petition I25), or it wears the missing face.
+     */
+    readonly objects: readonly WidgetType[];
+    /** The objects' springs (springs.ts `SPRINGS`). */
+    readonly springs?: ObjectSprings;
+    /** A deleted object's fade, ms (the prototype's 0.22 s). */
+    readonly ghostMs?: number;
+    /** The cull margin past the view, CSS px (the prototype's 200). */
+    readonly marginPx?: number;
+    /** The re-dressing after a zoom-through cut, ms (PORTAL.md §9's 320). */
+    readonly redressMs?: number;
+    /**
+     * The kinds' own state on this desk by kind name (kinds/world.ts `KindLocal` — the note's writing,
+     * D2c): threaded into every context of the kind as `ctx.local`, and told when an entity is FORGOTTEN
+     * (its ghost faded, it left the frame, it died unseen) so what it held — a raster's rect — goes back.
+     */
+    readonly locals?: ReadonlyMap<string, KindLocal>;
+    /** The interaction stack's marquee preview (out of the ECS — design-003 §5.7): the vellum the marks draw (D4a). */
+    readonly marquee?: () => MarqueeBuffer | undefined;
+    /**
+     * The engine's spatial index (design-015 §2.5; D6): the cull's broad phase — the frame's objects within the view, its margin and the
+     * kinds' reach, asked with a hysteresis band so a pan asks it again only when the view leaves the last answer. Absent (a test, a bare
+     * host), every member is tested.
+     */
+    readonly spatial?: SpatialSource;
+    /** The hand's reserves (petition I20 — `deskLayer({ hold })`): where the reading fit keeps clear of the host's chrome; `HOLD`'s by default. */
+    readonly hold?: HoldReserves;
+    /**
+     * THE KIND BOUNDARY (petition I24, faults.ts): every call into a kind's world half — `resolve`, `record` (and what a remake asks with
+     * them: `face`, `frame`, `rung`, its desk state's `landed`), `chip`, `hit`, the hand's, a ghost's, `lifted` and `veils` — is caught at the
+     * kind: the throw is a strike, the object it was made for is left out of this frame (its record reset, made afresh next time), and
+     * the frame goes on. A MISSING kind's objects — and an object whose type has no kind — are drawn by the missing face
+     * (`MISSING_OBJECT`) under their kind's name; nothing of a missing kind is called again. Absent (a unit, a bare host): as before — a
+     * throw is the caller's, and an object whose type has no kind is not drawn.
+     */
+    readonly faults?: KindFaults;
+}
+/**
+ * What the builder asks of the spatial index: the entries whose rects meet a world AABB (kernel's `SpatialIndex.search`), and how
+ * many it holds — core clears it at a nav cut and refills it on the NEXT tick's `spatialSync` (design-004 §7), so a build in which it
+ * holds fewer entries than the frame has members culls linearly and asks again next build.
+ */
+export interface SpatialSource {
+    search(bounds: {
+        readonly minX: number;
+        readonly minY: number;
+        readonly maxX: number;
+        readonly maxY: number;
+    }): readonly {
+        readonly id: Entity;
+    }[];
+    readonly size?: number;
+}
+/**
+ * The builder's PER-ENTITY WORK in a build — the O(1)-pan witness (design-015 §2.5, §11.4: "no per-entity work — a counter
+ * proves it"; D6). A camera move over a settled desk must leave every count at 0 but the cull's `visited`, which is the
+ * spatial index's answer, never the desk's population.
+ */
+export interface BuildWork {
+    /** Entities the membership query yielded (the frame's objects walked). */
+    readonly queried: number;
+    /** Members the cull walked, every slot. */
+    readonly visited: number;
+    /** Members sorted into paint order (0 = the last order stood). */
+    readonly sorted: number;
+    /** A kind's `resolve` — every slot's rows, the chips, the ghosts, the hand and its riders. */
+    readonly resolved: number;
+    /** A kind's `record`. */
+    readonly recorded: number;
+    /** Records REUSED from the last build — nothing about them changed (D6). */
+    readonly reused: number;
+    /** A kind's `rung` read (K6b): of each drawn object of a kind with one, on a frame its slot's zoom or the dpr moved — a remake only when it moved. */
+    readonly rungs: number;
+    /**
+     * Why records were remade (K6b, a rig's witness — the zoom's): the object had none (it came on screen), its RUNG moved, a `rezoom`
+     * kind's zoom moved, its kind's own state was restless (a board's density raised). Counted per cause: one remake may count twice.
+     */
+    readonly fresh: number;
+    readonly rerung: number;
+    readonly rezoomed: number;
+    readonly restless: number;
+    /** Chips a container's face could not draw (K8a): the child's chip named no finish of the container's `faceLaw` — left out, never redressed. */
+    readonly unchipped: number;
+}
+export interface DeskBuilderStats {
+    /** Objects Active in the frame this build saw. */
+    readonly active: number;
+    /** Objects drawn in the root slot — within the view and its margin, plus the ghosts. */
+    readonly objects: number;
+    /** Objects off screen this build (the root slot). */
+    readonly culled: number;
+    /** Deleted objects still fading. */
+    readonly ghosts: number;
+    /** Live insides built this frame, every depth (the departed desk's included). */
+    readonly portals: number;
+    /** True after a build while any spring or ghost is still moving, or a re-dressing ramp runs. */
+    readonly live: boolean;
+    /** This build's per-entity work (D6). */
+    readonly work: BuildWork;
+    /** The work of every build since the builder was made — a rig diffs two readings. */
+    readonly totals: BuildWork;
+    /** Under `verify(true)`: reused records that a fresh resolve would NOT have made — the persistent path's own witness; 0 or a bug. */
+    readonly mismatches: number;
+}
+/** What can dirty the builder: a journaled world write, a despawn, a document reset, the sibling order, the hover target, the marks' own facts (the snap's chrome, the vellum, a drag meeting tape, the gestures — D4a). */
+export type DeskWakeReason = "world" | "removed" | "reset" | "order" | "hover" | "marks";
+/** The springs a host may pin: each present key holds that spring at the value. */
+export type FluxPin = Partial<Pick<ObjectFlux, "lift" | "hover">>;
+/** What a build may be told beyond the camera (a harness's pins, the reflector's clocks). */
+export interface BuildOptions {
+    /** The frame's clock, ms (`FrameInfo.now`) — the re-dressing ramp's. */
+    readonly now?: number;
+    /** The mat's clocks and tilt for every slot this frame (the reflector's ambient frame). */
+    readonly mat?: MatFrame;
+    /** Live insides on (the default). Off, every face draws its far LOD alone (the oracle's `portals: false`). */
+    readonly portals?: boolean;
+    /** A pinned root dressing (the oracle's `lodZoom`). */
+    readonly lodZoom?: number;
+    /** Hold every spring and ghost where it is — a still of a moving frame (a rig's flight pin). */
+    readonly freeze?: boolean;
+    /** Hold the re-dressing ramp at its start (the prototype harness's `redressPinned`). */
+    readonly holdRedress?: boolean;
+    /** THE HAND PINNED (D4b — a still of the opening): the carry amount held at `e`, the kind's open motion snapped to `open` (default: open past 42 %). */
+    readonly hold?: HoldPin;
+    /** The kinds whose own state moved this tick (their `local.tick` wanted a frame — a print gliding, ink drying): their records are remade (D6). */
+    readonly restless?: ReadonlySet<string>;
+    /** Objects another presenter draws this frame (K5b — the tray's carry: an insert ghost growing out of the lifted copy, or shrinking home): none of the root's rows, no marks, their springs still run. */
+    readonly presented?: ReadonlySet<Entity>;
+}
+export interface HoldPin {
+    readonly e: number;
+    readonly open?: boolean;
+}
+/**
+ * The object IN HAND as the last build made it (design-015 §8; D4b): the entity, whether the pickup has settled and whether
+ * it is flying home (the fact already gone), the frame the pose seam publishes (core's `HeldScreenFrame`, CSS px), what the
+ * ground draws (`GroundFrameInputs.held` less its `stamp` — the reflector adds the camera's and the viewport's stamps), and the
+ * desk's own change count `deskSeq` — everything the desk copy depends on, never the held object's own facts.
+ */
+export interface HeldBuild {
+    readonly entity: Entity;
+    /** The carry amount this frame, 0 on the desk … 1 in hand (also `inputs.e` — here for the witnesses). */
+    readonly e: number;
+    readonly settled: boolean;
+    readonly landing: boolean;
+    readonly frame: {
+        readonly cx: number;
+        readonly cy: number;
+        readonly hx: number;
+        readonly hy: number;
+        readonly s: number;
+        readonly settled: boolean;
+    };
+    readonly inputs: Omit<HeldFrameInputs, "stamp">;
+    readonly deskSeq: number;
+}
+export interface BuiltDesk {
+    /** The root slot's objects in paint order — what `SlotInputs.objects` takes. */
+    readonly objects: readonly SlotObject[];
+    /** The root slot's live insides (MINIMAT.md §3). */
+    readonly portals: readonly PortalInputs[];
+    /** The current frame's grid: the root's, or the entered mini mat's inside grid. */
+    readonly grid: GridConfig;
+    /** The root's dressing: a flight's landing, a re-dressing's ramp, a pin — absent = its own zoom. */
+    readonly lodZoom?: number;
+    /** The root's presentation while a flight is on. */
+    readonly present?: Presentation;
+    /** The root's lamp while it is handed over (a flight, a re-dressing after a cut in). */
+    readonly light?: SlotLight;
+    /** The departed desk while a flight is on. */
+    readonly outgoing?: OutgoingInputs;
+    /** The desk's chrome this frame (stratum 5 — `GroundFrameInputs.marks`, D4a): the root slot's, the current frame's desk. */
+    readonly marks: MarksInput;
+    /** The object in hand, or flying home (D4b): out of `objects` and of the marks, drawn as a slot of its own over the desk out of focus. */
+    readonly held?: HeldBuild;
+    readonly stats: DeskBuilderStats;
+}
+export interface DeskBuilder {
+    /**
+     * Advance every on-screen object's springs by `dt` SECONDS and build this frame's records under
+     * `cam` and `vp`: `theme` and `grid` are the root's; `looks` is each kind's `theme()` result by
+     * kind name (the reflector keeps them per theme); `opts` the clocks and a harness's pins.
+     */
+    build(cam: CameraState, vp: BuildViewport, dt: number, theme: GroundTheme, grid: GridConfig, looks: ReadonlyMap<string, unknown>, opts?: BuildOptions): BuiltDesk;
+    /** True while a spring, a ghost or a re-dressing ramp still moves after the last build — the reflector paints again. */
+    live(): boolean;
+    /**
+     * PULL the world's dirt: did any fact a build reads change since the last pull — an object's
+     * position, size or props, its Grab, its selection, the Active set, a despawn, a document reset,
+     * the sibling order, the hover target? Call it every tick (it drains the journal); `wakes()` names
+     * what changed.
+     */
+    changed(): boolean;
+    /** How many times each fact has dirtied the builder since creation. */
+    wakes(): Readonly<Record<DeskWakeReason, number>>;
+    /** The last build's geometry for an entity — the pick source's mirror; `undefined` = not drawn (unseen, culled, gone). */
+    geometryOf(e: Entity): unknown | undefined;
+    /** The kind an entity draws by, once the builder has met it. */
+    kindOf(e: Entity): ObjectKind | undefined;
+    /** The last build's flux for an entity (the rig's witness). */
+    fluxOf(e: Entity): ObjectFlux | undefined;
+    /** The last build's view of a container's inside — its camera, presence and clip under the slot it was drawn in (a rig's witness). */
+    insideViewOf(e: Entity): InsideView | undefined;
+    /**
+     * THE SEAM's answer (design-015 §9): the container's face under the host camera `cam` — AS DRAWN
+     * when it was built in the current frame this frame, at REST otherwise (the frame's own container,
+     * an exit's) — with the inside's arrival, embedding, camera, presence and cover test. `undefined`:
+     * not a container kind, or a face with no area.
+     */
+    navFace(container: Entity, cam: CameraState): NavFace | undefined;
+    /**
+     * A per-entity asset the host pins — a committed raster, a note's greeked writing (`ObjectContext.asset`);
+     * `undefined` unpins. Kept BY ENTITY, met or not: a pin made in the same task as the spawn (the parity
+     * scene's ink, before the entity's facts are readable) waits for the first build. Dirties the builder.
+     */
+    pin(e: Entity, asset: unknown): void;
+    /**
+     * Pin an object's springs for a STILL (a parity scene's `held` = `{ lift: 1 }` — never a `Grab`,
+     * which would also carry it to the top of the paint order): each pinned spring SITS at its
+     * target, snapped, whatever the facts say; the unpinned ones keep following them. `undefined`
+     * unpins. Dirties the builder. Flux, never a world fact.
+     */
+    pinFlux(e: Entity, targets: FluxPin | undefined): void;
+    /** Every flux pin lifted. */
+    clearFlux(): void;
+    /** The widest `reach` among the desk's kinds, world units — the pick source's pad. */
+    reach(): number;
+    /** The selection menu's anchor as of the last build: the marks' box around the selection on screen, whether a gesture is on (D4a). */
+    anchor(): SelectionAnchor;
+    /**
+     * A drag a host refused on `e` outside core's move — a print's own carry (D3w): a taped object gives, as a core drag that
+     * meets the tape makes it give (D4a). The next `changed()` reports it.
+     */
+    meetTape(e: Entity): void;
+    /** The object in hand as of the last build (D4b) — what the pose seam answers from; undefined = nothing held or flying home. */
+    hand(): HeldBuild | undefined;
+    /**
+     * A point of the held object's own frame (core's `HeldPointer`: its open extent's units, centred) as a DESK point, through the
+     * pose the last build drew (the frame on screen, then the held slot's camera) — undefined unless `e` is in hand (D3t-a).
+     */
+    heldToWorld(e: Entity, x: number, y: number): readonly [number, number] | undefined;
+    /**
+     * A DESK point into the held slot's world for the object in hand or FLYING HOME (D7 #11): the pose the last build drew, through
+     * the desk camera of that build. The pick asks the kind's mirror there — the held geometry is resolved under the held slot's own
+     * camera, so a desk point tested against it raw picked nothing where the object is drawn. Undefined unless `e` is the hand's.
+     */
+    heldPoint(e: Entity, wx: number, wy: number): readonly [number, number] | undefined;
+    /** The held kind's part under such a point — its `hit` on the geometry it was drawn with in hand; null over nothing (the pose seam's `part`, D3t-a). */
+    heldPart(e: Entity, x: number, y: number): string | null;
+    /**
+     * What is under a world point of `e` as the last build drew it (the pick source's mirror, design-015 §4.5): its kind's `hit` on that
+     * geometry — or, drawn as the MISSING face (petition I24), its box. `null`: a miss (a kind whose `hit` throws takes a strike and misses
+     * — the pick goes on to the next object down); `undefined`: not drawn (unseen, culled, its kind gone missing since).
+     */
+    hitAt(e: Entity, wx: number, wy: number): string | null | undefined;
+    /** The objects the last build painted LIFTED by their kind's own state (D3t-a — a print carried or in the air): above their siblings, asked first by the pick. */
+    lifted(): readonly Entity[];
+    /** An entity a kind's state veiled in the last build (D3t-c — a note gone with its month): not drawn, never picked. */
+    veiled(e: Entity): boolean;
+    /** The last build's paint rank of `e` in the ROOT slot (D6 — a kind's residency asks it); undefined = not drawn there. */
+    rankOf(e: Entity): number | undefined;
+    /** Was `e` drawn in the last build — its record made or reused in ANY slot, the root's, an inside's, the hand's (K6b: the raster queue lets go of an ask whose object is not)? */
+    shows(e: Entity): boolean;
+    /** `e`'s record remade at the next build, and the desk woken (K6b — a raster LANDED on it: its record says where its ink is). */
+    remake(e: Entity): void;
+    /** Every record remade at the next build (a kind's law changed under them — `tuneLaw`). */
+    invalidate(): void;
+    /** Check every reused record against a fresh resolve each build (`stats().mismatches`) — a rig's witness, dear per frame. */
+    verify(on: boolean): void;
+    stats(): DeskBuilderStats;
+    dispose(): void;
+}
+/**
+ * Two records the same, value for value (D6's `verify`): plain objects and arrays by their entries, typed arrays by their elements,
+ * numbers with NaN equal to NaN, anything else — a picture's texture, a class instance — by identity.
+ */
+export declare function sameRecord(a: unknown, b: unknown): boolean;
+export declare function createDeskBuilder(world: World, opts: DeskBuilderOptions): DeskBuilder;
+/** The flux of an object nobody has met: at rest. */
+export { FLUX_REST };

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

@@ -0,0 +1,3 @@
+import { type World } from "../../../core/src/index";
+import type { DataChildren } from "../kinds/world";
+export declare function worldChildren(world: World): DataChildren;

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

@@ -0,0 +1,14 @@
+export { AMBIENT_DEFAULTS, type Ambient, type AmbientMode, type AmbientOptions, type AmbientPhase, type AmbientPin, type AmbientState, createAmbient } from "./ambient";
+export { type BuildViewport, type BuildWork, type BuiltDesk, createDeskBuilder, type DeskBuilder, type DeskBuilderOptions, type DeskBuilderStats, type DeskWakeReason, type HeldBuild, type HoldPin } from "./builder";
+export { createMarksCollector, type MarkRow, type MarksCollector, type MenuSlot, menuSlots, type SelectionAnchor, withKindActs } from "./marks";
+export { createPickSource } from "./pick";
+export { tapHit } from "./tap";
+export { createDeskReflector, type DeskReflector, type DeskReflectorOptions, type DeskReflectorStats, type DeskWakes } from "./reflector";
+export { instrumentSubmits, type SubmitHook, type SubmitInstrument, tapSubmits, type UploadTally } from "../submit-instrument";
+export { type Ablation, ablateKinds, type KindCost, type KindCostOptions, type KindCostReport, kindsIn, type Sampled, withoutKind } from "../gpu-ablation";
+export { createGpuProfiler, type GpuFrameCounts, type GpuFrameReport, type GpuProfileStats, type GpuProfiler, type GpuProfilerOptions, type Rolling, rolling, busyOf, spanOf, type TraceEvent, type TraceJson, traceOf } from "../gpu-profiler";
+export { instrumentPasses, type KindDraws, type PassCounts, type PassFrame, type PassInstrument, type PassInstrumentOptions, type PassTime, type PassTiming, readTimestamps, TIMESTAMP_QUANTUM_NS, UNQUANTISED_TIMESTAMPS_FLAG } from "../pass-instrument";
+export { type FormatBlock, formatBlock, type GpuMemory, type GpuMemoryRow, instrumentMemory, type MemoryLedger, regionBytes, textureBytes } from "../gpu-memory";
+export { type BudgetStats, createRasterBudget, type RasterBudget } from "../engine/budget";
+export { createRasterQueue, RASTER_BUDGET_MS, rasterPriority, type RasterQueue, type RasterQueueOptions, type RasterQueueStats, type RasterRun, type RasterWait } from "../engine/rasters";
+export { createRecordStore, type RecordStore, type RecordStoreStats } from "../engine/records";

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

@@ -0,0 +1,133 @@
+import { type HeldGlyph, type MenuActionDef, type MarqueeBuffer, type Entity, type World } from "../../../core/src/index";
+import type { HeldToolDef } from "../kinds/world";
+import { type MarkBox, type MarkFrame, type MarksInput } from "../marks/layout";
+/** One object as the builder hands it to the marks: its drawn frame and rect (world), the facts it cached. */
+export interface MarkRow {
+    readonly entity: Entity;
+    readonly frame: MarkFrame;
+    /** ICE's rect: Position (top-left) + Size, world units. */
+    readonly rect: {
+        readonly x0: number;
+        readonly y0: number;
+        readonly x1: number;
+        readonly y1: number;
+    };
+    readonly selected: boolean;
+    readonly locked: boolean;
+    readonly grabbed: boolean;
+    readonly resizable: boolean;
+}
+/** What the selection menu is placed from (the desk handle publishes it): the marks' box around the selection ON SCREEN, CSS px. */
+export interface SelectionAnchor {
+    /** The brackets' box (6 out) for one object, the union's (10 out) for several — null when nothing is selected. */
+    readonly box: MarkBox | null;
+    readonly count: number;
+    /** Every selected object is taped (the menu offers "Lift the tape"). */
+    readonly locked: boolean;
+    /** A gesture is on (a drag, a vellum, a pan, a pinch): the menu steps aside. */
+    readonly gesturing: boolean;
+    /** A note is being written (core's `Editing` — the one focused editor, D2c): the menu steps aside as for a gesture; the brackets stay. */
+    readonly editing: boolean;
+    /** The view it was placed in, CSS px, and whether the rulers are printed (the menu flips below their band). */
+    readonly view: {
+        readonly width: number;
+        readonly height: number;
+    };
+    readonly rulers: {
+        readonly margin: number;
+        readonly band: number;
+    } | null;
+    /** An object is IN HAND (design-015 §8, D4b): the menu travels to the foot and becomes the held bar — Send · the kind's tools · Done. Absent = nothing held. */
+    readonly held?: HeldAnchor;
+    /**
+     * The selection's KIND ACTS (K8a — its types' `defineObject({ menu })`): those every selected object's type declares, as plain data
+     * (the op stays on the type — the menu runs one through `ops.runMenuAction`). Absent: none (nothing selected declares any).
+     */
+    readonly menu?: readonly MenuSlot[];
+}
+/**
+ * The hand as the menu takes it (D4b): the kind's tools that take a slot in the bar (its `open.tools`, D3t-a: live), the mode
+ * in hand (core's `HeldTool` — the one slot marked), whether the object is flying home (the bar hides) and whether the pickup
+ * has settled.
+ */
+export interface HeldAnchor {
+    readonly tools: readonly HeldSlot[];
+    readonly active: string;
+    readonly landing: boolean;
+    readonly settled: boolean;
+    /**
+     * The held bar's TRAVEL (M1), ms, as the host set it (`deskLayer({ hold: { travelMs } })`, petition I20): the bar travels to the
+     * foot over it and back. Absent — the host set none — the bar keeps its own.
+     */
+    readonly travelMs?: number;
+    /** The kind's WORD in hand (petition I22 — its `open.readout`): "Page 2", "September". Absent — the kind says none (or none now). */
+    readonly readout?: string;
+}
+/** A kind's act as the selection menu shows it (K8a): plain data — the op stays on the widget type (`ops.runMenuAction`). */
+export interface MenuSlot {
+    readonly id: string;
+    readonly label: string;
+    readonly glyph?: HeldGlyph;
+    readonly keys?: string;
+}
+/** A selection's kind acts as the menu's slots (K8a): every act its types all declare (core's `menuActionsFor`), as plain data. */
+export declare function menuSlots(acts: readonly MenuActionDef[]): MenuSlot[];
+/**
+ * The anchor with the selection's KIND ACTS (K8a): every act all the selected objects' types declare (`menuOf` reads an object's
+ * type's `menu`), as the menu's slots — the anchor unchanged when nothing is selected or no act is shared.
+ */
+export declare function withKindActs(a: SelectionAnchor, selected: readonly Entity[], menuOf: (e: Entity) => readonly MenuActionDef[]): SelectionAnchor;
+/** A tool's slot as the bar shows it: plain data (the op stays on the widget type — the bar uses a tool through `ops.useHeldTool`). */
+export interface HeldSlot {
+    readonly id: string;
+    readonly label: string;
+    /** `mode` · `action`; absent = declared only (dim). */
+    readonly kind?: "mode" | "action";
+    readonly hint?: string;
+    /** Its glyph (core's `HeldGlyph`, K8a): a name of the bar's set, or the tool's own drawing (`{ path }`) — plain data either way. */
+    readonly glyph?: HeldGlyph;
+    /** A colour the slot shows instead of its glyph (a marker's ink), CSS. */
+    readonly swatch?: string;
+}
+/** The slots a kind's tools take in the bar: every tool not keys-only, as plain data, its swatch from the kind's look. */
+export declare function heldSlots(tools: readonly HeldToolDef[], swatches?: Readonly<Record<string, string>>): HeldSlot[];
+export interface MarksFrameInput {
+    readonly rows: readonly MarkRow[];
+    readonly cam: {
+        readonly x: number;
+        readonly y: number;
+        readonly zoom: number;
+    };
+    readonly view: {
+        readonly width: number;
+        readonly height: number;
+        readonly dpr: number;
+    };
+    readonly dt: number;
+    readonly night: boolean;
+    readonly rulers: {
+        readonly margin: number;
+        readonly band: number;
+    } | null;
+}
+export interface MarksCollector {
+    /** PULL what the marks read outside the builder's journal — the snap's chrome, the vellum, a drag meeting tape, the gestures; true when any changed (a wake). */
+    changed(): boolean;
+    /** This frame's marks: the clocks stepped by `dt`, the state assembled. */
+    frame(input: MarksFrameInput): MarksInput;
+    /** A clock still moves: the next frame paints too. */
+    live(): boolean;
+    /** The tape's give on an entity this frame, CSS px along x (0 at rest) — the builder shifts the object by it. */
+    giveOf(e: Entity): number;
+    /**
+     * A drag refused on `e` outside core's move — a print's own carry (D3w: a print is not core-movable, so no core drag of
+     * it ever meets the tape here): a taped `e` gives, as a core drag meeting tape makes it give. The next `changed()` wakes.
+     */
+    refused(e: Entity): void;
+    /** The selection menu's anchor, as of the last frame. */
+    anchor(): SelectionAnchor;
+    dispose(): void;
+}
+export declare function createMarksCollector(world: World, opts?: {
+    readonly marquee?: () => MarqueeBuffer | undefined;
+}): MarksCollector;

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

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