@vibecook/ice 0.11.0 → 0.14.0

package/dist/types/packages/kernel/src/atlas-pack.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Shelf packing for the atlas-slot allocator (design-012 §4, Q3 RATIFIED
+ * 2026-08-31) — pure rect math over a plain page struct. No ids, no sources,
+ * no GPU: the caller owns identity, residency and effects; this module owns only
+ * where a rect may sit, what it costs, and when a page should grow. That caller
+ * was `ground/atlas-allocator.ts` until B8 deleted the old leg; it is
+ * `@ice/core`'s `createLayerAllocator` now, over fixed 2048² layers.
+ *
+ * **Gutters.** Every placed rect is separated from its neighbours AND from the
+ * page edge by at least `gutter` px, so a linear tap at a slot's border never
+ * reaches a neighbour's texels. 2 px is the default (design-012 §4 says
+ * "1–2 px"): 1 px covers a bilinear tap's half-texel reach at dpr 1, 2 px
+ * covers non-integer scaling and mip level 1.
+ *
+ * **Shelves, not skyline.** Slots are top-aligned on horizontal shelves whose
+ * height is fixed by the first slot to open them. The band below a short slot
+ * on a tall shelf is unusable by construction — that loss is real and shows up
+ * in `pageWaste().packingWastePct` rather than hiding. A skyline packer would
+ * recover some of it at the cost of an O(n) contour per placement and a much
+ * harder free/coalesce story; shelves keep free + coalesce O(holes on one
+ * shelf), which is what makes the retention half of the ratified design cheap.
+ *
+ * **Growth never moves a slot.** Shelves are anchored at y=0 and grow right and
+ * down, so widening a page only lengthens every shelf's tail and heightening it
+ * only adds room below. Every existing rect stays valid at the same origin —
+ * the property that lets a page grow with content (Q3) without a repack.
+ */
+import type { Rect } from "./shapes";
+/** Default slot separation, in device px. See the gutter note above. */
+export declare const DEFAULT_ATLAS_GUTTER = 2;
+export interface SlotSize {
+    width: number;
+    height: number;
+}
+export interface PageSize {
+    width: number;
+    height: number;
+}
+/**
+ * One horizontal band. `height` is fixed when the shelf opens; `cursorX` is the
+ * next free content-origin x (it starts at `gutter` and retracts when the
+ * right-most slot is freed).
+ */
+export interface Shelf {
+    y: number;
+    height: number;
+    cursorX: number;
+}
+/**
+ * A packed page. Mutated in place by the functions below (a packer is state by
+ * nature — the kernel law it obeys is "no ECS/DOM/GPU", not "no mutation";
+ * `spatial-index` sets the same precedent).
+ */
+export interface ShelfPage {
+    width: number;
+    height: number;
+    readonly gutter: number;
+    shelves: Shelf[];
+    /**
+     * Reusable interior holes. Each spans its shelf's FULL height (freeing a
+     * short slot on a tall shelf releases the whole band — the sub-shelf
+     * remainder was never addressable), so `hole.y` identifies its shelf and
+     * coalescing is a one-dimensional merge.
+     */
+    holes: Rect[];
+    /** Σ of the areas handed out by `packRect` and not yet freed. */
+    usedArea: number;
+}
+export interface PageWaste {
+    /** `width × height` — addressable space, NOT memory (textures are lazily backed). */
+    pageArea: number;
+    /** `width × occupiedHeight` — the band shelves actually reach into. */
+    occupiedArea: number;
+    /** Live slot pixels. */
+    usedArea: number;
+    /** Interior fragmentation: reusable holes left by freed slots. */
+    holeArea: number;
+    /** `1 − usedArea/occupiedArea` — the number comparable to the spike's 19.5 %. */
+    packingWastePct: number;
+    /** `1 − usedArea/pageArea` — how much of the allocation is unspent. */
+    allocationWastePct: number;
+    /** `holeArea/occupiedArea` — the repack trigger. */
+    fragmentationPct: number;
+}
+export declare function createShelfPage(width: number, height: number, gutter?: number): ShelfPage;
+export declare function cloneShelfPage(page: ShelfPage): ShelfPage;
+/** Bottom edge (exclusive, gutter included) of the last shelf; 0 on an untouched page. */
+export declare function pageOccupiedHeight(page: ShelfPage): number;
+export declare function pageWaste(page: ShelfPage): PageWaste;
+/** True when `size` fits a page whose shelves are `page`'s but whose extent is `width × height`. */
+export declare function canPackAt(page: ShelfPage, width: number, height: number, size: SlotSize): boolean;
+/**
+ * Place a rect, mutating the page. `null` when it does not fit — the caller
+ * decides whether to grow (`nextGrowthStep`) or open another page.
+ */
+export declare function packRect(page: ShelfPage, size: SlotSize): Rect | null;
+/**
+ * Return a rect to the page. `false` when it belongs to no shelf here (a
+ * foreign or already-freed rect — the caller's bookkeeping is wrong).
+ *
+ * The rect's shelf band becomes reusable in full: a right-most rect retracts
+ * the shelf cursor (absorbing any holes the retraction reaches), anything else
+ * becomes a hole and coalesces with its neighbours.
+ */
+export declare function freeRect(page: ShelfPage, rect: Rect): boolean;
+/**
+ * Merge holes that are gutter-adjacent on the same shelf. The gutter between
+ * them joins the merged hole: it is addressable again once the slots either
+ * side of it are gone.
+ */
+export declare function coalesceHoles(page: ShelfPage): void;
+/**
+ * Reclaim vertical space: drop trailing empty shelves, and merge adjacent
+ * empty ones into a single taller shelf. Without the merge, a page that fully
+ * cycles its content keeps its original height ladder forever and can no
+ * longer accept a slot taller than any single old shelf.
+ */
+export declare function coalesceShelves(page: ShelfPage): void;
+/**
+ * The smallest page that could ever hold `size`: the next power of two on both
+ * sides, clamped into `[minSize, maxSize]`. `null` when the device limit cannot
+ * hold the slot at all — the honest answer is a refusal, not a clipped slot.
+ */
+export declare function initialPageSize(size: SlotSize, minSize: number, maxSize: number, gutter?: number): PageSize | null;
+/**
+ * The next growth step for a page: double the SHORTER side (ties go to width),
+ * capped at the device limit. `null` when both sides are already at the limit.
+ *
+ * Doubling overshoots — the 100-card uniform board lands on 4096×4096 where
+ * 4096×3044 would do, 34 % more addressable space than it spends. That is
+ * deliberate: `hic-bench` FINDINGS §6 measured `createTexture` at 0.0 MB and
+ * all cost at first write, so the unwritten tail is addressable, not resident,
+ * while every growth step IS a real texture realloc. The alternative that lost
+ * was growing height in exact shelf increments (tight pages, ~9 reallocs for
+ * that board instead of 3). `pageWaste` reports both numbers so the assumption
+ * stays visible: `packingWastePct` for packing quality, `allocationWastePct`
+ * for the overshoot.
+ */
+export declare function nextGrowthStep(current: PageSize, maxSize: number): PageSize | null;
+/**
+ * The page extent that would admit `size`, growing from the page's current one.
+ * `null` when the device limit is reached without room. Pure — the caller
+ * applies ONE growth to the answer rather than reallocating per step.
+ */
+export declare function planPageGrowth(page: ShelfPage, size: SlotSize, maxSize: number): PageSize | null;
+/** Widen/heighten a page in place. Existing rects keep their origins (see the module note). */
+export declare function growShelfPage(page: ShelfPage, size: PageSize): void;
+/**
+ * Repack a set of sizes into a fresh page of the given extent, tallest first —
+ * the classic shelf-packing order, and the only reason a repack is worth its
+ * re-uploads. Returns rects positionally matched to `sizes`, or `null` if the
+ * set does not fit (the caller keeps the page it has).
+ */
+export declare function packPage(width: number, height: number, gutter: number, sizes: readonly SlotSize[]): {
+    page: ShelfPage;
+    rects: Rect[];
+} | null;

