@vibecook/ice 0.11.0 → 0.14.0

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

@@ -0,0 +1,297 @@
+import type { Entity } from "../../../core/src/index";
+import type { CalEvent } from "./events";
+import { type CalendarLaw } from "./law";
+import { type CalendarDraw, CalendarPass, type SheetDraw } from "./pass";
+import { type EventLine, type PrintLook, type SheetPrint } from "./print";
+import { type PinnedSheet } from "./printing";
+import { type RollState } from "./roll";
+import { rollSheets } from "./turn";
+import { type TileGrid } from "./tiles";
+import { type HandLaw, type MatPass, type MarkFrame, type DeskEye, type Rigid, type ShaderText, LayeredKind } from "../../../desk/src/kit/index";
+import { type KindPass, type KindProgram, type SlotContext, type Palette, type RGB, type TokenRef, type KindHost, type KindLocal, type ObjectContext, type ObjectKind } from "../../../desk/src/index";
+/** The desk calendar's kind name — its key in the registry and in every slot's `objects`. */
+export declare const CALENDAR_KIND = "calendar";
+/** The print's presences over the paper: the day rules, the heading rule, the weekend's wash, a neighbour month's wash. */
+export interface CalendarAlpha {
+    readonly rule: number;
+    readonly head: number;
+    readonly weekend: number;
+    readonly outside: number;
+}
+export declare class CalendarKind extends LayeredKind<CalendarDraw, CalendarPass> {
+    /** The calendar's law — the pad's size, its roll, its eye, its shadow: the host's; `CALENDAR` until one says. */
+    law: CalendarLaw;
+    /** The print's presences — the PRODUCT's look (CALENDAR.md §4): a host sets them before a pad draws. */
+    alpha: CalendarAlpha | null;
+    /** The tile grid of the law's sheet (tiles.ts) — the page tables' shape, the host's `writeTable` names the same. */
+    private tiles;
+    /** The tile grid the pass's page tables have for the law in force — the one a host hands `kind.pass.writeTable`. */
+    get grid(): TileGrid;
+    /** 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): CalendarKind;
+    /**
+     * A slot's own pass of this kind takes the ROOT's host-set state before it prepares (its law and the print's presences): 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, and reads the desk's PRINT (K5b).
+     */
+    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 tile grid, the colours. */
+    protected prepareOwn(pass: CalendarPass, s: SlotContext, records: readonly CalendarDraw[]): number;
+}
+/** The desk calendar's program for a host's shader text: its pass made on the root's mat; its pads one composite run, the first stratum. */
+export declare function calendarProgram(text: ShaderText): KindProgram<CalendarDraw>;
+/**
+ * What the calendar's kind takes from the host's palette (CALENDAR.md §4): the paper and the print's inks, the
+ * chipboard, the tapes by name (cloth and foil), the print's presences; the pens a caret is drawn in are the note's
+ * (`pens`, kinds/paper.ts `PaperPalette`).
+ */
+export interface CalendarPalette extends Palette {
+    readonly calendars?: {
+        readonly paper: TokenRef;
+        readonly ink: TokenRef;
+        readonly muted: TokenRef;
+        readonly weekend: TokenRef;
+        readonly hot: TokenRef;
+        readonly chipboard: TokenRef;
+        readonly tapes: Readonly<Record<string, {
+            readonly cloth: TokenRef;
+            readonly foil: TokenRef;
+        }>>;
+        /** The presences; `faint` (a neighbour month's date) and `highlight` (a highlighter's dye) are the PRINT's (D3t-c). */
+        readonly alpha: CalendarAlpha & {
+            readonly faint?: number;
+            readonly highlight?: number;
+        };
+        /** The PRINT's inks (D3t-c): the pencil a past day is ticked in, the highlighters a run of days is banded in. */
+        readonly pencil?: TokenRef;
+        readonly highlighters?: Readonly<Record<string, TokenRef>>;
+    };
+    readonly pens?: Readonly<Record<string, TokenRef>>;
+}
+/** The calendar's look for a theme, parsed. */
+export interface CalendarObjectLook {
+    readonly paper: RGB;
+    readonly ink: RGB;
+    readonly muted: RGB;
+    readonly weekend: RGB;
+    readonly hot: RGB;
+    readonly chipboard: RGB;
+    readonly tapes: Readonly<Record<string, {
+        readonly cloth: RGB;
+        readonly foil: RGB;
+    }>>;
+    readonly pens: Readonly<Record<string, RGB>>;
+    readonly alpha: CalendarAlpha;
+    /** The PRINT's inks as the raster takes them (D3t-c) — absent when the palette names no pencil or highlighters. */
+    readonly print?: PrintLook;
+}
+/** A pad's still, pinned on the kind's own state (a FLUX pin): a month rolling (`dir` +1 up, −1 down, `p` of the way, the roll's tilt) or the corner's peek. */
+export interface PadPose {
+    readonly roll?: {
+        readonly dir: 1 | -1;
+        readonly p: number;
+        readonly tilt?: number;
+    };
+    readonly peek?: number;
+}
+/** A pad as the builder resolved it: what its record draws and its hit reads (the same eye the pass draws with). */
+export interface CalendarGeometry {
+    readonly shown: number;
+    readonly weekStart: 0 | 1;
+    readonly base: number;
+    readonly moving: number | null;
+    readonly roll: RollState | null;
+    readonly marksOn: 0 | 1;
+    readonly rigid: Rigid;
+    readonly lamp: readonly [number, number, number];
+    readonly lift: number;
+    readonly ring: number;
+    readonly eye: DeskEye;
+    readonly cx: number;
+    readonly cy: number;
+    /** In hand (D4b's `ctx.held`): the whole sheet is the pen's surface (`content`), never a miss (D3t-c). */
+    readonly held: boolean;
+    /** A month in motion (a turn — not the corner's peek): the sheet in motion is what a press takes. */
+    readonly turning: boolean;
+}
+/** The parts of a pad (the prototype's `CalendarHit`): where a point lands on its sheet, the day and the line there. */
+export type CalendarPartName = "tape" | "roll" | "moving" | "corner" | "foot" | "day" | "entry" | "sheet";
+export interface CalendarPart {
+    readonly part: CalendarPartName;
+    /** The sheet point: x from its left edge, y from its head (world units). */
+    readonly sx: number;
+    readonly sy: number;
+    /** The day under it (a neighbour month's day in the first or last row counts) — on `day` and `entry`. */
+    readonly day?: number;
+    /** The line there, as the print laid it — on `entry`. */
+    readonly line?: EventLine;
+}
+/**
+ * What a desk point lands on, on a pad as resolved (the prototype's `hit`, through the SAME desk eye the pass draws with, at the
+ * face's height): the tape; mid-turn the sheet in motion (within the roll's reach of its tangent line) or the sheet beneath; at
+ * rest the roll under the tape, the corner, the foot, a line of writing (the print's own boxes — a band a little taller), a day,
+ * or the sheet's paper. Null off the pad. The print is the month shown's (`lines` — none in Node: no lines are hit).
+ */
+export declare function partAt(G: CalendarGeometry, wx: number, wy: number, lines?: readonly EventLine[], law?: CalendarLaw): CalendarPart | null;
+/** The sheet point (x from its left edge, y from its head) under a desk point, at the pad's face through the eye — unclamped (a finger may leave the pad). */
+export declare function sheetPoint(G: CalendarGeometry, wx: number, wy: number, law?: CalendarLaw): {
+    readonly sx: number;
+    readonly sy: number;
+};
+/** A pad's sheet point (x from its left, y from its head, `z` up) on the screen, CSS px — through the eye the pad was drawn with. */
+export declare function sheetOnScreen(G: CalendarGeometry, sx: number, sy: number, z?: number, law?: CalendarLaw): readonly [number, number];
+/** A day's cell on the month a pad shows (sheet units) — a neighbour month's day in the first or last row counts — or null. */
+export declare function sheetDayBox(G: CalendarGeometry, day: number, law?: CalendarLaw): {
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+} | null;
+/** A run of days, an entry, a caret: what the calendar's hand says is marked on a pad (the driver's — objects/calendar-hand.ts). */
+export interface PadMarks {
+    /** The days selected, first to last (day numbers). */
+    readonly days?: readonly [number, number];
+    /** The entry selected — an event entity's id, or the draft's (−1). */
+    readonly entry?: number;
+    /** The day a note held over the pad would stick to. */
+    readonly drop?: number;
+    /** The entry being WRITTEN (the editor on it): printed whole, its time not set apart, the caret at `index` (`on`: the blink). */
+    readonly writing?: {
+        readonly entry: number;
+        readonly index: number;
+        readonly on: boolean;
+    };
+    /** The newest glyph being written and how far the pen's wipe has come over it (0 … 1 — the hand's clock). */
+    readonly wipe?: {
+        readonly entry: number;
+        readonly index: number;
+        readonly t: number;
+    };
+}
+/** An entry being written that the world does not hold yet (a new line: it is spawned when its session ends — D-D3t-c.4). */
+export interface PadDraft {
+    readonly start: number;
+    readonly end: number;
+    readonly text: string;
+    readonly seeds: readonly number[];
+    readonly ink: string;
+}
+/** The draft's id in a print (never an entity's). */
+export declare const DRAFT_ID = -1;
+/** The calendar's own state on one desk: each pad's id and page-table slots, its pinned still, its print and marks; the print's presences on the root pass. */
+export interface Pads extends KindLocal {
+    /** When the kind is next live (K7a — `KindLocal.due`, declared: the six built-ins all say). */
+    due(now: number): number;
+    pin(e: Entity, pose: PadPose | undefined): void;
+    /** The world half's: the pad's id, its slot pair (its base sheet's table is 2k, its moving sheet's 2k + 1) and its pin. */
+    state(e: Entity): {
+        readonly id: number;
+        readonly slot: number;
+        readonly pose: PadPose | undefined;
+    };
+    /** The world half's: the print's presences on the root pass (the product's look). */
+    alpha(a: CalendarAlpha): void;
+    /** A pad's events as its data children hold them. */
+    events(e: Entity): readonly {
+        readonly start: string | null;
+        readonly end: string | null;
+        readonly text: string | null;
+        readonly ink: string | null;
+    }[];
+    /** The day the print calls today: the pinned one (a still's), else the clock's. */
+    today(): number;
+    /** Pin today (a day key) for stills and rigs — null gives it back to the clock. */
+    pinToday(key: string | null): void;
+    /**
+     * Pin the ZONE a day is reckoned in (an IANA name) — today's, and the Moon's phases' local days on the print — for stills and rigs:
+     * the committed prints were drawn in one zone, and a scene that holds a live print to them pins it (D7). Null: the pad's own.
+     */
+    pinZone(zone: string | null): void;
+    /** The past days ticked off in pencil (CALENDAR.md Q-4; on by default). */
+    ticks(on?: boolean): boolean;
+    /** A pad's entries as the print takes them — its events by entity, and the draft being written. */
+    entries(e: Entity): readonly CalEvent[];
+    /** Month `month`'s print on pad `e` as the last frame laid it (its lines: where each entry landed), or undefined — no raster, or not laid. */
+    printOf(e: Entity, month: number): SheetPrint | undefined;
+    /** A month's COMMITTED tiles on pad `e` (a still's, a rig's pin): drawn instead of the live print; null takes them back. */
+    pinPrint(e: Entity, month: number, sheet: PinnedSheet | null): void;
+    /** What the calendar's hand marks on pad `e` this frame (undefined: nothing). */
+    mark(e: Entity, marks: PadMarks | undefined): void;
+    marksOf(e: Entity): PadMarks | undefined;
+    /** The entry being written that the world does not hold yet (null: none). */
+    draft(e: Entity, d: PadDraft | null): void;
+    draftOf(e: Entity): PadDraft | null;
+    /** The print's tiles: resident, still to draw, drawn since the desk began. */
+    tiles(): {
+        readonly resident: number;
+        readonly pending: number;
+        readonly drawn: number;
+        readonly starved: number;
+    };
+    /** The desk's raster reads a live sheet back as a fixture would hold it (level `level`'s tiles, RGBA) — a rig's door; undefined without a raster. */
+    readSheet(e: Entity, month: number, level: number): {
+        readonly tiles: ReadonlyMap<string, Uint8Array<ArrayBuffer>>;
+        readonly empty: ReadonlySet<string>;
+    } | undefined;
+    /** The sheets in play for pad `e` whose document month is `durable` (the kind's `resolve`): the month laid bare, the one in motion. */
+    sheets(e: Entity, durable: number): ReturnType<typeof rollSheets>;
+    /** A pad's turning as it stands (a witness): the month laid bare, the turn in flight, the corner's lift, a hand's roll pending. */
+    rollOf(e: Entity): {
+        readonly shown: number | null;
+        readonly turn: {
+            readonly dir: 1 | -1;
+            readonly p: number;
+            readonly target: 0 | 1;
+            readonly held: boolean;
+            readonly hand: boolean;
+        } | null;
+        readonly peek: number;
+        readonly pending: number | null;
+    } | undefined;
+    /** The corner lifts while the pointer is near the foot or the corner (the next month shows under it). */
+    peek(e: Entity, on: boolean): void;
+    /** A hand takes a sheet by `part` (the foot or the corner: up; the roll: down; the sheet in motion) at sheet point (sx, s from under the tape). False when it cannot. */
+    grab(e: Entity, part: "foot" | "corner" | "roll" | "moving", sx: number, s: number, now: number): boolean;
+    /** The finger at `s`: the moving sheet follows it. */
+    dragTo(e: Entity, s: number, now: number, moved: boolean): void;
+    /** Let go (or the press was cancelled): the turn decides. */
+    letGo(e: Entity, now: number, cancel?: boolean): void;
+    /** The hands' finished rolls since the last drain — each a month the document should now hold (the hand commits it). */
+    rolled(): readonly {
+        readonly e: Entity;
+        readonly month: number;
+    }[];
+    /** A hand's finished roll waits for `rolled` to drain it (K7a): the hand is not idle, the kind is due, until it is committed. */
+    rollOwed(): boolean;
+    /** A hand's roll the document REFUSED (read-only, a pad gone): the pad rolls back to the document's month. A landed roll is released by the roll itself, once the document speaks (turn.ts, D7 #3). */
+    unroll(e: Entity): void;
+    /** A pad is on this desk (D7 #14): the hand's peek follows the pointer while one is — the hand is idle only while neither the pointer nor the camera moved (K7a). */
+    busy(): boolean;
+    /** The notes stuck to its pads that go with their months (D3t-c): not drawn, never picked (`KindLocal.veils`). */
+    veils(): ReadonlySet<Entity>;
+    /** Draw a pad's print and its marks for this frame (the kind's `record`): the sheets' tiles brought up, the marks' boxes. */
+    draw(e: Entity, G: CalendarGeometry, view: ObjectContext["view"], print: PrintLook | undefined): Pick<CalendarDraw, "sel" | "mark" | "drop" | "caret" | "wipe">;
+}
+/** The calendar's `local()`: ids from 1, slot pairs from the lowest free (the pass's tables hold `MAX_CALENDARS` pads); the print's driver. */
+export declare function createPads(host: KindHost, opts?: {
+    readonly law?: CalendarLaw;
+    readonly now?: () => number;
+    readonly zone?: string;
+    readonly hand?: HandLaw;
+}): Pads;
+/** A sheet as the pass draws it (the oracle's `sheetDrawOf`): where its grid is printed, its rows, weekends and days, its table's slot. */
+export declare function sheetDraw(month: number, weekStart: 0 | 1, slot: number, law?: CalendarLaw): SheetDraw;
+/** How far a pad's drawing reaches past its sheet, world units: its lift through the eye and its shadow (the pad lies low), the ring's offset. */
+export declare function calendarReach(law?: CalendarLaw): number;
+/**
+ * A desk calendar's silhouette for the desk's marks (D4a — the brackets, a member's ticks, the tape): its sheet's footprint
+ * on the mat, square to it, about the pad's centre, with the sheet's corner. The height's parallax aside, as the print's;
+ * the oracle's marks read the same function (oracle/frame.mjs).
+ */
+export declare function calendarFrame(cx: number, cy: number, law?: CalendarLaw): MarkFrame;
+export interface CalendarKindOptions {
+    readonly text?: ShaderText;
+    /** The calendar's numbers (calendar/law.ts `CALENDAR`) — the engine's unless a host tweaks them. */
+    readonly law?: CalendarLaw;
+}
+/** The desk calendar's kind, whole (kinds/world.ts `ObjectKind`): the program, and the world half on the lab's own pad. */
+export declare function calendarKind(opts?: CalendarKindOptions): ObjectKind<CalendarGeometry, CalendarDraw, CalendarObjectLook>;

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

