@vibecook/ice 0.10.0 → 0.14.0

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

@@ -0,0 +1,34 @@
+import { type ServiceKey } from "./services";
+import type { HandLayout, HandMetrics } from "./text";
+/** r8 coverage rows, row 0 at the top — what the ink pages take (`PaperPass.write`). */
+export interface InkBitmap {
+    readonly bytes: Uint8Array<ArrayBuffer>;
+    readonly w: number;
+    readonly h: number;
+}
+export interface TextRaster {
+    /**
+     * The face's metrics in em (advances and kerning measured at 100 px, the box from the font's own
+     * ascent and descent) — `undefined` while the face loads: a sheet waits, blank, rather than write
+     * in a stand-in hand and re-write itself a moment later.
+     */
+    metrics(face: string): HandMetrics | undefined;
+    /** Bumped whenever a face lands: every layout keyed by it is laid again (the prototype's `fontVersion`). */
+    version(): number;
+    /**
+     * Tell `fn` whenever `version` moves — a face landed between frames (K7a: the desk wakes for it; a loop at rest polls no
+     * version). Returns an unsubscribe. Absent (a fake, a raster with fixed faces): the version never moves on its own.
+     */
+    onVersion?(fn: () => void): () => void;
+    /**
+     * Draw a layout's glyphs for a `box` (note units) at `band` texels per note unit: each glyph in its
+     * own frame — turned, scaled, at its pressure — over a faint stroke `bleed` note units wide (the pen's
+     * spread), the canvas's alpha read back as coverage.
+     */
+    raster(layout: HandLayout, face: string, box: {
+        readonly w: number;
+        readonly h: number;
+    }, band: number, bleed: number): InkBitmap;
+}
+/** The app's text raster as a desk SERVICE (K8a, kit/services.ts — `deskLayer({ text })` lends it): `host.use?.(TEXT_RASTER)`. */
+export declare const TEXT_RASTER: ServiceKey<TextRaster>;

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

@@ -0,0 +1 @@
+export declare const sdRoundBox: (px: number, py: number, bx: number, by: number, r: number) => number;

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

@@ -0,0 +1,11 @@
+/** The seeds as the cell stores them: base64 (no padding) of little-endian u32s. */
+export declare function encodeSeeds(seeds: ArrayLike<number>): string;
+/** The seeds a cell holds, as i32s (the layout's `seeds`) — whole seeds only; anything unreadable ends the run. */
+export declare function decodeSeeds(s: string): number[];
+/**
+ * The seeds a note's text is written with: the stored ones, index for index, and for every glyph
+ * past them the note's own `glyphSeed(noteSeed, i)` — exactly `text.length` of them.
+ */
+export declare function seedsFor(text: string, stored: string, noteSeed: number): number[];
+/** A fresh seed for a glyph just written — the host's randomness (`Math.random` in a browser). */
+export declare const freshSeed: () => number;

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

@@ -0,0 +1,34 @@
+/** A service's KEY (K8a): its name — the registry's identity — and, as a phantom, the type of what is lent under it. */
+export interface ServiceKey<T> {
+    readonly name: string;
+    /** Never set: carries `T` so `use(key)` answers the lent thing's own type. */
+    readonly __service?: T;
+}
+/** A key for a service of type `T` under `name` — namespace a plugin's own (`"clock.face"`); the desk's are bare words. */
+export declare const serviceKey: <T>(name: string) => ServiceKey<T>;
+/** One service as it is LENT: its key and the thing. Made by `service(key, value)`, which checks the pair's type. */
+export interface Lent<T = unknown> {
+    readonly key: ServiceKey<T>;
+    readonly value: T;
+}
+/** An entry to lend: `service(PRINT_RASTER, printRaster({ text }))`. */
+export declare const service: <T>(key: ServiceKey<T>, value: T) => Lent<T>;
+/** Where a service is found: `use(key)` answers what is lent under the key's name, or undefined — none on this desk. */
+export interface Services {
+    use<T>(key: ServiceKey<T>): T | undefined;
+}
+/**
+ * What an object's DOM half is handed to LEND (K8a): what is lent so far, and the desk's WAKE — a service whose work LANDS later (a
+ * face loaded, a picture decoded, a feed arrived) calls it when it does, so a sleeping loop steps and every kind is asked again (K7a's
+ * law: nothing is polled at rest; what arrives outside a step says so). The kinds that read the service see the landing in their tick.
+ */
+export interface LendHost extends Services {
+    wake(): void;
+}
+/** A registry of what has been lent so far (the desk layer's): `lend` adds entries — a name lent twice throws, naming both lenders. */
+export interface ServiceRegistry extends Services {
+    lend(entries: readonly Lent[], by: string): void;
+    /** The names lent, in lending order (a rig's and a test's witness). */
+    names(): readonly string[];
+}
+export declare function createServices(entries?: readonly Lent[], by?: string): ServiceRegistry;

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

