@vibecook/ice 0.11.0 → 0.14.0

package/dist/types/packages/objects/src/paper/layout.d.ts

@@ -0,0 +1,73 @@
+import type { RGB } from "../../../desk/src/index";
+import type { UvRect } from "./pages";
+import type { PaperGeometry } from "./paper";
+/** The most lines of a note's writing its far LOD greeks (K7b) — a mini mat's chip greeks as many (minimat.ts `CHIP_LINES`). */
+export declare const GREEK_LINES = 6;
+export declare const Paper: import("../../../desk/src/engine/index").StructDef<"layer" | "shadow" | "paper" | "ring" | "lamp" | "ink" | "centre" | "half" | "wipe" | "marks" | "lift" | "alpha" | "caret" | "slope" | "radius" | "rot" | "curl" | "cornerCurl" | "glue" | "uv" | "greek" | "glines">;
+export declare const PaperUniforms: import("../../../desk/src/engine/index").StructDef<"select" | "knobs" | "far">;
+export declare const MAX_PAPERS = 1024;
+/** One note for the pass: its geometry, its two colours, its ink and its live marks. */
+export interface PaperInstance {
+    readonly geometry: PaperGeometry;
+    /** The sheet's colour — the product's note surface (§2.2), or the host's. */
+    readonly paper: RGB;
+    /** The pen's colour and how dark it lays (1 = the colour itself where the raster is full). */
+    readonly ink: RGB;
+    readonly inkDensity?: number;
+    /** The fibre's amplitude, ±/255 — theme.ts `PAPER.grain` unless the host says. */
+    readonly grain?: number;
+    /** Where the ink lives (pages.ts): absent = a blank sheet. */
+    readonly raster?: {
+        readonly layer: number;
+        readonly uv: UvRect;
+    } | undefined;
+    /** The newest glyph's box and how far the pen has got through it. */
+    readonly wipe?: {
+        readonly x0: number;
+        readonly y0: number;
+        readonly x1: number;
+        readonly y1: number;
+        readonly t: number;
+    } | undefined;
+    /** The caret, when the note is being written. */
+    readonly caret?: {
+        readonly x: number;
+        readonly y: number;
+        readonly above: number;
+        readonly below: number;
+        readonly on: boolean;
+    } | undefined;
+    /** K7b — its writing GREEKED (the far LOD): the text's left edge and em, each line's baseline and width (note units); absent = unwritten. */
+    readonly greek?: {
+        readonly x0: number;
+        readonly em: number;
+        readonly lines: readonly {
+            readonly y: number;
+            readonly width: number;
+        }[];
+    } | undefined;
+}
+export declare function paperValues(p: PaperInstance, grain: number): {
+    centre: readonly [number, number];
+    half: readonly [number, number];
+    rot: number[];
+    slope: readonly [number, number];
+    lift: number;
+    curl: number;
+    cornerCurl: number;
+    glue: number;
+    radius: number;
+    ring: number;
+    alpha: number;
+    layer: number;
+    lamp: number[];
+    paper: number[];
+    ink: number[];
+    shadow: number[];
+    uv: number[];
+    wipe: number[];
+    caret: number[];
+    marks: number[];
+    greek: number[];
+    glines: number[];
+};

package/dist/types/packages/objects/src/paper/object.d.ts

@@ -0,0 +1,31 @@
+import { type Component, type Entity } from "../../../core/src/index";
+import { type KindDriver } from "../../../desk/src/index";
+import type { Writing } from "./writing";
+import { type NoteTyping } from "./typing";
+import { type NoteBody } from "./host/body";
+export { PENS, type PenName } from "../../../desk/src/kit/index";
+/** The papers a note is cut from — names; the sheets are the host's (the product's `--vf-note-surface` is `yellow`). */
+export declare const PAPERS: readonly ["yellow"];
+export type PaperName = (typeof PAPERS)[number];
+/** The note's durable type id — what `PrefabId` carries (a mini mat accepts it by what it provides — K8a, `CONTAINABLE`). */
+export declare const NOTE_TYPE = "desk.note";
+export declare const Note: import("../../../core/src/index").WidgetType;
+/** The note's writing as a cell (`desk.note:ink` — `{ text, seeds }`): what a typing session live-writes and commits whole. */
+export declare const NOTE_INK: Component<{
+    text: string;
+    seeds: string;
+}>;
+/** The note's other props (`desk.note:props` — `{ pen, paper, seed }`). */
+export declare const NOTE_PROPS: Component<{
+    pen: string;
+    paper: string;
+    seed: number;
+}>;
+/** The note's driver (`driversOf(Note)`): its typing session, its writing local and its membership — what its body asks of it. */
+export interface PaperDriver extends KindDriver {
+    readonly typing: NoteTyping;
+    readonly writing: () => Writing | undefined;
+    readonly isNote: (e: Entity) => boolean;
+    /** Its BODY (K8a — the note's text part, host/body.ts), once the host has made it: the doors that put the editor on a note. */
+    body: NoteBody | undefined;
+}

