@vibecook/ice 0.11.0 → 0.14.0

package/dist/types/packages/objects/src/calendar/pass.d.ts

@@ -0,0 +1,229 @@
+import type { RenderTarget, RGB } from "../../../desk/src/index";
+import { type FadeIn, type View, type MatConfig, type MatFrame, type MatPass, type MatLight, type DeskEye, type BuiltMesh, type Rigid } from "../../../desk/src/kit/index";
+import type { CalendarLaw } from "./law";
+import { type CalendarColours } from "./layout";
+import { type PadFrame } from "./pad";
+import type { RollState } from "./roll";
+import type { CalendarShaders } from "./shaders";
+import { type TileGrid } from "./tiles";
+/** A box on a sheet, x0 y0 x1 y1 (sheet units); absent = none. */
+export type SheetBox = readonly [number, number, number, number];
+/** One sheet in play: where its grid is printed and which rows and days it has, and its tile table. */
+export interface SheetDraw {
+    readonly x0: number;
+    readonly y0: number;
+    readonly cw: number;
+    readonly ch: number;
+    readonly rows: number;
+    /** Bit c set: column c is a weekend. */
+    readonly weekends: number;
+    readonly lead: number;
+    readonly days: number;
+    /** Its page table's slot (0 … TABLE_SLOTS − 1). */
+    readonly slot: number;
+}
+/** One calendar as the pass draws it this frame. */
+export interface CalendarDraw {
+    readonly id: number;
+    readonly frame: PadFrame;
+    /** The pad's static mesh (pad.ts `buildPad`: its solid parts, then from `sheetFirst` its paper), and its version — the upload's key. */
+    readonly mesh: BuiltMesh & {
+        readonly sheetFirst: number;
+        readonly rollFirst: number;
+    };
+    readonly version: number;
+    readonly rigid: Rigid;
+    /** The unit direction toward the lamp (world). */
+    readonly lamp: readonly [number, number, number];
+    readonly lift: number;
+    /** The ring's presence, 0 … 1. */
+    readonly ring: number;
+    readonly base: SheetDraw;
+    /** The sheet in motion and its roll, or none. */
+    readonly moving: SheetDraw | null;
+    readonly roll: RollState | null;
+    /** Which sheet the host's marks are on: 0 the base, 1 the moving sheet. */
+    readonly marksOn: 0 | 1;
+    readonly sel: readonly SheetBox[];
+    readonly mark: SheetBox | null;
+    readonly drop: SheetBox | null;
+    /** The caret: x, top, bottom, width — or none. */
+    readonly caret: readonly [number, number, number, number] | null;
+    /** The newest glyph's box and its progress (0 … 1). */
+    readonly wipe: {
+        readonly box: SheetBox;
+        readonly t: number;
+    } | null;
+    readonly colours: CalendarColours;
+    /** The look's print presences — the pass's fallback where no host set its own (a record made without the desk's local: a tray specimen, K5a). */
+    readonly alpha?: {
+        readonly rule: number;
+        readonly head: number;
+        readonly weekend: number;
+        readonly outside: number;
+    };
+}
+export interface CalendarStats {
+    readonly calendars: number;
+    readonly moving: number;
+}
+export declare class CalendarPass {
+    readonly name = "calendar/pads";
+    /** Tile layers in the print's texture array. */
+    readonly layers: number;
+    private readonly device;
+    private readonly mat;
+    private readonly knobs;
+    private readonly records;
+    /** What the GPU holds of the records: a prefix is written only when it changed (K4a). */
+    private readonly recordsSent;
+    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 readonly recordBuf;
+    private tableBuf;
+    private readonly layoutMain;
+    private readonly layoutComp;
+    private readonly facePipe;
+    private readonly sheetPipe;
+    private readonly solidPipe;
+    private readonly movingPipe;
+    private readonly recvPipe;
+    private readonly compPipe;
+    private readonly goboSampler;
+    private readonly noiseSampler;
+    private readonly tileSampler;
+    private readonly paperSampler;
+    /** The print tiles: a placeholder until the first tile is laid (K6a — a desk with no calendar holds none of their 41 MB). */
+    private tileTex;
+    private tilesReady;
+    /** When a pad was last drawn: its layer targets are let go once none was for a while (the kind's tick — K6a, D-K6a.3). */
+    private drawnAt;
+    private readonly paperTex;
+    private readonly gridVb;
+    private readonly gridIb;
+    private readonly gridCount;
+    private mainGroup;
+    private boundAssets;
+    /**
+     * The pass whose PRINT this one samples — its own, or (K5b) the root's: a slot that made its own calendar pass (the tray's specimen)
+     * reads the root's tile texture and page tables, where the desk's pads print (their local writes the root pass), never a copy.
+     */
+    private print;
+    private boundTiles;
+    private boundTable;
+    /** The frame's target (the canvas; the hand) and the held desk copy's, apart (D7) — `t` the one this prepare is for (`use`). */
+    private readonly frameT;
+    private copyT;
+    private t;
+    private tableCount;
+    /** The records the last prepare turned away at the pass's cap — not drawn; the ground reports them (`GroundStats.dropped`, D7). */
+    dropped: number;
+    /** Profiling switches: 2 no print or paper detail · 4 no gobo · 8 no rolls' shade · 16 no layer on the mat · 32 no marks · 64 no tiles · 128 no mat under it · 256 no moving sheet · 512 flat colour. */
+    debug: number;
+    /**
+     * Turns over at every pass-wide resource a layer reads changing (K7a) — a tile, a page table, the main group made again: with the
+     * target's meshes' generation, the silhouette's key, what the pass lists and the box — and by CONTENT the knobs, the records and the
+     * slot's view block — what a target's layer is laid again by, undrawn (`BoxTargets.holds`).
+     */
+    private gen;
+    private readonly sig;
+    private readonly read;
+    /** Layers drawn and laid again undrawn since the pass was made (a witness). */
+    private layerDraws;
+    private layerKept;
+    private constructor();
+    static create(device: GPUDevice, format: GPUTextureFormat, src: CalendarShaders, mat: MatPass, layers?: number): Promise<CalendarPass>;
+    private rebind;
+    /** Sample `root`'s print — its tiles and page tables — rather than this pass's own (K5b: the tray's specimen reads the desk's print). */
+    sharePrintOf(root: CalendarPass): void;
+    /** Size the page tables for a sheet's tile grid (every table the same); re-makes the buffer, all entries missing. */
+    private fitTables;
+    /**
+     * The page tables let go (the desk has no pad — K7a, found by rig:stress: 227 KB of tables stood after the last pad left, the
+     * calendar kind over its 1 MB "none on the desk" line): the 16-byte stand-in again; the next sheet's grid makes them afresh.
+     */
+    releaseTables(): void;
+    /** A sheet's page table (a layer per tile, or MISSING / EMPTY), into its slot. */
+    writeTable(slot: number, grid: TileGrid, table: Int32Array): void;
+    /** The tiles' texture, made on the first tile laid (K6a). */
+    private tiles;
+    /** What the tiles hold on the device: 0 before the first tile and after `releaseTiles`. */
+    get tileBytes(): number;
+    /** The tiles let go (the desk has no pad): the placeholder again; the kind's tile cache starts afresh. */
+    releaseTiles(): void;
+    /** A tile's raster (the host's canvas, TILE_TEX², straight alpha) into its layer. */
+    uploadTile(layer: number, source: HTMLCanvasElement | OffscreenCanvas): void;
+    /** A tile's COMMITTED raster (RGBA bytes, TILE_TEX² × 4, straight alpha, row 0 at the top) into its layer — a host with no canvas (the Node oracle; D3t-c). */
+    writeTileBytes(layer: number, bytes: Uint8Array<ArrayBuffer>): void;
+    /** Was a pad drawn within the last `ms`? */
+    drawnWithin(ms: number): boolean;
+    /** When the layer was last drawn (`performance.now()`; -Infinity before the first) — the kind's registered wake lets it go LAYER_IDLE_MS after (K7a). */
+    get lastDrawn(): number;
+    /** Is the frame's layer made? */
+    get layerMade(): boolean;
+    /** The layers drawn and the ones laid again undrawn (nothing they are drawn from moved) since the pass was made (K7a). */
+    get layerFrames(): {
+        readonly drawn: number;
+        readonly kept: number;
+    };
+    /**
+     * Every mesh on the device given back — the frame's and the held copy's (K7a: the desk has none of this kind's objects left, and
+     * no prepare will come to sweep the ones it no longer lists).
+     */
+    releaseMeshes(): void;
+    /** The frame's layer targets let go (no pad drawn for a while, or none on the desk): made again at the next pad drawn. */
+    releaseLayer(): void;
+    private upload;
+    /**
+     * This frame's calendars: the mat's block, the knobs and the eye, each pad's record (placement, lamp,
+     * roll, sheets, marks, palette), its mesh. Returns how many will draw.
+     */
+    prepare(view: View & {
+        readonly dpr: number;
+    }, fadeIn: FadeIn, cfg: MatConfig, frame: MatFrame | undefined, light: MatLight | undefined, eye: DeskEye, law: CalendarLaw, grid: TileGrid, colours: {
+        readonly cast: RGB;
+        readonly select: RGB;
+        readonly alpha: {
+            readonly rule: number;
+            readonly head: number;
+            readonly weekend: number;
+            readonly outside: number;
+        };
+    }, calendars: readonly CalendarDraw[]): number;
+    get drawn(): CalendarStats;
+    /** The render target the next prepare, layer and composite are for (D7): the frame's, or the held desk copy's — made on first use. */
+    use(target: RenderTarget): void;
+    /** The hold is over: the desk copy's target gives its layer and meshes back (D7). */
+    endHold(): void;
+    /** The pads' screen box on an attachment of `size` device px, clamped to it — the layer's scissor and the composite's; null when none shows. */
+    private boxOf;
+    /** The pads' screen box of the last layer, device px [x, y, w, h] — what the composite paints at most; null: no layer to lay. */
+    get screenBox(): readonly [number, number, number, number] | null;
+    /** Draw the prepared pads into the layer (its own command buffer — submit it before the ground's). */
+    renderLayer(size: {
+        readonly w: number;
+        readonly h: number;
+    }, dpr: number): void;
+    /**
+     * Record the prepared pads into their LAYER, into `encoder` — ahead of the pass it is laid in: the host's own command buffer
+     * (`renderLayer`), or the desk's frame, after the mat's wind (the calendar a kind of its registry — kinds/calendar.ts). Draw order:
+     * the sheet in motion, the faces, the past roll, the solid, the mat under each. `size`: the attachment's device px. Returns
+     * whether there is a layer to lay (its box: `screenBox`).
+     */
+    layer(encoder: GPUCommandEncoder, size: {
+        readonly w: number;
+        readonly h: number;
+    }, dpr: number): boolean;
+    /**
+     * Lay the last layer over what `pass` holds — premultiplied, one fullscreen triangle — scissored to `scissor` (the pads' box, or
+     * a part of it a host narrows it to). Nothing without a layer, or with the debug bit 16 (no layer on the mat). `underlay()` is
+     * the same draw for a host that lays it through the ground's `underlays`.
+     */
+    composite(pass: GPURenderPassEncoder, scissor?: readonly [number, number, number, number] | null): void;
+    /** The layer laid on the mat, for the ground to draw inside its own pass (ground.ts `underlays`). */
+    underlay(): {
+        draw(pass: GPURenderPassEncoder): void;
+    } | null;
+    dispose(): void;
+}