@@ -0,0 +1,12 @@
+export declare function spring(x0: number, v0: number, target: number, hz: number, damping: number, dt: number, substeps?: number): [number, number];
+export declare function settled(x: number, v: number, target: number, eps?: number): boolean;
+/**
+ * The objects' springs: the hold's lift (the hover's rise rides the same numbers). The selection RING's spring is gone (D6): the
+ * kinds' own ring retired at D4a — the marks draw the selection — and a spring that only ever fed a zero kept the desk live for
+ * a second after every selection change (the D4a landing's owed item).
+ */
+export interface ObjectSprings {
+    readonly liftHz: number;
+    readonly liftDamp: number;
+}
+export declare const SPRINGS: ObjectSprings;

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

@@ -0,0 +1,93 @@
+import { type Entity, type GuardedTx, type World } from "../../../core/src/index";
+/** A board's data child: a stroke (`marker`, with `erase` for the eraser) or a wipe. */
+export declare const BoardStroke: import("@vibecook/strata-ecs").Component<import("@vibecook/strata-ecs").ValueOf<{
+    readonly tool: import("@vibecook/strata-ecs").FieldSpec<"string", true>;
+    readonly ink: import("@vibecook/strata-ecs").FieldSpec<"string", true>;
+    readonly tip: import("@vibecook/strata-ecs").FieldSpec<"string", true>;
+    readonly erase: import("@vibecook/strata-ecs").FieldSpec<"bool", true>;
+    readonly points: import("@vibecook/strata-ecs").FieldSpec<"string", true>;
+    readonly speed: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly times: import("@vibecook/strata-ecs").FieldSpec<"string", true>;
+    readonly page: import("@vibecook/strata-ecs").FieldSpec<"u32", true>;
+    readonly seed: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+}>, {
+    readonly tool: import("@vibecook/strata-ecs").FieldSpec<"string", true>;
+    readonly ink: import("@vibecook/strata-ecs").FieldSpec<"string", true>;
+    readonly tip: import("@vibecook/strata-ecs").FieldSpec<"string", true>;
+    readonly erase: import("@vibecook/strata-ecs").FieldSpec<"bool", true>;
+    readonly points: import("@vibecook/strata-ecs").FieldSpec<"string", true>;
+    readonly speed: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly times: import("@vibecook/strata-ecs").FieldSpec<"string", true>;
+    readonly page: import("@vibecook/strata-ecs").FieldSpec<"u32", true>;
+    readonly seed: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+}>;
+/** A stroke's cell as the board reads it (a tolerant reader: a string field strata hands back as null reads as its default). */
+export interface StrokeRow {
+    readonly tool: string | null;
+    readonly ink: string | null;
+    readonly tip: string | null;
+    readonly erase: boolean | null;
+    readonly points: string | null;
+    readonly speed: number | null;
+    readonly times?: string | null;
+    /** The notebook page it is on (D3t-b — v3): 2i + 1 a sheet's recto, 2i + 2 its verso; 0 (or absent, a v2 reader's) = none. */
+    readonly page?: number | null;
+    /** Its fibre seed (D7 #13 — v4): the one the live pen laid with; −1 (or absent, a v3 reader's) = the seed its position gives it. */
+    readonly seed?: number | null;
+}
+/** The durable id a stroke entity carries (`PrefabId`) — a data child, never a widget. */
+export declare const STROKE_TYPE = "desk.stroke";
+/**
+ * A stroke's durable prefab: its one cell and its `ChildOf` edge to the board (or the book) it is on. Version 2 (D3t-a) added
+ * `times`; a v1 stroke migrates to an empty one — it keeps its `speed` (the replay spaces it as before). Version 3 (D3t-b) added
+ * `page`; a v2 stroke — a board's — migrates to page 0. The Board and the Notebook declare it as their `data`, so the engine's
+ * catalog stamps, gates and migrates it with them.
+ */
+export declare const StrokePrefab: import("../../../core/src/index").Prefab;
+/** A row's fibre seed: its own (v4, the pen's) — or, for a row from before or without one, the `n`-th op's positional seed. */
+export declare const seedOfRow: (s: Pick<StrokeRow, "seed">, n: number) => number;
+/**
+ * A stroke as an author states one: the path in melamine units (a notebook's: page units, on its `page`) and its pace — each
+ * sample's time (ms from the first), or one speed; a wipe has no path.
+ */
+export interface StrokeSpec {
+    readonly tool?: "marker" | "wipe" | "pen";
+    readonly ink?: string;
+    readonly tip?: string;
+    readonly erase?: boolean;
+    readonly points?: readonly (readonly [number, number])[];
+    readonly times?: readonly number[];
+    readonly speed?: number;
+    /** The notebook page (D3t-b): 2i + 1 sheet i's recto, 2i + 2 its verso; absent = 0, a board's. */
+    readonly page?: number;
+    /** The fibre seed the pen laid with (D7 #13): stored, so the replay lays the same stamps whatever lands before it; absent = the position's. */
+    readonly seed?: number;
+}
+/** A path as the cell stores it: base64 (no padding) of LE f32 (x, y) pairs. */
+export declare function encodePoints(points: readonly (readonly [number, number])[]): string;
+/** A cell's path back: whole points only (a tolerant reader — anything unreadable ends the path). */
+export declare function decodePoints(s: string): Array<readonly [number, number]>;
+/** The samples' times as the cell stores them (D3t-a): base64 (no padding) of LE f32 milliseconds from the first sample. */
+export declare function encodeTimes(times: readonly number[]): string;
+/** A cell's times back (a tolerant reader: "" — an old stroke — is none). */
+export declare function decodeTimes(s: string): number[];
+/** A path's mean pace, world units/s — what a v2 stroke leaves in `speed` for a reader that knows no `times`; the default for a dot. */
+export declare function meanSpeed(points: readonly (readonly [number, number])[], times: readonly number[]): number;
+/** The row a spec is — defaults as the prefab has them; timed, its `speed` is the path's mean pace unless the spec names one. */
+export declare function strokeRow(s: StrokeSpec): {
+    tool: string;
+    ink: string;
+    tip: string;
+    erase: boolean;
+    points: string;
+    speed: number;
+    times: string;
+    page: number;
+    seed: number;
+};
+/** Lay a stroke on a board (or a book's page) — one entity, the object's newest child — inside the caller's transaction (one stroke, one undo step). */
+export declare function addStroke(tx: GuardedTx, board: Entity, s: StrokeSpec): Entity;
+/** The fibre seed of the `n`-th op a replay walks — the bench's `97.13 ×` the ops before it; the live pen seeds its stroke with the next. */
+export declare const strokeSeed: (n: number) => number;
+/** A stroke is in hand (a local pointer's press is a tool's): a history waits for it to land (BOARD.md §5 — the bench's `!this.open?.stroke`). */
+export declare function inking(world: World): boolean;

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