@@ -0,0 +1,151 @@
+export interface CalendarLaw {
+    /** The sheet's bands, head to foot, and its margins. */
+    readonly sheet: {
+        /** Left and right, beside the grid (the week numbers print in the left one). */
+        readonly margin: number;
+        /** The cloth tape across the head: the sheets are bound under it. */
+        readonly tape: number;
+        /** Blank paper under the tape: where the roll of the months before lies. */
+        readonly rollZone: number;
+        /** The month's name and the two small months. */
+        readonly title: number;
+        /** The weekdays' row. */
+        readonly weekdays: number;
+        readonly foot: number;
+        /** The pad's corners. */
+        readonly radius: number;
+    };
+    readonly grid: {
+        /** A day's width. */
+        readonly cw: number;
+        /** The grid's height: a month's rows share it (four, five or six). */
+        readonly height: number;
+        /** The rules between days, and the heavier one under the weekdays (world units). */
+        readonly rule: number;
+        readonly head: number;
+    };
+    /** The printed type (the product's stack, DESIGN.md §3: big is light, small is medium). */
+    readonly print: {
+        readonly numeral: {
+            readonly size: number;
+            readonly baseline: number;
+            readonly pad: number;
+            readonly weight: number;
+        };
+        readonly title: {
+            readonly size: number;
+            readonly baseline: number;
+            readonly weight: number;
+            readonly year: number;
+        };
+        readonly weekday: {
+            readonly size: number;
+            readonly tracking: number;
+            readonly weight: number;
+        };
+        readonly mini: {
+            readonly size: number;
+            readonly pitch: number;
+            readonly col: number;
+            readonly gap: number;
+        };
+        readonly small: {
+            readonly size: number;
+            readonly weight: number;
+        };
+        readonly moon: {
+            readonly r: number;
+            readonly inset: number;
+        };
+    };
+    /** The handwriting in the cells (paper/text.ts's hand, at a pen's size). */
+    readonly hand: {
+        readonly size: number;
+        /** A line's pitch. */
+        readonly pitch: number;
+        /** The first line's top, from the cell's top (under the date). */
+        readonly top: number;
+        readonly pad: number;
+        /** A timed line's time, × the pen's size. */
+        readonly time: number;
+        /** A band's height, and how far its ends rag. */
+        readonly band: number;
+        readonly rag: number;
+    };
+    /** A sticky note stuck to a day: the note's own side, and the gap it keeps from the cell's foot. */
+    readonly note: {
+        readonly size: number;
+        readonly gap: number;
+    };
+    /** The pad's build: the chipboard back, the sheets under the month (the months after), each sheet. */
+    readonly pad: {
+        readonly board: number;
+        readonly block: number;
+        readonly sheet: number;
+    };
+    /**
+     * The ROLL: a month rolled up goes into a roll of paper under the tape — an Archimedean spiral whose
+     * turns thicken by `tau` each (paper's thickness, made visible), wound on a core so its outer radius
+     * at rest is `rest`; `turns` of it are drawn (the rest is inside). The corner's tilt as a roll starts.
+     */
+    readonly roll: {
+        readonly rest: number;
+        readonly tau: number;
+        readonly turns: number;
+        readonly tilt: number;
+        readonly peek: number;
+    };
+    /** Carried, the pad rises this far. */
+    readonly lift: number;
+    /** Springs: [hz, damping]. */
+    readonly springs: {
+        readonly roll: readonly [number, number];
+        readonly lift: readonly [number, number];
+        readonly ring: readonly [number, number];
+        readonly peek: readonly [number, number];
+    };
+    /** The light: the sky's share, the lambert's cap, the dapple's share on paper and on cloth. */
+    readonly light: {
+        readonly ambient: number;
+        readonly cap: number;
+        readonly dapple: number;
+        readonly clothDapple: number;
+    };
+    /** The shadows: σ at contact, σ per unit of height, the cast's alpha, the contact's alpha and σ. */
+    readonly shadow: {
+        readonly sigma0: number;
+        readonly perUnit: number;
+        readonly alpha: number;
+        readonly contact: number;
+        readonly contactSigma: number;
+        readonly slopeMax: number;
+    };
+    /** The paper (the notebook's baked texture): fibre, mottle, tooth, cockle. */
+    readonly paper: {
+        readonly fibre: number;
+        readonly mottle: number;
+        readonly tooth: number;
+        readonly cockle: number;
+    };
+    readonly cloth: {
+        readonly pitch: number;
+        readonly relief: number;
+        readonly sheen: readonly [number, number];
+    };
+    /** The selection ring around the pad (CSS px). */
+    readonly ring: {
+        readonly offset: number;
+        readonly width: number;
+    };
+    /** The eye (the notebook's desk eye). */
+    readonly eye: {
+        readonly k: number;
+        readonly min: number;
+    };
+}
+export declare const CALENDAR: CalendarLaw;
+/** The sheet's size under a law. */
+export declare const sheetSize: (law: CalendarLaw) => {
+    readonly W: number;
+    readonly H: number;
+};

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