package/dist/types/packages/objects/src/paper/pages.d.ts

@@ -0,0 +1,43 @@
+export interface InkRect {
+    readonly layer: number;
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}
+/** A WRITTEN rect inside a layer, normalised — the record's `u0 v0 u1 v1` (design-013 §5's; the card's content term had it first). */
+export interface UvRect {
+    readonly u0: number;
+    readonly v0: number;
+    readonly u1: number;
+    readonly v1: number;
+}
+/** A written rect in texels as the record's normalised uv. */
+export declare function uvOf(x: number, y: number, w: number, h: number, texW: number, texH: number): UvRect;
+export declare class InkShelves {
+    readonly size: number;
+    readonly layers: number;
+    private readonly stack;
+    constructor(size?: number, layers?: number);
+    /** A rect for a `w × h` raster, or null when no layer has room (the note then draws its paper alone). */
+    alloc(w0: number, h0: number): InkRect | null;
+    /** In layer `l`, the first run of adjacent rows that hold nothing and are `h` tall together: one row of `h` holding the rect, the rest one empty row. */
+    private recarve;
+    /** Give a rect back; adjacent free spans merge. A rect not from `alloc` is ignored. */
+    free(r: InkRect): void;
+    reset(): void;
+    /**
+     * Give back every layer's TRAILING rows that hold nothing (D2c): a row keeps its height for life, so a
+     * zoom through the band ladder would otherwise leave each layer carved into rows of every rung, and a
+     * raster of a new height would find no room though the texels are free. A trimmed layer's cursor
+     * retreats; a layer emptied entirely is carved afresh. Rows before a used one stay — the rects in
+     * them are the notes' own. Returns the rows given back.
+     */
+    trim(): number;
+    /** Texels in use, rows opened, layers touched — the churn instrument. */
+    get stats(): {
+        readonly used: number;
+        readonly rows: number;
+        readonly layersUsed: number;
+    };
+}

package/dist/types/packages/objects/src/paper/paper-pass.d.ts

