@vibecook/ice 0.11.0 → 0.14.0

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

@@ -0,0 +1,103 @@
+import type { Entity } from "../../../core/src/index";
+/**
+ * Where the textarea stands while lent (container px): its box's top-left and size BEFORE any turn, the size its text is laid
+ * at, and — for a turned part (a note stuck at its tilt) — the turn about the box's centre, the padding, the line height and
+ * whether lines wrap. Absent: unturned, no padding, one line the box's height, no wrap (a day's line).
+ */
+export interface EditorPlace {
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+    readonly fontPx: number;
+    /** The turn about the box's centre, radians — the editor is placed translate · rotate · translate (never a scale, never a matrix). */
+    readonly angle?: number;
+    /** The text's inset from the box's edges, px. */
+    readonly pad?: number;
+    /** The line height, px (default: the box's height — one line). */
+    readonly lineHeight?: number;
+    /** Lines wrap (a note's body) or run on (a day's line — default). */
+    readonly wrap?: boolean;
+    /** The face the platform lays the text in (the caret's arrows by line): the editor's own (the desk's hand) unless the part says. */
+    readonly font?: {
+        readonly family: string;
+        readonly weight: number;
+    };
+}
+/**
+ * A LEASE on the ONE editor (D3t-c; K8a — any kind's): while lent, the textarea's value, keys, caret and blur are the lease's, and
+ * it says where the textarea stands; another lease, a blur, `release`, or `live()` answering false ends it (`ended`).
+ */
+export interface EditorLease {
+    /** The TEXT PART this lease writes — its kind's declared `TextPart.part` ("note.body", "calendar.line"): what `lease()` names. */
+    readonly part?: string;
+    /** The textarea's accessible name while lent ("write on the note"). */
+    readonly label?: string;
+    /**
+     * The value the textarea holds — asked when the lease begins and each frame after, so a write the world made between sessions
+     * (a peer's, an undo) reaches the platform's field; `null`: keep the field's own (a session is open — the field is the truth).
+     */
+    value(): string | null;
+    /** The platform's value after an input event. */
+    input(value: string): void;
+    /** A key the lease takes: true — handled (the editor prevents its default, so the keymap stands down). */
+    keydown(ev: KeyboardEvent): boolean;
+    /** The caret moved (a selection change, a tap, a value the world moved): its index. */
+    caret(index: number): void;
+    /** Where the textarea stands — null keeps it where it was. */
+    place(): EditorPlace | null;
+    /** 1 s without input (never mid-IME): a session's end; the focus stays. */
+    idle(): void;
+    /** The lease is over (a blur, another lease, `release`, `live()` false). */
+    ended(): void;
+    /** Asked each frame while lent, before the value: false lets the lease go (its object was deleted, or left the frame by a nav cut). */
+    live?(): boolean;
+}
+/** THE ONE EDITOR (the desk's service since K8a — `DeskLayerHandle.editor()`, `ObjectDomHost.editor`): lent, never owned by a kind. */
+export interface DeskEditor {
+    readonly element: HTMLTextAreaElement;
+    /** Lend the editor (D3t-c): a lease holding it ends first; the textarea takes focus, its value the lease's, the caret at `caret` (the end by default). */
+    lend(lease: EditorLease, caret?: number): void;
+    /** End the lease (only `lease`'s, when named). */
+    release(lease?: EditorLease): void;
+    /** The lease holding the editor, if any. */
+    lease(): EditorLease | undefined;
+    /** End whatever lease holds it (the editor hidden, the focus given back). */
+    blur(): void;
+    /** After each draw: the lease's `live` and value asked, the textarea placed where the lease says. */
+    follow(): void;
+    /** Where the editor's box stands on screen (container px): its centre, size and turn — null while hidden. */
+    placement(): {
+        readonly cx: number;
+        readonly cy: number;
+        readonly w: number;
+        readonly h: number;
+        readonly angle: number;
+    } | null;
+    dispose(): void;
+}
+/**
+ * A TAP the desk read on its container (DOM-at-event-time, design-007 §2 — a press and release within the drag slop, the primary
+ * button, no modifier): its world point and the object the pointer EXACTLY hit — the interaction stack's own answer. `found`
+ * false: the pointer is gone (a touch lifted before the click) and a part may look for itself; `hit` undefined with `found`: the
+ * pointer hit nothing, or an object is in hand (a tap in hand is the hand's).
+ */
+export interface TextTap {
+    readonly wx: number;
+    readonly wy: number;
+    readonly found: boolean;
+    readonly hit: Entity | undefined;
+}
+/**
+ * A kind's TEXT PART (K8a — declared with its object, `defineObject({ host: { text } })`): a part of its objects that takes the
+ * ONE editor. `part` names it ("note.body"); a part with `tap` is routed every TAP by the desk — it answers the lease the tap
+ * takes (the editor is lent to it, the caret where the tap put it) or undefined (not its object; refused). A part without `tap`
+ * is leased by its kind's own DOM half at event time (the desk calendar's day line: a day selected).
+ */
+export interface TextPart {
+    readonly part: string;
+    tap?(t: TextTap): {
+        readonly lease: EditorLease;
+        readonly caret?: number;
+    } | undefined;
+}

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