@@ -0,0 +1,142 @@
+export interface HandMetrics {
+    /** em above the baseline, em below — the face's own box. */
+    readonly ascent: number;
+    readonly descent: number;
+    /** A glyph's advance, em. */
+    advance(ch: string): number;
+    /** Optional pair kerning, em (negative tightens). */
+    kern?(a: string, b: string): number;
+}
+/** The hand's law (theme.ts `HAND`): the size in world units, and how far each glyph may stray. */
+export interface HandLaw {
+    /** The pen's size, world units (CSS px at zoom 1). */
+    readonly size: number;
+    /** Line pitch, × size. */
+    readonly lineHeight: number;
+    /** The margin the writing keeps from the paper's edge, world units. */
+    readonly pad: number;
+    readonly jitter: {
+        /** Each glyph's tilt, ± radians. */
+        readonly rot: number;
+        /** Each glyph's rise off the baseline, ± em. */
+        readonly rise: number;
+        /** Each glyph's size, ± fraction. */
+        readonly scale: number;
+        /** The pen's pressure — the ink's presence — between these. */
+        readonly press: readonly [number, number];
+    };
+    readonly wander: {
+        /** The line's slow drift, ± em. */
+        readonly amp: number;
+        /** …over this many em along the line. */
+        readonly period: number;
+    };
+}
+export interface HandGlyph {
+    readonly ch: string;
+    /** Its index in the text. */
+    readonly index: number;
+    /** The glyph's origin on its baseline, note units from the paper's top-left. */
+    readonly x: number;
+    readonly y: number;
+    /** The advance it takes, note units. */
+    readonly advance: number;
+    readonly rot: number;
+    readonly scale: number;
+    readonly press: number;
+    readonly line: number;
+}
+export interface HandLine {
+    /** Text indices [start, end). */
+    readonly start: number;
+    readonly end: number;
+    /** The baseline, note units. */
+    readonly y: number;
+    readonly width: number;
+}
+export interface HandLayout {
+    readonly glyphs: readonly HandGlyph[];
+    readonly lines: readonly HandLine[];
+    /** The caret's place BEFORE each index (and after the last): x, baseline y — `2 × (text.length + 1)`. */
+    readonly positions: Float32Array;
+    /** The writing ran past the bottom margin. */
+    readonly overflow: boolean;
+    /** The em, and the caret's height above and below the baseline. */
+    readonly em: number;
+    readonly ascent: number;
+    readonly descent: number;
+}
+/**
+ * Four floats in [0, 1) from a glyph's seed and its character — a 32-bit mix
+ * (Wang's hash twice, xorshift between) that changes wholly for a change of
+ * one bit in either. Deterministic across hosts: only integer arithmetic.
+ */
+export declare function hashHand(seed: number, code: number): readonly [number, number, number, number];
+/** A glyph's seed when the host carries none: the note's seed and the glyph's place. */
+export declare const glyphSeed: (noteSeed: number, index: number) => number;
+/**
+ * Lay `text` into a `box` (note units) under `law` with the face's `metrics`.
+ * `seeds[i]` is glyph i's own seed (the host's, carried through edits) — absent,
+ * it is derived from `noteSeed` and the index.
+ */
+export declare function layoutText(text: string, box: {
+    readonly w: number;
+    readonly h: number;
+}, law: HandLaw, metrics: HandMetrics, noteSeed?: number, seeds?: ArrayLike<number>): HandLayout;
+/** The caret before `index`: its left edge on the baseline, and its extent above and below. */
+export declare function caretAt(L: HandLayout, index: number): {
+    readonly x: number;
+    readonly y: number;
+    readonly above: number;
+    readonly below: number;
+};
+/** The box a glyph's ink can reach (its advance wide, the face's box tall, grown by the hand's jitter), note units — what the wipe reveals. */
+export declare function glyphBox(L: HandLayout, g: HandGlyph): {
+    readonly x0: number;
+    readonly y0: number;
+    readonly x1: number;
+    readonly y1: number;
+};
+/**
+ * The hand's seeds carried through an edit: the common prefix and suffix of
+ * the old and new text keep their seeds, the inserted run gets fresh ones from
+ * `fresh()`. Returns the new seeds and the inserted range [from, to).
+ */
+export declare function carrySeeds(oldText: string, oldSeeds: ArrayLike<number>, newText: string, fresh: () => number): {
+    seeds: number[];
+    from: number;
+    to: number;
+};
+/**
+ * The HAND — how the pen writes on the paper (STICKY.md §3; `paper/text.ts`). The face is
+ * the host's (the lab's Caveat, an OFL hand); its size is in world units; the jitter is
+ * each glyph's own — a tilt, a rise, a size, a pressure — and the line wanders slowly.
+ * The wipe is how a typed glyph arrives: revealed left to right in `wipeMs`, the pen's stroke.
+ */
+export declare const HAND: {
+    readonly size: 24;
+    readonly lineHeight: 1.16;
+    readonly pad: 16;
+    readonly jitter: {
+        readonly rot: 0.028;
+        readonly rise: 0.03;
+        readonly scale: 0.05;
+        readonly press: readonly [number, number];
+    };
+    readonly wander: {
+        readonly amp: 0.022;
+        readonly period: 9;
+    };
+    readonly wipeMs: 110;
+};
+/** The pens a hand writes with (STICKY.md §3) — names; the inks are the host's (the note's, and the desk calendar's lines). */
+export declare const PENS: readonly ["felt", "ball", "fountain", "red"];
+export type PenName = (typeof PENS)[number];
+/** A face: its family and weight, and the file it loads from (absent = the platform's own). */
+export interface FaceSpec {
+    readonly family: string;
+    readonly weight: number;
+    readonly url?: string;
+}
+/** The hand's faces by name (STICKY.md §3) — the families and weights; the app supplies the files (desk/host/ink.ts `penFaces`). */
+export declare const PEN_FACES: Readonly<Record<string, Omit<FaceSpec, "url">>>;

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