@@ -0,0 +1,86 @@
+import { type GroundTheme, type RGB } from "../../../desk/src/index";
+import { type FadeIn, type View, type MatConfig, type MatFrame, type SlotLight, type MatPass, type Presentation, type MatLight } from "../../../desk/src/kit/index";
+import { type PaperInstance } from "./layout";
+import { InkShelves, type InkRect, type UvRect } from "./pages";
+import { type PaperLaw } from "./paper";
+import type { PaperShaders } from "./shaders";
+/** The ink pages: this many texels a side, this many layers — 4 MB a layer as r8, 16 MB in all. */
+export declare const INK_PAGE = 2048;
+export declare const INK_LAYERS = 4;
+export declare class PaperPass {
+    readonly name = "paper/notes";
+    private readonly knobs;
+    /** The notes' PERSISTENT records (engine/records.ts, design-015 §4.3; D6): a slot per note while it is drawn, written when it changed. */
+    private readonly store;
+    /** The records the last prepare turned away at the pass's cap — not drawn; the ground reports them (`GroundStats.dropped`, D7). */
+    dropped: number;
+    private readonly knobBuf;
+    /** What the GPU holds of the knobs: they are written only when they change (K4a — a standing value costs a frame nothing). */
+    private readonly knobsSent;
+    private group;
+    private boundAssets;
+    private boundStore;
+    private count;
+    /** This frame's slot is lit from elsewhere: it draws with the second pipeline. */
+    private litElsewhere;
+    private lawNow;
+    /** The paper's numbers (theme.ts `PAPER`) — the caret's and the ring's widths, the fibre. A host tweaks the root's; every slot copies it. A new law repacks every record (the fibre is packed). */
+    get law(): PaperLaw;
+    set law(next: PaperLaw);
+    /** The day's chain on the paper: false = a lit sheet shows its configured byte; true = the mat's own double gamma (the golden note). */
+    chain: boolean;
+    /** The wipe's softness — how wide the pen's edge is as a glyph arrives, note units. */
+    wipeSoft: number;
+    private readonly device;
+    private readonly shared;
+    private readonly mat;
+    private constructor();
+    /** The root's pass, on the root's mat. */
+    static create(device: GPUDevice, format: GPUTextureFormat, src: PaperShaders, mat: MatPass): Promise<PaperPass>;
+    /** A second slot on the same pipeline and pages, reading ITS mat's silhouette — a portal's inside, a flight's departed frame. */
+    spawn(mat: MatPass): PaperPass;
+    /** Copy the root's tuning — what every slot takes each frame. */
+    tune(from: PaperPass): void;
+    /** The ink pages' carving — shared by every slot: a raster's place is the same on both hosts when the notes come in the same order. */
+    get shelves(): InkShelves;
+    /** Room for a `w × h` raster, or null when the pages are full (the note then draws its paper alone). */
+    alloc(w: number, h: number): InkRect | null;
+    free(r: InkRect): void;
+    /** Give back the layers' trailing empty rows (pages.ts `trim`) — the writing's own housekeeping after a free (D2c). */
+    trim(): number;
+    /**
+     * Every raster forgotten — a scene reload. The texels stay until overwritten — and a raster's
+     * edge, sampled bilinearly, reads one texel beyond its rect, so a host that wants the pages as a
+     * fresh device has them (a parity scene: the Node oracle's pages start blank) passes `clear`.
+     */
+    reset(clear?: boolean): void;
+    /** Write r8 coverage rows (row 0 = top) into a rect `alloc` gave; returns the rect's uv for the record. */
+    write(r: InkRect, bytes: Uint8Array<ArrayBuffer>): UvRect;
+    private rebind;
+    /**
+     * This frame's notes in paint order — through the persistent store (D6): a note keyed by `keys[i]` keeps its slot and is
+     * written only when its record changed; no keys = every record packed afresh (the oracle's form) — and the mat's block for
+     * this slot's camera, its light (`light` the Sun or the Moon, `lit` the lamp it is seen by — MINIMAT.md §4): the dapple,
+     * the lamp's shading and the shadow. Returns the count that will draw.
+     */
+    prepare(view: View & {
+        readonly dpr: number;
+    }, fadeIn: FadeIn, cfg: MatConfig, frame: MatFrame | undefined, instances: readonly PaperInstance[], present: Presentation | undefined, light?: MatLight, select?: RGB, lit?: SlotLight, keys?: readonly number[]): number;
+    /** The store's counters (a rig's witness): records written, bytes, draw-list writes, slots in use. */
+    get records(): import("../../../desk/src/index").RecordStoreStats;
+    /** K7b: this slot's resources for the note's card material (shaders.ts `paperCard`), in its bindings' order — made again when the store grew. */
+    cardResources(): {
+        readonly version: number;
+        readonly resources: readonly (GPUBuffer | GPUTextureView | GPUSampler)[];
+    };
+    private card;
+    /** K7b: every note of the last prepare is the card's to draw — its slot in the store. */
+    cardSlot(index: number): number;
+    get drawn(): number;
+    draw(pass: GPURenderPassEncoder): void;
+    drawRange(pass: GPURenderPassEncoder, first: number, end: number): void;
+    /** This slot's buffers; the pages go with the last slot standing. */
+    dispose(): void;
+}
+/** A theme's select for the ring — the one colour the pass takes from the theme. */
+export declare const selectOf: (theme: GroundTheme) => RGB;

package/dist/types/packages/objects/src/paper/paper.d.ts