@@ -0,0 +1,37 @@
+import type { CameraState, Viewport } from "./nav";
+export interface DeskEye {
+    /** The eye's foot on the desk: the view's centre, world units. */
+    readonly ex: number;
+    readonly ey: number;
+    /** How far up it stands, world units. */
+    readonly h: number;
+    readonly zoom: number;
+    /** The viewport, CSS px. */
+    readonly vw: number;
+    readonly vh: number;
+}
+/** The eye for a camera: over the view's centre, `k` view-diagonals up, never nearer than `min`. */
+export declare function eyeOf(cam: CameraState, vp: Viewport, law: {
+    readonly k: number;
+    readonly min: number;
+}): DeskEye;
+/** A world point (z up) → CSS px on the screen. */
+export declare function project(e: DeskEye, x: number, y: number, z: number): readonly [number, number];
+/** CSS px → the desk point under it (z = 0): the ortho camera's own inverse. */
+export declare function deskAt(e: DeskEye, sx: number, sy: number): readonly [number, number];
+/** The world point at height z that lands on the desk point (dx, dy) — along the eye's ray. */
+export declare function unproject(e: DeskEye, dx: number, dy: number, z: number): readonly [number, number];
+/** The eye's ray through a desk point: origin (the eye) and direction (toward the desk point, unnormalised). */
+export declare function rayThrough(e: DeskEye, dx: number, dy: number): {
+    readonly o: readonly [number, number, number];
+    readonly d: readonly [number, number, number];
+};
+/**
+ * The clip-space numbers the shader's `nb_clip` reads: x, y are 2·zoom·(p − E)/viewport (y up),
+ * w = (H − z)/H, and z is a perspective depth over distances from the eye in [near, far] —
+ * `near` above the tallest thing a book can reach, `far` just under the desk.
+ */
+export declare function eyeValues(e: DeskEye, reach?: number): {
+    eye: [number, number, number, number];
+    view: [number, number, number, number];
+};

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

@@ -0,0 +1 @@
+export { carryOf, HOLD, readingTarget } from "../hold/pose";

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

@@ -0,0 +1,26 @@
+export * from "./arrays";
+export * from "./blobs";
+export * from "./book";
+export * from "./editor";
+export * from "./eye";
+export * from "./hold";
+export * from "./inside";
+export * from "./layer";
+export * from "./light";
+export * from "./mesh";
+export * from "./mips";
+export * from "./nav";
+export * from "./paper-tex";
+export * from "./physics";
+export * from "./place";
+export * from "./print";
+export * from "./raster";
+export * from "./sdf";
+export * from "./seeds";
+export * from "./services";
+export * from "./springs";
+export * from "./strokes";
+export * from "./text";
+export * from "./uniform";
+export * from "./view";
+export * from "./wgsl";

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

