@vibecook/ice 0.10.0 → 0.14.0

package/dist/types/packages/core/src/widget/held-tools.d.ts

@@ -0,0 +1,83 @@
+/**
+ * THE HELD BAR'S TOOLS (design-015 §8; D3t-a) — what an object in hand offers beyond being held: the kind's
+ * `open.tools`, declared on its WIDGET TYPE (`defineWidget({ heldTools, heldTool })` — the desk's `defineObject`
+ * passes its kind's), so the one keymap and the one held bar reach them through the engine, never through a kind.
+ * Each tool is a glyph, a key and a KIND:
+ *  - a `mode` makes itself the held object's ACTIVE tool — the runtime `HeldTool` on the object in hand, the user's
+ *    fact, never in the document (the board's four markers and its eraser; a notebook's pens; a calendar's pen). A
+ *    `toggle` mode chosen again while active hands back the mode before it (the board's eraser lays down for the
+ *    marker it took over from);
+ *  - an `action` runs its op once (`run`, handed a `HeldToolApi` — outside the tick, like every op): undo and redo
+ *    (the DOCUMENT's history: a held object's history is the document's, design-015 §5.1), the board's wipe.
+ * Keys route only while an object is held (the keymap asks `matchHeldTool` before its own entries). A tool with no
+ * `kind` is DECLARED ONLY — the bar shows it dim and nothing routes to it (a kind whose tools are a later slice's).
+ */
+import type { Entity, World } from "@vibecook/strata-ecs";
+import type { GuardedTx } from "../guards/guarded-tx";
+/** What an action's op is handed: the object in hand, the document's history and ONE transaction on the document. */
+export interface HeldToolApi {
+    readonly world: World;
+    /** The object in hand. */
+    readonly entity: Entity;
+    /** The document's history — the one ⌘Z walks (false: nothing to undo, or a read-only document). */
+    undo(): boolean;
+    redo(): boolean;
+    /** ONE transaction on the document (one undo step unless `undoable: false`); false — nothing written — on a read-only one. */
+    transact(fn: (tx: GuardedTx) => void, opts?: {
+        readonly undoable?: boolean;
+    }): boolean;
+    /** The held object's own props as the world holds them now. */
+    props(): Readonly<Record<string, unknown>>;
+    /** The held object's own props, validated, in ONE transaction (`ops.setWidgetProps`'s path — the board's tip, a calendar's month); false on a read-only document. */
+    setProps(props: Readonly<Record<string, unknown>>, opts?: {
+        readonly undoable?: boolean;
+    }): boolean;
+}
+/**
+ * A held tool's GLYPH (design-016 §5 · K-L2, K8a): a NAME the bar draws (its set — `SELECTION_GLYPHS` in `@ice/react`, which an
+ * app may extend), or the tool's OWN drawing — SVG path data in the bar's 24-unit box, stroked 2 units in the bar's ink as the
+ * bar's own are, or filled (`fill`). A plugin kind in its own package, which draws no React, declares its drawing; a name the bar
+ * does not know is never drawn as another glyph (the bar marks it missing and says so).
+ */
+export type HeldGlyph = string | {
+    readonly path: string;
+    readonly fill?: boolean;
+};
+/** One tool of the held bar, as a kind declares it (its `open.tools`). */
+export interface HeldToolDef {
+    /** Unique within the type: what `HeldTool.id` holds for a mode, what `ops.useHeldTool` names. */
+    readonly id: string;
+    /** Its name — the slot's accessible label and its tip. */
+    readonly label: string;
+    /** `mode` (the active tool) or `action` (an op, run once); absent = declared only (dim, inert). */
+    readonly kind?: "mode" | "action";
+    /** The keys that choose it while held: `KeyboardEvent.key` with `mod+` (⌘ or ctrl), `shift+`, `alt+` — "1", "e", "mod+z", "mod+Backspace". */
+    readonly keys?: readonly string[];
+    /** The key as the tip shows it ("1", "E", "⌘Z"). */
+    readonly hint?: string;
+    /** Its glyph (`HeldGlyph`, K8a): a name of the bar's set, or its own drawing (`{ path }`). */
+    readonly glyph?: HeldGlyph;
+    /** A mode chosen again while active hands the hand back the mode before it. */
+    readonly toggle?: boolean;
+    /** The cursor over the object's drawing surface (its `content` part) while this mode is active — "none" where the tool draws itself. */
+    readonly cursor?: string;
+    /** false: keys only — no slot in the bar (the board's tip, its wipe). */
+    readonly bar?: boolean;
+    /** An action's op. */
+    run?(api: HeldToolApi): void;
+}
+/** A key press as the keymap reads it: `KeyboardEvent.key`, ⌘-or-ctrl, ⇧, ⌥. */
+export interface KeyChord {
+    readonly key: string;
+    readonly mod: boolean;
+    readonly shift: boolean;
+    readonly alt: boolean;
+}
+/** Does a tool's key spec name this chord? Every modifier must match exactly; the key compares case-blind (Caps Lock types "E"). */
+export declare function keyMatches(spec: string, chord: KeyChord): boolean;
+/** The live tool a chord chooses among `tools` — the first whose keys name it; a declared-only tool routes nothing. */
+export declare function matchHeldTool(tools: readonly HeldToolDef[], chord: KeyChord): HeldToolDef | undefined;
+/** A type's tools at definition time: unique ids, a known kind, an action with its op, well-formed keys. */
+/** Is this a glyph a tool may declare — none, a non-empty name, or a drawing with non-empty path data (K8a)? */
+export declare function isHeldGlyph(g: unknown): g is HeldGlyph | undefined;
+export declare function validateHeldTools(type: string, tools: readonly HeldToolDef[]): void;

