@vibecook/ice 0.10.0 → 0.14.0

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

@@ -0,0 +1,388 @@
+import type { Surface } from "./engine/device";
+import { CardPass } from "./card/card";
+import { HoldPass } from "./hold/focus";
+import type { HoldShaders } from "./hold/shaders";
+import { type KindPass, type KindProgram, type RenderTarget, type StratumName } from "./kind";
+import { type View } from "./lattice/lod";
+import type { MatLight } from "./mat/night";
+import { type GridConfig, type GridStats, type SlotFrame } from "./mat/grid";
+import { CuttingMat } from "./mat/mat-pass";
+import type { MatShaders } from "./mat/shaders";
+import type { MarksInput } from "./marks/layout";
+import { MarksPass } from "./marks/pass";
+import type { MarksShaders } from "./marks/shaders";
+import { type TrayFrameInputs, TrayPass } from "./tray/pass";
+import type { TrayShaders } from "./tray/shaders";
+import { TraySlots } from "./tray/specimens";
+import { type Presentation } from "./nav/portal";
+import type { GroundTheme } from "./theme";
+export type { CardBinding, CardMaterial, KindExtra, KindPass, KindProgram, RenderTarget, SlotContext, StratumName } from "./kind";
+export { STRATA } from "./kind";
+export type { MarkBar, MarkBox, MarkFrame, MarkGuide, MarkMarquee, MarkObject, MarkRuler, MarksInput, MarkTape, MarkUnion } from "./marks/layout";
+export { MARKS_SHADER_FILES, marksShaders } from "./marks/shaders";
+export type { TrayFrameInputs } from "./tray/pass";
+export { TRAY_SHADER_FILES, trayShaders } from "./tray/shaders";
+export interface GroundOptions {
+    /**
+     * The device the HOST owns — the engine's (`acquireCompositorDevice()`, handed to the layer through its
+     * context) or the layer's own (`engine/device.ts` `acquire()`, as the oracle's is). The ground never
+     * makes one: every texture the compose pass samples must live on the same device.
+     */
+    readonly device: GPUDevice;
+    /**
+     * The swap chain the frames go into — the HOST makes it (`surface(device, canvas)` from
+     * `@ice/desk`'s src/host/, the one module that names a canvas; a test's fake), so this composition
+     * root never touches the DOM (design-015 §3 `desk-dom-free`, D2a-world).
+     */
+    readonly surface: Surface;
+    /** The cutting mat (mat/mat-pass.ts) — the ground's own: every slot draws it first. */
+    readonly mat: MatShaders;
+    /**
+     * The kinds this ground draws — its REGISTRY (kind.ts; the desk's own are `DESK_KINDS`, `@ice/desk/kinds`).
+     * Names are unique. Each kind's pass is made on the root's mat; the kinds prepare in this order and draw
+     * stratum by stratum, then in each slot's paint order.
+     */
+    readonly kinds: readonly KindProgram[];
+    /**
+     * The desk's chrome (marks/pass.ts; design-015 §7, D4a): the marks pass, drawn in the ROOT's pass after every
+     * stratum — the selection's brackets, the vellum, the laser, the tape — when a frame names its `marks`. Absent =
+     * a ground that draws no chrome.
+     */
+    readonly marks?: MarksShaders;
+    /**
+     * The hand (hold/focus.ts; design-015 §8, D4b): the focus behind an object in hand and the object over it, when a
+     * frame names its `held`. Absent = a ground that never picks anything up (a frame's `held` is then ignored).
+     */
+    readonly hold?: HoldShaders;
+    /**
+     * The pegboard tray (tray/pass.ts; design-017, K3): the drawer, drawn in the ROOT's pass after the marks when a frame names its
+     * `tray`. Absent = a ground with no tray.
+     */
+    readonly tray?: TrayShaders;
+}
+/** A layer a host rendered first, laid on the mat inside the ground's pass (it sets its own scissor; the ground restores the slot's). */
+export interface Underlay {
+    draw(pass: GPURenderPassEncoder): void;
+}
+/**
+ * One object on a desk as the ground takes it: its kind's name (a registered one) and the record that kind's pass draws — and
+ * its KEY (D6, design-015 §4.3): stable across frames (the builder's entity; a ghost's negated), so the kind's persistent records
+ * keep the object's slot and write it only when the record object changed. Absent: the record is packed afresh every frame.
+ */
+export interface SlotObject {
+    readonly kind: string;
+    readonly record: unknown;
+    readonly key?: number | undefined;
+}
+/** One desk's ground: its camera, grid, objects and presentation — the root's, a departed desk's, or a mini mat's inside. */
+export interface SlotInputs extends SlotFrame {
+    /** The grid; the root may leave it unset and set `ground.grid` instead — every other slot names its own. */
+    readonly grid?: GridConfig;
+    /**
+     * Things drawn ON THE MAT by passes of their own, beneath everything else on the desk
+     * (CALENDAR.md: the desk calendar — the host renders its layer first, the ground lays it here).
+     */
+    readonly underlays?: readonly Underlay[];
+    /**
+     * The objects on this desk in PAINT ORDER, lowest first — the caller sorts: strata first (the ground draws
+     * stratum by stratum whatever the list says), then its own order within each. A kind's records are its
+     * objects, in this order; every kind named must be registered.
+     */
+    readonly objects?: readonly SlotObject[];
+    /** The live insides of this desk's sheets (MINIMAT.md §3): each drawn right after the object `at` names. */
+    readonly portals?: readonly PortalInputs[];
+}
+/**
+ * A mini mat's inside through its face (PORTAL.md §2.1, MINIMAT.md §3): `present` carries
+ * the presence (its opacity — the gate's answer) and the face (its clip); `view` may leave
+ * `box` unset — the ground sizes the slot's box from the clip.
+ */
+export interface PortalInputs extends SlotInputs {
+    readonly grid: GridConfig;
+    /** The mini mat's index in the parent's `objects` (paint order): the slot draws just AFTER it, over its face. */
+    readonly at: number;
+}
+/** The departed desk's ground for one flight frame: its own camera, grid, objects and presentation. */
+export interface OutgoingInputs extends SlotInputs {
+    readonly grid: GridConfig;
+    /** design-006's z-rule for a FROZEN flight: under on enter, over on exit. */
+    readonly order: "under" | "over";
+    /**
+     * ENTER through a live portal (PORTAL.md §2.4): the mini mat's index in the DEPARTED desk's
+     * `objects` — the two desks draw as one tree, the arriving one through the mini mat's face,
+     * so the objects over the mini mat stay over the inside and fade with their desk (a live
+     * portal of the departed desk at the same index is neither prepared nor drawn: the arriving
+     * desk is that face). Absent = two whole slots, `order` decides: a frozen flight, and every
+     * EXIT — the departed inside draws OVER the whole parent (whose own live portal shows the
+     * same pixels under it) and fades onto them at the landing.
+     */
+    readonly at?: number;
+}
+/**
+ * THE HAND for one frame (design-015 §8; D4b — the builder makes it, the ground draws it): the one object in hand as a slot
+ * of its own — its record, the pose's CAMERA (`view`) and its grid (no dapple in hand) — drawn by its kind's own pass over the
+ * desk out of focus. `e` is the carry amount (the focus follows it); `blur` the radius the ONE blur is made at (CSS px: 14, a
+ * phone's 10); `dim` the desk's dim behind (already by the carry); `filter` the reading light on the hand (1, 1 by day);
+ * `light` the hand's own light (the day's mixed in by night); `stamp` the desk copy's identity — while it stands, the blurred
+ * desk is reused (rendered ONCE per settled state, the held object alone redrawing).
+ */
+export interface HeldFrameInputs {
+    readonly object: SlotObject;
+    /** What rides with it (D3t-c — a calendar's stuck notes): drawn in the hand's slot after it, under the same camera. */
+    readonly riders?: readonly SlotObject[];
+    readonly view: View & {
+        readonly dpr: number;
+    };
+    readonly grid: GridConfig;
+    readonly e: number;
+    readonly blur: number;
+    readonly dim: number;
+    readonly filter: {
+        readonly saturate: number;
+        readonly brightness: number;
+    };
+    readonly light: MatLight;
+    readonly stamp: string;
+}
+export interface GroundFrameInputs extends SlotInputs {
+    /** The theme in force (`theme.ts`): the clear colour, the selection's colour and the mat's light (the Sun or the Moon) come from it. */
+    readonly theme: GroundTheme;
+    /** Present only while a nav flight is on. */
+    readonly outgoing?: OutgoingInputs;
+    /** The desk's marks this frame, in screen px (marks/layout.ts) — stratum 5, over everything; absent = none. */
+    readonly marks?: MarksInput;
+    /** The object in hand (design-015 §8, D4b) while one is held or flying home; absent = the desk as it is. At `e` 0 the frame is the rest frame, byte for byte. */
+    readonly held?: HeldFrameInputs;
+    /** The pegboard drawer this frame (design-017 — the renderer's flux: its slide, its shown scroll), over the marks; absent = none. Never drawn over the hand. */
+    readonly tray?: TrayFrameInputs;
+}
+export interface GroundStats extends GridStats {
+    /** The root's records drawn this frame, by kind name — every registered kind, 0 where it had none. */
+    readonly kinds: Readonly<Record<string, number>>;
+    /** The departed slot's grid while a flight is on. */
+    readonly outgoing: GridStats | null;
+    /** Live portals drawn this frame, the root's and the departed desk's together. */
+    readonly portals: number;
+    /** The records the kinds' CAPS turned away this frame, by kind name, every slot's (absent: none) — resolved and NOT drawn (D7). */
+    readonly dropped?: Readonly<Record<string, number>>;
+}
+/** One registered kind as a slot holds it: the registry's name and stratum, and the slot's own pass (and whether it lays a composite — `KindProgram.composite`). */
+export interface SlotKind {
+    readonly name: string;
+    readonly stratum: StratumName;
+    readonly pass: KindPass;
+    readonly composite?: boolean;
+}
+/** The passes one slot owns: the mat's, and every registered kind's by name, in registration order. The root's are the ground's; the pool spawns the rest on the same pipelines. */
+export interface SlotSet {
+    readonly mat: CuttingMat;
+    readonly kinds: ReadonlyMap<string, SlotKind>;
+    /** The slot's FLAT-CARD pass (K7b, card/card.ts) over its kinds — absent when no registered kind declares a card material. */
+    readonly card?: CardPass;
+}
+/** One slot's passes for `drawFrame` — the ground's own, or the oracle's. A parent carries its nested slots. */
+export interface DrawSlot {
+    readonly mat: CuttingMat;
+    readonly present?: Presentation | undefined;
+    /** BARE: no mat is drawn — the hand's slot (D4b) lays its one object over a frame that is already there. */
+    readonly bare?: boolean | undefined;
+    /** Layers laid on the mat before everything (the calendar's). */
+    readonly underlays?: readonly Underlay[] | undefined;
+    /** The slot's kinds, prepared (its `SlotSet.kinds`): an object's kind names its stratum and its pass. */
+    readonly kinds: ReadonlyMap<string, SlotKind>;
+    /** The slot's objects in paint order — only their kinds matter to the draw: each kind's records are counted along them. */
+    readonly objects?: readonly {
+        readonly kind: string;
+    }[] | undefined;
+    /**
+     * The FLAT CARDS (K7b): each object's card in the card pass's list this frame (`route[i]`, −1 = its kind draws it) — a run of cards
+     * is one draw whatever kinds it interleaves. Absent: every object is its kind's.
+     */
+    readonly card?: {
+        readonly pass: CardPass;
+        readonly route: Int32Array;
+    } | undefined;
+    /** Nested slots, each drawn right after the object `at` names (MINIMAT.md §3) — one that names no object here draws over them all. */
+    readonly children?: readonly {
+        readonly at: number;
+        readonly slot: DrawSlot;
+    }[] | undefined;
+    /** What the slot's grid did this frame. */
+    readonly stats: GridStats;
+}
+/** A slot at opacity 0 draws nothing: "source over" with alpha 0 leaves every pixel as it was. */
+export declare const visible: (p: Presentation | undefined) => boolean;
+/**
+ * The root slot's passes: the mat's (made first — every kind's pass is made on it) and every registered
+ * kind's, made in parallel on the root's mat, in registration order. Names must be unique and strata known.
+ * Shared by the ground and the Node oracle.
+ */
+export declare function createSlotSet(device: GPUDevice, format: GPUTextureFormat, mat: CuttingMat, programs: readonly KindProgram[]): Promise<SlotSet>;
+/** Slots beyond the root, spawned on first use and reused every frame: `reset()` then `acquire()` per slot the frame needs. */
+export declare class SlotPool {
+    private readonly slots;
+    private used;
+    private readonly root;
+    constructor(root: SlotSet);
+    reset(): void;
+    /** The next slot: on first use its mat spawned from the root's, then every registered kind's pass on that mat, in registration order. */
+    acquire(): SlotSet;
+    /** Slots spawned so far — the churn instrument. */
+    get size(): number;
+    dispose(): void;
+}
+/**
+ * Draw one slot into an open render pass: scissored to its portal (nothing
+ * outside it is shaded), skipped outright at opacity 0 — the mat, the layers on
+ * it, then the objects stratum by stratum: within a stratum in paint order, one
+ * `drawRange` per RUN of one kind (each kind counting its own records), the run
+ * cut after an object with a live inside — the inside over its face (restoring
+ * this slot's scissor), then that object's marks over the inside. Returns
+ * whether it drew.
+ */
+export declare function drawSlot(pass: GPURenderPassEncoder, size: {
+    readonly w: number;
+    readonly h: number;
+}, dpr: number, slot: DrawSlot): boolean;
+/**
+ * Record one frame into an open render pass: the root slot with its nested
+ * slots, and — while a flight is on — the departed slot: through the mini mat
+ * as one tree (`outgoing.at`), or whole, under or over, when the flight is
+ * frozen. Shared with the Node oracle so both hosts draw a frame through the
+ * same code. Returns each slot's grid stats (null = not drawn).
+ */
+export declare function drawFrame(pass: GPURenderPassEncoder, size: {
+    readonly w: number;
+    readonly h: number;
+}, dpr: number, incoming: DrawSlot, outgoing?: (DrawSlot & {
+    readonly order: "under" | "over";
+    readonly at?: number | undefined;
+}) | null): {
+    incoming: GridStats;
+    outgoing: GridStats | null;
+};
+/** What `prepareFrame` hands the draw: the two slots and the counts the stats report. */
+export interface PreparedFrame {
+    readonly incoming: DrawSlot;
+    readonly outgoing: (DrawSlot & {
+        readonly order: "under" | "over";
+        readonly at?: number | undefined;
+    }) | null;
+    readonly portals: number;
+    /** The root's records that will draw, by kind name — every registered kind. */
+    readonly kinds: Readonly<Record<string, number>>;
+    /** What the kinds' caps turned away, by kind name, every slot's (absent: nothing) — `GroundStats.dropped` (D7). */
+    readonly dropped?: Readonly<Record<string, number>>;
+    /** K5a: the tray's specimens, one slot each, prepared — drawn over the board, inside its edge (`drawTray`); absent = none. */
+    readonly tray?: readonly DrawSlot[];
+    /** K5b: what the tray carries, one slot each, prepared — drawn over the drawer, whole (`drawTray`); absent = none. */
+    readonly carried?: readonly DrawSlot[];
+}
+/** Where `prepareFrame` finds a specimen's slot (tray/specimens.ts `TraySlots`): undefined while its kind's pass is being made. */
+export interface TraySlotSource {
+    get(type: string, kind: string): SlotSet | undefined;
+}
+/**
+ * Upload one frame's records into its slots — the root's, each live portal's
+ * (from the pool), the departed desk's — run the mat's wind where its clock
+ * moved, and return the draw tree. Per slot, every registered kind prepares its
+ * own records (the slot's objects of that kind, in paint order), told which of
+ * them carries a live inside. Shared by the ground and the Node oracle. `grid`
+ * is the root's when its inputs name none.
+ */
+export declare function prepareFrame(encoder: GPUCommandEncoder, root: SlotSet, pool: SlotPool, inputs: GroundFrameInputs, grid?: GridConfig, target?: RenderTarget, traySlots?: TraySlotSource): PreparedFrame;
+/**
+ * THE TRAY, drawn (design-017 §5, §8; K5a) — shared by `Ground.render` and the Node oracle: the drawer UNDER its specimens (the dim, its
+ * shadows, the board to its edge, the accessories), each specimen by its own kind through the drawer's face (inside the edge — the rim
+ * laid over them all retired, design-018 §2), their name tags (the marks' pills), then the VEIL over them all at the top (design-018
+ * rev 5: the plain board, whole in the header and fading out over its ramp — what hangs there fades into the board, never see-through
+ * over a hole); then what the tray carries, whole. Shut (p 0) the drawer draws nothing (its pass laid no quad) and only a carried copy
+ * is drawn. Leaves the scissor on the whole view.
+ */
+export declare function drawTray(pass: GPURenderPassEncoder, size: {
+    readonly w: number;
+    readonly h: number;
+}, dpr: number, tray: TrayPass, slots: readonly DrawSlot[] | undefined, marks: MarksPass | null, carried?: readonly DrawSlot[]): void;
+export declare class Ground {
+    readonly device: GPUDevice;
+    readonly surface: Surface;
+    /** The cutting mat — the root slot's; its plates, noise and glyph atlas are every slot's. */
+    readonly mat: CuttingMat;
+    /** The root slot's passes: the mat's and every registered kind's, by name (the registry, in registration order). */
+    readonly root: SlotSet;
+    /** Slots beyond the root — the departed desk's, the live insides of mini mats — spawned on first use. */
+    readonly pool: SlotPool;
+    /** The root's grid when a frame names none. */
+    grid: GridConfig;
+    /** The desk's chrome — stratum 5 (D4a); null when the options named no marks shaders. */
+    readonly marks: MarksPass | null;
+    /** The hand — the focus behind an object in hand and the object over it (D4b); null when the options named no hold shaders. */
+    readonly hold: HoldPass | null;
+    /** The pegboard drawer (design-017, K3); null when the options named no tray shaders. */
+    readonly tray: TrayPass | null;
+    /** The tray's specimens' slots (K5a) — one per specimen, made as the tray first shows each; null with no tray. */
+    readonly traySlots: TraySlots | null;
+    /** The desk copy's cache (D4b): the stamp it was made for and the stats of that frame. */
+    private readonly heldCache;
+    /** How many desk copies the hand has made so far (D4b) — a rig's witness that the blurred desk is made once per settled state. */
+    heldCopies(): number;
+    /** The drops last said, by kind (D7). */
+    private readonly dropSaid;
+    private constructor();
+    static create(opts: GroundOptions): Promise<Ground>;
+    /** The root's pass of the kind registered as `name` (undefined if none) — a host reaches its kind's own API through it: the note's ink pages, the whiteboard's rasters. */
+    pass(name: string): KindPass | undefined;
+    /** Size the canvas to its CSS box; returns the CSS size and dpr the frame should use. (A host may size the canvas itself instead.) */
+    fit(maxDpr?: number): {
+        changed: boolean;
+        width: number;
+        height: number;
+        cssWidth: number;
+        cssHeight: number;
+        dpr: number;
+    };
+    /** Render one frame now. Synchronous submit; the caller owns the cadence. */
+    render(inputs: GroundFrameInputs): GroundStats;
+    /** A kind whose cap turns objects away is an ERROR on the host's console (D7): said when the drop begins and again if it grows. */
+    private said;
+    /** The pool's slots, then the root's kinds in reverse registration order, then the mat. */
+    dispose(): void;
+    /** Make the passes the tray's composite specimens need (K5a — `TraySlots.warm`); `onReady` asks for the frame that shows them. */
+    warmTray(wanted: readonly (readonly [string, string])[], onReady: () => void): void;
+    /** The tray's slots let go of what they make again at their next draw once undrawn a while (D-K6a.3; `TraySlots.idle`) — every tick. */
+    idleTray(): void;
+    /** When `idleTray` next lets a tray layer go (K7a — a time the host registers; ∞ — nothing to let go). */
+    trayIdleAt(): number;
+}
+/** The specimens' name tags this frame (K5a): each label centred under its specimen — below a shelf's plank — in screen px. */
+export declare function tagsOf(tray: TrayFrameInputs | undefined): {
+    readonly label: string;
+    readonly x: number;
+    readonly y: number;
+}[];
+/** The desk copy's cache between held frames (D4b): the `stamp` it was made for (null: none yet), the stats of that frame, and how many copies were ever made (the "once per settled state" witness). */
+export interface HeldCache {
+    stamp: string | null;
+    stats: GroundStats | null;
+    copies: number;
+}
+/** Where a held frame goes: the swap chain's view and size (the ground's surface, or the oracle's target dressed as one). */
+export interface HeldInto {
+    view(): GPUTextureView;
+    size(): {
+        readonly w: number;
+        readonly h: number;
+    };
+}
+/**
+ * A HELD FRAME (design-015 §8; D4b) — shared by `Ground.render` and the Node oracle so both hosts draw it through one code path:
+ *  1. the DESK COPY, only when its `stamp` moved: the frame WITHOUT the held object (the builder left it out), no marks, prepared
+ *     and drawn at half the dpr into the hold pass's half-size target, then blurred — its own encoder, SUBMITTED FIRST: the root's
+ *     passes are about to be prepared again for the hand, and a queue write lands before every later submit, never an earlier one;
+ *  2. the HAND: the one object under the pose's camera, its kind's own pass into a transparent full-size target (no mat — a bare
+ *     slot), the hand's light (the day's by night, as the carry rises);
+ *  3. the FRAME: the desk out of focus (the sharp copy mixed toward the blurred one by the carry, dimmed), then the hand over it
+ *     through the reading light. Two fullscreen draws; the marks stay quiet (the builder hands none).
+ * Returns the desk copy's stats (the frame's objects behind the hand).
+ */
+export declare function renderHeldFrame(device: GPUDevice, hold: HoldPass, root: SlotSet, pool: SlotPool, grid: GridConfig, into: HeldInto, inputs: GroundFrameInputs, held: HeldFrameInputs, cache: HeldCache): GroundStats;