@@ -0,0 +1,116 @@
+import type { Box } from "../lattice/lod";
+import type { SlotLight } from "../mat/layout";
+import { type CameraState, type FitBand, type Flight, type PortalAffine, type Rect, type Viewport } from "../nav/flight";
+import { type PortalClip, type Presentation } from "../nav/portal";
+import type { RGB } from "../theme";
+/** A container's inside under the host camera (MINIMAT.md §3–§5): what `insideView` answers — ALWAYS, past the gate or not. */
+export interface InsideView {
+    /** The embedding: inside → host (`host = o + inside · s`) — the flight's own. */
+    readonly M: PortalAffine;
+    /** The inside's arrival camera — what its lattice is DRESSED for (PORTAL.md §9). */
+    readonly arrival: CameraState;
+    /** The camera the inside renders under at the host's camera: the enter flight's c0 at the cut. */
+    readonly cam: CameraState;
+    /** The face on screen: the live inside's clip. */
+    readonly clip: PortalClip;
+    /** The gate's answer (0..1): the live inside's presence — 0 = the face is the far LOD alone. */
+    readonly presence: number;
+    /** The live inside's box on the attachment. */
+    readonly box: Box;
+}
+/**
+ * The FINISH a container's face draws a child's chip in (K8a — open: until K8a a chip was a `ChipKind`, `"paper" | "mat"`, the two
+ * built-ins' own names, so no plugin kind could have one): a name among the container's `FaceLaw.finishes` — the mini mat draws
+ * `"paper"` (a sheet in the chip's colour, its writing greeked) and `"vinyl"` (grained, its frame line at `margin`) — and a plugin
+ * container draws its own. A chip names one, or several in preference order; the first the container draws wins, and a chip the
+ * container draws none of is not drawn (the builder counts it: `BuildWork.unchipped`) — never a finish it did not ask for.
+ */
+export type ChipFinish = string;
+/** The two finishes the kit names — a chip's shared vocabulary (a note's `paper`, a mini mat's `vinyl`); a container may draw more. */
+export declare const PAPER_FINISH: ChipFinish;
+export declare const VINYL_FINISH: ChipFinish;
+/** One child as the face's far LOD draws it, in the CHILD's frame (the inside's world). */
+export interface ChildShape {
+    /** Its finish (`ChipFinish`) — or finishes, in preference order; the builder hands the container the one it draws. */
+    readonly finish: ChipFinish | readonly ChipFinish[];
+    readonly cx: number;
+    readonly cy: number;
+    /** Half extents, the tilt (radians), the corner radius — the child's own. */
+    readonly hx: number;
+    readonly hy: number;
+    readonly angle: number;
+    readonly radius: number;
+    /** Its colour: the paper's, or the vinyl's. */
+    readonly colour: RGB;
+    /** How far it stands off the face, child units — what its contact shadow is cast from. */
+    readonly height: number;
+    /** A note's writing, GREEKED: the pen's colour, the text's left edge and em (note units from the sheet's top-left), and each line's baseline and width. */
+    readonly writing?: {
+        readonly ink: RGB;
+        readonly x0: number;
+        readonly em: number;
+        readonly lines: readonly {
+            readonly y: number;
+            readonly width: number;
+        }[];
+    } | undefined;
+    /** A mini mat's printed border, child units. */
+    readonly margin?: number | undefined;
+}
+/**
+ * A CONTAINER kind's FACE LAW (K8a — the container's own, declared on its kind as `ObjectKind.faceLaw`; until K8a `FACE_RADIUS` and
+ * `FACE_CHIPS_MAX` were the kit's, the mini mat's numbers imposed on every container): the corner its face clips its inside by (the
+ * live inside, the far LOD, a flight through it — `clipOf(face, radius, cam)`), the most chips its face draws, and the chip finishes
+ * it draws them in. Absent on a kind with a `face`: square, and no chips.
+ */
+export interface FaceLaw {
+    readonly radius: number;
+    readonly chips: number;
+    readonly finishes: readonly ChipFinish[];
+}
+/** The finish a container draws a chip in: the chip's first that the container draws, or undefined — none (the chip is not drawn). */
+export declare function finishOf(finish: ChipFinish | readonly ChipFinish[], drawn: readonly ChipFinish[]): ChipFinish | undefined;
+/**
+ * The same view from a FACE rect and its corner alone (D2b; the corner the container's own since K8a — `FaceLaw.radius`): what a
+ * kind's `face(geometry)` hands the builder, so any container kind's inside is built by the one law — the mini mat's `faceClip` is
+ * `clipOf(faceOf(G), its radius, cam)`, so the numbers are its `insideView`'s to the bit.
+ */
+export declare function insideViewOfFace(K: Rect, radius: number, content: Rect | null, cam: CameraState, vp: Viewport, fit?: FitBand, gate?: readonly [number, number]): InsideView | null;
+/** The live inside's presentation at rest: through its face, its mat whole, its objects at the gate's answer (MINIMAT.md §5). */
+export declare const insidePresent: (view: InsideView) => Presentation;
+/**
+ * The presentations of a flight through a mini mat's face: `flightOpacity` as ever, and — on an
+ * ENTER — the arriving desk's objects at the gate's answer for the face as it is this frame, so
+ * a mini mat entered from its far LOD grows through the gate on the way in and its chips give way
+ * to its objects as it does (the arriving desk's mat is whole from the cut: the same lattice as
+ * the face's, by the same lamp). An exit keeps its objects whole and lands on whatever the face
+ * shows at the landing (the old landing fade). A frozen flight is a dissolve.
+ */
+/** What the flight helpers read of a flight: its kind, its progress, whether it is frozen — the prototype's `Flight` or core's `NavTransition` alike. */
+export type FlightState = Pick<Flight, "kind" | "p" | "frozen">;
+export declare function flightPresent(f: FlightState, clip: PortalClip | undefined, gate?: readonly [number, number]): {
+    readonly incoming: Presentation;
+    readonly outgoing: Presentation;
+};
+/**
+ * When a flight hands the lamp over, as progress windows. ENTER hands it over once the departed
+ * desk starts to go (flightOpacity: it holds to 0.3) — until then the frame IS the rest frame
+ * under the departed camera; an EXIT hands it back in its first half — from then on the frame IS
+ * the rest frame under the flying camera, the inside lit as a mini mat's inside is.
+ */
+export declare const HANDOVER: {
+    readonly enter: readonly [0.3, 1];
+    readonly exit: readonly [0, 0.5];
+};
+/**
+ * The LAMPS a flight hands between the two desks (MINIMAT.md §4). At rest a mini mat's inside is
+ * lit by the desk the mini mat lies on; a desk the camera is on, by its own lamp. ENTER: the
+ * arriving desk starts under the departed desk's lamp (`outCam` — at the cut, the portal's own
+ * light, bit for bit) and ends under its own. EXIT: the departed desk starts under its own and
+ * ends under the arriving desk's — the lamp its mini mat's inside is lit by at rest. A frozen
+ * flight is two whole desks under their own lamps.
+ */
+export declare function flightLights(f: FlightState, cam: CameraState, outCam: CameraState): {
+    readonly incoming?: SlotLight;
+    readonly outgoing?: SlotLight;
+};

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

