@vibecook/ice 0.11.0 → 0.14.0

package/dist/types/packages/objects/src/notebook/ink.d.ts

@@ -0,0 +1,70 @@
+import type { RGB } from "../../../desk/src/index";
+export interface InkPoint {
+    readonly s: number;
+    readonly y: number;
+    readonly w: number;
+}
+export interface InkStroke {
+    readonly colour: RGB;
+    readonly points: InkPoint[];
+}
+/** A page's ink: its strokes, and a version that moves whenever they change (a raster's key). */
+export interface PageInk {
+    strokes: InkStroke[];
+    version: number;
+}
+/** One page's raster: 1024 texels across its width (5.5 per world unit on the law's page), its height in proportion. */
+export declare const INK_W = 1024;
+export declare const INK_H = 1360;
+/** Page rasters on the device at once — the spread, a sheet or two in the air, a turn's neighbours. */
+export declare const INK_LAYERS = 8;
+/** Pages a book can name in its record's table (the spread and the sheets in the air). */
+export declare const INK_TABLE = 8;
+/**
+ * The pen's law: a nib `width` wide at a writing pace, thinning as it hurries (a fountain pen
+ * laying down less ink) and swelling slow — bounded both ways; a stylus's pressure, when the
+ * device has one, leads instead.
+ */
+export interface PenLaw {
+    readonly width: number;
+    readonly thin: number;
+    readonly thick: number;
+    readonly pace: number;
+}
+export declare const PEN: PenLaw;
+/** The nib's width at a speed (world units per second) and, from a stylus, a pressure in 0 … 1. */
+export declare function nibWidth(law: PenLaw, speed: number, pressure: number | null): number;
+/** A page point → its raster's texel (the page is `len` wide and `height` tall in world units). */
+export declare function texelOf(p: {
+    readonly s: number;
+    readonly y: number;
+}, len: number, height: number): readonly [number, number];
+/** Texels per world unit across the page — a nib's width in the raster. */
+export declare const texelsPerUnit: (len: number) => number;
+/**
+ * The nib's width at each sample (D3t-b) — the pen's law over the hand's pace, as the prototype's pen laid it (lab/notebook.ts
+ * `penTo`): the first at rest; each sample that moved at least `still` from the last that did takes 0.6 of that one's width and
+ * 0.4 of the law's at the pace between them; one nearer keeps the width it had (a resting pen neither swells nor thins — the
+ * prototype dropped such a sample, the data keeps it). Timed samples (ms from the first) read their own clocks; untimed ones are
+ * spaced by `speed` (world units/s) as the board's replay spaces an old stroke. Square roots and the four operations only: the
+ * widths are bit-identical wherever they are computed (the oracle's Node, the desk's Chrome).
+ */
+export declare function nibWidths(points: readonly (readonly [number, number])[], times: readonly number[] | null, speed: number, law?: PenLaw, still?: number): number[];
+/** A stroke's samples as the raster draws them: page units with the nib's width at each (`nibWidths`). */
+export declare function inkPoints(points: readonly (readonly [number, number])[], times: readonly number[] | null, speed: number, law?: PenLaw): InkPoint[];
+/** The page a side of the open spread shows (D3t-b): the right is its top sheet's recto (2i + 1), the left its top sheet's verso (2i + 2); null — an endpaper. */
+export declare function pageOfSide(pose: {
+    readonly rightTop: number;
+    readonly leftTop: number;
+}, side: 0 | 1): number | null;
+/**
+ * The pages in view (the prototype's `drawBooks`): once the cover stands past the vertical, the spread — its left page, then its
+ * right — and both faces of every sheet in the air (a turn, the peek); none while the book is shut.
+ */
+export declare function pagesInView(pose: {
+    readonly rightTop: number;
+    readonly leftTop: number;
+    readonly airs: readonly {
+        readonly index: number;
+    }[];
+}, swing: number): number[];

package/dist/types/packages/objects/src/notebook/kind.d.ts