package/dist/types/packages/objects/src/calendar/print.d.ts

@@ -0,0 +1,87 @@
+import type { CalendarLaw } from "./law";
+import { type CalEvent } from "./events";
+import { type MonthGrid, type MoonPhase } from "./month";
+import { type Box, type SheetLayout } from "./sheet";
+import { type PrintFace, type HandLaw, type HandLayout, type HandMetrics } from "../../../desk/src/kit/index";
+/** A 2D context the print draws into — the browser's (a canvas's or an OffscreenCanvas's); a TYPE, never a touch of the DOM. */
+export type PrintContext = CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
+/** The print's colours as CSS (the product's — `vf-theme.ts` `calendarPrint`): straight colour + alpha, drawn onto a clear canvas. */
+export interface PrintLook {
+    /** The dates, the month's name. */
+    readonly ink: string;
+    /** The year, the eyebrows, the weekend's dates, the small print. */
+    readonly muted: string;
+    /** A neighbour month's date: the ink at this alpha. */
+    readonly faint: number;
+    /** Today's ring. */
+    readonly hot: string;
+    /** A past day's tick. */
+    readonly pencil: string;
+    readonly pens: Readonly<Record<string, string>>;
+    readonly highlighters: Readonly<Record<string, string>>;
+    /** The alpha a highlighter lays down (the shader multiplies it into the paper). */
+    readonly highlight: number;
+}
+export declare const SANS = "system-ui, -apple-system, \"Helvetica Neue\", sans-serif";
+export declare const MONO = "ui-monospace, \"SF Mono\", SFMono-Regular, Menlo, monospace";
+/** One thing printed or written: its bounds on the sheet, the cells it belongs to, and how to draw it (in sheet coordinates). */
+export interface PrintItem {
+    readonly x0: number;
+    readonly y0: number;
+    readonly x1: number;
+    readonly y1: number;
+    draw(ctx: PrintContext): void;
+}
+/** Where an event's writing landed: the editor places its caret by it, the pointer picks by it. */
+export interface EventLine {
+    readonly event: CalEvent;
+    readonly day: number;
+    /** The line's (or the band segment's) box on the sheet. */
+    readonly box: Box;
+    /** The hand's layout and the sheet point its origin is at (a timed line's layout starts after its time). */
+    readonly layout: HandLayout;
+    readonly ox: number;
+    readonly oy: number;
+    readonly band: boolean;
+}
+export interface SheetPrint {
+    readonly sheet: SheetLayout;
+    readonly items: readonly PrintItem[];
+    /** What each cell holds, as a key: a tile over a cell whose key moved is drawn again. Index row·7 + col; the last is the sheet's own print. */
+    readonly keys: readonly string[];
+    readonly lines: readonly EventLine[];
+    /** Days whose count of lines did not fit ("+2 more"). */
+    readonly hidden: ReadonlyMap<number, number>;
+}
+export interface PrintInputs {
+    readonly law: CalendarLaw;
+    readonly look: PrintLook;
+    readonly sheet: SheetLayout;
+    readonly events: readonly CalEvent[];
+    /** Days with a sticky note stuck to them (their cells keep the foot clear). */
+    readonly noted: ReadonlySet<number>;
+    readonly today: number;
+    readonly moons: ReadonlyMap<number, MoonPhase>;
+    readonly face: PrintFace;
+    readonly metrics: HandMetrics;
+    /** The sticky note's hand (theme.ts `HAND`): its jitter and wander; the size is the calendar's. */
+    readonly hand: HandLaw;
+    readonly measure: (font: string, text: string) => number;
+    /** Tick the past days off in pencil. */
+    readonly ticks: boolean;
+    /** A key of everything above that is not per cell (the face, the look, the law's print): part of every cell's key. */
+    readonly style: string;
+    /** The entry being written: printed whole, its time not set apart, so the pen's caret maps one to one (−1 = none). */
+    readonly plain?: number;
+}
+/** Everything inked on one month's sheet. */
+export declare function printSheet(inp: PrintInputs): SheetPrint;
+/** Is an event drawn on this sheet at all (a band may start or end off it)? */
+export declare const onSheet: (e: CalEvent, g: MonthGrid) => boolean;
+/**
+ * Draw the rectangle [x, y, w, h] of a sheet (sheet units) into `ctx`, `band` texels a unit, onto a
+ * clear canvas: the items it overlaps, in order. The canvas's alpha is the ink's presence.
+ */
+export declare function drawRegion(ctx: PrintContext, print: SheetPrint, x: number, y: number, w: number, h: number, band: number): number;
+/** Does anything print in the rectangle? (An empty tile is never drawn nor stored.) */
+export declare function anyIn(print: SheetPrint, x: number, y: number, w: number, h: number): boolean;