@@ -0,0 +1,117 @@
+import { type Lamp } from "../../../desk/src/kit/index";
+/** The paper's numbers (theme.ts `PAPER`) — the engine's unless a host tweaks them. */
+export interface PaperLaw {
+    readonly size: number;
+    readonly radius: number;
+    readonly tilt: number;
+    readonly glue: number;
+    readonly curl: number;
+    readonly cornerCurl: number;
+    readonly relief: number;
+    readonly lift: {
+        readonly height: number;
+        readonly scale: number;
+    };
+    readonly shadow: {
+        readonly sigma: number;
+        readonly alpha: number;
+        readonly sigmaPerUnit: number;
+        readonly alphaHeld: number;
+        readonly slopeMax: number;
+    };
+    readonly grain: number;
+    readonly ring: number;
+    readonly caret: {
+        readonly width: number;
+        readonly blinkMs: number;
+    };
+    readonly far: {
+        readonly px: readonly [number, number];
+        readonly weight: number;
+        readonly alpha: number;
+    };
+}
+export declare const DEFAULT_PAPER_LAW: PaperLaw;
+export { type Lamp, lampOf } from "../../../desk/src/kit/index";
+/** A note's tilt from its seed: within ± `maxDeg`, radians — never square, never the same twice. */
+export declare const tiltOf: (seed: number, maxDeg: number) => number;
+export interface PaperRect {
+    /** World centre. */
+    readonly cx: number;
+    readonly cy: number;
+    /** The sheet, world units. */
+    readonly w: number;
+    readonly h: number;
+    /** Radians; positive turns clockwise on screen. */
+    readonly angle: number;
+}
+/** What moves: the hold's lift (0..1), the selection ring's presence (0..1), the presence itself (1 … 0 gone). */
+export interface PaperMotion {
+    readonly held: number;
+    readonly ring: number;
+    readonly fade: number;
+}
+export declare const PAPER_REST: PaperMotion;
+export interface PaperGeometry {
+    readonly centre: readonly [number, number];
+    /** Half extents as drawn (the hold's scale applied). */
+    readonly half: readonly [number, number];
+    readonly cos: number;
+    readonly sin: number;
+    readonly angle: number;
+    /** World units off the mat: the hold's rise; the free edge's curl over it; the corners' extra; the flat strip's share. */
+    readonly lift: number;
+    readonly curl: number;
+    readonly cornerCurl: number;
+    readonly glue: number;
+    /** The slope's exaggeration for the shading. */
+    readonly relief: number;
+    readonly radius: number;
+    readonly shadow: {
+        readonly sigma: number;
+        readonly alpha: number;
+        readonly sigmaPerUnit: number;
+    };
+    /** The shadow's ground offset per unit of height, world axes — away from the lamp, capped. */
+    readonly slope: readonly [number, number];
+    /** The unit direction to the lamp, world axes (x right, y down the screen, z off the desk). */
+    readonly lamp: readonly [number, number, number];
+    readonly ring: number;
+    readonly alpha: number;
+    readonly scale: number;
+}
+export declare function resolvePaper(n: PaperRect, m: PaperMotion, law: PaperLaw, lamp: Lamp): PaperGeometry;
+/** World → the sheet's own frame (paper.wgsl `paper_local`). */
+export declare function localOf(G: PaperGeometry, wx: number, wy: number): readonly [number, number];
+/** The sheet's own frame → world. */
+export declare function worldOf(G: PaperGeometry, qx: number, qy: number): readonly [number, number];
+/** The sheet's signed distance at a world point. */
+export declare function sdPaper(G: PaperGeometry, wx: number, wy: number): number;
+export type PaperHit = "paper" | "outside";
+export declare const pickPaper: (G: PaperGeometry, wx: number, wy: number) => PaperHit;
+/**
+ * The sheet's height off the mat at a local point (paper.wgsl `paper_height`):
+ * the hold's rise everywhere; flat under the strip; from the strip's lower edge
+ * to the free edge the curl rises as t², the corners by `cornerCurl` more.
+ */
+export declare function heightAt(G: PaperGeometry, qx: number, qy: number): number;
+/** How far the shadow can reach past the sheet, world units — the vertex quad's pad. */
+export declare function shadowReach(G: PaperGeometry): number;
+/** The sheet's axis-aligned bounds in world units, grown by `pad`. */
+export declare function boundsOf(G: PaperGeometry, pad?: number): {
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+};
+/** Texels per world unit a note's ink is drawn with: the bands are powers of two between these. */
+export declare const BAND_MIN = 0.25;
+export declare const BAND_MAX = 8;
+/**
+ * The band for a zoom: the smallest power of two at or above the screen's own
+ * density (`zoom × dpr`), so the ink is never magnified — and, given the band
+ * in use, that band stays while it is still at or above the density and under
+ * 2.3× it (a hysteresis that crosses no band on a frame's wobble). `cap` is the
+ * most the note's raster may take (the page's side over the note's).
+ */
+export declare function rasterBand(zoom: number, dpr: number, current?: number, cap?: number): number;