package/dist/types/packages/desk/src/hold/focus.d.ts

@@ -0,0 +1,53 @@
+import { Target } from "../engine/target";
+import type { HoldShaders } from "./shaders";
+/** The pass's knobs: `texel` = (1/w, 1/h of the SOURCE, the Kawase offset in half-texels, 0); `mix` = (the carry e, the dim, the saturate, the brightness). */
+export declare const HoldUniformsStruct: import("../engine").StructDef<"texel" | "mix">;
+/** The dual-Kawase chain's shape: two levels below the half-size copy; the offset per texel of radius. */
+export declare const KAWASE: {
+    readonly levels: 2;
+    readonly offsetPerTexel: 0.25;
+};
+export interface CompositeKnobs {
+    /** The carry amount: how far toward the blurred copy the background goes. */
+    readonly e: number;
+    /** The dim of the desk behind (already scaled by the carry). */
+    readonly dim: number;
+    /** The reading light on the hand (1, 1 by day; toward .62, .82 by night as the carry rises). */
+    readonly saturate: number;
+    readonly brightness: number;
+}
+export declare class HoldPass {
+    private readonly device;
+    private readonly layout;
+    private readonly sampler;
+    private readonly down;
+    private readonly up;
+    private readonly deskPipe;
+    private readonly handPipe;
+    /** The desk's half-size copy, the Kawase levels below it, the blurred copy back at half size, the hand at full size. */
+    readonly desk: Target;
+    readonly blurred: Target;
+    readonly hand: Target;
+    private readonly levels;
+    /** One uniform buffer per draw the chain records (each holds its own texel size and offset). */
+    private readonly knobs;
+    private readonly values;
+    private groups;
+    /** The size the groups were built for — rebuilt when a target resized. */
+    private built;
+    private constructor();
+    /** The four pipelines on `format` (the surface's — every target here is that format too, so one layout serves all). */
+    static create(device: GPUDevice, format: GPUTextureFormat, src: HoldShaders): Promise<HoldPass>;
+    /** Size the targets to the surface (device px): the copies at half, the hand at full. True when any target was remade (its contents gone). */
+    fit(w: number, h: number): boolean;
+    private rebind;
+    private knob;
+    /**
+     * The blur: from the desk copy through the levels and back into `blurred`, at `radiusTexels` (the radius in the copy's
+     * texels: the CSS radius × dpr / 2). Recorded into `encoder` after the copy was drawn; one chain per settled desk.
+     */
+    blur(encoder: GPUCommandEncoder, radiusTexels: number): void;
+    /** The frame: the desk out of focus, then the hand over it in its light — two fullscreen draws into the open pass. */
+    composite(pass: GPURenderPassEncoder, k: CompositeKnobs): void;
+    dispose(): void;
+}