package/dist/types/packages/objects/src/calendar/printing.d.ts

@@ -0,0 +1,80 @@
+import type { PrintRaster, TileSource } from "../../../desk/src/kit/index";
+import { type SheetPrint } from "./print";
+import { type TileGrid } from "./tiles";
+/** What the driver asks of the calendar's pass: its layers, a tile uploaded or written, a page table written. */
+export interface PrintPass {
+    readonly layers: number;
+    uploadTile(layer: number, source: TileSource): void;
+    writeTileBytes(layer: number, bytes: Uint8Array<ArrayBuffer>): void;
+    writeTable(slot: number, grid: TileGrid, table: Int32Array): void;
+}
+/** A sheet's committed tiles (a fixture): one level's tiles by `tx:ty`, RGBA TILE_TEX² each, and the ones nothing prints in. */
+export interface PinnedSheet {
+    readonly level: number;
+    readonly tiles: ReadonlyMap<string, Uint8Array<ArrayBuffer>>;
+    readonly empty: ReadonlySet<string>;
+}
+/** A sheet rectangle in view (sheet units). */
+export interface SheetView {
+    readonly x0: number;
+    readonly y0: number;
+    readonly x1: number;
+    readonly y1: number;
+}
+/** A string's 32-bit FNV-1a, as a tile's content key. */
+export declare function fnv(s: string): string;
+/** What a tile of a print shows — the keys of the cells under it and the sheet's own. */
+export declare function contentOf(print: SheetPrint, x: number, y: number, w: number, h: number): string;
+export interface PrintTilesOptions {
+    readonly grid: TileGrid;
+    /** The clock the frame's budget runs on (ms). */
+    readonly now?: () => number;
+    /** The most raster a frame spends, ms (a tile is ~0.3–1 ms): the rest come on the frames after. */
+    readonly budgetMs?: number;
+}
+/** The tile driver of one desk's pads: the layers' cache, each slot's page table, the frame's budget. */
+export declare class PrintTiles {
+    readonly grid: TileGrid;
+    private readonly now;
+    private readonly budgetMs;
+    private cache;
+    private readonly tables;
+    private t0;
+    /** Tiles the last frame left waiting, by sheet slot — a pad's own, so a pad forgotten takes its waiting tiles with it (D7). */
+    private readonly pendingBy;
+    private starvedN;
+    private drawnN;
+    constructor(opts: PrintTilesOptions);
+    /** Tiles still to draw after the last frame (the desk asks for another). */
+    pending(): number;
+    /** Tiles drawn since the driver was made (a witness). */
+    drawn(): number;
+    /** Tiles the last frame wanted and no layer could hold (every one in use by that frame) — a witness. */
+    starved(): number;
+    /** Resident tiles. */
+    resident(): number;
+    private cacheOf;
+    /** A new frame: its budget starts now; what it touches is kept from eviction until the next. */
+    begin(pass: PrintPass): void;
+    /** A sheet's page table in `slot`, owned by (pad, month): made again (all missing) when the owner changes. */
+    private tableFor;
+    /**
+     * Bring a sheet's tiles up to date for this frame: the coarse levels for the whole sheet, the view's level (and the one
+     * under it) for what is in view — resident ones kept, empty ones marked, the rest drawn (the view's centre first) within the
+     * frame's budget. `owner` names the sheet (`${pad}:${month}`); a sheet with no print yet (its face loading) keeps its table.
+     */
+    sheet(pass: PrintPass, raster: PrintRaster<SheetPrint>, owner: string, slot: number, print: SheetPrint, view: SheetView, level: number, rungs?: 1 | 2): void;
+    /**
+     * A sheet's COMMITTED tiles (a still's — the Node oracle's, a rig's pin): its table names the fixture's level alone (the rest
+     * missing: the shader falls back to it from any density), each tile written once into a layer of its own. The table is the
+     * pinned sheet's EXACTLY: a pin under an owner that pinned another sheet before (the oracle's pad 1 in September, scene after
+     * scene) keeps none of that sheet's entries — a blank pin is a blank sheet.
+     */
+    pin(pass: PrintPass, owner: string, slot: number, pinned: PinnedSheet): void;
+    /** The frame's page tables that moved, into the pass. */
+    end(pass: PrintPass): void;
+    /** A tile gave up its layer: every table pointing at it forgets it (the shader falls back a level). */
+    private forget;
+    /** A pad gone: its tiles, its tables and its waiting tiles (by its slots) forgotten. */
+    drop(pad: number, slots: readonly number[]): void;
+}