@@ -0,0 +1,159 @@
+import type { KindPass, RenderTarget, SlotContext } from "../kind";
+import type { View } from "../lattice/lod";
+import type { MatPass } from "./view";
+import type { ComposeOptions } from "../engine/shader";
+import type { ShaderText } from "../shaders";
+/** The composite's entry: a resolved, premultiplied layer laid over what the ground drew (the layered kinds share it). */
+export declare const LAYER_COMPOSITE_FILE = "kit/composite.wgsl";
+/**
+ * The program that lays a layer — its entry, from the host's shader text, after the kit's view block and portal chain: the layer is
+ * laid through the slot's chain (design-018 §4), so a layered object keeps the kit's contract as one — the tray's feather included.
+ */
+export declare function layerComposite(text: ShaderText): ComposeOptions;
+/** The composite's bindings (every layered kind's): the resolved layer, its box's origin, and the slot's view block (its chain). */
+export declare function layerCompositeLayout(device: GPUDevice, label: string): GPUBindGroupLayout;
+/** A device-px rect: x, y, width, height. */
+export type Rect4 = readonly [number, number, number, number];
+/**
+ * The attachment a slot's view names, device px: what every host sizes its canvas to — `surface().fit`, the reflector's
+ * `attach.resize`, the oracle's target — `max(1, round(css · dpr))`. A layer is made at this size, so its texel is the pixel.
+ */
+export declare const attachmentOf: (v: View & {
+    readonly dpr: number;
+}) => {
+    readonly w: number;
+    readonly h: number;
+};
+/** Two device-px rects intersected; a width or height of 0 when they do not meet. */
+export declare function clip(a: Rect4, b: Rect4): Rect4;
+/** What a layered kind asks of its pass: the layer recorded into an encoder, laid by one draw, its screen box. */
+export interface LayerPass {
+    layer(encoder: GPUCommandEncoder, size: {
+        readonly w: number;
+        readonly h: number;
+    }, dpr: number): boolean;
+    composite(pass: GPURenderPassEncoder, scissor?: Rect4 | null): void;
+    readonly screenBox: Rect4 | null;
+    /** The render target the next prepare is for (D7 — `SlotContext.target`): a pass keeps the held desk copy's state apart. */
+    use?(target: RenderTarget): void;
+    /** The hold is over: the copy's state given back. */
+    endHold?(): void;
+    /** The records its last prepare turned away at its cap (D7). */
+    readonly dropped?: number;
+    /** K6a (D-K6a.3): its frame layer's targets are made (at the first object drawn)… */
+    readonly layerMade?: boolean;
+    /** …was one of its objects drawn within `ms` (and when last: `performance.now()`'s ms — the release's due, K7a)… */
+    drawnWithin?(ms: number): boolean;
+    readonly lastDrawn?: number;
+    /** …and let them go (made again at the next object drawn). */
+    releaseLayer?(): void;
+    dispose(): void;
+}
+/**
+ * The part of a layered kind that is the same for both: ROOT ONLY — a spawned slot's pass holds nothing and draws nothing (its
+ * `pass` is null; D-D18: a notebook or a pad is never drawn in a mini mat's inside or a flight's departed desk) — the layer recorded
+ * after its pass prepared, and laid ONCE over the whole range the ground hands it (a kind registered with `composite: true`: the
+ * ground draws it as one run after the rest of its stratum).
+ */
+export declare abstract class LayeredKind<R, P extends LayerPass> implements KindPass<R> {
+    /** The root slot's pass — the host's door to its own API (the ink, the tiles, the law); null in a spawned slot (root only). */
+    readonly pass: P | null;
+    /** The slot's scissor this frame, device px — the layer is laid inside it and it is given back after (null: nothing to lay). */
+    private within;
+    /** How many records `prepare` was handed: the whole range the layer lays. */
+    private handed;
+    constructor(pass: P | null);
+    abstract spawn(mat: MatPass): KindPass<R>;
+    /** The pass's own prepare for this slot (its records, eye and look); returns the count that will draw. */
+    protected abstract prepareOwn(pass: P, s: SlotContext, records: readonly R[]): number;
+    prepare(encoder: GPUCommandEncoder, s: SlotContext, records: readonly R[]): number;
+    /** The layer over the frame: once, for the whole range [0, count) — one draw lays every object; a part of it cannot be drawn from one layer. */
+    drawRange(pass: GPURenderPassEncoder, first: number, end: number): void;
+    endHold(): void;
+    /**
+     * Let this slot's layer go when none of its objects was drawn within `ms` (D-K6a.3 for a slot the host keeps beyond the root — the
+     * tray's specimen, K5a; the ROOT's layer goes by its kind's own tick). Made again at the next object drawn.
+     */
+    idle(ms: number): void;
+    /** When `idle(ms)` next lets the layer go — its last object drawn + `ms` (K7a: the host's registered TIME wake); ∞ with none. */
+    idleAt(ms: number): number;
+    dropped(): number;
+    dispose(): void;
+}
+/** A box's targets grow and shrink by this many device px a side, so a pan's jitter never makes them again (K7a). */
+export declare const BOX_STEP = 256;
+/**
+ * A layered kind's TARGETS AT ITS SCREEN BOX (K7a — design-016 §6): the 4× colour and depth and their resolve sized to the box
+ * its objects cover on the attachment (rounded up to BOX_STEP, at most the attachment), never the canvas — a notebook's layer at
+ * 2400 × 1600 was 136 MB for a book a tenth of the screen. The layer is drawn through a viewport shifted by the box's ORIGIN over
+ * the whole attachment, so the pixel grid is the attachment's (a fragment lands on the pixel it always did, the target's texel
+ * `pixel − origin`); the composite reads the texel at its pixel less the origin (its uniform, binding 1 beside the layer). What a
+ * fragment samples BY its position adds `origin` back (the passes carry it in their knobs). The rasteriser is not exactly
+ * translation-invariant in floating point: a handful of edge samples and 1-LSB interpolants move against a canvas-sized layer
+ * (D-K7a.4 — 13 golden scenes re-blessed).
+ */
+export declare class BoxTargets {
+    private readonly device;
+    private readonly label;
+    private readonly layoutComp;
+    private readonly samples;
+    private readonly view;
+    msaa: GPUTexture | null;
+    depth: GPUTexture | null;
+    resolve: GPUTexture | null;
+    compGroup: GPUBindGroup | null;
+    /** The box's top-left on the attachment, device px (the layer's texel 0, 0). */
+    readonly origin: [number, number];
+    /** The targets' size as made, device px (0 × 0: none). */
+    readonly size: {
+        w: number;
+        h: number;
+    };
+    private originBuf;
+    private readonly sent;
+    private readonly next;
+    /** What the layer the targets hold was drawn from — its pass's signature at the draw (K7a); NaN: nothing drawn since made. */
+    private readonly drawnFrom;
+    /** …and the content it read, by value (the knobs, the records, the view block), with each copy's length. */
+    private readonly drawnBytes;
+    private readonly drawnLen;
+    /** `view`: the slot's view block (`MatPass.view`) — the composite lays the layer through its portal chain (`layerCompositeLayout`). */
+    constructor(device: GPUDevice, label: string, layoutComp: GPUBindGroupLayout, samples: number, view: GPUBuffer);
+    /** The targets are made (a layer holds device memory). */
+    get made(): boolean;
+    /**
+     * Fit the targets to `box` [x0, y0, x1, y1] (device px) on an `attach` of its size: made when none are or the box outgrew them,
+     * made smaller when they are more than four times its area — never larger than the attachment; the origin written for the
+     * composite when it moved.
+     */
+    fit(box: readonly [number, number, number, number], attach: {
+        readonly w: number;
+        readonly h: number;
+    }): void;
+    /**
+     * Begin the layer's pass into the fitted targets: cleared, the viewport the whole `attach` shifted by the origin, the scissor the
+     * box — `box` [x0, y0, x1, y1] as fitted.
+     */
+    begin(encoder: GPUCommandEncoder, label: string, attach: {
+        readonly w: number;
+        readonly h: number;
+    }, box: readonly [number, number, number, number]): GPURenderPassEncoder;
+    /**
+     * The layer the targets hold was drawn from exactly `sig` and `bytes` (K7a — every input of its draw the same since: the pass's
+     * numbers — its resources' generation, what it lists, the box — and the CONTENT the draw read, compared by value: this target's
+     * knobs and records as prepared, the slot's view block. By content, not by version: a held frame's desk copy writes the shared
+     * buffers between two of the hand's frames, and the hand's layer is still what they held): it may be laid again undrawn.
+     */
+    holds(sig: ArrayLike<number>, bytes: readonly Uint8Array[]): boolean;
+    /** The layer was drawn from `sig` and `bytes` (copied; the copies grow once and are reused). */
+    drew(sig: ArrayLike<number>, bytes: readonly Uint8Array[]): void;
+    /** The targets let go, the origin's uniform with them (the next `fit` makes them again). */
+    release(): void;
+    dispose(): void;
+}
+/**
+ * How long a layered kind's frame targets (its 4× layer, its resolve; the notebook's shadow maps) stand with none of its objects
+ * drawn before the kind lets them go (K6a, design-016 §6 — made again at the next one drawn): render targets at the canvas's size,
+ * never a cache the raster budget holds (D-K6a.3).
+ */
+export declare const LAYER_IDLE_MS = 5000;

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