package/dist/types/packages/desk/src/hold/pose.d.ts

@@ -0,0 +1,132 @@
+import type { ObjectRect } from "../kinds/world";
+import { type MatLight } from "../mat/night";
+import type { CameraState } from "../nav/flight";
+/** The hand's numbers (desk.js `HOLD`). Times in ms; `margin`/`top`/`band` CSS px; `blur` CSS px; `narrow` = a phone's width. */
+export declare const HOLD: {
+    readonly inMs: 560;
+    readonly outMs: 440;
+    readonly closeLead: 0.14;
+    readonly openAt: 0.42;
+    readonly blur: 14;
+    readonly blurPhone: 10;
+    readonly dim: 0.08;
+    readonly margin: 56;
+    readonly marginPhone: 16;
+    readonly top: 56;
+    readonly topPhone: 60;
+    readonly band: 72;
+    readonly max: 3;
+    readonly zoomMin: 0.72;
+    readonly zoomMax: 3;
+    readonly narrow: 640;
+    /** The reading light by night (Q-n): the held object keeps its day light, filtered. */
+    readonly light: {
+        readonly saturate: 0.62;
+        readonly brightness: 0.82;
+    };
+    /** The cover's spring in hand (desk.js `COVER`): a palm, not a desk. */
+    readonly cover: {
+        readonly hz: 1.4;
+        readonly zeta: 0.78;
+    };
+    /** The held bar's travel (M1 morph) and its return after the landing. */
+    readonly bar: {
+        readonly travelMs: 340;
+        readonly backMs: 200;
+    };
+};
+export interface HeldViewport {
+    readonly width: number;
+    readonly height: number;
+}
+/** The reading pose's target: where the open extent's centre goes on screen (CSS px), the scale there (CSS px per object unit), one page or the spread. */
+export interface ReadingTarget {
+    readonly cx: number;
+    readonly cy: number;
+    readonly s: number;
+    readonly single: boolean;
+}
+/** A phone's width (desk.js `narrow`). */
+export declare const isNarrow: (vp: HeldViewport) => boolean;
+/**
+ * The reading size (desk.js `heldTarget`): the extent fits the view inside the margins and above the bar's band, never past 3×.
+ * `spread`: the extent is a two-page spread that may open one page at a time — on a portrait phone (W < 0.85·H) it does when
+ * one page reads at least 1.3× larger than the whole spread would; then the RIGHT page is centred (the extent's centre sits a
+ * quarter of its width left of the middle) — or, `face` → 1, the LEFT (D3t-b: the notebook reads page by page; between, the view
+ * glides).
+ */
+export declare function readingTarget(extent: ObjectRect, vp: HeldViewport, spread?: boolean, face?: number): ReadingTarget;
+/** Where the extent lies on screen at rest, under the desk's camera: its centre (CSS px), the scale (the zoom) and the object's turn. */
+export interface HomePose {
+    readonly cx: number;
+    readonly cy: number;
+    readonly s: number;
+    readonly angle: number;
+}
+export declare function homePose(extent: ObjectRect, angle: number, cam: CameraState): HomePose;
+/** The user's facts on the held object (core's `HeldView`). */
+export interface HeldUser {
+    readonly zoom: number;
+    readonly panX: number;
+    readonly panY: number;
+}
+export declare const HELD_USER_REST: HeldUser;
+/** The pose between the desk and the hand: the extent's centre on screen, CSS px per unit, the turn, the carry amount. */
+export interface HeldPose {
+    readonly cx: number;
+    readonly cy: number;
+    readonly s: number;
+    readonly angle: number;
+    readonly e: number;
+}
+/** desk.js `heldPose`: position on the island curve (the caller eases `e`), size in log scale, the tilt let go. */
+export declare function heldPose(home: HomePose, target: ReadingTarget, user: HeldUser, e: number): HeldPose;
+/** The carry amount for the pickup's progress `p` (0 … 1) — the island ease; the put-down runs it backwards from where it was. */
+export declare const carryOf: (p: number) => number;
+/** The pickup's progress at a carry amount — the island ease inverted by bisection (a put-down caught mid-flight, a pinned still). */
+export declare function progressOf(e: number): number;
+/** The focus behind the hand and the light on it at a carry amount (the builder's and the oracle's ONE reading of §8's numbers). */
+export interface HeldFocus {
+    /** The radius the ONE blur is made at, CSS px (14; a phone's 10). */
+    readonly blur: number;
+    /** The desk's dim behind, by the carry (8 % at the top). */
+    readonly dim: number;
+    /** The reading light on the hand (Q-n): 1, 1 by day; toward saturate .62 · brightness .82 by night as the carry rises. */
+    readonly filter: {
+        readonly saturate: number;
+        readonly brightness: number;
+    };
+    /** The hand's own light: the desk's by day; by night the day's mixed in by the carry. */
+    readonly light: MatLight;
+}
+export declare function heldFocus(e: number, vp: HeldViewport, theme: {
+    readonly name: string;
+    readonly matLight: MatLight;
+}): HeldFocus;
+/**
+ * The held slot's CAMERA (the pose IS a camera) and the factor a kind with height must reach by rising. The object's rect centre
+ * lies `offset` (its own units, unturned) from its extent's centre; the pose turns that offset by its angle and puts the extent's
+ * centre at (pose.cx, pose.cy), so the rect's centre lands at P − R(angle)·offset·s. A flat kind's camera zooms to `pose.s` and
+ * grows nothing; an `eye` kind keeps the desk's zoom when the pose is larger (grow = pose.s / zoom ≥ 1, the rise does the rest)
+ * and zooms out with the camera when the pose is smaller (a book picked up from very close: grow 1).
+ */
+export declare function heldCamera(pose: HeldPose, rect: ObjectRect, extent: ObjectRect, deskZoom: number, eye: boolean, vp: HeldViewport): {
+    readonly cam: CameraState;
+    readonly grow: number;
+};
+/**
+ * The held object's frame ON SCREEN (what the pose seam publishes, core's `HeldScreenFrame`): the shown extent's centre and half
+ * extents, CSS px, its scale. `single`: one page alone — the right (`face` 0), the left (`face` 1), a glide between (D3t-b).
+ */
+export declare function heldFrame(pose: HeldPose, extent: ObjectRect, single: boolean, face?: number): {
+    readonly cx: number;
+    readonly cy: number;
+    readonly hx: number;
+    readonly hy: number;
+    readonly s: number;
+};
+/** The focus behind the hand: the blur radius (CSS px) and the dim at a carry amount. */
+export declare const focusOf: (e: number, vp: HeldViewport) => {
+    readonly blur: number;
+    readonly dim: number;
+};