@@ -0,0 +1,8 @@
+import type { StructBuffer } from "../engine/struct";
+/** What a pass keeps beside a buffer it writes change-only: the bytes the GPU holds (sized to the buffer). */
+export declare const sentBytes: (size: number) => Uint8Array;
+/**
+ * Write `block` (its first `elements`, or all) into `buffer` at 0 only when its bytes differ from `sent` — which then holds
+ * them. Returns whether it wrote.
+ */
+export declare function writeChanged(queue: GPUQueue, buffer: GPUBuffer, block: StructBuffer<string>, sent: Uint8Array, elements?: number): boolean;

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

@@ -0,0 +1,39 @@
+import type { GlyphAtlasMeta } from "../mat/layout";
+export { type Box, type FadeIn, type Lod, lod, type View } from "../lattice/lod";
+export { type LineLaw, type LineWeight, lineWeight } from "../lattice/line";
+export type { RulerLaw } from "../lattice/ruler";
+export { DEFAULT_GRID, dressScale, type GridConfig } from "../mat/grid";
+export { type GlyphAtlasMeta, GLYPHS, litByOwn, type MatConfig, type MatFrame, MatUniforms, type PlateName, type RulerConfig, type SlotLight } from "../mat/layout";
+export type { Mat4 } from "../mat/projector";
+/** The silhouette a kind's marks go around (`ObjectKind.frame`) — the marks' own type (marks/layout.ts). */
+export type { MarkFrame } from "../marks/layout";
+/**
+ * A SLOT'S MAT as a kind's pass reads it: what the slot lends every kind drawn in it — the mat's animated silhouette (the
+ * lamp's gobo through the wind, this slot's own), the blue noise, the rulers' glyph atlas and its metrics, and the version
+ * of those assets (a pass rebinds when it turns over). `KindProgram.create` makes a kind's root pass on the root's; every
+ * other slot's pass is `spawn`ed onto that slot's. The ground's `CuttingMat` is the one there is; a kind never makes one.
+ */
+export interface MatPass {
+    /**
+     * The slot's ONE VIEW BLOCK (design-016 K-L3): a `MatUniforms` buffer the slot writes once a frame — the camera and box, the
+     * clocks, the lamp's gobo, the night, the portal chain, the objects' presence (`view.w`; the mat's own is `presence.x`) — which every kind pass binds at
+     * `@group(0) @binding(0)` as `u` (`kitWgsl`'s `view` piece). A kind never writes it and never keeps a copy.
+     */
+    readonly view: GPUBuffer;
+    /** The slot's animated gobo silhouette (r8, PLATE_SIZE²) — what an object's shadow and dapple sample. */
+    readonly silhouette: GPUTextureView;
+    /** The blue-noise tile (NOISE_SIZE², shared by every slot). */
+    readonly noiseTexture: GPUTexture;
+    /** The rulers' glyph atlas (a 1×1 empty cell until a host uploads one) and its metrics. */
+    readonly glyphTexture: GPUTexture;
+    readonly glyphs: GlyphAtlasMeta;
+    /** Turns over whenever a plate, the noise or the glyphs land: a pass holding a bind group over them rebinds. */
+    readonly assetVersion: number;
+    /**
+     * The view block's bytes as the slot last uploaded them, and the key of what the silhouette holds (K7a): a layered kind whose
+     * layer was drawn from the same bytes and key, with nothing of its own moved, lays it again without drawing it. Absent (a host's
+     * own mat): the layer is always drawn.
+     */
+    readonly viewBytes?: Uint8Array;
+    readonly silhouetteKey?: number;
+}

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

