@vibecook/ice 0.11.0 → 0.14.0

package/dist/types/packages/desk/src/kinds/world.d.ts

@@ -0,0 +1,429 @@
+import type { Component, Entity, HeldToolDef, Relation, Tag, WidgetType, World } from "../../../core/src/index";
+import type { TypingDocs } from "../docs";
+import type { RasterBudget } from "../engine/budget";
+import type { RasterQueue } from "../engine/rasters";
+import type { KindPass, KindProgram, StratumName } from "../kind";
+import type { DeskEditor, TextPart } from "../kit/editor";
+import type { ChildShape, FaceLaw, InsideView } from "../kit/inside";
+import type { Lamp } from "../kit/light";
+import type { LendHost, Lent, ServiceKey, Services } from "../kit/services";
+import type { Rect } from "../kit/nav";
+import type { GridConfig, View } from "../kit/view";
+import type { MarkFrame } from "../marks/layout";
+import type { GroundTheme, Palette, ThemeName } from "../theme";
+/**
+ * What the builder hands a CONTAINER kind's `record` about its inside (D2b): the bounds of the
+ * children's rects (`content`, null = empty — the arrival is the empty desk's), the inside's
+ * embedding and camera under this slot's camera (`view`, from the kind's own `face` — the
+ * flight's numbers, so the face's far LOD and the live inside agree to the bit), and the children
+ * as their kinds chip them (`chips`, in the inside's own units — the kind maps them through `view.M`).
+ */
+export interface InsideContext {
+    readonly content: Rect | null;
+    readonly view: InsideView | null;
+    readonly chips: readonly ChildShape[];
+}
+/** An object's rect on its desk, world units, CENTRED — converted from ICE's top-left `Position` + `Size` by the builder, once. */
+export interface ObjectRect {
+    readonly cx: number;
+    readonly cy: number;
+    readonly w: number;
+    readonly h: number;
+}
+/**
+ * What moves, per entity — the builder's springs, each 0..1 and SNAPPED to its target when settled
+ * (the B7 trap: a spring that never quite lands keeps the desk awake forever). `lift` follows the
+ * `Grab` fact (held), `hover` the local mouse pointer's exact hit (the B9 pairing — never the
+ * dead-band `Targets`), `fade` the delete ghost (1 alive … 0 gone). `ring` is ALWAYS 0 from the
+ * builder: the kinds' own selection ring retired at D4a (the marks draw the selection) and its
+ * spring went at D6; the Node oracle alone hands a ring, for the baseline against the prototype.
+ */
+export interface ObjectFlux {
+    readonly lift: number;
+    readonly hover: number;
+    readonly ring: number;
+    readonly fade: number;
+}
+/** A kind's answer to "what is under this world point" — the widget itself (`content`/`frame`), a part, or nothing. */
+export type ObjectHit = "content" | "frame" | (string & {});
+/**
+ * A slot of the held bar for a kind in hand (design-015 §8 — "the kind's tools take the middle"): core's `HeldToolDef`
+ * (D3t-a — widget/held-tools.ts), declared by the kind and carried onto its widget type by `defineObject`, so the one
+ * keymap and the one bar reach it through the engine: a `mode` (the tool in hand, core's `HeldTool`), an `action` (an op),
+ * or — no `kind` — declared only (dim; a later slice builds it). `glyph` names one of the bar's.
+ */
+export type { HeldToolDef } from "../../../core/src/index";
+/**
+ * The kind's OPENING (design-015 §8; D4b) — what "pick it up" means for this kind. `extent`: the OPEN rect in the object's
+ * own desk units, centred as its rect is and UNTURNED (the builder turns it with the object): a notebook's spread (twice the
+ * case's width, left of the spine), a board's face, a calendar's month — what the reading size fits into the view. `pose`: how
+ * the reading size is reached — `camera` (a flat kind, the default: the held slot's camera maps the extent to the held rect
+ * and the kind draws at rest) or `eye` (a thing with height: the camera keeps the desk's zoom and the kind RISES toward the
+ * desk eye by `ctx.held.grow`). `openness`: how far the kind's own open motion has come (0 shut … 1 open) — the put-down
+ * flies home once it is under 0.35 and lands once under 0.02 (absent: 0, a kind with no motion of its own). `spread`: a
+ * two-page extent that opens one page at a time on a portrait phone (Q-p); `page`: which of its two is in view there — 0 the
+ * right (the default) … 1 the left, flux the view glides by (D3t-b: the notebook reads page by page). `tools`: the held bar's
+ * slots (D3t-a: live — a mode or an action each); `tool`: the mode in hand when it is picked up, from its props (default: the first mode);
+ * `swatches`: the colour a slot shows instead of its glyph (the board's four inks — the product's palette, through the look).
+ */
+export interface OpenBinding {
+    extent(ctx: Pick<ObjectContext, "rect" | "props">): ObjectRect;
+    readonly pose?: "camera" | "eye";
+    openness?(ctx: Pick<ObjectContext, "entity" | "local">): number;
+    readonly spread?: boolean;
+    page?(ctx: Pick<ObjectContext, "entity" | "local">): number;
+    readonly tools?: readonly HeldToolDef[];
+    tool?(props: Readonly<Record<string, unknown>>): string;
+    swatches?(look: unknown): Readonly<Record<string, string>>;
+}
+/**
+ * What the builder hands the object IN HAND (D4b, beside its flux): the carry amount `e` (0 on the desk … 1 in hand — the
+ * lift's height, the focus behind), whether it should be OPEN (past 42 % of the pickup going up; never going down), the
+ * factor an `eye` kind must reach by rising (1 for a flat kind — the camera did it), and `snap` (a still: the open motion
+ * sits at its target, no spring).
+ */
+export interface HeldContext {
+    readonly e: number;
+    readonly open: boolean;
+    readonly grow: number;
+    readonly snap: boolean;
+}
+/**
+ * Everything a kind is handed for one entity, one frame. The props are the widget type's group
+ * fields as the builder cached them (refreshed from the change journal, never re-read per frame —
+ * the 09-23 profile); `look` is what the kind's own `theme()` made of the palette in force.
+ */
+export interface ObjectContext {
+    readonly entity: Entity;
+    readonly rect: ObjectRect;
+    readonly props: Readonly<Record<string, unknown>>;
+    readonly flux: ObjectFlux;
+    /** The kind's `theme(palette, name)` result for the theme in force; `undefined` when the kind declares none. */
+    readonly look: unknown;
+    readonly theme: GroundTheme;
+    /** The desk's one lamp — the gobo projector on the desk plane (`lampOf`), world units. */
+    readonly lamp: Lamp;
+    /** The slot's camera and attachment (CSS px) with the device pixel ratio. */
+    readonly view: View & {
+        readonly dpr: number;
+    };
+    /** The slot's grid: the mat's config (its vinyl, its gobo, its rulers) and the lattice's fade-in. */
+    readonly grid: GridConfig;
+    /** The frame's dt, SECONDS (the engine's clamped dt). */
+    readonly dt: number;
+    /**
+     * A per-entity asset the HOST pinned through the builder (`DeskBuilder.pin`) — `undefined` = none.
+     * Flux, never a world fact. (The note's committed raster moved into its kind's `local` at D2c.)
+     */
+    readonly asset?: unknown;
+    /**
+     * The kind's OWN state on this desk — what `ObjectKind.local()` made for it (the note's writing:
+     * its layouts, its rasters' residency, the caret, the wipe — D2c); `undefined` when the kind keeps
+     * none. Flux, never a world fact; the builder threads it and tells it when an entity is forgotten.
+     */
+    readonly local?: unknown;
+    /** A container's inside, for its `record` (D2b): the content bounds, the view through its face, the children's chips. Absent = not a container, or `resolve`. */
+    readonly inside?: InsideContext;
+    /** The object is IN HAND (D4b): its carry amount, its open target, the eye kind's rise. Absent = on the desk. */
+    readonly held?: HeldContext;
+}
+/** What a desk hands a kind's `local()` (D2c): its ROOT pass once the ground is made, the SERVICES lent on this desk, and the builder's doors. */
+export interface KindHost {
+    /** The kind's root pass on this desk's ground; `undefined` before `Ground.create` resolves and after the layer ends. */
+    pass(): KindPass | undefined;
+    /**
+     * THE SERVICES (K8a, kit/services.ts — an open registry by key): what the host lends (its text raster `TEXT_RASTER`, the picture
+     * decoder `PICTURE_DECODER`, the app's byte store `BLOB_STORE`, anything in `deskLayer({ services })`) and what any object's DOM
+     * half lends (`ObjectHost.lend` — the desk calendar's `PRINT_RASTER`): `use(key)` answers it, or undefined when nothing on this
+     * desk lends it (in Node the oracle pins committed rasters and tiles). Absent: a bare host (a test) — no services at all.
+     * D-K8a.1: the desk's OWN doors stay fields of this host — `pass`, `children`, `drawn`, `budget`, `rasters`, `remake`, `wake`: the
+     * builder's word, its budget, its queue and its loop, made by the desk for each kind and never lent, replaced or taken by a kind.
+     */
+    use?<T>(key: ServiceKey<T>): T | undefined;
+    /** An object's DATA children (D3w, design-015 §5.1 — a board's strokes, a pad's events and pins); absent = none (a test, the oracle). */
+    readonly children?: DataChildren | undefined;
+    /**
+     * The builder's word on what is DRAWN (D6, persistent records): the paint rank of `e` in the last build's root slot, undefined when it
+     * was not drawn there. A kind's residency reads it instead of counting its own `record` calls — those come only when a record is
+     * remade. Absent (a bare host, the oracle): the kind counts its own.
+     */
+    readonly drawn?: ((e: Entity) => number | undefined) | undefined;
+    /**
+     * THE RASTER BUDGET (D6, engine/budget.ts): one ledger for every raster a kind keeps as a cache of its data — a board's ink, a
+     * notebook page's CPU raster, the calendar's tiles. A kind charges what it makes with a way to let it go and answers `keeps` for
+     * what is on screen; the host trims the ledger once a tick. Absent: nothing is counted or evicted.
+     */
+    readonly budget?: RasterBudget | undefined;
+    /**
+     * THE FRAME'S RASTER QUEUE (K6b, engine/rasters.ts): a raster the zoom asks again (a new band, a new density) or an object come on
+     * screen holding none is ASKED here, with a priority, and made in the queue's turn under the frame's budget — the kind draws what
+     * it has meanwhile. Absent (a bare host, the oracle): a kind rasters in the frame that asks, as before.
+     */
+    readonly rasters?: RasterQueue | undefined;
+    /** `e`'s record remade at the next build (K6b — a raster the queue laid: the record says where its ink is), the desk woken. */
+    readonly remake?: ((e: Entity) => void) | undefined;
+    /**
+     * THE KIND'S WAKE (K7a — registered wakes): something arrived OUTSIDE a frame that changes how the kind draws (a picture
+     * decoded, a tile printed, a detail fetched): the kind is ticked at the next frame, and a sleeping loop wakes for it. A
+     * kind never polls for what an arrival can tell it. Absent (a bare host, the oracle): its tick is asked every frame.
+     */
+    readonly wake?: (() => void) | undefined;
+}
+/**
+ * An object's DATA children as its kind reads them (D3w): entities `ChildOf` the object, never members of the desk's
+ * paint order — the `stamp` turns over whenever the set or its order changes (strata's order stamp), and `rows` are the
+ * children's values of one component, in sibling order (the oldest stroke first).
+ */
+export interface DataChildren {
+    stamp(parent: Entity): number;
+    rows<T>(parent: Entity, c: Component<T>): readonly T[];
+    /** The children holding `c`, each with its value, in sibling order (D3t-c — a pad's events by entity: the line you point at is one). */
+    entries?<T>(parent: Entity, c: Component<T>): readonly {
+        readonly entity: Entity;
+        readonly value: T;
+    }[];
+    /** A child's one edge `r` — the entity it names (D3t-c — a pin's note), undefined when it names none. */
+    target?(child: Entity, r: Relation): Entity | undefined;
+}
+/**
+ * A kind's own state on ONE desk (D2c) — made once per desk by `ObjectKind.local`, threaded by the
+ * builder into every context of the kind as `ctx.local`, and told the frame's clock and each entity's
+ * end, so a kind can keep per-entity residency (a raster, a decoded picture) outside the world.
+ */
+export interface KindLocal {
+    /** Once a tick, before the draw, with the frame's clock (ms): does the state want a frame now (a wipe, a blink, an asset landed)? */
+    tick?(now: number): boolean;
+    /**
+     * WHEN THE KIND IS NEXT LIVE (K7a — registered wakes, design-015 §2.4): asked after each of its ticks, on the same clock —
+     * `now` or before: the next frame (a motion runs: a wipe, a roll, a flight, ink drying); a later time: then (the caret's
+     * next blink, a layer let go, midnight); `Infinity`: never on its own — only when the desk's facts move, an input comes, or
+     * the kind calls `KindHost.wake`. A loop at rest ticks a kind only when it is due: nothing is polled. Absent while `tick`
+     * is declared: due every frame — a kind that never said keeps the desk awake.
+     */
+    due?(now: number): number;
+    /**
+     * What has LANDED on `e` so far — a count the kind moves when something arrives that changes how the object looks with no fact
+     * of its own moving (a picture decoded, ink replayed, a raster laid, tiles drawn, a wipe ended), never for a running motion (the
+     * ink drying, a wipe running, a pen). The builder reads it after it remakes a restless kind's record: a desk object's that moved
+     * remakes the blurred desk copy behind the hand (D7 — its stamp saw only the facts). Absent: nothing lands.
+     */
+    landed?(e: Entity): number;
+    /** The entity left this desk for good — its ghost faded, it left the frame, the desk was reset: free what it held. */
+    forget?(e: Entity): void;
+    /**
+     * The entity is drawn LIFTED off the desk's order and away from its facts (D3t-a — a print in a hand, flicked, gliding or
+     * flying home): the builder paints it with the carried set, above its siblings, and the pick asks it first where it is drawn.
+     */
+    lifted?(e: Entity): boolean;
+    /**
+     * Entities this kind's state says are NOT drawn this frame, of any kind (D3t-c — a note stuck to a day of a month the calendar is
+     * not showing): the builder draws none of them and the pick answers `outside` for them. Asked after `tick`, before the draw.
+     */
+    veils?(): ReadonlySet<Entity>;
+    /** The kind's word on a raster it charged to the budget (D6): true = on screen this frame, never evicted now. */
+    keeps?(key: string): boolean;
+    dispose?(): void;
+}
+/** What a kind's `rung` reads (K6b): the object as the builder holds it, its SLOT's zoom (an inside's is its host's face's) and the dpr, and its kind's state on this desk. */
+export interface RungContext {
+    readonly entity: Entity;
+    readonly rect: ObjectRect;
+    readonly props: Readonly<Record<string, unknown>>;
+    readonly zoom: number;
+    readonly dpr: number;
+    /** The kind's `local()` on this desk (`KindLocal`); undefined when it keeps none. */
+    readonly local: unknown;
+    /**
+     * The object's distance from the view's centre, screen px — the ORDER of what a kind asks at the new zoom (a raster at another band,
+     * of the frame raster queue: `KindHost.rasters`). The rung returned never reads it: it is where the camera is.
+     */
+    readonly px: number;
+}
+/**
+ * A kind, whole: the render half the ground registers (`KindProgram` — name, stratum, the pass)
+ * and the world half the builder and the pick source drive. `G` is the kind's resolved geometry,
+ * `R` the record its pass draws, `L` its look (what `theme()` returns).
+ */
+export interface ObjectKind<G = unknown, R = unknown, L = unknown> extends KindProgram<R> {
+    /**
+     * How far the kind's drawing may reach PAST its rect, world units — its shadow, its lift, its
+     * tilt's overhang: the builder's cull margin, and the pick source's pad (`FramePickSource.pad`).
+     */
+    readonly reach: number;
+    /** Components and tags the kind reads beyond its own props (the builder adds them to its change journal). */
+    readonly reads?: {
+        readonly components?: readonly Component[];
+        readonly tags?: readonly Tag[];
+    };
+    /**
+     * The record reads the view's ZOOM or dpr CONTINUOUSLY (a far-LOD lattice whose lines fade with every step of the zoom) and nothing
+     * else of the camera (design-015 §4.3; D6): the builder remakes it whenever they move and reuses it across a pan. A record that
+     * reads them only in steps says so with `rung` instead. Absent (and no `rung`) = the record is the facts' and the flux's alone. A
+     * composite kind is remade every frame it is drawn whatever it says (its `resolve` steps its own motion).
+     */
+    readonly rezoom?: boolean;
+    /**
+     * The record reads the view's zoom or dpr ONLY THROUGH A RUNG (K6b, design-016 §6 — a raster's band): this object's rung under
+     * its slot's zoom, and the builder remakes the record only when that moves — a zoom within a rung remakes and writes nothing.
+     * Asked of a drawn object whenever its slot's zoom or the dpr moved since its rung was last read, never on a pan; it reads the
+     * zoom, never where the camera is. Wins over `rezoom`. A kind whose raster the frame queue makes asks for it HERE (ordered by
+     * `ctx.px`) and answers the rung of what it HOLDS — the record shows that until the queue lays the new one (`KindHost.remake`).
+     */
+    rung?(ctx: RungContext): number;
+    /** A host's LIVE law (D5a — the dev panel's door, `handle.tuneLaw`): the kind resolves under it from the next build. Absent, its law is fixed. */
+    tune?(law: unknown): void;
+    /** The entity's geometry this frame, from its rect, its props and its flux — the prototype's `resolve*`. */
+    resolve(ctx: ObjectContext): G;
+    /** The record the kind's pass draws for that geometry — the prototype's instance. */
+    record(geometry: G, ctx: ObjectContext): R;
+    /** The CPU mirror on the SAME geometry the pass drew: the part under a world point, or null for a miss. */
+    hit(geometry: G, wx: number, wy: number): ObjectHit | null;
+    /**
+     * A CONTAINER kind's FACE as drawn — the window its inside shows through, in the desk's units
+     * (the mini mat: the sheet inset by its printed border, through its springs). The builder builds
+     * the live inside through it and the nav geometry seam answers core's nav with it (design-015 §9).
+     * Absent = the kind holds no desk.
+     */
+    face?(geometry: G): Rect | undefined;
+    /**
+     * A CONTAINER kind's face law (K8a, kit/inside.ts `FaceLaw`): its face's corner radius, the most chips its face draws and the
+     * finishes it draws them in — the container's own numbers, never the kit's. Absent on a container: square, no chips.
+     */
+    readonly faceLaw?: FaceLaw;
+    /**
+     * The kind's CHIP — its far impostor inside a container's face (MINIMAT.md §5; K8a: any kind's): the child as a `ChildShape` in
+     * ITS desk's units, in a finish the container draws — a note as paper with its writing greeked, a mini mat as vinyl with its
+     * border, a plugin kind as either or a finish of a plugin container's; `null` = nothing to chip. Absent = the kind has no chip
+     * (the oracle's prints): inside a far face it is not drawn.
+     */
+    chip?(geometry: G, ctx: ObjectContext): ChildShape | null;
+    /** The grid a CONTAINER kind's inside draws with (the mini mat: the desk's fade-in, the mat in its vinyl, no rulers). Absent = the root's. */
+    insideGrid?(ctx: Pick<ObjectContext, "props" | "look">, root: GridConfig): GridConfig;
+    /**
+     * The silhouette the desk's MARKS go around (D4a — the brackets, a member's ticks, several's union, the tape):
+     * the geometry's centre, half extents AS DRAWN (the lift's scale in), turn and corner, world units. Absent =
+     * the rect, square to the mat (`rectFrame`).
+     */
+    frame?(geometry: G): MarkFrame;
+    /** The kind's colours from the host's palette, per theme — the look `record` reads (`ctx.look`). */
+    theme?(palette: Palette, name: ThemeName): L;
+    /** The kind's own state on one desk (`ctx.local`) — made by the host once per desk; absent = none (D2c). */
+    local?(host: KindHost): KindLocal;
+    /** The kind's OPENING (design-015 §8, D4b): what picking it up means. Absent = the object never opens (`ops.open` refuses it). */
+    readonly open?: OpenBinding;
+}
+/**
+ * What the host lends a kind's DRIVERS (D7 #5, D-D7-A.3 — the hand onto the kind's state: a pen, a carry, a leaf, the
+ * calendar's writing and marks). A kind declares them in `defineObject` (`ObjectDef.drivers`); the host makes them once per
+ * desk, generically, and ticks them before the kinds' clocks — a third-party openable kind with held tools gets its driver
+ * the same way. Everything a driver needs comes through here: the world, the document's doors (docs.ts), the kind's own
+ * local and look, the builder's word (geometry as drawn, a held point into the world, the hand), the builder's give.
+ */
+export interface KindDriverHost {
+    readonly world: World;
+    /** The document's doors — `current()`, the writer's gate, the commit door, the history doors (docs.ts). */
+    readonly docs: TypingDocs;
+    /** This kind's own local (`ObjectKind.local`), if it declared one. */
+    readonly local: KindLocal | undefined;
+    /** This kind's look as the desk composed it (the swatches a pen draws in). */
+    readonly look: () => unknown;
+    /** Is `e` an object of this kind? */
+    readonly isKind: (e: Entity) => boolean;
+    /** Is `e` an object of the kind named — undefined when that kind is not on this desk. */
+    readonly kind: (name: string) => ((e: Entity) => boolean) | undefined;
+    /**
+     * Does `e`'s object type PROVIDE the key (K8a — `defineObject({ provides })`: the calendar asks after what is `PINNABLE`)? Undefined
+     * when no object type on this desk provides it. A kind asks after a capability, never after another kind's name.
+     */
+    readonly provides: (key: string) => ((e: Entity) => boolean) | undefined;
+    /** The builder's word: an object's geometry as drawn (the kind's `G`), a held-screen point into its world, the hand. */
+    readonly geometryOf: (e: Entity) => unknown;
+    readonly heldToWorld: (e: Entity, x: number, y: number) => readonly [number, number] | undefined;
+    readonly hand: () => {
+        readonly entity: Entity;
+        readonly landing: boolean;
+        readonly frame: {
+            readonly cx: number;
+            readonly cy: number;
+            readonly s: number;
+        };
+    } | undefined;
+    /** The builder's give for a drag the kind refuses (a taped print meets the tape — D4a). */
+    readonly refused: (e: Entity) => void;
+    /** Ask the desk for a frame (something landed, a mark moved). */
+    readonly wake: () => void;
+}
+/** A kind's driver on one desk: ticked once a frame before the kinds' clocks; idle when it has nothing to follow (D7 #14). */
+export interface KindDriver {
+    follow(now: number): void;
+    /** Nothing to follow this frame — nothing in hand, no press, no rest or roll owed: the host may skip `follow` (the idle-tick budget). Absent: never skipped. */
+    idle?(): boolean;
+    dispose?(): void;
+}
+/**
+ * An object's DOM HALF (K4b, design-016 §5 · K-L2) — what its kind needs of the browser, DECLARED with the object as its drivers
+ * are (`defineObject({ host })`): the desk layer builds what the registered objects declare and never finds a half by type or
+ * names a kind. Three moments, in the layer's order:
+ * - `lend`, before any kind's local: SERVICES only a browser can make, each under its key (K8a, kit/services.ts — the desk
+ *   calendar lends `PRINT_RASTER`, in the host's hand, none without a text raster), handed what is lent so far (the host's, then
+ *   the objects' before it) and the desk's wake for a service whose work lands later (`LendHost.wake` — K7a's sleeping loop steps);
+ *   any kind's world half `use`s them (`KindHost.use`), a DOM half too (`ObjectDomHost.use`);
+ * - `text`, once the drivers are made: the object's TEXT PARTS (K8a, kit/editor.ts `TextPart`) — the parts of its objects that
+ *   LEASE the desk's ONE editor: a part with a `tap` the desk routes every tap to (the note's body), a part without one its own
+ *   half leases at event time (the desk calendar's day line). The editor is the DESK's (desk/host/editor.ts): no kind makes it;
+ * - `mount`, after that: a screen-space half, handed the editor like every half (the desk calendar's days and pen lease it). A
+ *   mounted half is ended by what it joins — the calendar's by the calendar's driver.
+ */
+export interface ObjectHost {
+    readonly lend?: (host: LendHost) => readonly Lent[];
+    readonly text?: (host: ObjectDomHost) => readonly TextPart[] | undefined;
+    readonly mount?: (host: ObjectDomHost) => void;
+}
+/**
+ * What the host lends an object's DOM half (K4b): the screen-space container, the object the half was declared on and ITS
+ * driver, its kind's look, and the builder's word — a driver host's fields, and the few a browser half adds.
+ */
+export interface ObjectDomHost {
+    /** The host's container (screen space): a half's elements go in it, its taps are read on it. */
+    readonly container: HTMLElement;
+    readonly world: World;
+    /** The document's doors (docs.ts) — a half that writes, writes through them. */
+    readonly docs: TypingDocs;
+    /** The services lent on this desk (K8a — `KindHost.use`'s registry): a DOM half uses them by key as a world half does. */
+    readonly use: Services["use"];
+    /** The desk's ONE focused editor (K8a — the desk makes it; every kind leases it: kit/editor.ts `EditorLease`). */
+    readonly editor: DeskEditor;
+    /** The object the half was declared on — its compiled widget type (its props' groups). */
+    readonly object: WidgetType;
+    /** The object's own driver (`defineObject({ drivers })`), if it declared one. */
+    readonly driver: KindDriver | undefined;
+    /** The object's kind's look as the desk composed it. */
+    readonly look: () => unknown;
+    /** The builder's word: an object's geometry as drawn, the hand, a held-screen point into its world. */
+    readonly geometryOf: KindDriverHost["geometryOf"];
+    readonly hand: KindDriverHost["hand"];
+    readonly heldToWorld: KindDriverHost["heldToWorld"];
+    /** Ask the desk for a frame. */
+    readonly wake: () => void;
+    /** A writing session ends after this long without input, ms (`DeskLayerOptions.idleMs`); absent: the half's own. */
+    readonly idleMs?: number | undefined;
+}
+/** The strata a kind may declare — re-exported beside the contract for a kind's author. */
+export type { StratumName };
+/** ICE's top-left `Position` + `Size` → the centred rect every law reads: the ONE conversion. */
+export declare function rectOf(pos: {
+    readonly x: number;
+    readonly y: number;
+}, size: {
+    readonly w: number;
+    readonly h: number;
+}): ObjectRect;
+/** An object's marks' silhouette when its kind draws none of its own: the rect, square to the mat, no corner. */
+export declare const rectFrame: (r: ObjectRect) => MarkFrame;
+/** The flux of an object at rest: down, unhovered, unselected, whole. */
+export declare const FLUX_REST: ObjectFlux;
+/** A prop read with a type and a default — the kinds' one door to `ctx.props`. */
+export declare const numberProp: (props: Readonly<Record<string, unknown>>, name: string, fallback: number) => number;
+export declare const stringProp: (props: Readonly<Record<string, unknown>>, name: string, fallback: string) => string;
+/** Is this opaque widget binding a desk kind — the world half present beside the program? */
+export declare function isObjectKind(binding: unknown): binding is ObjectKind;