package/dist/types/packages/desk/src/hold/shaders.d.ts

@@ -0,0 +1,9 @@
+import type { ShaderPart } from "../engine/shader";
+export interface HoldShaders {
+    readonly entry: ShaderPart;
+}
+export interface HoldShaderText {
+    readonly hold: string;
+}
+export declare const HOLD_SHADER_FILES: Record<keyof HoldShaderText, string>;
+export declare function holdShaders(t: HoldShaderText): HoldShaders;

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

@@ -0,0 +1,18 @@
+import { type World } from "../../../core/src/index";
+import type { DeskEditor, TextPart } from "../kit/editor";
+/** design-007's claim marker (`@ice/dom` KEYBOARD_CLAIM_ATTR — the desk may not import dom): the keymap cedes to a focused claim. */
+export declare const KEYBOARD_CLAIM_ATTR = "data-canvas-keyboard";
+/** The editor's own marker — the one element the desk puts in screen space for text. */
+export declare const EDITOR_ATTR = "data-desk-editor";
+export interface DeskEditorOptions {
+    /** The host's container (screen space): the editor goes in it, the taps are read on it. */
+    readonly container: HTMLElement;
+    readonly world: World;
+    /** The text parts the registered objects declared, in registration order (asked at each tap — the layer fills them after the drivers). */
+    readonly parts: () => readonly TextPart[];
+    /** A session ends after this long without input, ms (1000). */
+    readonly idleMs?: number;
+    /** Ask the desk for a frame. */
+    readonly wake: () => void;
+}
+export declare function createDeskEditor(opts: DeskEditorOptions): DeskEditor;

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