package/dist/types/packages/core/src/widget/menu-actions.d.ts

@@ -0,0 +1,44 @@
+/**
+ * A KIND'S MENU ACTIONS (design-016 §5 · K-L2, K8a) — the acts a widget type offers in the selection menu for a selection of its
+ * objects, declared on its TYPE (`defineWidget({ menu })` — the desk's `defineObject` passes them through), so the one menu and
+ * an app's keys reach them through the engine (`ops.runMenuAction`), never through a kind: the menu shows an act when EVERY selected
+ * object's type declares it (a selection of that kind), and the op runs it on the selected objects whose types declare it — each
+ * type's own `run`, handed its own objects. Until K8a a kind's act (the mini mat's vinyl) was app code over a type name.
+ */
+import type { Entity, World } from "@vibecook/strata-ecs";
+import type { GuardedTx } from "../guards/guarded-tx";
+import { type HeldGlyph } from "./held-tools";
+/** What an act's op is handed (outside the tick, like every op): its type's selected objects and ONE door each to write them. */
+export interface MenuActionApi {
+    readonly world: World;
+    /** The selected objects of the declaring type, in selection order. */
+    readonly entities: readonly Entity[];
+    /** An object's own props as the world holds them now. */
+    props(entity: Entity): Readonly<Record<string, unknown>>;
+    /** An object's props, validated, in ONE transaction (`ops.setWidgetProps`'s path); false on a read-only document. */
+    setProps(entity: Entity, props: Readonly<Record<string, unknown>>, opts?: {
+        readonly undoable?: boolean;
+    }): boolean;
+    /** ONE transaction on the document (one undo step unless `undoable: false`); false — nothing written — on a read-only one. */
+    transact(fn: (tx: GuardedTx) => void, opts?: {
+        readonly undoable?: boolean;
+    }): boolean;
+}
+/** One act of the selection menu, as a type declares it. */
+export interface MenuActionDef {
+    /** Unique within the type: what `ops.runMenuAction` names (and what an app's key names). */
+    readonly id: string;
+    /** Its name — the button's accessible label and its tip. */
+    readonly label: string;
+    /** Its glyph (`HeldGlyph`): a name of the bar's set, or its own drawing (`{ path }`). */
+    readonly glyph?: HeldGlyph;
+    /** The key that does the same, as the tip and More show it ("T") — the app binds it to `ops.runMenuAction`. */
+    readonly keys?: string;
+    run(api: MenuActionApi): void;
+}
+export declare function validateMenuActions(type: string, acts: readonly MenuActionDef[]): void;
+/**
+ * The acts the selection menu shows for `entities`: those EVERY entity's type declares (by id; the first type's declaration names
+ * it), in the first type's order — none for an empty selection or an object of a type that declares none.
+ */
+export declare function menuActionsFor(entities: readonly Entity[], menuOf: (entity: Entity) => readonly MenuActionDef[]): readonly MenuActionDef[];