@@ -0,0 +1,47 @@
+import type { RGB } from "../../../desk/src/index";
+import type { CalendarLaw } from "./law";
+import { type TileGrid } from "./tiles";
+export declare const CalUniforms: import("../../../desk/src/engine/index").StructDef<"view" | "eye" | "light" | "shadow" | "shadow2" | "paper" | "cloth" | "castCol" | "select" | "ring" | "alpha" | "tiles" | "tileNx" | "tileNy" | "tileOff">;
+export declare const CalPad: import("../../../desk/src/engine/index").StructDef<"size" | "model" | "inv" | "lamp" | "recv" | "col0" | "col1" | "col2" | "col3" | "col4" | "col5" | "col6" | "col7" | "z" | "drop" | "sel" | "wipe" | "mark" | "caret" | "roll" | "roll2" | "gridA" | "gridB" | "gridC" | "gridD" | "slots" | "wipe2" | "col8">;
+export declare const MAX_CALENDARS = 4;
+/** Two sheets in play per calendar: its base's table and its moving sheet's. */
+export declare const TABLE_SLOTS: number;
+/** A calendar's colours, as the pass takes them (lab/theme.ts `calendarLook`). */
+export interface CalendarColours {
+    readonly paper: RGB;
+    readonly ink: RGB;
+    readonly muted: RGB;
+    readonly weekend: RGB;
+    readonly hot: RGB;
+    readonly chipboard: RGB;
+    readonly cloth: RGB;
+    readonly foil: RGB;
+    /** The pen the caret is drawn in. */
+    readonly pen: RGB;
+}
+/** The pass's knobs by name. */
+export declare function calUniformValues(law: CalendarLaw, eye: {
+    eye: number[];
+    view: number[];
+}, dpr: number, cast: RGB, select: RGB, alpha: {
+    readonly rule: number;
+    readonly head: number;
+    readonly weekend: number;
+    readonly outside: number;
+}, grid: TileGrid, debug: number): {
+    eye: number[];
+    view: number[];
+    light: number[];
+    shadow: number[];
+    shadow2: number[];
+    paper: number[];
+    cloth: number[];
+    castCol: number[];
+    select: number[];
+    ring: number[];
+    alpha: number[];
+    tiles: number[];
+    tileNx: number[];
+    tileNy: number[];
+    tileOff: number[];
+};

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