@@ -0,0 +1,15 @@
+import type { ComposeOptions } from "../engine/shader";
+import { type ShaderText } from "../shaders";
+export { type ShaderText, shaderText } from "../shaders";
+/** The kit's pieces of WGSL (below, in compose order). */
+export type KitWgslPiece = "view" | "portal" | "sdf" | "light" | "ruler" | "book";
+/** A name of the kit's WGSL: a piece, or another name for one (`lamp`, `gobo`, `night` and `noise` are `light`). */
+export type KitWgslName = KitWgslPiece | "lamp" | "gobo" | "night" | "noise";
+/** The .wgsl file behind each of the kit's module pieces — what a host's `ShaderText` is asked for. */
+export declare const KIT_WGSL_FILES: Readonly<Partial<Record<KitWgslPiece, string>>>;
+/**
+ * A kind's program with the kit's named pieces before its own: the kit's structs, then its modules (each labelled by its
+ * file, as a kind's own map labelled it), in the kit's order; then the kind's `own` structs, modules and entry. `text` is
+ * the host's (default: the generated module). An unknown name throws — a misspelt piece never composes silently.
+ */
+export declare function kitWgsl(names: readonly KitWgslName[], own: ComposeOptions, text?: ShaderText): ComposeOptions;

package/dist/types/packages/desk/src/lattice/line.d.ts