@@ -0,0 +1,3 @@
+export { type Lamp, lampOf } from "../mat/lamp";
+export { DAY_LIGHT, linear, type MatLight } from "../mat/night";
+export type { ProjectorSpec, Quat, Vec3 } from "../mat/projector";

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

@@ -0,0 +1,29 @@
+export declare const VERTEX_FLOATS = 16;
+export declare const VERTEX_BYTES: number;
+/** Flags: a face seen from both sides (a sheet in the air, the spine). */
+export declare const FLAG_TWO_SIDED = 1;
+/** A growable vertex + index writer. */
+export declare class MeshWriter {
+    v: Float32Array;
+    ix: Uint32Array;
+    nv: number;
+    ni: number;
+    readonly min: [number, number, number];
+    readonly max: [number, number, number];
+    constructor(vcap?: number, icap?: number);
+    reset(): void;
+    vert(px: number, py: number, pz: number, nx: number, ny: number, nz: number, u: number, v: number, mat: number, page: number, flags: number, ao: number, sx: number, sy: number, e0?: number, e1?: number): number;
+    tri(a: number, b: number, c: number): void;
+    quad(a: number, b: number, c: number, d: number): void;
+    /** A grid's quads: `cols` × `rows` vertices laid out row-major from `first`. */
+    gridQuads(first: number, cols: number, rows: number): void;
+}
+/** A built mesh: views onto the writer's arrays (copy before the next build) and the local bounds. */
+export interface BuiltMesh {
+    readonly vertices: Float32Array;
+    readonly indices: Uint32Array;
+    readonly vcount: number;
+    readonly icount: number;
+    readonly min: readonly [number, number, number];
+    readonly max: readonly [number, number, number];
+}

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