package/dist/types/packages/kernel/src/bezier.d.ts

@@ -29,21 +29,6 @@ export declare function cubicPoint(c: Cubic, t: number): Vec2;
  * culling/picking prefilters.
  */
 export declare function cubicAABB(c: Cubic): AABB;
-export interface Tessellation {
-    /** Flattened polyline, interleaved [x0,y0, x1,y1, …] in the cubic's own space. */
-    points: Float32Array;
-    /** Cumulative arc length at each polyline point (same unit; [0] = 0). */
-    arcLength: Float32Array;
-}
-/**
- * Adaptive cubic flattening + prefix arc length (2026-07-16, the @ice/ground
- * wires pass: stroke tessellation and dash placement both ride this). Emit
- * density follows curvature — flat spans emit one segment regardless of
- * length; tolerance is in the cubic's OWN space (the ground renderer passes
- * screen-px cubics with ~0.25 px tolerance, so density tracks zoom for free).
- * `maxDepth` bounds pathological inputs (2^depth segments worst case).
- */
-export declare function tessellateCubic(c: Cubic, tolerance?: number, maxDepth?: number): Tessellation;
 /** Distance from a point to a line segment. */
 export declare function distanceToSegment(px: number, py: number, ax: number, ay: number, bx: number, by: number): number;
 /**

package/dist/types/packages/kernel/src/coords.d.ts

@@ -41,42 +41,3 @@ export declare function fitCamera(content: Rect, vpW: number, vpH: number, opts:
     minZoom: number;
     maxZoom: number;
 }): CameraState;
-/**
- * Camera → the ONE per-plane CSS transform (design-002 §5 `planeTransform`).
- * Children are laid out in WORLD units inside the plane (left/top = world x/y),
- * the plane carries `transform: translate(tx px, ty px) scale(scale)` with
- * `transform-origin: 0 0` — so a child at world point p lands at
- * `p·zoom + t = (p − camera)·zoom`, i.e. exactly `worldToScreen(p)`.
- */
-export declare function planeCssTransform(camera: CameraState): {
-    tx: number;
-    ty: number;
-    scale: number;
-};
-/** World → island (center-origin, Y-up). THE Y-flip, direction one. */
-export declare function worldToIsland(worldX: number, worldY: number, widget: Rect): Vec2;
-/** Island → world. THE Y-flip, direction two. */
-export declare function islandToWorld(islandX: number, islandY: number, widget: Rect): Vec2;
-/**
- * Camera → the P2 composite ortho frustum + camera position (world units,
- * Y-up scene). `left/top` pin the viewport's top-left to `Camera.{x,y}`
- * exactly like `planeCssTransform` does for the DOM planes: the frustum spans
- * `viewport / zoom` world units and the camera sits at the world origin
- * offset, so a quad at `worldRectToComposite(rect)` lands on the same screen
- * pixels as a DOM host at `rect` under the plane transform.
- */
-export declare function compositeCameraFrustum(camera: CameraState, viewportW: number, viewportH: number): {
-    left: number;
-    right: number;
-    top: number;
-    bottom: number;
-    x: number;
-    y: number;
-};
-/** World rect → composite-quad center + scale in the Y-up P2 scene. */
-export declare function worldRectToComposite(rect: Rect): {
-    x: number;
-    y: number;
-    sx: number;
-    sy: number;
-};