@@ -0,0 +1,15 @@
+import { type FadeIn } from "./lod";
+export interface LineLaw {
+    /** Half-widths at the window's top and a decade above it, DEVICE px (the reference's hairlines). */
+    readonly thin: number;
+    readonly thick: number;
+    /** Coverage alphas at the same two points. */
+    readonly alphaThin: number;
+    readonly alphaThick: number;
+}
+export interface LineWeight {
+    readonly halfWidth: number;
+    readonly alpha: number;
+}
+/** mat.wgsl `line_weight`, for a rung whose on-screen cell is `cellPx` (CSS px). */
+export declare function lineWeight(cellPx: number, fadeIn: FadeIn, law: LineLaw): LineWeight;

package/dist/types/packages/desk/src/lattice/lod.d.ts

@@ -0,0 +1,52 @@
+export declare const BASE_SPACING = 20;
+export declare const LOD_TARGET = 20;
+export declare const ZOOM_MIN = 1e-8;
+export declare const ZOOM_MAX = 100000000;
+export interface View {
+    readonly camX: number;
+    readonly camY: number;
+    readonly zoom: number;
+    /** CSS px — the attachment. */
+    readonly width: number;
+    readonly height: number;
+    /**
+     * The slot's BOX on the attachment, CSS px (PORTAL.md §2.3): what is
+     * culled — a mini mat's face for a nested slot.
+     * Absent = the whole attachment. Positions never change with it: a site
+     * lands where it lands under the camera; the box only decides which sites
+     * exist. A root slot's box is the attachment and every number is what it
+     * always was.
+     */
+    readonly box?: Box;
+}
+export interface Box {
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}
+/** The effective box: the view's own, or the attachment. */
+export declare const boxOf: (v: View) => Box;
+/** The `box` record the uniform blocks carry: x, y, w, h. */
+export declare const boxValues: (v: View) => number[];
+export interface Lod {
+    readonly k0: number;
+    readonly fade: number;
+    readonly fine: number;
+    readonly mid: number;
+    readonly coarse: number;
+    readonly wrapPeriod: number;
+}
+export declare const wrap: (v: number, p: number) => number;
+/**
+ * How a rung presents itself: ONE size for every rung, and a rung's alpha is
+ * `smoothstep(fadeIn, cellPx)` of its OWN cell — so a decade wrap (the fine rung
+ * becoming the mid rung at the same cell) is continuous by construction, and
+ * nothing is drawn below `fadeIn[0]` px of pitch: the product's classic-grid law
+ * (`worldGrid.fadeIn`). The prototype's size LADDER (fine 0.55× · mid 0.85→1.25×
+ * · coarse 1.55×, the fine rung's alpha the decade fade — every tenth site bigger,
+ * a size pop at every wrap) was retired on 2026-09-04; nothing of it remains.
+ */
+export type FadeIn = readonly [number, number];
+export declare const smoothstep: (a: number, b: number, x: number) => number;
+export declare function lod(v: View): Lod;