@@ -0,0 +1,75 @@
+/** A civil date: year, month 1–12, day 1–31. */
+export interface Ymd {
+    readonly y: number;
+    readonly m: number;
+    readonly d: number;
+}
+/** Days since 1970-01-01 of a civil date (Hinnant's days_from_civil). */
+export declare function dayNumber(y: number, m: number, d: number): number;
+/** The civil date of a day number (Hinnant's civil_from_days). */
+export declare function civil(n: number): Ymd;
+/** 0 = Sunday … 6 = Saturday (1970-01-01 was a Thursday). */
+export declare const weekday: (n: number) => number;
+/** "2026-09-24". */
+export declare const keyOf: (n: number) => string;
+/** The day number of a "YYYY-MM-DD" key. */
+export declare function dayOfKey(key: string): number;
+export declare const isLeap: (y: number) => boolean;
+export declare const daysIn: (y: number, m: number) => number;
+/** A month as one integer (y·12 + m − 1): the pad counts months with it. */
+export declare const monthIndex: (y: number, m: number) => number;
+export declare const monthOf: (index: number) => {
+    readonly y: number;
+    readonly m: number;
+};
+/** The month a day falls in, as its index. */
+export declare const monthOfDay: (n: number) => number;
+export declare const MONTH_NAMES: readonly ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"];
+/** Sunday first; a sheet rotates them by its week's start. */
+export declare const WEEKDAY_NAMES: readonly ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+/** A month's grid as the sheet prints it: whole weeks, from the week holding the 1st to the week holding the last day. */
+export interface MonthGrid {
+    readonly y: number;
+    readonly m: number;
+    readonly index: number;
+    /** The weekday a row starts on: 0 Sunday, 1 Monday. */
+    readonly weekStart: 0 | 1;
+    /** The day number of the first cell (a day of the month before, unless the 1st starts the week). */
+    readonly first: number;
+    /** Weeks the month spans: 4 (a February that starts the week), 5 or 6. */
+    readonly rows: number;
+    /** Cells before the 1st. */
+    readonly lead: number;
+    readonly days: number;
+}
+export declare function monthGrid(index: number, weekStart: 0 | 1): MonthGrid;
+/** The day number in a grid's cell. */
+export declare const cellDay: (g: MonthGrid, row: number, col: number) => number;
+/** Does a day belong to the grid's own month (not a neighbour's day in its first or last row)? */
+export declare const inMonth: (g: MonthGrid, n: number) => boolean;
+/** The row and column of a day in a grid (either may fall outside it). */
+export declare const cellOf: (g: MonthGrid, n: number) => {
+    readonly row: number;
+    readonly col: number;
+};
+/** Is a column a weekend (Saturday or Sunday) under this grid's week? */
+export declare const isWeekendCol: (g: MonthGrid, col: number) => boolean;
+/** ISO 8601 week number of a day (weeks start Monday; week 1 holds the year's first Thursday). */
+export declare function isoWeek(n: number): number;
+/** The local civil day of a moment (ms since the epoch) under the platform's time zone. */
+export declare function localDay(ms: number): number;
+/** The civil day of a moment in the IANA zone `zone` — the calendar's CLOCK SEAM (D7); absent, the platform's own (`localDay`). */
+export declare function dayIn(ms: number, zone?: string): number;
+/** Today — the platform's clock and time zone unless the caller hands its own (a pad's clock seam, D7). */
+export declare const today: (ms?: number, zone?: string) => number;
+/** 0 new · 1 first quarter · 2 full · 3 last quarter. */
+export type MoonPhase = 0 | 1 | 2 | 3;
+/** The Julian Ephemeris Day of the principal phase `k` (an integer + 0, .25, .5 or .75 — Meeus 49.1 with its periodic terms). */
+export declare function phaseJde(k: number): number;
+/** A Julian Day → ms since the epoch (ΔT, about a minute, is left in: it moves no phase across a midnight that matters here). */
+export declare const jdToMs: (jd: number) => number;
+/**
+ * The principal phases whose instant falls on a day of [n0, n1] (inclusive), each on the LOCAL day
+ * `dayOf` gives it (the platform's time zone unless a test pins one).
+ */
+export declare function phasesBetween(n0: number, n1: number, dayOf?: (ms: number) => number): Map<number, MoonPhase>;

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