package/dist/types/packages/objects/src/paper/shaders.d.ts

@@ -0,0 +1,18 @@
+import type { CardMaterial } from "../../../desk/src/index";
+import type { ComposeOptions } from "../../../desk/src/engine/index";
+import { type ShaderText } from "../../../desk/src/kit/index";
+/** The note's own shader files (the kit's pieces come by name). */
+export declare const PAPER_SHADER_FILES: {
+    readonly paper: "paper/paper.wgsl";
+    readonly paperCard: "paper/paper-card.wgsl";
+    readonly paperPass: "paper/paper-pass.wgsl";
+};
+/** The paper pass's program: the kit's view · portal · sdf · light, then the note's records, module, its quad and fragment, and its entry. */
+export type PaperShaders = ComposeOptions;
+export declare function paperShaders(text: ShaderText): PaperShaders;
+/**
+ * The note's CARD MATERIAL (K7b, design-016 §6 K7): the flat-card pipeline draws a note with paper-card.wgsl's quad and fragment
+ * over the paper pass's own records, knobs, samplers and ink pages (`PaperPass.cardResources`, in this order) — every note, so
+ * interleaved with the prints and the boards it is one run.
+ */
+export declare function paperCard(text: ShaderText): CardMaterial;

package/dist/types/packages/objects/src/paper/theme.d.ts

@@ -0,0 +1,58 @@
+/**
+ * PAPER — the desk's first object (STICKY.md): a sticky note as a MATERIAL under the
+ * mat's one light. A square of thin paper pressed flat under its adhesive strip and
+ * free below it, where it rises a little off the mat and its corners rise most; stuck
+ * a degree or two off square, as a hand leaves it; lit by the lamp that casts the
+ * palm's shadow (the gobo projector — `paper.ts` `lampOf`), so the dapple crosses it
+ * and its shadow falls away from that lamp; by night, under the Moon like the mat.
+ * Lengths are world units (CSS px at zoom 1). The paper's colour is the product's
+ * (`--vf-note-surface`, lab/theme.ts); the pen's ink is the host's too.
+ */
+export declare const PAPER: {
+    /** The note's side — a 3″ square read at about the card grid's scale (DESIGN.md §4: small 155). */
+    readonly size: 200;
+    /** The die-cut corner. */
+    readonly radius: 1.5;
+    /** Never stuck square: each note takes its own tilt within ± this, degrees. */
+    readonly tilt: 2.5;
+    /** The fraction of the height pressed flat under the adhesive strip. */
+    readonly glue: 0.3;
+    /** How far the free edge rises off the mat, and how much more its corners rise than its middle. */
+    readonly curl: 3;
+    readonly cornerCurl: 0.6;
+    /** How far a HELD note rises and the scale it reads at: the one physics's (kit/physics.ts). */
+    readonly lift: {
+        readonly height: 12;
+        readonly scale: 1.03;
+    };
+    /** The contact shadow on the mat: the one physics's penumbra (kit/physics.ts). */
+    readonly shadow: {
+        readonly sigma: 2.2;
+        readonly alpha: 0.36;
+        readonly sigmaPerUnit: 0.9;
+        readonly alphaHeld: 0.4;
+        readonly slopeMax: 2.2;
+    };
+    /** How much the sheet's slope is exaggerated for the lamp's shading: a curl of a few px over a hundred is invisible at 1; at this it reads as paper. */
+    readonly relief: 3.5;
+    /** The paper's fibre: ±/255 on the albedo. */
+    readonly grain: number;
+    /** The sole-selection ring (DESIGN.md §7), CSS px, in `--vf-select`: the one physics's. */
+    readonly ring: 1.5;
+    /** The caret: CSS px wide, the platform's blink. */
+    readonly caret: {
+        readonly width: 1.5;
+        readonly blinkMs: 530;
+    };
+    /**
+     * The FAR LOD (K7b, design-016 §6 K7): under `px[1]` CSS px (the sheet's longer side on screen) the writing crossfades to its
+     * GREEKED lines — bars of the pen's ink at `alpha`, `weight` × the em thick through each line's x-height, as a mini mat's chip
+     * greeks a note (MINIMAT.md §5) — and the fibre fades out with it (the cheap path: the grain aliases once a device px spans units
+     * of paper); under `px[0]` the note is greeked alone: no raster held, none asked, no fibre computed.
+     */
+    readonly far: {
+        readonly px: readonly [48, 64];
+        readonly weight: 0.3;
+        readonly alpha: 0.42;
+    };
+};