@@ -0,0 +1,2 @@
+export declare const mipCount: (w: number, h: number) => number;
+export declare function generateMips(device: GPUDevice, texture: GPUTexture): void;

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

@@ -0,0 +1,2 @@
+export { arrivalCamera, type CameraState, FIT, type FitBand, type Flight, flightOpacity, type NavKind, outgoingCamera, type PortalAffine, portalAffine, type Rect, type Viewport, visibleRect } from "../nav/flight";
+export { boxOfPortal, clipOf, PORTAL_GATE, type PortalClip, portalPresence, type Presentation } from "../nav/portal";

package/dist/types/packages/desk/src/kit/paper-tex.d.ts

@@ -0,0 +1,5 @@
+export declare const PAPER_TEX = 256;
+/** How much of the tooth's slope one step of B/A encodes (the decode multiplies back). */
+export declare const TOOTH_SCALE = 48;
+/** The texture's bytes (deterministic: the same page everywhere, every run). */
+export declare function paperTexture(seed?: number): Uint8Array<ArrayBuffer>;

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

@@ -0,0 +1,44 @@
+export declare const PHYSICS: {
+    /** How far a HELD note rises (§7's lift, as a height), and the scale it reads at (§7's 1.05, kept). */
+    readonly lift: {
+        readonly height: 12;
+        readonly scale: 1.03;
+    };
+    /**
+     * The contact shadow on the mat: Gaussian-blurred coverage of the sheet cast along the lamp's
+     * ground direction by its height — σ and alpha at contact, σ growing per unit of height, the
+     * alpha a held note casts, and the slope's cap (a note far from the lamp keeps a finite shadow).
+     */
+    readonly shadow: {
+        readonly sigma: 2.2;
+        readonly alpha: 0.36;
+        readonly sigmaPerUnit: 0.9;
+        readonly alphaHeld: 0.4;
+        readonly slopeMax: 2.2;
+    };
+    /**
+     * A SLAB's shadow (a notebook, a whiteboard, a mini mat): the note's penumbra swept down its height, with a contact
+     * term at its base (the tree-shadow design system's paper elevation, mat.css `--lift-1`) — theme.ts `BOOK.shadow` until K4a.
+     */
+    readonly slab: {
+        readonly penumbra: {
+            readonly sigma0: 2.2;
+            readonly sigmaPerHeight: 0.9;
+            readonly alpha: 0.36;
+        };
+        /** The contact term: σ, alpha, and the gap (world units) it has faded over once the object floats. */
+        readonly contact: {
+            readonly sigma: 1.1;
+            readonly alpha: 0.3;
+            readonly reach: 2.5;
+        };
+        readonly slopeMax: 2.2;
+    };
+    /** The lamp's fill on a face turned away from it; how far past a flat face one turned toward it may brighten. */
+    readonly light: {
+        readonly ambient: 0.5;
+        readonly cap: 1.35;
+    };
+    /** The sole-selection ring (DESIGN.md §7), CSS px, in `--vf-select`. */
+    readonly ring: 1.5;
+};

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