package/dist/types/packages/kernel/src/index.d.ts

@@ -7,10 +7,10 @@ export * from "./shapes";
 export * from "./coords";
 export * from "./snap";
 export * from "./spatial-index";
-export * from "./zoom-bands";
-export * from "./eviction";
 export * from "./anchors";
 export * from "./bezier";
 export * from "./easing";
 export * from "./nav-flight";
 export * from "./layout";
+export * from "./tray";
+export * from "./atlas-pack";

package/dist/types/packages/kernel/src/nav-flight.d.ts

@@ -58,6 +58,12 @@ export declare function composeAffine(outer: PortalAffine, inner: PortalAffine):
  * (design-006 §3.1); only the ARRIVAL camera is clamped by the caller.
  */
 export declare function solveFlightStart(A: PortalAffine, camPre: CameraState): CameraState;
+/**
+ * Destination camera expressed in departed-frame coordinates. Rendering a
+ * procedural outgoing program with this camera is pixel-equivalent to first
+ * mapping its points through A and then rendering under `destination`.
+ */
+export declare function outgoingCamera(A: PortalAffine, destination: CameraState): CameraState;
 /** Zoom distance in octaves — the flight-length measure (design-006 §4/§5). */
 export declare function flightOctaves(from: CameraState, to: CameraState): number;
 /**

package/dist/types/packages/kernel/src/tray.d.ts

@@ -0,0 +1,155 @@
+/**
+ * THE PEGBOARD TRAY'S LATTICE LAW (design-017 §8; K5a) — where the kinds hang on the board: pure, one frame (the BOARD's —
+ * x from the drawer's left edge, y down from the board's top at scroll 0), plain structs in and out.
+ *
+ * The lattice (§6.1) in pitches: holes at x = c + ¼ + ½·(r odd), rows at y = r + ¾; a hole is punched only where its centre
+ * lies ≥ ¾ from both sides (the solid border, D-K3.1). The desk's shader and its CPU mirror (desk/tray/lattice.ts) read the
+ * same three numbers from here.
+ *
+ * A kind's HANG (its `defineObject({ tray: { hang } })`): its size on the board (CSS px), its accessory — a hook, a shelf, a
+ * clip or a rail, SKÅDIS-style — and its PEGS, the holes the accessory plugs into, in pitches from the specimen's HANG POINT:
+ * the centre of its top edge (a hook, a clip, a rail hang it from above) or of its bottom edge (a shelf holds it up). Every
+ * peg lands on a hole centre, so the pegs' offsets must be what the stagger allows: between two pegs a whole number of rows,
+ * and across them a whole number of pitches on the same parity or a half on the other (`hangError`).
+ *
+ * The LAW (`layTray`): the items in (category, order, type) order, packed left to right across the board's columns, a line
+ * at a time; each placed at the first holes at or after the line's top and the cursor — its row's PARITY is where the stagger
+ * puts a hole under its first peg; a pitch between neighbours, a clear row between lines. `bottom` is the last line's foot;
+ * the scroll's range is that plus a pitch, less the face the drawer shows (`trayScrollMax`).
+ */
+/** The lattice's phase and border, pitches (design-017 §6.1). */
+export declare const PEG_LATTICE: {
+    /** A hole's centre: x = c + colPhase + ½·(r odd) from the board's left edge… */
+    readonly colPhase: 0.25;
+    /** …at y = r + rowPhase below its top at scroll 0. */
+    readonly rowPhase: 0.75;
+    /** A hole is punched only where its centre lies this far from both sides (the solid border). */
+    readonly border: 0.75;
+};
+/** What holds a specimen to the board (design-016 §7.7 — SKÅDIS's accessories). */
+export type TrayAccessory = "hook" | "shelf" | "clip" | "rail";
+export declare const TRAY_ACCESSORIES: readonly TrayAccessory[];
+/** How a kind hangs on the tray: its size (CSS px), its pegs (pitches from its hang point), its accessory. */
+export interface TrayHang {
+    readonly w: number;
+    readonly h: number;
+    /** The holes the accessory plugs into, `[dx, dy]` pitches from the hang point — the top edge's centre, or the bottom edge's on a shelf. */
+    readonly pegs: readonly (readonly [number, number])[];
+    readonly accessory: TrayAccessory;
+}
+/**
+ * The accessories' own geometry, pitches — the law's footprints and the desk's drawing read the same numbers. A HOOK drops
+ * from its hole to its tip; a SHELF's plank lies under the specimen (its overhang past each side) on a bracket from each
+ * hole; a CLIP's body grips the specimen's top edge from its hole; a RAIL's bar runs through its holes past the outer two.
+ */
+export declare const TRAY_ACCESSORY: {
+    /** Round a peg: the plug in its hole and the reach of what sits on it (a hole is 0.26 × 0.66). */
+    readonly plug: {
+        readonly hx: 0.17;
+        readonly hy: 0.4;
+    };
+    readonly hook: {
+        readonly hx: 0.12;
+        readonly drop: 0.62;
+    };
+    readonly shelf: {
+        readonly thick: 0.24;
+        readonly overhang: 0.3;
+        readonly bracket: 0.1;
+    };
+    readonly clip: {
+        readonly hx: 0.3;
+        readonly below: 0.55;
+    };
+    readonly rail: {
+        readonly hy: 0.13;
+        readonly overhang: 0.4;
+    };
+};
+/** One item the law lays: a kind's type, its hang, and its place in the order. */
+export interface TrayItem {
+    readonly type: string;
+    readonly hang: TrayHang;
+    /** Sorted first (strings; absent = ""). */
+    readonly category?: string;
+    /** Then this (absent = 0), then the type. */
+    readonly order?: number;
+}
+/** A box, pitches or px by context: left, top, right, bottom. */
+export interface TrayBox {
+    readonly x0: number;
+    readonly y0: number;
+    readonly x1: number;
+    readonly y1: number;
+}
+/** A peg as laid: its hole (row, column) and the hole's centre, board px. */
+export interface TrayPeg {
+    readonly row: number;
+    readonly col: number;
+    readonly x: number;
+    readonly y: number;
+}
+/** An item as laid, board px: the specimen's rect (top-left, size), its pegs on their holes, its footprint (the specimen and its accessory), its line. */
+export interface TrayPlaced {
+    readonly type: string;
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+    readonly pegs: readonly TrayPeg[];
+    readonly box: TrayBox;
+    readonly line: number;
+}
+export interface TrayLayout {
+    readonly placed: readonly TrayPlaced[];
+    /** The last line's foot, board px (0: nothing laid). */
+    readonly bottom: number;
+}
+/**
+ * The law's spacing, pitches: the side margin, the gap between neighbours, the first line's top, the clear row between lines. The first
+ * line lies below the drawer's HEADER and its fade (design-018 R4, D-R4.2 — the desk's `DRAWER`: the arris 1.5 px, the clear header 48,
+ * the ramp 32): at rest nothing laid is faded, every footprint at 99 % of the ramp or past it (2 pitches = 80 px ≥ 1.5 + 48 + 0.944·32;
+ * the desk's test holds the two numbers together — the kernel imports no drawer).
+ */
+export interface TraySpacing {
+    readonly margin: number;
+    readonly gap: number;
+    readonly top: number;
+    readonly clear: number;
+}
+export declare const TRAY_SPACING: TraySpacing;
+/** Why a hang cannot be laid (a message), or null: its size, its pegs on the lattice, its accessory. */
+export declare function hangError(h: TrayHang): string | null;
+/** The (category, order, type) order. */
+export declare function trayOrder(a: TrayItem, b: TrayItem): number;
+/** A hang's footprint, pitches from its hang point: the specimen, its pegs' plugs and its accessory. */
+export declare function hangFootprint(h: TrayHang, pitch: number): TrayBox;
+/**
+ * Lay the items on a board `width` px wide at `pitch` px (design-017 §8): in (category, order, type) order, left to right, a
+ * line at a time — an item that would cross the right margin (or put a peg in the right border) starts the next line, a clear
+ * row below the last one's foot. A line's specimens hang with their top edges together (as near as their holes allow): each
+ * below the line's top by the most any item's accessory reaches above its specimen. Every peg on a punched hole's centre.
+ */
+export declare function layTray(items: readonly TrayItem[], width: number, pitch: number, spacing?: TraySpacing): TrayLayout;
+/** The board's scroll range (design-017 §8): the last line's foot plus a pitch, less the face the drawer shows — never below 0. */
+export declare function trayScrollMax(bottom: number, face: number, pitch: number): number;
+/**
+ * A specimen's FIT (design-017 §8–§9; K5a's law, K5b's grab point): its object at its natural size seen at the scale its hang asks —
+ * the smaller of the two ratios, so the whole object shows — centred in the hang's rect. `zoom` is that scale; `x`/`y`/`w`/`h` the
+ * object as drawn, in the rect's units: what a press on the specimen grabs (the insert's anchor is the press across THIS rect).
+ */
+export declare function specimenFit(rect: {
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}, natural: {
+    readonly w: number;
+    readonly h: number;
+}): {
+    readonly zoom: number;
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+};

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