package/dist/types/packages/objects/src/calendar/roll.d.ts

@@ -0,0 +1,45 @@
+export interface RollState {
+    /** Where the tangent line crosses x = `px`, from the tape's edge (L = nothing wound). */
+    readonly a: number;
+    /** The line's tilt (radians): negative lifts the right-hand corner first, positive the left. */
+    readonly alpha: number;
+    readonly px: number;
+    /** The core's radius, and how much thinner each turn is. */
+    readonly r0: number;
+    readonly tau: number;
+    /** The sheet's free length (the tape's edge to its foot). */
+    readonly L: number;
+}
+export interface RollPoint {
+    /** Sheet x, s and height above the sheet's face. */
+    readonly x: number;
+    readonly s: number;
+    readonly z: number;
+    /** The FRONT face's normal (the printed side): up when flat, toward the roll's axis when wound. */
+    readonly nx: number;
+    readonly ns: number;
+    readonly nz: number;
+    /** How far round the spiral (radians); 0 flat. */
+    readonly phi: number;
+}
+/** The core that makes a whole sheet wound (tangent line at `rest`) a roll of radius `rest`. */
+export declare function coreOf(rest: number, tau: number, L: number): number;
+/** The radius of the roll where the wound length is D. */
+export declare const radiusOf: (r0: number, tau: number, D: number) => number;
+/** The roll's outer radius and its axis's place, at x (a tilted roll is a little fatter at its lifted end). */
+export declare function rollAt(R: RollState, x: number): {
+    readonly radius: number;
+    readonly wound: number;
+};
+/** A sheet point (x, s) as the roll bends it. */
+export declare function rollPoint(R: RollState, x: number, s: number): RollPoint;
+/**
+ * The roll for a sheet a fraction `p` of the way up (0 flat … 1 at rest against the tape), with a
+ * corner's tilt `tilt0` that straightens over the first third, pivoting at the grabbed side.
+ */
+export declare function rollState(p: number, law: {
+    readonly rest: number;
+    readonly tau: number;
+}, L: number, W: number, tilt0: number): RollState;
+/** Where the tangent line lies at x (the flat part's end, along s). */
+export declare const tangentAt: (R: RollState, x: number) => number;

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