package/dist/types/packages/objects/src/paper/typing.d.ts

@@ -0,0 +1,51 @@
+import { type Component, type Entity, type World } from "../../../core/src/index";
+import { type TypingDocs } from "../../../desk/src/index";
+export { type TypingDocs, writable, type WritableSession } from "../../../desk/src/index";
+/**
+ * THE TAP'S NOTE (D7 #4): the note a tap by the local pointer `pid` writes into — the interaction stack's exact hit for that
+ * pointer — or none. NONE while any object is in hand: a tap in hand is the hand's (a put-down, a held tool), and the pointer's
+ * hit is frozen at the pick-up anyway (l1-pick skips `HandledByWidget` pointers, which the hold stamps every tick), so it would
+ * name whatever the pointer touched then — the note hovered before ⏎ opened the board. `found` says whether the pointer is
+ * known at all (a touch that has lifted is gone: the caller may ask the drawn notes instead).
+ */
+export declare function tapNote(world: World, pid: string, isNote: (e: Entity) => boolean): {
+    readonly found: boolean;
+    readonly note: Entity | undefined;
+};
+export interface NoteTypingOptions {
+    readonly world: World;
+    readonly docs: TypingDocs;
+    /** The note's cells: its writing (`{ text, seeds }`, live-written and committed whole) and its other props (the seed). The object hands its own (D-D7-A.3). */
+    readonly ink: Component<{
+        text: string;
+        seeds: string;
+    }>;
+    readonly props: Component<{
+        seed?: number;
+    }>;
+    /** A fresh seed for a glyph just written (`Math.random` unless a test says). */
+    readonly fresh?: () => number;
+}
+export interface NoteTyping {
+    /** The note the editor is on — the `Editing` claim — or undefined. */
+    editing(): Entity | undefined;
+    /** A session is open: the note's ink written live and not yet committed. */
+    open(): boolean;
+    /** The note's writing as the world holds it now (the live value mid-session). */
+    ink(e: Entity): {
+        readonly text: string;
+        readonly seeds: string;
+    } | undefined;
+    /** Claim `e` for writing (`Editing`); a claim on another note ends first. False for a dead entity or a non-note. */
+    begin(e: Entity): boolean;
+    /** The platform's value for the claimed note: seeds carried, the cell written LIVE. The inserted run, or null when nothing changed. */
+    input(value: string): {
+        readonly from: number;
+        readonly to: number;
+    } | null;
+    /** End the SESSION: ONE transaction with the live cell, unless it nets to nothing. Whether it committed. The claim stays. */
+    commit(): boolean;
+    /** End the claim: commit, then lift `Editing`. A dead note has nothing to commit — the claim died with it. */
+    end(): void;
+}
+export declare function createNoteTyping(opts: NoteTypingOptions): NoteTyping;

package/dist/types/packages/objects/src/paper/writing.d.ts