@@ -0,0 +1,180 @@
+import { type GroundTheme, type RGB } from "../../../desk/src/index";
+import { type FadeIn, type View, type MatConfig, type MatFrame, type MatPass, type Presentation, type MatLight } from "../../../desk/src/kit/index";
+import type { BoardOp } from "./history";
+import { type BoardInstance } from "./layout";
+import type { BoardShaders } from "./shaders";
+import { type Tool } from "./stroke";
+/** Stamps one upload carries — a longer stroke replays in chunks. */
+export declare const STAMP_CAP: number;
+/** The far-LOD thumbnails' layer side, texels (a board's ink chain from its first level that fits: 1 texel a unit for the law's board). */
+export declare const BOARD_THUMB = 512;
+/** The pool: the rasters one frame binds (the boards larger on screen than their thumbnail serves). */
+export declare const BOARD_SLOTS = 8;
+/** Density changes (re-rasters) one step asks for — the rest wait a frame, their old raster standing. */
+export declare const BOARD_RASTERS_A_STEP = 2;
+/**
+ * THE ZOOM RUNG (K6a): the density a board's raster is made at for `zd` device px a world unit (zoom × dpr × the hold's scale) —
+ * two texels a device px as the law's 4 gave at zoom 1 on a 2× screen, a power of two, from 1 (the thumbnail's own) to `max`.
+ */
+export declare function boardRung(zd: number, max?: number): number;
+/** The board's materials the host hands in (lab/theme.ts `BOARD_LOOK`): a marker's barrel, the eraser's felt and back. */
+export interface BoardLook {
+    readonly barrel: RGB;
+    readonly felt: RGB;
+    readonly wood: RGB;
+}
+export declare class BoardPass {
+    readonly name = "board/whiteboards";
+    private readonly knobs;
+    /** The boards' PERSISTENT records (engine/records.ts, design-015 §4.3; D6): a slot per drawn board, written when its record or its raster's facts 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 stampU;
+    private readonly inkU;
+    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;
+    /** Each drawn board's index in the list `prepare` was handed (a board with no ink to show is skipped) — what `drawRange` counts in. */
+    private drawnFrom;
+    /** The materials a host projects (lab/theme.ts); black until it says. */
+    look: BoardLook;
+    /** The day's chain on the board: false = a lit melamine shows its configured byte; true = the mat's double gamma. */
+    chain: boolean;
+    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: BoardShaders, mat: MatPass): Promise<BoardPass>;
+    /** A second slot on the same pipelines and rasters, reading ITS mat's silhouette — a portal's inside, a flight's departed frame. */
+    spawn(mat: MatPass): BoardPass;
+    /** Copy the root's tuning — what every slot takes each frame. */
+    copy(from: BoardPass): void;
+    /** K7b: instance `index` of the last prepare drawn by the flat-card pipeline — its slot in the store — or −1: this pass draws it (or no one). */
+    cardSlot(index: number): number;
+    private cards;
+    private cardsN;
+    /** K7b: this slot's resources for the board's card material (shaders.ts `boardCard`), in its bindings' order — made again when the store or the thumbnails grew. */
+    cardResources(): {
+        readonly version: number;
+        readonly resources: readonly (GPUBuffer | GPUTextureView | GPUSampler)[];
+    };
+    private card;
+    private cardOver;
+    private rebind;
+    /**
+     * The raster board `id` draws with: a melamine `surface` world units across at `density`
+     * texels a unit. Made on first ask and whenever the size or density changes — `true` then:
+     * it is blank, and the host replays the board's history into it.
+     */
+    ensure(id: number, surface: readonly [number, number], density?: number): boolean;
+    /**
+     * Would `ensure` make board `id`'s raster — none held (never made, or evicted), or another size or density (K6b: the frame raster
+     * queue's to make, in its turn)?
+     */
+    makes(id: number, surface: readonly [number, number], density?: number): boolean;
+    /** The thumbnails' EMPTY layer (K6b): taken and filled with nothing on first need; null when the device holds no more layers. */
+    private bareLayer;
+    /**
+     * A layer of the thumbnails' array (K9 R1) — the array's own while it has one; at the device's cap, RECLAIMED from the board
+     * that can best spare it: one whose raster the budget evicted (its thumbnail was its only ink on the device — replayed when it is
+     * next drawn, as after any eviction) and that was drawn neither in this frame nor the last, the least recently drawn of those;
+     * failing that, one of a board that HOLDS its raster (its thumbnail is cut again from it at its next commit or replay) drawn as
+     * long ago. Null when every thumbnail is a board's drawn lately — the caller draws without a layer, honestly.
+     */
+    private takeLayer;
+    /** Forget board `id` — its raster, its thumbnail's layer, its slot (it left the desk; a scene's board). */
+    release(id: number): void;
+    /**
+     * Let board `id`'s RASTER go and keep its thumbnail (the budget's eviction — the raster is a cache of its strokes, replayed
+     * when it is next wanted): destroyed, its slot freed.
+     */
+    evict(id: number): void;
+    /** Board `id`'s far-LOD thumbnail cut again from its raster's chain (the ink changed): its layer taken on the first cut. */
+    private cutThumb;
+    /** Is board `id`'s raster bound this frame (a pool slot, or the live one)? The budget keeps what is. */
+    bound(id: number): boolean;
+    /** The thumbnails' array: what it weighs on the device, its whole capacity (the GPU ledger's row). */
+    get thumbnailBytes(): number;
+    /** What the thumbnails' layers IN USE weigh — the budget's resident `board`/`thumbnails` charge (K9 R2). */
+    get thumbnailUsedBytes(): number;
+    /** The thumbnails' layers in use, and the array's capacity (K9 R5 — the kind's `stats`). */
+    get thumbnailLayers(): number;
+    get thumbnailCapacity(): number;
+    /** Has board `id` its far-LOD thumbnail (a layer, cut)? */
+    thumbed(id: number): boolean;
+    /** Board `id`'s raster density (texels a unit), or null without one. */
+    densityOf(id: number): number | null;
+    /**
+     * THE FRAME BOUNDARY (the kind's tick, before the next build): the slots of boards no frame asked for since the last step are
+     * freed (their rasters stay, a cache), the live slot of a board no longer laid on or wet; and the boards that asked for more
+     * than their raster holds — largest first, BOARD_RASTERS_A_STEP a step — are returned with the density to remake them at
+     * (the kind replays their strokes into it). Nothing is freed when nothing was drawn since the last step — a frame that drew only
+     * FAR boards (K7b: they ask nothing) frees the slots they held.
+     */
+    step(): {
+        readonly id: number;
+        readonly density: number;
+    }[];
+    /** The last frame's asks still unanswered (K7a): the next tick owes them a `step` — a slot freed, a board raised to its rung. */
+    get stepOwed(): boolean;
+    /** The raster's size in texels, or null. */
+    sizeOf(id: number): readonly [number, number] | null;
+    /** Is any board's ink still drying (the host keeps its clock awake)? */
+    get wetting(): boolean;
+    private clear;
+    private writeStampTool;
+    /** Stamp `count` stamps (from `data`) into the raster's stroke layer. The caller submits `enc` before the next upload. */
+    private stampInto;
+    /** Every stamp of `data`, in chunks: one upload and one submit each. */
+    private stampAll;
+    /** Lay the stroke layer into the ink (and, live, mark it wet), then clear the stroke layer. */
+    private composite;
+    /** The ink's mip chain, from level 0 down. */
+    private mips;
+    /** Queue stamps for the stroke being laid on board `id` (they reach its stroke layer at the next `prepare`). */
+    lay(id: number, tool: Tool, stamps: Float32Array): void;
+    /** Send the queued stamps now: one upload, one submit, per board with any. */
+    private flush;
+    /** The lift: the stroke's last stamps, laid into the ink, marked wet; the mips follow. */
+    commit(id: number, tool: Tool): void;
+    /** A stroke abandoned: its stamps dropped, its layer cleared. */
+    cancel(id: number): void;
+    /** The board's ink rebuilt from its history (history.ts `replay`): a cleared raster, every op in order, dry. */
+    replay(id: number, ops: readonly BoardOp[]): void;
+    /** Fresh ink dries: every wet raster's wet layer fades by `dt` seconds (sent at the next `prepare`). */
+    dry(dt: number): void;
+    /** The ink's bytes, level 0 — rgba8 premultiplied linear, row 0 the melamine's top (a harness's witness). */
+    readInk(id: number): Promise<{
+        width: number;
+        height: number;
+        bytes: Uint8Array;
+    } | null>;
+    /**
+     * Send what the host queued (stamps, the drying), then upload this frame's boards (in paint
+     * order) and the mat's block for this slot's camera and light: the dapple, the lamp's shading
+     * and the shadows. A board whose raster is missing is skipped. Returns the count that will draw.
+     */
+    prepare(view: View & {
+        readonly dpr: number;
+    }, fadeIn: FadeIn, cfg: MatConfig, frame: MatFrame | undefined, instances: readonly BoardInstance[], present: Presentation | undefined, light?: MatLight, theme?: GroundTheme, keys?: readonly number[], hand?: boolean): 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;
+    /** The wet layers' fading, sent: one pass each at the accumulated factor, or a clear once dry. */
+    private dryNow;
+    get drawn(): number;
+    /** Every board drawn this frame. */
+    draw(pass: GPURenderPassEncoder): void;
+    /**
+     * The boards `prepare` was handed at [first, end) — indices into ITS list, as the ground's runs count a
+     * kind's records (a board with no ink to show draws nothing) — as ONE instanced draw (K6a, K-L4): the
+     * slot's group and the pool's bound once, each board an instance whose record says where its ink is.
+     */
+    drawRange(pass: GPURenderPassEncoder, first: number, end: number): void;
+    /** This slot's buffers; the rasters and the stamp buffers go with the last slot standing. */
+    dispose(): void;
+}