package/dist/types/packages/desk/src/lattice/ruler.d.ts

@@ -0,0 +1,88 @@
+import { type Lod } from "./lod";
+export interface RulerLaw {
+    /** CSS px: the band's width, and the mat's unprinted margin between the viewport's edge and the frame. */
+    readonly band: number;
+    readonly margin: number;
+    /** CSS px: the ticks' lengths — minor · medium · major. */
+    readonly tick: readonly [number, number, number];
+    /** CSS px: the width of every printed line — the ticks and the frame. */
+    readonly line: number;
+    /** Ink presence of the frame's lines, the ticks and the labels (1 = the mat's cream, full). */
+    readonly alpha: {
+        readonly frame: number;
+        readonly tick: number;
+        readonly label: number;
+    };
+    /** CSS px of pitch between which the fine rung's ticks (and its fifths) fade in. */
+    readonly ticksFrom: readonly [number, number];
+    /** CSS px of pitch between which a level's labels fade in. */
+    readonly labelsFrom: readonly [number, number];
+    /** The text: its size (CSS px — the atlas's em), its inset from the outer line, its gap after the tick. */
+    readonly text: {
+        readonly size: number;
+        readonly top: number;
+        readonly gap: number;
+    };
+    /** The most characters a label may have; a level whose labels would be wider than its pitch carries none. */
+    readonly maxChars: number;
+}
+/** One level of sites, with everything the pass draws for it this frame. */
+export interface RulerLevel {
+    /** World units between sites. */
+    readonly spacing: number;
+    /** CSS px between sites. */
+    readonly pitch: number;
+    /** A site's value is `index · mult · 10^exp` (index = its count from the world origin). */
+    readonly mult: 1 | 2;
+    readonly exp: number;
+    /** CSS px; the label pulls a tick to the major length as it appears. */
+    readonly tickLen: number;
+    readonly tickAlpha: number;
+    readonly labelAlpha: number;
+    /** The lattice's wrap period over this spacing — an exact integer (100 · 20 · 10 · 2 · 1). */
+    readonly perWrap: number;
+}
+export type RulerLevels = readonly [RulerLevel, RulerLevel, RulerLevel, RulerLevel, RulerLevel];
+/**
+ * The five levels this frame. `maxAbs` is the largest |value| a label on
+ * screen can carry (`labelReach`) — a level whose widest label would not fit
+ * its pitch carries none, so labels never overlap whatever the coordinates.
+ */
+export declare function rulerLevels(l: Lod, zoom: number, law: RulerLaw, maxAbs?: number): RulerLevels;
+/** A mono glyph's advance as a fraction of its em — the layout's estimate (the atlas carries the measured one; SF Mono is 0.6). */
+export declare const ADVANCE_EM = 0.6;
+/** The finest level that carries labels this frame, or -1 — the level the pass lays text out on. */
+export declare function finestLabelled(levels: RulerLevels): number;
+/** The lattice's wrap count of a camera coordinate: `cam = wraps · period + phase`, exact in doubles (lod.ts wraps the phase). */
+export declare const wrapsOf: (cam: number, period: number) => number;
+/**
+ * The text of a site's label: `index · mult · 10^exp`, plain digits — no
+ * suffixes (a "1k" that reads "1000" at the next zoom would change under the
+ * eye), and no trailing zeros in a fraction ("1.0" is "1" at every level, so
+ * a label's text never changes while it is visible). ruler.wgsl `ruler_char`
+ * is the same arithmetic per character.
+ */
+export declare function formatLabel(index: number, mult: 1 | 2, exp: number): string;
+/** How many characters the widest label of magnitude ≤ `maxAbs` takes at this level (the sign included). */
+export declare function labelChars(maxAbs: number, mult: 1 | 2, exp: number): number;
+/** The largest |world coordinate| a label along an axis can show: the far edge of the band's reach. */
+export declare function labelReach(cam: number, zoom: number, span: number): number;
+export interface RulerLabel {
+    /** The site's world coordinate and its count from the origin at the finest labelled level. */
+    readonly value: number;
+    readonly index: number;
+    /** CSS px along the axis where the site (its tick) stands. */
+    readonly at: number;
+    readonly text: string;
+    readonly alpha: number;
+    /** The site's level — the coarsest it lies on. */
+    readonly level: number;
+}
+/**
+ * The labels along one axis this frame, in order — the CPU mirror of what
+ * ruler.wgsl lays out, site for site: the finest labelled level's sites from
+ * the band's inner corner to the frame's far line, each with the alpha of the
+ * coarsest level it lies on. `cam` is the camera's UNWRAPPED coordinate;
+ * `span` the attachment's extent along the axis (CSS px).
+ */
+export declare function labelsAlong(cam: number, zoom: number, span: number, levels: RulerLevels, law: RulerLaw): RulerLabel[];

