@vibecook/ice 0.11.0 → 0.14.0

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

@@ -0,0 +1,285 @@
+import { type MarqueeBuffer, type NavFace, type Entity, type WidgetType, type World } from "../../../core/src/index";
+import type { HeldFrameInputs, OutgoingInputs, PortalInputs, SlotObject } from "../ground";
+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.
+     */
+    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;
+}
+/**
+ * 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;
+    /** 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,126 @@
+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;
+}
+/** 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">>, opts?: {
+    readonly moving?: () => boolean;
+}): FramePickSource;

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

@@ -0,0 +1,111 @@
+import { type Entity, type ReflectorDef, type World } from "../../../core/src/index";
+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 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>;
+    /**
+     * 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,38 @@
+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;
+    /**
+     * 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;