@@ -0,0 +1,236 @@
+import { type Entity, type HeldToolApi, type HeldToolDef } from "../../../core/src/index";
+import { type MatPass, type MarkFrame, type DeskEye, type BuiltMesh, MeshWriter, type Rigid, type ShaderText, LayeredKind } from "../../../desk/src/kit/index";
+import { type KindPass, type KindProgram, type SlotContext, type Palette, type RGB, type RGBA, type TokenRef, type KindHost, type KindLocal, type ObjectHit, type ObjectKind } from "../../../desk/src/index";
+import { type NotebookLaw } from "./law";
+import { type NotebookLook } from "./layout";
+import { type NotebookMotion } from "./motion";
+import { type InkTable, type LiveStroke, PageInk, type PageStroke } from "./pages";
+import { type NotebookDraw, NotebookPass } from "./pass";
+import { type NotebookHit } from "./pick";
+import { type Frame, type NotebookPose } from "./shape";
+/** The notebook's kind name — its key in the registry and in every slot's `objects`. */
+export declare const NOTEBOOK_KIND = "notebook";
+export declare class NotebookKind extends LayeredKind<NotebookDraw, NotebookPass> {
+    /** The notebook's law — its eye, its light and shadow, its lift: the host's (a lab's panel edits it); `NOTEBOOK` until one says. */
+    law: NotebookLaw;
+    /** The ruling's ink and its presence on the page — the PRODUCT's colour (the theme gate): a host sets it before a book draws. */
+    ruleInk: RGBA | null;
+    /** Root only (D-D18): a spawned slot's pass — a mini mat's inside, a flight's departed desk — holds nothing and draws nothing. */
+    spawn(_mat: MatPass): NotebookKind;
+    /**
+     * A slot's own pass of this kind takes the ROOT's host-set state before it prepares (its law and the ruling's ink): a spawned pass draws nothing, but a
+     * slot that made its own from the program — the tray's specimen (design-017 §8, K5a) — draws with the desk's.
+     */
+    tune(root: KindPass<unknown>): void;
+    /** The pass's own `prepare`, as the prototype's lab called it: the slot's camera, grid, clocks and light, the desk eye over the slot's view, the law, the colours. */
+    protected prepareOwn(pass: NotebookPass, s: SlotContext, records: readonly NotebookDraw[]): number;
+}
+/** The notebook's program for a host's shader text: its pass made on the root's mat; its objects one composite run, last in `things`. */
+export declare function notebookProgram(text: ShaderText): KindProgram<NotebookDraw>;
+/**
+ * What the notebook's kind takes from the host's palette (NOTEBOOK.md's covers): the page, the ruling's ink and its
+ * presence, and each cover by name — its cloth, band, three accents, endpaper, its design and whether it is paper. Its
+ * pens' inks (D3t-b) are the note's — the palette's `pens` (kinds/paper.ts `PaperPalette`), by name.
+ */
+export interface NotebookPalette extends Palette {
+    readonly notebooks?: {
+        readonly paper: TokenRef;
+        readonly ink: TokenRef;
+        /** The ruling's presence on the page (the dots, the rules), 0 … 1. */
+        readonly rule: number;
+        readonly covers: Readonly<Record<string, {
+            readonly cloth: TokenRef;
+            readonly band: TokenRef;
+            readonly a: TokenRef;
+            readonly b: TokenRef;
+            readonly c: TokenRef;
+            readonly endpaper: TokenRef;
+            readonly design: NotebookLook["design"];
+            readonly paperCover: boolean;
+        }>>;
+    };
+    readonly pens?: Readonly<Record<string, TokenRef>>;
+}
+/** The notebook's look for a theme, parsed: each cover's `NotebookLook`, the ruling's ink with its presence; the pens' inks (sRGB) and each pen tool's swatch (D3t-b). */
+export interface NotebookObjectLook {
+    readonly covers: Readonly<Record<string, NotebookLook>>;
+    readonly ruleInk: RGBA;
+    readonly pens: Readonly<Record<string, RGB>>;
+    readonly swatches: Readonly<Record<string, string>>;
+}
+/** A book's still, pinned on the kind's own state (a FLUX pin — D-D2a-world.5): open (or a swing, 0 … 1), a sheet mid-turn, the peek, the tilt. */
+export interface BookPose {
+    readonly open?: boolean | number;
+    readonly turn?: {
+        readonly dir: 1 | -1;
+        readonly phi: number;
+        readonly psi: number;
+        readonly twist?: number;
+    };
+    readonly peek?: number;
+    readonly tilt?: readonly [number, number];
+}
+/** A book as the builder resolved it: what its record draws, and what its hit reads — the same eye the pass draws with. */
+export interface NotebookGeometry {
+    readonly frame: Frame;
+    readonly pose: NotebookPose;
+    readonly mesh: BuiltMesh;
+    readonly version: number;
+    readonly rigid: Rigid;
+    readonly lamp: readonly [number, number, number];
+    readonly theta: number;
+    readonly ring: number;
+    readonly eye: DeskEye;
+    readonly fade: number;
+    /** Where it lies: the case's centre on the mat and its turn (the placement's, before the lift and the tilt). */
+    readonly cx: number;
+    readonly cy: number;
+    readonly angle: number;
+    /** In hand (D3t-b): its hit answers parts — a turn, the pen's page, the case. */
+    readonly held: boolean;
+    /** Its pages can turn (open, the cover landed) — the turn parts exist only then. */
+    readonly turnable: boolean;
+    /** The law it was resolved under (the hit, the hand's pick). */
+    readonly law: NotebookLaw;
+}
+/** The notebook's own state on one desk: each book's id, mesh and pinned pose, the carry's tilt; the ruling's ink on the root pass; in hand (D3t-b) its sheets' motion, the pen's stroke and the pages' ink. */
+export interface Books extends KindLocal {
+    /** When the kind is next live (K7a — `KindLocal.due`, declared: the six built-ins all say). */
+    due(now: number): number;
+    /** A still's pose on `e` (undefined unpins). */
+    pin(e: Entity, pose: BookPose | undefined): void;
+    /** The world half's: the book's pin and its tilt state. */
+    state(e: Entity): BookState;
+    /** The world half's: the mesh for a pose, rebuilt only when the pose moved. */
+    meshFor(e: Entity, F: Frame, pose: NotebookPose, law: NotebookLaw): {
+        readonly mesh: BuiltMesh;
+        readonly version: number;
+    };
+    /** The world half's: the ruling's ink on the root pass — the product's colour (the theme gate). */
+    ink(rule: RGBA): void;
+    /** The pages' ink on this desk — the pass's eight layers, a cache of the strokes (a witness's door: its replays, a page's raster). */
+    readonly pages: PageInk;
+    /** A book's strokes on a page as its raster draws them — the children's, in order, then the stroke the pen lifted until it lands. */
+    strokesOn(e: Entity, page: number): readonly PageStroke[];
+    /** The world half's: the ink table for a resolved book — its pages in view with ink, each on a layer, brought up to its strokes. */
+    table(e: Entity, G: NotebookGeometry, look: NotebookObjectLook): InkTable;
+    /** The pen (D3t-b): its stroke in hand on `e` — begun (its samples grow in place, laid a segment at a time) or dropped (null). */
+    write(e: Entity, live: LiveStroke | null): void;
+    /** The pen lifted its stroke, whose cell will read `key`: drawn to its end, then ADOPTED when its child lands (no replay). */
+    lift(e: Entity, key: string): void;
+    /** Its transaction was refused (a read-only document, the book gone): the page is its children's again. */
+    refuse(e: Entity): void;
+    /** The spread the hand asks for (a turn by hand, a click, a key), until its transaction lands; null — the document's again. */
+    ask(e: Entity, spread: number | null): void;
+    /** The hand moved the book's sheets (a sheet in the hand, the peek): the next frame builds. */
+    stir(e: Entity): void;
+    /** On a portrait phone, the page of the spread in view (D3t-b — page by page): 0 the right, 1 the left; sprung (the view glides to it). */
+    face(e: Entity, side: 0 | 1): void;
+}
+interface BookState {
+    readonly id: number;
+    pose: BookPose | undefined;
+    /** The carry's tilt (radians about x and y), sprung into the rect's motion; where the rect was. */
+    tiltX: number;
+    tiltXV: number;
+    tiltY: number;
+    tiltYV: number;
+    lastX: number;
+    lastY: number;
+    /** The cover IN HAND (D4b): its swing 0 shut … 1 open on the hand's spring, and its velocity. */
+    coverT: number;
+    coverV: number;
+    writer: MeshWriter | null;
+    mesh: BuiltMesh | null;
+    key: string;
+    version: number;
+    /** IN HAND (D3t-b): the sheets' motion, kept from frame to frame (null on the desk and in a still). */
+    motion: NotebookMotion | null;
+    /** The spread the hand asked for, until the document says it (null: the document's). */
+    pending: number | null;
+    /** The pen's stroke in hand, and the one it lifted until its child lands (with the page's stroke count at the lift). */
+    live: LiveStroke | null;
+    adopt: {
+        readonly page: number;
+        readonly stroke: PageStroke;
+        readonly at: number;
+    } | null;
+    /** The book's strokes by page, as of the children's stamp — and each decoded once (by `pageStrokeKey`), kept while it is the book's. */
+    byPage: Map<number, PageStroke[]>;
+    decoded: Map<string, PageStroke>;
+    stamp: number;
+    /** The last frame in hand moved a sheet or the peek, or has turns to go: the next asks a frame too. */
+    stirring: boolean;
+    /** The phone's page in view (0 the right … 1 the left), sprung toward `faceT`. */
+    face: number;
+    faceV: number;
+    faceT: 0 | 1;
+}
+/** The notebook's `local()`. */
+export declare function createBooks(host: KindHost): Books;
+/** A page of the law's book, open: its width out of the gutter and its height, page units — what a page's raster spans (`INK_W × INK_H`). */
+export declare const NOTEBOOK_PAGE: {
+    readonly len: number;
+    readonly height: number;
+};
+/** A book's DEFAULT turn on the mat when a host lays one: the lab's `makeBook` (never set down quite square). */
+export declare const bookAngle: (seed: number) => number;
+/**
+ * How far a book's drawing reaches past its closed case, world units: the open spread to its left (a cover and the
+ * spine), the lift (held and opening) seen through the desk eye and cast along the lamp's capped slope, blurred.
+ */
+export declare function notebookReach(law?: NotebookLaw): number;
+/**
+ * A book's silhouette for the desk's marks (D4a — the brackets, a member's ticks, the tape): the footprint of its case on
+ * the mat at its turn — the closed case W × H about the book's centre and, as the cover swings over, the cover's own
+ * footprint beside it (open, the whole spread) — with the fore-edge's corner. The height's parallax aside, as the print's:
+ * the marks go around where the book LIES. The oracle's marks read the same function (oracle/frame.mjs).
+ */
+export declare function bookFrame(F: Frame, theta: number, cx: number, cy: number, angle: number): MarkFrame;
+/** The notebook's silhouette on a resolved book (`bookFrame` on its geometry). */
+export declare const notebookFrame: (G: NotebookGeometry) => MarkFrame;
+/** The page (and where on it) under a desk point of a resolved book — the pick through the SAME eye the pass drew it with (the hand's). */
+export declare const pageHitAt: (G: NotebookGeometry, wx: number, wy: number) => NotebookHit | null;
+/** A page hit's share of the page that TURNS it (the outer `turnZone` of its length — NOTEBOOK.md §7). */
+export declare const inTurnZone: (h: NotebookHit, law: NotebookLaw) => boolean;
+/**
+ * A held book's PART under a hit (D3t-b): a page's outer 30 % that has a sheet to turn — `turn`; the rest of a page that takes
+ * ink — `content`, the pen's (a mode in hand makes a press there the tool's); the case, the endpapers — `frame`, the book itself
+ * (two taps put it down — the notebook's case rule).
+ */
+export declare function partOf(G: NotebookGeometry, h: NotebookHit): ObjectHit;
+/** The pens a notebook is written with — the NOTE's (objects/note.ts `PENS`, STICKY.md §3): names; the inks are the host's. */
+export declare const NOTEBOOK_PENS: readonly ["felt", "ball", "fountain", "red"];
+/** The pen in hand when a book is picked up (the note's own default). */
+export declare const DEFAULT_PEN = "fountain";
+/** A pen's tool id in the held bar ("pen:fountain"). */
+export declare const penToolId: (pen: string) => string;
+/** The pen a tool id names, or undefined. */
+export declare const penOfTool: (id: string) => string | undefined;
+/**
+ * Runtime, on the notebook in hand (D3t-b): the pages the keys and the bar asked to turn — a running count, +1 a page on, −1 a
+ * page back. The hand (objects/leaf.ts) turns by what the count moved since it last looked: a tool writes a fact, the hand
+ * turns (a spread of turns — a sheet each frame — fans; on a portrait phone a step is ONE page). The user's, never the document's.
+ */
+export declare const PageTurns: import("@vibecook/strata-ecs").Component<import("@vibecook/strata-ecs").ValueOf<{
+    readonly n: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+}>, {
+    readonly n: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+}>;
+/** Ask for a turn: the count moves by `dir` (a tool's op — a runtime write, as the tool in hand is). */
+export declare function askTurn(api: Pick<HeldToolApi, "world" | "entity">, dir: 1 | -1): void;
+/**
+ * The notebook's tools in hand (*Marks on the Mat* v2's held bar, `heldBarHTML`): ‹ and › (← → and PageUp/PageDown) — a page
+ * back, a page on; the four pens (`1`–`4`) — MODES, the tool in hand, the cursor a crosshair over a page (NOTEBOOK.md §7); undo
+ * (⌘Z) and, on keys alone, redo (⇧⌘Z) — the DOCUMENT's history over the book's strokes (a stroke is one transaction), waiting
+ * for a stroke in hand to land. A turn is never on the undo stack (D-D3t-b.2): ⌘Z takes back ink, never a page.
+ */
+export declare const NOTEBOOK_TOOLS: readonly HeldToolDef[];
+export interface NotebookKindOptions {
+    readonly text?: ShaderText;
+    /** The notebook's numbers (notebook/law.ts `NOTEBOOK`) — the engine's unless a host tweaks them. */
+    readonly law?: NotebookLaw;
+}
+/** The notebook's kind, whole (kinds/world.ts `ObjectKind`): the program, and the world half on the lab's own book. */
+export declare function notebookKind(opts?: NotebookKindOptions): ObjectKind<NotebookGeometry, NotebookDraw, NotebookObjectLook>;
+export {};