package/dist/types/packages/desk/src/marks/assemble.d.ts

@@ -0,0 +1,65 @@
+import { type LaserCamera, type WorldBar, type WorldBox, type WorldGuide } from "./laser";
+import { type MarkBox, type MarkFrame, type MarksInput } from "./layout";
+/** One object as its marks need it — the builder's cached facts and flux, or a still's. */
+export interface MarkedObject {
+    /** Its silhouette AS DRAWN, world units (the kind's `frame` on this frame's geometry). */
+    readonly frame: MarkFrame;
+    /** ICE's rect (Position + Size), unturned, world units — what the snap aligned and the vellum touches. */
+    readonly rect: WorldBox;
+    readonly selected: boolean;
+    /** Taped down (`Locked`): no knobs, and the vellum passes over it. */
+    readonly locked: boolean;
+    /** Carried (`Grab`): its knobs hide, and it is the laser's dragged set. */
+    readonly moving: boolean;
+    readonly resizable: boolean;
+    /** The selection's clocks: the lock-on's LINEAR progress and the presence (1 at rest; the leave fades it). */
+    readonly lock: {
+        readonly t: number;
+        readonly a: number;
+    };
+    /** The tape's clocks: each strip's press (0..1, linear) and the tape's presence (0 = none drawn). */
+    readonly tape: {
+        readonly press: readonly [number, number];
+        readonly a: number;
+    };
+}
+export interface MarksState {
+    readonly view: MarksInput["view"];
+    /** The ROOT slot's camera (`Camera.x/y` = the view's world top-left). */
+    readonly cam: LaserCamera;
+    readonly night: boolean;
+    /** The desk's objects in paint order. */
+    readonly objects: readonly MarkedObject[];
+    /** Several's union: its lock-on (linear) and presence. */
+    readonly union: {
+        readonly t: number;
+        readonly a: number;
+    };
+    /** The vellum being drawn: its WORLD rect (core's `MarqueeBuffer.rect`) and the cursor on screen. */
+    readonly marquee: {
+        readonly rect: WorldBox;
+        readonly pointer: {
+            readonly x: number;
+            readonly y: number;
+        } | null;
+    } | null;
+    /** The vellum released: its last rect ON SCREEN and the fold's linear progress. */
+    readonly fold: {
+        readonly rect: MarkBox;
+        readonly t: number;
+    } | null;
+    /** The snap's facts, world units (core's `GuideLine` / `SpacingBar`). */
+    readonly guides: readonly WorldGuide[];
+    readonly bars: readonly WorldBar[];
+    readonly strike: number;
+    /** The rulers printed on this desk (their margin and band, CSS px), or null. */
+    readonly ruler: {
+        readonly margin: number;
+        readonly band: number;
+    } | null;
+}
+/** The vellum's world rect, normalised (a drag may run any way). */
+export declare const normalBox: (b: WorldBox) => WorldBox;
+/** What the vellum touches — never the tape (Q-g); core's `queryHits` on the same rects. */
+export declare function vellumHits(objects: readonly MarkedObject[], rect: WorldBox): MarkedObject[];
+export declare function assembleMarks(s: MarksState): MarksInput;

package/dist/types/packages/desk/src/marks/ease.d.ts

@@ -0,0 +1,4 @@
+/** `--vf-ease-lift`: cubic-bezier(0.2, 0.9, 0.3, 1.2) — overshoots past 1 on the way. */
+export declare const easeLift: (x: number) => number;
+/** `--vf-ease-island`: cubic-bezier(0.25, 1, 0.3, 1). */
+export declare const easeIsland: (x: number) => number;