package/dist/types/packages/core/src/widget/mount-store.d.ts

@@ -1,55 +1,30 @@
 /**
- * Widget lifecycle: cull → keep-mounted LRU → the external mount store
- * (design-004 §2).
+ * The widget runtime: the CULL (design-004 §2, what survives of it at design-015 D5b).
  *
- * - `cullSystem` (derive): viewport test over equipped widgets' EFFECTIVE size
- *   (MeasuredSize where present, else Size), overscan scaled by zoom; flips
- *   Visible/Culled CHANGE-ONLY. GATED (2026-07-15, the activeMembership
- *   playbook): a real `runIf` — camera/viewport window compare as the `extra`
- *   trigger (full pass; the window moved under everyone) ∨ a petition-7
- *   collector on Position/Size/MeasuredSize + Active flips (delta pass —
- *   drags/spawns/measures re-test only the journaled entities). Idle frames
- *   skip; camera frames stay O(active) by the widgetQ Active scope.
- * - `mountSystem` (derive, after cull): maintains the mount list — every
- *   Visible widget is mounted; Culled widgets stay mounted-but-hidden
- *   (`display:none` at the host; React state preserved) within a count LRU
- *   budget (default RUNTIME_BUDGETS.keepMountedWidgets); beyond it the
- *   least-recently-visible unmount for real. Decisions are ENGINE-side; the
- *   dom host reflector and the React portal hook both consume the snapshot.
- *   GATED the same way on Visible/Culled flips (+ destroys of tagged
- *   widgets); LRU recency is stamped at the flip (identical eviction order —
- *   "last tick seen visible" = the tick it stopped being visible).
- * - The store implements the `useSyncExternalStore` contract: `subscribe` /
- *   `getSnapshot` with snapshot identity changing IFF membership or a hidden
- *   flag changed. Listener notification is deferred to post-notify (the
- *   engine flush reflector) — never from inside the tick.
+ * - `cullSystem` (derive): viewport test over equipped widgets' `Size`, overscan
+ *   scaled by zoom; flips Visible/Culled CHANGE-ONLY. GATED (2026-07-15, the
+ *   activeMembership playbook): a real `runIf` — camera/viewport window compare
+ *   as the `extra` trigger (full pass; the window moved under everyone) ∨ a
+ *   petition-7 collector on Position/Size + Active flips (delta pass —
+ *   drags/spawns re-test only the journaled entities). Idle frames skip; camera
+ *   frames stay O(active) by the widgetQ Active scope. `Visible`/`Culled` is the
+ *   desk renderer's WORKING SET: the builder walks the visible objects and the
+ *   pick source answers for them.
+ *
+ * GONE at design-015 D5b: the mount system, its keep-mounted LRU, the
+ * `useSyncExternalStore` snapshot, `retainForTransition` and the post-notify
+ * listener flush — every one of them existed so a DOM host or a GL island could
+ * stay mounted-but-hidden and be held across a nav crossfade. An object has no
+ * view to mount; the desk draws it from the world (design-015 §1). The
+ * facade's `runtime.store` went with them.
  */