package/dist/types/packages/objects/src/notebook/law.d.ts

@@ -0,0 +1,129 @@
+export interface NotebookLaw {
+    /** The case: the cover's width × height, a board's thickness, its fore-edge corner radius. */
+    readonly cover: {
+        readonly width: number;
+        readonly height: number;
+        readonly board: number;
+        readonly radius: number;
+    };
+    /** The text block: sheets and their thickness; the squares (the case's overhang past the pages); the joint (the gap between the spine and the first page when closed); a page's fore-edge corner radius. */
+    readonly block: {
+        readonly sheets: number;
+        readonly sheet: number;
+        readonly square: number;
+        readonly joint: number;
+        readonly radius: number;
+    };
+    /** The quarter binding: the spine band's width on the face; the spine's bulge when closed. */
+    readonly spine: {
+        readonly band: number;
+        readonly bulge: number;
+    };
+    /**
+     * The GUTTER, open: every sheet is bound at one line and rises from it to its own height in the
+     * stack. A sheet leaves the binding at `entry0 + entryPer · rise` radians (at most `entryMax`) and
+     * bends flat — so a thick stack climbs steeply out of the valley and a thin one barely dips, and
+     * the upper sheets' fore-edges are drawn in toward the gutter more than the lower ones' (the fan
+     * a real open notebook shows). `dip` is the least a page falls into the valley even when its
+     * stack is thin (the binding pulls every page down).
+     */
+    readonly gutter: {
+        readonly entry0: number;
+        readonly entryPer: number;
+        readonly entryMax: number;
+        readonly dip: number;
+    };
+    /**
+     * The desk EYE: the camera stays top-down, but what rises off the mat is seen from a point above
+     * the view's centre, so a lifted book grows and a standing cover keystones — the desk plane
+     * itself maps exactly as the ortho camera maps it. The eye stands `k` view-diagonals up (a fixed
+     * field of view when zoomed out), never nearer than `min` world units (the perspective of a book
+     * held close stays a book's, not a fish-eye's).
+     */
+    readonly eye: {
+        readonly k: number;
+        readonly min: number;
+    };
+    /** The lamp's shading: the sky's share where the lamp is blocked or faced away, and how far a face turned toward it may brighten over a flat one. */
+    readonly light: {
+        readonly ambient: number;
+        readonly cap: number;
+    };
+    /**
+     * The SHADOW — the desk's one law (the note's, PAPER.shadow, and the photo's): a penumbra σ at
+     * contact that grows per unit of height between the caster and the receiver; its darkness on
+     * the mat; the slope's cap (a book far from the lamp keeps a finite shadow). Plus a CONTACT term
+     * (ambient occlusion where the case meets the mat) that lets go as the book rises.
+     */
+    readonly shadow: {
+        readonly sigma0: number;
+        readonly perUnit: number;
+        readonly alpha: number;
+        readonly slopeMax: number;
+        readonly contact: {
+            readonly sigma: number;
+            readonly alpha: number;
+            readonly reach: number;
+        };
+    };
+    /** How much of the leaves' dapple a page takes (1 = the mat's own) — the palm must not blind the writing. */
+    readonly dapple: {
+        readonly page: number;
+        readonly cover: number;
+    };
+    /** The lift: a held book rises `held` units and tilts into its motion (radians per unit of CSS px/s, capped). Opening, it rises `open` units while the cover stands, and settles as it lands. Under the pointer a closed book rises `hover` — an invitation to pick it up. */
+    readonly lift: {
+        readonly held: number;
+        readonly open: number;
+        readonly hover: number;
+        readonly tiltPer: number;
+        readonly tiltMax: number;
+    };
+    /** The springs (Hz, damping ratio): the cover's swing, a sheet's root and its free edge, the lift, the tilt, the corner's peek, the ring. */
+    readonly springs: {
+        readonly cover: readonly [number, number];
+        readonly root: readonly [number, number];
+        readonly edge: readonly [number, number];
+        readonly lift: readonly [number, number];
+        readonly tilt: readonly [number, number];
+        readonly peek: readonly [number, number];
+        readonly ring: readonly [number, number];
+    };
+    /** A sheet's bend: how its angle travels from the root to the free edge (1 = a circular arc; more = the edge curls most). */
+    readonly bend: number;
+    /** The corner's peek on hover: the free edge's lift (rad) and the twist that keeps it to one corner; the zone that invites it (units from the corner). */
+    readonly peek: {
+        readonly angle: number;
+        readonly twist: number;
+        readonly zone: number;
+    };
+    /** A page's outer share that turns it on a click (the rest of the page is for the pen). */
+    readonly turnZone: number;
+    /** The flutter as a book lands open: the first sheets' kick (rad/s), falling off by sheet. */
+    readonly flutter: {
+        readonly kick: number;
+        readonly sheets: number;
+    };
+    /** The paper: fibre and mottle (±/255), the tooth's relief, the cockle (units), the ruling (units). */
+    readonly paper: {
+        readonly fibre: number;
+        readonly mottle: number;
+        readonly tooth: number;
+        readonly cockle: number;
+        readonly pitch: number;
+        readonly dot: number;
+        readonly margin: number;
+    };
+    /** The cloth: the weave's pitch (units), its relief, the sheen (blinn exponent, strength). */
+    readonly cloth: {
+        readonly pitch: number;
+        readonly relief: number;
+        readonly sheen: readonly [number, number];
+    };
+    /** The selection ring on the mat around a selected book: offset from the footprint, width (CSS px). */
+    readonly ring: {
+        readonly offset: number;
+        readonly width: number;
+    };
+}
+export declare const NOTEBOOK: NotebookLaw;

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