package/dist/types/packages/desk/src/kit/arrays.d.ts

@@ -0,0 +1,88 @@
+/** The level of a `w × h` chain whose both sides first fit `side` (0 when the whole chain does). */
+export declare function tailBase(w: number, h: number, side: number): number;
+/** Bytes of `levels` of a chain from `w × h` at `texel` bytes a texel. */
+export declare function chainBytes(w: number, h: number, levels: number, texel?: number): number;
+/**
+ * THE LAYER ALLOCATOR: an array's layers handed out lowest first and taken back; `take` says the capacity the array must hold
+ * for the layer it hands out (doubling, from `first`, to the device's `max`) — null when it holds no more. K9 R2: `shrunk` says
+ * the capacity the layers in use let the array fall back to — halves, and nothing at all when none is in use.
+ */
+export declare class Layers {
+    readonly first: number;
+    readonly max: number;
+    private free;
+    private next;
+    capacity: number;
+    constructor(first?: number, max?: number);
+    take(): {
+        readonly layer: number;
+        readonly capacity: number;
+    } | null;
+    give(layer: number): void;
+    get used(): number;
+    /** The highest layer in use (−1 when none): what a smaller array must still hold. */
+    get highest(): number;
+    /**
+     * The capacity an array holding these layers may shrink to (K9 R2): halved while fewer than a QUARTER of it is in use and the
+     * highest layer in use fits the half — down to `first`; 0 when none is in use; the current capacity when it cannot shrink.
+     */
+    shrunk(): number;
+    /** The allocator's word after the array was remade at `capacity` (from `shrunk()`): the layers past it are forgotten. */
+    shrinkTo(capacity: number): void;
+}
+/** The plain format an `-srgb` one is viewed as for a copy (the bytes pass unchanged); a plain format is its own. */
+export declare const plainFormat: (f: GPUTextureFormat) => GPUTextureFormat;
+export interface LayerArrayOptions {
+    /** The label every array is made with (`photo/thumbnails`) — the memory ledger's row. */
+    readonly label: string;
+    readonly format: GPUTextureFormat;
+    /** The layers' side, texels (square); every layer holds its full mip chain. */
+    readonly side: number;
+    /** Layers at the first growth (then doubling). */
+    readonly first?: number;
+}
+/** One kind's array of layers on one device: its texture (null before the first layer), the allocator, the fill. */
+export declare class LayerArray {
+    readonly side: number;
+    readonly mips: number;
+    readonly format: GPUTextureFormat;
+    private readonly device;
+    private readonly label;
+    private readonly layers;
+    private tex;
+    /** The texture's layers (kept here: a fake device's texture has no count of its own). */
+    private cap;
+    /** Bumped whenever the texture is remade (a bind group holding its view must be made again). */
+    version: number;
+    /** The fill's pipeline, made on the first fill — labelled with the array's own name, so the profiler counts its passes as the kind's. */
+    private fillPipe;
+    constructor(device: GPUDevice, opts: LayerArrayOptions);
+    /** The array (null before its first layer). */
+    get texture(): GPUTexture | null;
+    /** Layers in use; the array's capacity. */
+    get used(): number;
+    get capacity(): number;
+    /** What the array weighs on the device, every layer of its capacity with its chain (the GPU ledger's row). */
+    get bytes(): number;
+    /** What the layers IN USE weigh (K9 R2: the budget's resident charge — the capacity's slack is the ledger's to show, bounded by `give`'s shrink). */
+    get usedBytes(): number;
+    /** A layer for a new object (the array grown — its old layers copied — when it must be); null when the device holds no more. */
+    take(): number | null;
+    /**
+     * A layer given back — and the array SHRUNK when fewer than a quarter of its layers are in use and the ones in use fit the
+     * half (K9 R2: an array never shrank before, so its charge survived a document switch): remade at half, its low layers copied;
+     * let go entirely when none is in use. The version moves as on a growth — a holder rebinds its view.
+     */
+    give(layer: number): void;
+    /**
+     * Layer `layer`'s every level from `src`'s chain: level `base + m` at the origin, its edge carried to the layer's; a level past
+     * the chain's end takes its last. `src` must allow the plain view of its format (`viewFormats`) when that format is `-srgb`.
+     */
+    fill(src: GPUTexture, srcMips: number, layer: number, base: number, encoder?: GPUCommandEncoder): void;
+    /** A `2d-array` view of the whole array — or of `blank` (a 1 × 1 × 1 stand-in the caller keeps) before its first layer. */
+    view(blank: GPUTexture): GPUTextureView;
+    destroy(): void;
+    /** The array made again at `capacity` layers — the old one's layers copied, as many as both hold — and the old destroyed. */
+    private remake;
+    private pipeline;
+}