@@ -0,0 +1,44 @@
+import type { Lamp } from "./light";
+export interface Placement {
+    readonly cx: number;
+    readonly cy: number;
+    /** Radians in the mat's plane; positive turns clockwise on screen. */
+    readonly angle: number;
+    /** Units off the mat. */
+    readonly lift: number;
+    /** Radians about the book's own x (its head dips for +) and y (its fore-edge dips for +) axes, through its middle `zc` up. */
+    readonly tiltX: number;
+    readonly tiltY: number;
+    readonly zc: number;
+}
+/** A rigid transform: 3×3 rotation (row-major) and a translation. */
+export interface Rigid {
+    readonly r: readonly number[];
+    readonly t: readonly [number, number, number];
+}
+export declare function rigidOf(p: Placement): Rigid;
+export declare function toWorld(g: Rigid, x: number, y: number, z: number): [number, number, number];
+export declare function dirToWorld(g: Rigid, x: number, y: number, z: number): [number, number, number];
+export declare function toLocal(g: Rigid, x: number, y: number, z: number): [number, number, number];
+export declare function dirToLocal(g: Rigid, x: number, y: number, z: number): [number, number, number];
+/** Column-major 4×4 (WGSL's mat4x4f) of a rigid transform. */
+export declare function matrixOf(g: Rigid): Float32Array;
+/** The unit direction toward the lamp from a desk point, the ground slope capped (a book far from the lamp keeps a finite shadow). */
+export declare function lampDir(lamp: Lamp, x: number, y: number, slopeMax: number): [number, number, number];
+/**
+ * The shadow map's frame for a book: an orthographic view along the light, square, fitted to
+ * the book's world-space box (grown by `pad`). Out: the world → clip matrix (x, y in −1…1, z
+ * 0 nearest the lamp … 1), the world size of one texel at `res`, and the depth range (world).
+ */
+export declare function lightFrame(L: readonly [number, number, number], lo: readonly [number, number, number], hi: readonly [number, number, number], res: number, pad?: number, receivers?: readonly (readonly [number, number, number])[]): {
+    matrix: Float32Array;
+    texel: number;
+    depth: number;
+};
+/** A local box through the rigid transform → its world-space bounds. */
+export declare function worldBounds(g: Rigid, lo: readonly [number, number, number], hi: readonly [number, number, number]): {
+    lo: [number, number, number];
+    hi: [number, number, number];
+};
+/** The inverse of a rigid transform. */
+export declare function inverseOf(g: Rigid): Rigid;

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