@@ -0,0 +1,46 @@
+import type { RGB, RGBA } from "../../../desk/src/index";
+import type { NotebookLaw } from "./law";
+export { NbBook, NbUniforms } from "../../../desk/src/kit/index";
+export declare const MAX_NOTEBOOKS = 32;
+/** Books with a shadow map of their own (the rest cast the contact only). */
+export declare const MAX_SHADOWED = 8;
+export declare const SHADOW_RES = 1024;
+export type Ruling = "plain" | "dots" | "rules" | "grid";
+export declare const RULINGS: readonly Ruling[];
+export type Design = "plain" | "orbit" | "tiles" | "label" | "bordered";
+export declare const DESIGNS: readonly Design[];
+/**
+ * A notebook's LOOK — the host's colours (lab/theme.ts `NOTEBOOK_LOOK`) and its choices: the
+ * cloth, the band, three accents the design prints with, the endpaper, the page, the print's
+ * ink; the design; whether the cover is paper rather than cloth.
+ */
+export interface NotebookLook {
+    readonly cloth: RGB;
+    readonly band: RGB;
+    readonly accents: readonly [RGB, RGB, RGB];
+    readonly endpaper: RGB;
+    readonly paper: RGB;
+    readonly ink: RGB;
+    readonly design: Design;
+    readonly paperCover: boolean;
+}
+export declare const rulingCode: (r: Ruling) => number;
+export declare const designCode: (d: Design) => number;
+/** The pass's knobs by name, from the law and the host's colours. */
+export declare function nbUniformValues(law: NotebookLaw, eye: {
+    eye: number[];
+    view: number[];
+}, dpr: number, cast: RGB, select: RGB, ruleInk: RGBA): {
+    eye: number[];
+    view: number[];
+    light: number[];
+    shadow: number[];
+    shadow2: number[];
+    paper: number[];
+    rule: number[];
+    cloth: number[];
+    castCol: number[];
+    select: number[];
+    ruleInk: number[];
+    ring: number[];
+};