@@ -0,0 +1,9 @@
+export { deskLayer, type DeskLayerContext, type DeskLayerFactory, type DeskLayerHandle, type DeskLayerOptions, type DeskLayerPerf, type DeskLayerStatus, type DeskTrayDoor, type MatPin, type SelectionSource, type TrayAnchor } from "./layer";
+export type { SelectionAnchor } from "../compose/marks";
+export { surface, type Surface } from "./surface";
+export { createDeskEditor, type DeskEditorOptions, EDITOR_ATTR, KEYBOARD_CLAIM_ATTR } from "./editor";
+export { type FaceSpec, inkRaster, type InkRaster, type InkRasterOptions, PEN_FACES, penFaces } from "./ink";
+export { decodePicture } from "./picture";
+export { DEFAULT_MAT_CONFIG, GLYPH_PAD, GLYPHS, type GlyphAtlasMeta, type MatConfig, type PlateName, type RulerConfig } from "../mat/layout";
+export type { GridConfig } from "../mat/grid";
+export { type ObjectSprings, SPRINGS } from "../kit/springs";

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

@@ -0,0 +1,18 @@
+import type { TextRaster } from "../kit/raster";
+import { type FaceSpec } from "../kit/text";
+export { type FaceSpec, PEN_FACES } from "../kit/text";
+/** The desk's faces with the app's files: `{ caveat: url, "caveat-bold": url, kalam: url }` → face specs. */
+export declare function penFaces(urls: Readonly<Record<string, string>>): Readonly<Record<string, FaceSpec>>;
+export interface InkRasterOptions {
+    /** The faces by name — `penFaces({ … })` for the desk's own. */
+    readonly faces: Readonly<Record<string, FaceSpec>>;
+    /** The document whose font set the faces join (the window's). */
+    readonly document?: Document;
+}
+export interface InkRaster extends TextRaster {
+    /** Load a face (once): resolves whether the browser can draw it. `metrics()` asks for this itself. */
+    load(face: string): Promise<boolean>;
+    /** Is the face loaded (and drawable)? */
+    ready(face: string): boolean;
+}
+export declare function inkRaster(opts: InkRasterOptions): InkRaster;