@@ -0,0 +1,161 @@
+import type { Entity } from "../../../core/src/index";
+import { type KindHost } from "../../../desk/src/index";
+import { type View, type HandLaw, type HandLayout, type TextRaster } from "../../../desk/src/kit/index";
+import type { PaperInstance } from "./layout";
+import type { InkRect, UvRect } from "./pages";
+import { type PaperGeometry } from "./paper";
+/** The pages a writing allocates in — the root paper pass (paper-pass.ts) satisfies it. */
+export interface InkPages {
+    alloc(w: number, h: number): InkRect | null;
+    free(r: InkRect): void;
+    write(r: InkRect, bytes: Uint8Array<ArrayBuffer>): UvRect;
+    /** Every rect forgotten (the shelves carved afresh); `clear` zeroes the texels too. */
+    reset(clear?: boolean): void;
+    /** Give back the layers' trailing empty rows (pages.ts `trim`). */
+    trim?(): number;
+}
+/** The hand's law as theme.ts states it (`HAND`) — the engine's unless a host says. */
+export declare const DEFAULT_HAND_LAW: HandLaw;
+/** The default face — Caveat medium (STICKY.md §3; the app ships the file). */
+export declare const DEFAULT_FACE = "caveat";
+/** The pen's bleed, note units — a faint stroke under each glyph (STICKY.md §3). */
+export declare const DEFAULT_BLEED = 0.3;
+export interface WritingOptions {
+    /** The ink pages — the root paper pass once the ground is made; `undefined` before (a sheet waits). */
+    readonly pages: () => InkPages | undefined;
+    /** The host's text raster (desk/host/ink.ts); absent — the Node oracle — nothing is rastered live. */
+    readonly text?: TextRaster | undefined;
+    readonly hand?: HandLaw;
+    readonly face?: string;
+    readonly bleed?: number;
+    /** K7b — the far LOD's low edge (theme.ts `PAPER.far`), CSS px of the sheet's longer side: under it no raster is held or asked (the note greeks). */
+    readonly far?: number;
+    /** A typed glyph's wipe, ms (theme.ts `HAND.wipeMs`). */
+    readonly wipeMs?: number;
+    /** The caret's blink, ms (theme.ts `PAPER.caret.blinkMs`). */
+    readonly blinkMs?: number;
+    /** Only a note within this many CSS px of the view pays for a raster (the prototype's 200). */
+    readonly marginPx?: number;
+    /**
+     * The builder's word on what is DRAWN (D6, persistent records — `KindHost.drawn`): the paint rank of a note in the root slot this
+     * frame, undefined when it is not drawn. With it, "drawn" means the builder's set, not the last `draw` call (a reused record makes
+     * none): the eviction spares what is on screen and `noteAt` ranks by paint order. Absent, the writing counts its own draws.
+     */
+    readonly drawn?: ((e: Entity) => number | undefined) | undefined;
+    /** The desk's frame raster queue (K6b, `KindHost.rasters`): a new band or a first raster is asked there; absent, laid at once. */
+    readonly queue?: KindHost["rasters"];
+    /** The builder's door (K6b, `KindHost.remake`): a note's record remade once the queue laid its raster. */
+    readonly remake?: KindHost["remake"];
+}
+/** What a note draws with this frame — the paper kind's record takes it whole. */
+export interface NoteInk {
+    readonly raster?: {
+        readonly layer: number;
+        readonly uv: UvRect;
+    };
+    readonly wipe?: PaperInstance["wipe"];
+    readonly caret?: PaperInstance["caret"];
+}
+/** Where a note's ink lives and what it was drawn at — the rigs' witness. */
+export interface NoteRasterInfo {
+    readonly band: number;
+    readonly w: number;
+    readonly h: number;
+    readonly layer: number;
+    readonly x: number;
+    readonly y: number;
+    readonly pinned: boolean;
+}
+export interface WritingStats {
+    /** Notes holding a raster now (pinned included). */
+    readonly resident: number;
+    readonly pinned: number;
+    /** Layouts laid and rasters drawn since the mount — the "re-rasters on an edit or a rung only" instrument. */
+    readonly layouts: number;
+    readonly rasters: number;
+    /** Rasters refused because the pages were full (the sheet drew blank). */
+    readonly blanks: number;
+    /** Rasters evicted to make room. */
+    readonly evicted: number;
+    /** Notes whose raster is asked of the queue and not laid yet (K6b) — each draws what it holds meanwhile. */
+    readonly queued: number;
+}
+export interface Writing {
+    /** The frame's clock, once a tick before the draw: does the writing want a frame now? */
+    tick(now: number): boolean;
+    /**
+     * When the writing is next live (K7a — `KindLocal.due`): now while a frame is owed or a wipe runs on a drawn note; the
+     * caret's next blink phase while it stands; never otherwise — a face landing is the text raster's wake, an edit the
+     * editor's. A desk at rest with a caret standing takes one frame a blink phase, and none without one.
+     */
+    due(now: number): number;
+    /**
+     * What note `e` draws with this frame: its ink (pinned or live), the pen's wipe, the caret. A `fading` note (a
+     * delete ghost) draws only the raster it already holds — never a new layout or raster, no marks.
+     */
+    draw(e: Entity, props: Readonly<Record<string, unknown>>, rect: {
+        readonly cx: number;
+        readonly cy: number;
+        readonly w: number;
+        readonly h: number;
+    }, view: View & {
+        readonly dpr: number;
+    }, geometry: PaperGeometry, fading?: boolean): NoteInk;
+    /**
+     * The band note `e` asks at `zoom` × `dpr` (K6b — the paper kind's RUNG): its raster's band under the ladder's hysteresis, the one
+     * `draw` would raster at; 0 when it asks none (an empty sheet, a pinned still, no text raster). The note's record reads the zoom
+     * through this alone, so a zoom within the band remakes nothing.
+     */
+    bandOf(e: Entity, props: Readonly<Record<string, unknown>>, rect: {
+        readonly w: number;
+        readonly h: number;
+    }, zoom: number, dpr: number): number;
+    /**
+     * Note `e`'s RUNG at `zoom` × `dpr` (K6b — the paper kind's `rung`): without a queue, the band it asks (`bandOf` — its record,
+     * remade at a crossing, rasters it at once); with one, the band of the raster it HOLDS — what its record shows — the band the zoom
+     * asks being ASKED of the queue here, `px` (screen px from the view's centre) its order: a crossing remakes no record, the raster's
+     * landing does (`remake`).
+     */
+    rungOf(e: Entity, props: Readonly<Record<string, unknown>>, rect: {
+        readonly w: number;
+        readonly h: number;
+    }, zoom: number, dpr: number, px: number): number;
+    /** The note's layout as last drawn (undefined before, for a still, or while the face loads). */
+    layoutOf(e: Entity): HandLayout | undefined;
+    rasterOf(e: Entity): NoteRasterInfo | undefined;
+    /** Pin a committed raster (r8 rows) on a note — allocated NOW, in call order (the oracle's texels). */
+    pin(e: Entity, bytes: Uint8Array<ArrayBuffer>, size: {
+        readonly w: number;
+        readonly h: number;
+    }): boolean;
+    isPinned(e: Entity): boolean;
+    /** The editor's caret: on note `e` before glyph `index`, its blink restarted at `now`; `undefined` lifts it. */
+    caret(e: Entity | undefined, index?: number, now?: number): void;
+    /** The caret as drawn: its note, its index, whether it shows. */
+    caretOf(): {
+        readonly entity: Entity;
+        readonly index: number;
+        readonly on: boolean;
+    } | undefined;
+    /** A glyph was just written at `index` (the pen's wipe from `now`); `undefined` = nothing to wipe (a paste, a newline). */
+    wrote(e: Entity, index: number | undefined, now: number): void;
+    wipeOf(e: Entity): {
+        readonly index: number;
+        readonly t0: number;
+    } | undefined;
+    /** What has LANDED on the note, counted — its raster laid, its wipe let go (D7 — `KindLocal.landed`); never the wipe running. */
+    landed(e: Entity): number;
+    /** The caret index nearest a world point on a drawn note — where a tap puts the pen. */
+    caretIndexAt(e: Entity, wx: number, wy: number): number | undefined;
+    /** The topmost note drawn last frame under a world point. */
+    noteAt(wx: number, wy: number): Entity | undefined;
+    /** The note left the desk for good: its rect back to the pages. */
+    forget(e: Entity): void;
+    /** Every raster forgotten and the pages carved afresh (a scene reload). */
+    reset(): void;
+    stats(): WritingStats;
+    dispose(): void;
+}
+/** The caret index nearest a point in a note's own units (the prototype's `caretIndexAt`): lines weigh three times the columns. */
+export declare function caretIndexIn(L: HandLayout, nx: number, ny: number, length: number): number;
+export declare function createWriting(opts: WritingOptions): Writing;