package/dist/types/packages/desk/src/kit/blobs.d.ts

@@ -0,0 +1,40 @@
+import { type ServiceKey } from "./services";
+/** A blob as the store holds it: its bytes and its media type (`image/png`, `RGBA_TYPE`, …). */
+export interface StoredBlob {
+    readonly bytes: Uint8Array<ArrayBuffer>;
+    readonly type: string;
+}
+/** The app's content-addressed byte store (D-D12): the desk names a blob by its hash; keeping the bytes is the app's. */
+export interface BlobStore {
+    /** Keep `bytes` (idempotent by content); resolves to their hash — the name a print's `blob` prop carries. */
+    put(bytes: Uint8Array<ArrayBuffer>, type: string): Promise<string>;
+    /** The blob under a hash, or undefined when the store has none (a peer's picture not arrived yet, a hash from another desk). */
+    get(hash: string): Promise<StoredBlob | undefined>;
+}
+/** A picture ready for the pass: raw RGBA rows, or a source the device copies from (a browser's `ImageBitmap`) — closed once uploaded. */
+export type DecodedPicture = {
+    readonly kind: "rgba";
+    readonly bytes: Uint8Array<ArrayBuffer>;
+    readonly width: number;
+    readonly height: number;
+} | {
+    readonly kind: "source";
+    readonly source: unknown;
+    readonly width: number;
+    readonly height: number;
+    close?(): void;
+};
+/** The host's decoder for an encoded blob, scaled so its long side is at most `max` texels; undefined when it cannot. */
+export type PictureDecoder = (blob: StoredBlob, max: number) => Promise<DecodedPicture | undefined>;
+/** The app's byte store as a desk SERVICE (K8a, kit/services.ts — `deskLayer({ blobs })` lends it): `host.use?.(BLOB_STORE)`. */
+export declare const BLOB_STORE: ServiceKey<BlobStore>;
+/** The host's picture decoder as a desk SERVICE (K8a — the layer lends `decodePicture` in a browser): `host.use?.(PICTURE_DECODER)`. */
+export declare const PICTURE_DECODER: ServiceKey<PictureDecoder>;
+/** Raw RGBA8 rows, row-major, no header — the one media type the desk decodes itself (its size is the print's `width` × `height`). */
+export declare const RGBA_TYPE = "image/x-ice-rgba";
+/** The name a blob goes by: SHA-256 over its bytes, lowercase hex. */
+export declare function hashBytes(bytes: Uint8Array<ArrayBuffer>): Promise<string>;
+/** The reference store: every blob in a Map, for the life of the page. */
+export declare function createMemoryBlobStore(): BlobStore & {
+    size(): number;
+};

package/dist/types/packages/desk/src/kit/book.d.ts

@@ -0,0 +1,2 @@
+export declare const NbUniforms: import("../engine").StructDef<"view" | "eye" | "light" | "shadow" | "shadow2" | "paper" | "rule" | "cloth" | "castCol" | "select" | "ruleInk" | "ring">;
+export declare const NbBook: import("../engine").StructDef<"size" | "light" | "model" | "inv" | "lamp" | "sh" | "page" | "open" | "look" | "foot" | "recv" | "inkPage" | "inkLayer" | "col0" | "col1" | "col2" | "col3" | "col4" | "col5" | "col6" | "col7">;