package/dist/types/packages/objects/src/board/board-pen.d.ts

@@ -0,0 +1,36 @@
+import { type Component, type Entity, type World } from "../../../core/src/index";
+import { type BoardInk, type BoardObjectLook } from "./kind";
+import { type TypingDocs } from "../../../desk/src/index";
+export interface BoardPenOptions {
+    readonly world: World;
+    /** The document a stroke commits into — the facade's `engine.docs`. */
+    readonly docs: TypingDocs;
+    /** The board's props cell (its `cap`, its `tip`) — the object hands its own (D-D7-A.3); absent, the marker is black, the tip a bullet. */
+    readonly props?: Component | undefined;
+    /** The board kind's state on this desk (undefined before it is made). */
+    readonly ink: () => BoardInk | undefined;
+    /** The board kind's look for the theme in force (the markers' inks). */
+    readonly look: () => BoardObjectLook | undefined;
+    /** Is this entity a board (the desk's builder knows each entity's kind). */
+    readonly isBoard: (e: Entity) => boolean;
+    /** A point of the held object's own frame as a desk point, through the pose the last frame drew (the builder's). */
+    readonly heldToWorld: (e: Entity, x: number, y: number) => readonly [number, number] | undefined;
+    /** The geometry the board was drawn with in hand (the builder's). */
+    readonly geometryOf: (e: Entity) => unknown;
+    /** Where a transaction runs: out of the frame (a microtask) unless a test says. */
+    readonly defer?: (fn: () => void) => void;
+}
+export interface BoardPen {
+    /** Nothing to follow (D7 #14): no board in hand, no stroke laid, no marker to lie down. */
+    idle(): boolean;
+    /** Once a frame, before the kinds' clocks: the hand onto the board in hand, its stroke laid, lifted, committed. */
+    follow(now: number): void;
+    /** The stroke in hand: its board and how many samples so far; null when none. */
+    live(): {
+        readonly board: Entity;
+        readonly samples: number;
+    } | null;
+    /** Strokes committed since creation (a rig's witness). */
+    commits(): number;
+}
+export declare function createBoardPen(opts: BoardPenOptions): BoardPen;