@@ -0,0 +1,45 @@
+import { type Entity } from "../../../core/src/index";
+import { type CalendarPart, type Pads } from "./kind";
+import { type KindDriver } from "../../../desk/src/index";
+import { type CalendarHand } from "./hand";
+import { type CalendarWriting } from "./writing";
+/** The tapes a pad is bound with (CALENDAR.md §4) — names; the cloths and foils are the host's. */
+export declare const TAPES: readonly ["ink", "tobacco", "kraft"];
+export type TapeName = (typeof TAPES)[number];
+/** The desk calendar's durable type id. */
+export declare const CALENDAR_TYPE = "desk.calendar";
+/**
+ * What sticks to a day (D3t-c): an object that PROVIDES `PINNABLE` (K8a — the note does; a plugin kind may), asked of the host by that
+ * key (`KindDriverHost.provides`) — never by another kind's name: a desk where nothing provides it lends no predicate, and the pad
+ * pins nothing.
+ */
+export { PINNABLE } from "../../../desk/src/index";
+export declare const Calendar: import("../../../core/src/index").WidgetType;
+/** The calendar's DOM half as its driver sees it (host/calendar-input.ts implements it): the caret on the line being written, the part under a client point, the selection's doors. */
+export interface CalendarInputDoors {
+    caret(): {
+        readonly index: number;
+        readonly t0: number;
+        readonly wipe: {
+            readonly index: number;
+            readonly t0: number;
+        } | null;
+    } | null;
+    partAtClient(x: number, y: number): {
+        readonly pad: Entity;
+        readonly part: CalendarPart;
+    } | null;
+    selectDays(pad: Entity, anchor: number, focus: number): void;
+    selectEntry(pad: Entity, entry: Entity): void;
+    clear(): void;
+    dispose(): void;
+}
+/** The calendar's driver (`driversOf(Calendar)`): its writing, its hand, its pads, its membership — and the DOM half that joins it. */
+export interface CalendarDriver extends KindDriver {
+    readonly writing: CalendarWriting;
+    readonly hand: CalendarHand;
+    readonly pads: () => Pads | undefined;
+    readonly isPad: (e: Entity) => boolean;
+    /** The DOM half, once the host has made it (the days and the pen at event time); the hand reads its caret. */
+    input: CalendarInputDoors | undefined;
+}

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

