@vibecook/ice 0.11.0 → 0.15.0-desk.1

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">;

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

@@ -0,0 +1,105 @@
+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`, `live()` answering false or the editor's `dispose` (the desk
+ * unmounted — petition I25) 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;
+    /** The editor goes with its desk: a lease still held ends first (`ended` — a typing session commits), then the textarea leaves. */
+    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, type HoldReserves, 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>;