-import { type Entity, type TickSystem, type World } from "@vibecook/strata-ecs";
+import { type TickSystem, type World } from "@vibecook/strata-ecs";
 import type { Engine } from "../engine/engine";
-import type { MeasureQueue } from "../input/measure-queue";
-export interface MountEntry {
-    readonly entity: Entity;
-    /** Culled-but-kept-mounted: host hides, React state survives. */
-    readonly hidden: boolean;
-}
-export interface WidgetMountStore {
-    subscribe(listener: () => void): () => void;
-    getSnapshot(): readonly MountEntry[];
-}
 export interface WidgetRuntime {
-    readonly store: WidgetMountStore;
     readonly cullSystem: TickSystem;
-    readonly mountSystem: TickSystem;
-    /** Post-notify listener flush — install registers it as a reflector. */
-    flush(): void;
 }
-export declare function createWidgetRuntime(world: World, opts?: {
-    keepMounted?: number;
-}): WidgetRuntime;
-/** Install cull + mount + the post-notify listener flush on an engine. */
-export declare function installWidgetRuntime(engine: Engine, opts?: {
-    keepMounted?: number;
-    measureQueue?: MeasureQueue;
-}): WidgetRuntime & {
+export declare function createWidgetRuntime(world: World): WidgetRuntime;
+/** Install membership → equip → cull → breakpoint on an engine. */
+export declare function installWidgetRuntime(engine: Engine): WidgetRuntime & {
     uninstall(): void;
 };

package/dist/types/packages/core/src/widget/spawn.d.ts

@@ -45,7 +45,7 @@ export declare function attachSpawnParent(tx: {
  * whole-group prop values). Shared by `spawnWidget` and the doc sink's
  * create-intent execution (draw tool) so the two can never diverge.
  */
-export declare function widgetSpawnInits(type: string, opts: SpawnWidgetOpts): {
+export declare function widgetSpawnInits(type: string, opts: SpawnWidgetOpts, resolvedWidget?: WidgetType): {
     prefab: import("../schema/prefab").Prefab;
     overrides: ComponentInit[];
 };

package/dist/types/packages/desk/src/assets/blue-noise.gen.d.ts

@@ -0,0 +1,10 @@
+/** The tile is square and rgba8: 128 × 128 × 4 = 65536 bytes. */
+export declare const BLUE_NOISE_SIZE = 128;
+/**
+ * The 128×128 rgba8 blue-noise tile the cutting mat samples, decoded once.
+ *
+ * Hand it to the pack's injection point — `matPass.setNoise(blueNoise())` — the
+ * same seam a lab feeds from a `?url` fetch. Decoding is lazy so a board that
+ * never registers the mat pays nothing for it.
+ */
+export declare function blueNoise(): Uint8Array<ArrayBuffer>;

package/dist/types/packages/desk/src/card/card.d.ts

@@ -0,0 +1,103 @@
+import { type BindEntry } from "../engine/pipeline";
+import { type ComposeOptions } from "../engine/shader";
+import type { CardMaterial, KindPass, KindProgram, SlotContext } from "../kind";
+import type { MatPass } from "../kit/view";
+/** A card's slot in its kind's records: the low 24 bits; the high byte its material. */
+export declare const CARD_SLOT_BITS = 24;
+/** A kind composed into the card: its name (the ground's key), its material, and its program (the material's `shaders()`, asked once). */
+export interface CardKind {
+    readonly name: string;
+    readonly material: CardMaterial;
+    readonly shaders: ComposeOptions;
+}
+/** What one card pipeline composes: its kinds by material index, and what it could not (a limit it would pass — they draw themselves). */
+export interface CardPlan {
+    readonly kinds: readonly CardKind[];
+    readonly left: readonly {
+        readonly name: string;
+        readonly why: string;
+    }[];
+}
+type Limits = Pick<GPUSupportedLimits, "maxSampledTexturesPerShaderStage" | "maxSamplersPerShaderStage" | "maxStorageBuffersPerShaderStage" | "maxUniformBuffersPerShaderStage" | "maxBindingsPerBindGroup">;
+/** A binding's name from its WGSL (`var<uniform> paper_k: PaperUniforms` → `paper_k`); null when it declares none the card can read. */
+export declare const bindingName: (wgsl: string) => string | null;
+/**
+ * The kinds one card pipeline composes, in registration order — a material kind is left out (and draws itself) when it is a
+ * composite (its objects are one target's), when adding it would pass one of the device's per-stage limits, or (K9 R3) when a
+ * name of its would collide with the card's own or an earlier kind's.
+ */
+export declare function planCards(programs: readonly KindProgram[], limits: Limits): CardPlan;
+/** The card's own entry: its bindings, every material's, their `only` and card functions, and the dispatch on the card's material. */
+export declare function cardEntry(kinds: readonly CardKind[]): string;
+/** The card's program: every material's structs (by name) and modules (by label) once, in order, then the card's entry. */
+export declare function cardShaders(kinds: readonly CardKind[]): ComposeOptions;
+/** The layout: the card's own four, then every material's bindings in order. */
+export declare function cardLayoutEntries(kinds: readonly CardKind[]): BindEntry[];
+/** The pipelines every slot's card draws with (once per device). */
+export interface CardShared {
+    /** The kinds composed, by material index. */
+    readonly kinds: readonly string[];
+    readonly material: ReadonlyMap<string, number>;
+    readonly layout: GPUBindGroupLayout;
+    readonly pipeline: GPURenderPipeline;
+    /** The same, for a slot lit from elsewhere (MINIMAT.md §4) — the materials' `LIT_ELSEWHERE`. */
+    readonly litPipeline: GPURenderPipeline;
+    /** What was left out, and why. */
+    readonly left: CardPlan["left"];
+}
+/**
+ * The card's pipelines for the registered programs; null when none declares a material the device can compose. A material the
+ * device REFUSES (K9 R3 — a plugin's WGSL error, a binding whose type its layout belies) takes only its own kind out of the card:
+ * each material is then compiled alone and the ones that fail are left with their error; if what remains still fails together (a
+ * collision the plan did not see), the last registered goes until the card compiles (a plugin registers after the built-ins).
+ * Every kind left out draws itself, as one past the device's limits does, and is said once (`console.error`, and `left`).
+ */
+export declare function createCardShared(device: GPUDevice, format: GPUTextureFormat, programs: readonly KindProgram[]): Promise<CardShared | null>;
+/**
+ * One slot's card: its draw list (the ground pushes a card for every object a material kind's pass lets go, in the order its
+ * runs walk them) and the bind group over the slot's view block and mat and ITS kinds' resources — made again only when one of
+ * them was replaced. The list is uploaded only when it changed (a camera move over a settled desk writes nothing).
+ */
+export declare class CardPass {
+    readonly name = "card";
+    /** Off: the ground routes nothing here — every object is drawn by its kind's own pass (a witness's second draw, a rig's A/B). */
+    on: boolean;
+    private list;
+    private sent;
+    private n;
+    private sentN;
+    private buffer;
+    private group;
+    /** What the group was made over: the mat's assets, the list's buffer, and each material's version. */
+    private boundOver;
+    private litElsewhere;
+    /** Each object's card this frame (−1: none) — a slot's route, reused frame to frame (`route`). */
+    private routes;
+    private readonly device;
+    private readonly shared;
+    private readonly mat;
+    private readonly kinds;
+    private bufferVersion;
+    constructor(device: GPUDevice, shared: CardShared, mat: MatPass, kinds: ReadonlyMap<string, {
+        readonly pass: KindPass;
+    }>);
+    /** A slot's card on the same pipelines, over ITS mat and kinds. */
+    spawn(mat: MatPass, kinds: ReadonlyMap<string, {
+        readonly pass: KindPass;
+    }>): CardPass;
+    /** The material index of kind `name`, or undefined when the card does not draw it. */
+    materialOf(name: string): number | undefined;
+    /** A frame's list begins, and a route for `n` objects, every one −1 (drawn by its kind). */
+    begin(n: number): Int32Array;
+    /** A card for record `slot` of material `m`: its index in this frame's list (the ground's run counts it). */
+    push(m: number, slot: number): number;
+    /** The list uploaded when it changed, the group made again when anything under it moved, the pipeline for the slot's light. */
+    prepare(slot: SlotContext): number;
+    private rebind;
+    /** Cards [first, end) of this frame's list — interleaved objects of every material kind — as ONE instanced draw. */
+    drawRange(pass: GPURenderPassEncoder, first: number, end: number): void;
+    /** The cards this frame. */
+    get count(): number;
+    dispose(): void;
+}
+export {};

package/dist/types/packages/desk/src/compose/ambient.d.ts

@@ -0,0 +1,59 @@
+import { type MatFrame } from "../mat/layout";
+export type AmbientMode = "live" | "idle" | "still";
+export interface AmbientOptions {
+    /** `idle` by default (design-015 D-D9). */
+    readonly mode?: AmbientMode;
+    /** How long after the last touch the wind keeps blowing, ms (20 000). */
+    readonly idleMs?: number;
+    /** How long the wind takes to ease to still once idle, ms (2 000). */
+    readonly settleMs?: number;
+    /** Seconds of gobo time per second at full speed (theme.ts `MAT_GRID.gobo.wind`). */
+    readonly wind?: number;
+    /** Radians of projector tilt per unit of smoothed pointer NDC (theme.ts `MAT_GRID.gobo.tilt`). */
+    readonly tilt?: number;
+    /** The OS asked for reduced motion: the mode is `still` whatever was set. */
+    readonly reducedMotion?: boolean;
+    /** The blue noise's re-roll (Math.random); a test's fake. */
+    readonly random?: () => number;
+}
+export type AmbientPhase = "live" | "easing" | "still" | "pinned";
+export interface AmbientState {
+    readonly mode: AmbientMode;
+    readonly phase: AmbientPhase;
+    /** The wind's speed, 0 … 1 of full. */
+    readonly speed: number;
+    readonly reducedMotion: boolean;
+    readonly pinned: boolean;
+}
+/** A pinned still's clocks (a parity scene): whatever is absent keeps the engine's still values. */
+export interface AmbientPin {
+    readonly time?: number;
+    readonly goboTime?: number;
+    readonly noise?: readonly [number, number];
+}
+export interface Ambient {
+    /** The pointer moved, a gesture or a flight ran: the wind (re)starts its `idleMs`. */
+    touch(now: number): void;
+    /** Advance the clocks by `dt` seconds at `now` ms, the tilt following `pointer` (NDC, or null before the pointer was seen); `live` = another frame is wanted. */
+    step(dt: number, now: number, pointer: readonly [number, number] | null): {
+        readonly frame: MatFrame;
+        readonly live: boolean;
+    };
+    /** The frame as the clocks stand, NOT advanced (the pinned one while pinned) — the desk behind the hand stands still (§8, D7). */
+    frame(): MatFrame;
+    /** Pin the clocks (a still) or unpin (`null`). Pinned, `step` returns the pinned frame and wants no frame. */
+    pin(frame: AmbientPin | null): void;
+    configure(opts: Pick<AmbientOptions, "mode" | "idleMs" | "settleMs" | "reducedMotion">): void;
+    state(): AmbientState;
+    /** The clocks as they stand (a rig's witness). */
+    clocks(): {
+        readonly time: number;
+        readonly goboTime: number;
+    };
+}
+export declare const AMBIENT_DEFAULTS: {
+    readonly mode: AmbientMode;
+    readonly idleMs: 20000;
+    readonly settleMs: 2000;
+};
+export declare function createAmbient(opts?: AmbientOptions): Ambient;