@@ -0,0 +1,30 @@
+import { type ServiceKey } from "./services";
+import type { HandMetrics } from "./text";
+/** The hand's face as a print sets it: a family and a weight (the host loads it — desk/host/ink.ts `PEN_FACES`). */
+export interface PrintFace {
+    readonly family: string;
+    readonly weight: number;
+}
+/** What a pass takes a tile as: the host's canvas (TILE_TEX², straight alpha) — a type only. */
+export type TileSource = HTMLCanvasElement | OffscreenCanvas;
+/**
+ * THE PRINT'S RASTER (the host's seam, as `TextRaster` is the note's): the hand's face and its metrics (undefined while the
+ * face loads — the print waits rather than set the hand in a stand-in face), a version that turns over when a face lands,
+ * the type's widths, and a rectangle of a print drawn into a tile at `band` texels a unit.
+ */
+export interface PrintRaster<P = unknown> {
+    hand(): {
+        readonly face: PrintFace;
+        readonly metrics: HandMetrics;
+    } | undefined;
+    version(): number;
+    measure(font: string, text: string): number;
+    tile(print: P, x: number, y: number, w: number, h: number, band: number): TileSource;
+    /** The same rectangle as RGBA bytes, TILE_TEX² × 4, row 0 at the top — a fixture's (a rig reads the live print through it). */
+    bytes(print: P, x: number, y: number, w: number, h: number, band: number): Uint8Array<ArrayBuffer>;
+}
+/**
+ * The print raster as a desk SERVICE (K8a, kit/services.ts): lent by the object whose DOM half makes it (the desk calendar's,
+ * over the host's text raster) and `use`d by any kind that prints — `host.use?.(PRINT_RASTER)`.
+ */
+export declare const PRINT_RASTER: ServiceKey<PrintRaster>;