@@ -0,0 +1,12 @@
+import type { ComposeOptions } from "../../../desk/src/engine/index";
+import { type ShaderText } from "../../../desk/src/kit/index";
+/** The calendar's own shader files (the kit's pieces come by name). */
+export declare const CALENDAR_SHADER_FILES: {
+    readonly calendar: "calendar/calendar.wgsl";
+    readonly pass: "calendar/calendar-pass.wgsl";
+};
+export interface CalendarShaders {
+    readonly program: ComposeOptions;
+    readonly composite: ComposeOptions;
+}
+export declare function calendarShaders(text: ShaderText): CalendarShaders;

package/dist/types/packages/objects/src/calendar/sheet.d.ts

@@ -0,0 +1,43 @@
+import type { CalendarLaw } from "./law";
+import { type MonthGrid } from "./month";
+export interface Box {
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}
+export interface SheetLayout {
+    readonly W: number;
+    readonly H: number;
+    readonly grid: MonthGrid;
+    /** The grid's top-left, a cell's size. */
+    readonly x0: number;
+    readonly y0: number;
+    readonly cw: number;
+    readonly ch: number;
+    readonly rows: number;
+    /** Where the title band and the weekday row start. */
+    readonly titleY: number;
+    readonly weekdaysY: number;
+}
+export declare function sheetOf(g: MonthGrid, law: CalendarLaw): SheetLayout;
+export declare const cellBox: (L: SheetLayout, row: number, col: number) => Box;
+/** The cell under a sheet point, with its day — or null off the grid. */
+export declare function cellAt(L: SheetLayout, x: number, y: number): {
+    readonly row: number;
+    readonly col: number;
+    readonly day: number;
+} | null;
+/** A day's cell on this sheet (a neighbour month's day in the first or last row counts), or null. */
+export declare function dayBox(L: SheetLayout, day: number): Box | null;
+/** Where a sticky note stuck to a day sits: centred across the cell, its foot `gap` above the cell's. */
+export declare function noteSlot(L: SheetLayout, row: number, col: number, law: CalendarLaw): {
+    readonly x: number;
+    readonly y: number;
+};
+/** How many lines of writing a cell holds (bands included) — fewer when a note hangs at its foot. */
+export declare function lineCapacity(L: SheetLayout, law: CalendarLaw, noted: boolean): number;
+/** The i-th line's box in a cell (a band's lane or a day's line). */
+export declare function lineBox(L: SheetLayout, row: number, col: number, i: number, law: CalendarLaw): Box;
+/** A band's box in its week row: from its first column to its last, in its lane. */
+export declare function bandBox(L: SheetLayout, row: number, col0: number, col1: number, lane: number, law: CalendarLaw): Box;