package/dist/types/packages/objects/src/notebook/leaf.d.ts

@@ -0,0 +1,44 @@
+import { type Component, type Entity, type World } from "../../../core/src/index";
+import { type Books } from "./kind";
+import { type TypingDocs } from "../../../desk/src/index";
+/** The notebook's props cell (`desk.notebook:props` — its `spread` the durable fact a completed turn moves). */
+export interface NotebookHandOptions {
+    readonly world: World;
+    /** The document a stroke commits into — the facade's `engine.docs`. */
+    readonly docs: TypingDocs;
+    /** The notebook's props cell (its `spread`) — the object hands its own (D-D7-A.3); absent, the spread reads 0. */
+    readonly props?: Component | undefined;
+    /** The notebook kind's state on this desk (undefined before it is made). */
+    readonly books: () => Books | undefined;
+    /** Is this entity a notebook (the desk's builder knows each entity's kind). */
+    readonly isBook: (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 book 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 NotebookHand {
+    /** Once a frame, before the kinds' clocks: the hand onto the book in hand — its stroke laid, lifted, committed. */
+    follow(now: number): void;
+    /** Nothing to follow (D7 #14): no book in hand, no stroke laid, no turn in progress. */
+    idle(): boolean;
+    /** The stroke in hand: its book, its page and how many samples so far; null when none. */
+    live(): {
+        readonly book: Entity;
+        readonly page: number;
+        readonly samples: number;
+    } | null;
+    /** Strokes committed since creation (a rig's witness). */
+    commits(): number;
+    /** The turn in the hand: its book, the side it was taken from, the sheet held (null until the hand has travelled); null when none. */
+    turning(): {
+        readonly book: Entity;
+        readonly side: 0 | 1;
+        readonly sheet: number | null;
+    } | null;
+    /** Spreads written since creation — each completed turn one transaction (a rig's witness). */
+    turns(): number;
+}
+export declare function createNotebookHand(opts: NotebookHandOptions): NotebookHand;

package/dist/types/packages/objects/src/notebook/mesh.d.ts

@@ -0,0 +1,20 @@
+import { type BuiltMesh, type MeshWriter } from "../../../desk/src/kit/index";
+import type { NotebookLaw } from "./law";
+import { type Frame, type NotebookPose } from "./shape";
+/** The materials, by the number a vertex carries. */
+export declare const MAT: {
+    readonly cover: 0;
+    readonly endpaper: 1;
+    readonly board: 2;
+    readonly page: 3;
+    readonly edge: 4;
+    readonly spine: 5;
+    readonly ribbon: 6;
+};
+export { type BuiltMesh, FLAG_TWO_SIDED, MeshWriter, VERTEX_BYTES, VERTEX_FLOATS } from "../../../desk/src/kit/index";
+/**
+ * The whole notebook for a pose, into the writer (reset first). The back board never moves;
+ * the front board swings on the spine's arc; the stacks sit on their boards; the sheets in the
+ * air turn between them. Bounds are tracked as it writes.
+ */
+export declare function buildMesh(m: MeshWriter, F: Frame, pose: NotebookPose, law: NotebookLaw): BuiltMesh;

package/dist/types/packages/objects/src/notebook/motion.d.ts

@@ -0,0 +1,107 @@
+import type { NotebookLaw } from "./law";
+import type { NotebookPose } from "./shape";
+export interface SheetMotion {
+    /** Where it rests, or is heading when in the air: 0 right, 1 left. */
+    side: 0 | 1;
+    air: boolean;
+    phi: number;
+    phiV: number;
+    psi: number;
+    psiV: number;
+    tw: number;
+    twV: number;
+    /** Held by the pointer: the pinch's angle (and its pace, from the hand) set the sheet; its twist follows the hand. */
+    held: boolean;
+    psiT: number;
+    twT: number;
+    /** The held sheet's pinch angle, its pace (rad/s, smoothed), and the side it was taken from. */
+    grip: number;
+    gripV: number;
+    from: 0 | 1;
+}
+export interface NotebookMotion {
+    opened: boolean;
+    theta: number;
+    thetaV: number;
+    held: boolean;
+    lift: number;
+    liftV: number;
+    /** The tilt (radians about x and y) and where the hand's motion asks it to be. */
+    tiltX: number;
+    tiltXV: number;
+    tiltY: number;
+    tiltYV: number;
+    tiltTX: number;
+    tiltTY: number;
+    selected: boolean;
+    ring: number;
+    ringV: number;
+    sheets: SheetMotion[];
+    /** The corner's peek: its amount and which corner (+1 the tail's, −1 the head's). */
+    peek: number;
+    peekV: number;
+    peekOn: boolean;
+    peekSide: 1 | -1;
+    /** The landing flutter has played for this opening. */
+    fluttered: boolean;
+    /** The pointer is over the (closed) book: it rises a little. */
+    hover: number;
+    hoverV: number;
+    hoverOn: boolean;
+}
+/** A notebook at rest: closed (or open), `left` sheets turned. */
+export declare function newMotion(sheets: number, left?: number, opened?: boolean): NotebookMotion;
+/** The lowest index resting on the right — its recto is the right page; −1 when none. */
+export declare function rightTop(m: NotebookMotion): number;
+/** The highest index resting on the left — its verso is the left page; −1 when none. */
+export declare function leftTop(m: NotebookMotion): number;
+/** Sheets resting on each side. */
+export declare function counts(m: NotebookMotion): {
+    right: number;
+    left: number;
+};
+/** The spread as a reader names it: the left page's number (0 = the endpaper) and the right's. */
+export declare function spreadOf(m: NotebookMotion): {
+    left: number;
+    right: number;
+};
+export declare const anyAir: (m: NotebookMotion) => boolean;
+/** A page may turn only in an open book whose cover has landed. */
+export declare const turnable: (m: NotebookMotion) => boolean;
+/**
+ * Turn a page: forward (+1) lifts the right stack's top sheet, back (−1) the left's. A turn the
+ * other way while sheets are still flying the first way sends the last of them back instead —
+ * sheets are bound in order and can never cross. The edge is kicked up first. False when
+ * there is nothing to turn.
+ */
+export declare function turnPage(m: NotebookMotion, dir: 1 | -1, law: NotebookLaw): boolean;
+/** Take hold of the top sheet on a side (0 the right page, 1 the left) — a drag begins. Null when there is none or sheets are flying. */
+export declare function grabSheet(m: NotebookMotion, side: 0 | 1): number | null;
+/**
+ * The hand moves a held sheet: the page is pinched at arc length `sGrab` from the gutter, and the
+ * pointer is at `xLocal` across the book (right-model x). The pinch follows the pointer's x — its
+ * angle about the gutter is the GRIP — and the sheet bows toward the hand: the edge leads the
+ * root by a bend that is most while the sheet stands and nothing while it lies. `yFrac` (−1 the
+ * head … +1 the tail) is where along the page the pinch is: that corner leads. `dt` is the time
+ * since the last move (the grip's pace, which a release reads).
+ */
+export declare function dragSheet(m: NotebookMotion, i: number, xLocal: number, xg: number, sGrab: number, _len: number, yFrac: number, law: NotebookLaw, dt?: number): void;
+/** Let go of a held sheet: it goes where the hand was taking it — flung, or past the vertical — else back. */
+export declare function releaseSheet(m: NotebookMotion, i: number): void;
+/** Open or close. Closing lands every sheet in the air on the side it was heading. */
+export declare function setOpen(m: NotebookMotion, open: boolean): void;
+/**
+ * The SHEETS and the PEEK alone, by dt seconds (D3t-b): a book in hand, whose cover, lift and tilt are the hand's (kinds/notebook.ts
+ * — the cover on the palm's spring), keeps its sheets' springs here — the same substeps `stepMotion` takes. True while any moves.
+ */
+export declare function stepLeaves(m: NotebookMotion, dt0: number, law: NotebookLaw): boolean;
+/** Advance every spring by dt seconds; true while anything still moves. */
+export declare function stepMotion(m: NotebookMotion, dt0: number, law: NotebookLaw): boolean;
+/** The hand's velocity (CSS px / s) → the tilt it asks for: the leading edge dips, capped. */
+export declare function tiltToward(m: NotebookMotion, vx: number, vy: number, law: NotebookLaw): void;
+/** The pose the mesh is built for: the swing, the stacks' counts and tops, the sheets in the air (a peek is one). */
+export declare function poseOf(m: NotebookMotion, law: NotebookLaw): NotebookPose;
+/** The pose with the desk under the book (−its lift, in its own z): what the ribbon hangs to. */
+export declare const withDesk: (p: NotebookPose, lift: number) => NotebookPose;
+/** A key that changes whenever the pose would build a different mesh. */
+export declare function poseKey(p: NotebookPose): string;