@@ -0,0 +1,42 @@
+import type { CalendarLaw } from "./law";
+import { type BuiltMesh, type MeshWriter } from "../../../desk/src/kit/index";
+/** The materials, by the number a vertex carries. */
+export declare const CMAT: {
+    readonly base: 0;
+    readonly moving: 1;
+    readonly past: 2;
+    readonly edge: 3;
+    readonly board: 4;
+    readonly tape: 5;
+};
+export interface PadFrame {
+    readonly W: number;
+    readonly H: number;
+    /** The tape's depth down the head, and the sheet's free length below it. */
+    readonly T: number;
+    readonly L: number;
+    /** The board's top, the pad's face (the base sheet), the moving sheet's face, the tape's top. */
+    readonly zb: number;
+    readonly zt: number;
+    readonly zm: number;
+    readonly zTape: number;
+    /** The past roll's radius, and how much of its spiral is drawn (radians). */
+    readonly rest: number;
+    readonly turns: number;
+}
+export declare function padFrame(law: CalendarLaw): PadFrame;
+/** A sheet point (x from the left edge, s down from the tape's edge) → pad coordinates. */
+export declare const padOf: (F: PadFrame, sx: number, s: number, z: number) => readonly [number, number, number];
+/**
+ * The pad's static mesh: the board's and the block's sides, the base sheet, the tape, the past roll.
+ * Rebuilt only when the law changes; the pad moves by its matrix.
+ */
+export declare function buildPad(m: MeshWriter, F: PadFrame, law: CalendarLaw): BuiltMesh & {
+    readonly sheetFirst: number;
+    readonly rollFirst: number;
+};
+/** The moving sheet's grid: (u, v) in [0, 1]², `cols` × `rows` quads; the vertex shader lays it on the sheet and rolls it. */
+export declare function movingGrid(cols: number, rows: number): {
+    readonly vertices: Float32Array<ArrayBuffer>;
+    readonly indices: Uint32Array<ArrayBuffer>;
+};