package/dist/types/packages/objects/src/calendar/tiles.d.ts

@@ -0,0 +1,67 @@
+/** A tile's texels of sheet, and its gutter each side. */
+export declare const TILE = 256;
+export declare const GUTTER = 2;
+export declare const TILE_TEX: number;
+/** 0.25 … 8 texels a unit. */
+export declare const LEVELS = 11;
+/** The coarsest levels kept resident for every sheet in play (the fallbacks). */
+export declare const BASE_LEVELS = 3;
+/** Page-table entries: a layer, or one of these. */
+export declare const MISSING = -1;
+export declare const EMPTY = -2;
+export declare const bandOf: (level: number) => number;
+/** The level for a density (texels wanted per unit): the rung at or above it. */
+export declare function levelFor(density: number): number;
+/** Each level's tile counts across and down a sheet, and where its entries start in the page table. */
+export interface TileGrid {
+    readonly W: number;
+    readonly H: number;
+    readonly nx: readonly number[];
+    readonly ny: readonly number[];
+    readonly offset: readonly number[];
+    /** Entries in one sheet's page table. */
+    readonly count: number;
+}
+export declare function tileGrid(W: number, H: number): TileGrid;
+/** A tile's rectangle on the sheet (its content, without the gutter), sheet units. */
+export declare function tileRect(level: number, tx: number, ty: number): {
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+};
+/** The tiles of a level that a sheet rectangle touches (clamped to the sheet). */
+export declare function tilesIn(g: TileGrid, level: number, x0: number, y0: number, x1: number, y1: number): Array<readonly [number, number]>;
+/** A tile's page-table index within its sheet's table. */
+export declare const entryOf: (g: TileGrid, level: number, tx: number, ty: number) => number;
+/**
+ * The texture layers the tiles live in: `layers` of them, handed out by key (which sheet, level and
+ * tile) and CONTENT (what the tile shows — the keys of the cells under it); a tile whose content moved
+ * is stale and draws again. When the layers run out, the one used longest ago that this frame has not
+ * touched is given up.
+ */
+export declare class TileCache {
+    readonly layers: number;
+    private readonly byKey;
+    private readonly byLayer;
+    private frame;
+    constructor(layers: number);
+    /** A new frame: what it touches is protected from eviction until the next. */
+    tick(): void;
+    /** The layer holding this tile with this content, or null (absent, or stale). Touches it. */
+    get(key: string, content: string): number | null;
+    /** Is a stale copy of the tile resident (it may be shown until the fresh one is drawn)? */
+    stale(key: string): number | null;
+    /**
+     * A layer for this tile (its old one, a free one, or the least-recently-used one not touched this
+     * frame), and the key of the tile it evicted (a page table pointing at it must forget it); null when
+     * every layer is in use this frame.
+     */
+    put(key: string, content: string): {
+        readonly layer: number;
+        readonly evicted: string | null;
+    } | null;
+    /** Forget every tile whose key starts with `prefix` (a calendar gone, a style changed). */
+    drop(prefix: string): void;
+    get size(): number;
+}

package/dist/types/packages/objects/src/calendar/turn.d.ts

@@ -0,0 +1,73 @@
+import type { CalendarLaw } from "./law";
+import type { PadFrame } from "./pad";
+import { type RollState } from "./roll";
+/** A turn in flight. */
+export interface Turn {
+    readonly dir: 1 | -1;
+    /** How far the moving sheet is rolled: 0 flat on the pad … 1 in the roll at rest. */
+    p: number;
+    v: number;
+    target: 0 | 1;
+    /** The corner's tilt it started with. */
+    readonly tilt: number;
+    /** The hand on it: the sheet point under the finger (`s` from under the tape), its velocity, whether it moved. */
+    drag: {
+        lastS: number;
+        lastT: number;
+        vs: number;
+        moved: boolean;
+    } | null;
+    /** A quick run (several months to go): the spring's frequency multiplied. */
+    fast: number;
+    /** A HAND's turn (its end a month the document does not know yet), not one toward the document's month. */
+    readonly hand: boolean;
+}
+/** One pad's turning, the local's own. */
+export interface PadRoll {
+    /** The month laid bare (null until the pad is first seen: it shows the document's then). */
+    shown: number | null;
+    turn: Turn | null;
+    peek: number;
+    peekV: number;
+    peekOn: boolean;
+    /** A hand's finished roll asked of the document, not yet there — held until the document SPEAKS (its month moves, to this or elsewhere). */
+    pending: number | null;
+    /** A hand's roll finished (the hand commits `shown`); cleared by whoever drains it. */
+    rolled: boolean;
+    /** The document's month as last seen. */
+    durable: number | null;
+    /** The document's month as `stepRoll` last heard it (a move from it is the document speaking — D7 #3). */
+    heard: number | null;
+}
+export declare const newRoll: () => PadRoll;
+/** The sheets in play for a pad: the month on it and the one in motion, the roll's line — the prototype's `sheetsOf`. */
+export declare function rollSheets(r: PadRoll, durable: number, law: CalendarLaw, F: PadFrame): {
+    readonly shown: number;
+    readonly base: number;
+    readonly moving: number | null;
+    readonly roll: RollState | null;
+    readonly marksOn: 0 | 1;
+    readonly turning: boolean;
+};
+/** The month the pad rolls toward: a hand's pending one, else the document's. */
+export declare const targetOf: (r: PadRoll) => number | null;
+/** Start a turn: up (`dir` 1, from the corner's lift) or down (−1, the last month off the roll). False while one runs. */
+export declare function startTurn(r: PadRoll, dir: 1 | -1, tilt: number, law: CalendarLaw, F: PadFrame, opts?: {
+    readonly hand?: boolean;
+    readonly fast?: number;
+    readonly drag?: {
+        readonly s: number;
+        readonly now: number;
+    };
+}): boolean;
+/** A hand takes the sheet in motion mid-turn (the prototype's press on `moving`). */
+export declare function grabMoving(r: PadRoll, s: number, now: number): boolean;
+/** The finger at `s` (the sheet point under it, from under the tape): the moving sheet follows it; `moved` once it has. */
+export declare function dragTo(r: PadRoll, s: number, now: number, moved: boolean, law: CalendarLaw, F: PadFrame): void;
+/** Let go: a click takes the whole month (or brings it); a flick goes where it was flicked; else past a third it goes, short of it it falls back. */
+export declare function letGo(r: PadRoll, now: number, law: CalendarLaw, F: PadFrame, cancel?: boolean): void;
+/**
+ * Advance a pad's turning by `dt` seconds toward the document's month `durable`: the corner's peek, the turn's spring, its end (a
+ * month rolled away or back — a hand's is `pending` and `rolled`), the next turn toward the target. True while anything moves.
+ */
+export declare function stepRoll(r: PadRoll, durable: number, dt: number, law: CalendarLaw, F: PadFrame): boolean;