@vibecook/ice 0.11.0 → 0.15.0-desk.1

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

@@ -1,9 +1,13 @@
-import type { Component, Tag } from "@vibecook/strata-ecs";
+import type { Component, Entity, Tag, World } from "@vibecook/strata-ecs";
 import type { AnyBehaviorAttachSpec, AnyBehaviorDef } from "../behavior/types";
+import { type DeskStratum } from "../catalog";
 import { type Prefab } from "../schema/prefab";
 import type { PropSpec, PropsDecl } from "./props";
-export type WidgetSurface = "dom" | "gl";
-export type SizeMode = "fixed" | "auto-height" | "auto";
+import { type HeldToolDef } from "./held-tools";
+import { type MenuActionDef } from "./menu-actions";
+import { type TrayHang } from "../../../kernel/src/index";
+import type { CanvasType } from "../canvas/define-canvas-type";
+import type { FrameProjection } from "../canvas/frame-projection";
 export interface WidgetPortDecl {
     readonly id: string;
     readonly side: "n" | "e" | "s" | "w";
@@ -43,6 +47,39 @@ export interface WidgetRenameEntry {
  * `Behavior.with({...})` for a starting value (design-009 §6).
  */
 export type WidgetBehaviorDecl = AnyBehaviorDef | AnyBehaviorAttachSpec;
+export interface WidgetPortalInsets {
+    readonly top?: number;
+    readonly right?: number;
+    readonly bottom?: number;
+    readonly left?: number;
+}
+export interface WidgetContainerDef {
+    /** Compatibility-key projection written to the durable Accepts cell. */
+    readonly accepts: readonly string[];
+    readonly provides?: readonly string[];
+    /** Fixed CanvasType binding; omitted by legacy defineWidget({container}). */
+    readonly canvas?: CanvasType;
+    /** Explicit narrower ingress WidgetTypes, unioned with accepts keys. */
+    readonly widgets?: readonly WidgetType[];
+    /** Omitted drop policy inherits the complete CanvasType legal set. */
+    readonly inheritCanvasPlacement?: boolean;
+    /** Card-local portal insets; full widget body when absent. */
+    readonly portal?: WidgetPortalInsets;
+    /** Optional declared facet projection overriding the CanvasType default. */
+    readonly frameProjection?: FrameProjection;
+    /** Internal normalized distinction between defineContainer and legacy sugar. */
+    readonly typed?: boolean;
+}
+export interface WidgetContainerEntry {
+    readonly canvasTypeId: string;
+    readonly canvasSemanticVersion: number;
+    readonly accepts: readonly string[];
+    readonly widgetTypeIds: readonly string[];
+    readonly inheritCanvasPlacement: boolean;
+    readonly portal: Readonly<Required<WidgetPortalInsets>>;
+    readonly frameProjection: FrameProjection | undefined;
+    readonly typed: boolean;
+}
 /** Normalized pre-attachment (registry truth for the spawn + equip paths). */
 export interface WidgetBehaviorEntry {
     readonly behavior: AnyBehaviorDef;
@@ -51,6 +88,14 @@ export interface WidgetBehaviorEntry {
 export interface WidgetInteraction {
     readonly selectable?: boolean;
     readonly movable?: boolean;
+    /**
+     * May this widget be dropped INTO an accepting container (design-015 §9, D-D6 — D2b)?
+     * `"into"` (default): yes — for a GPU object, when its centre is let go over the container's
+     * FACE, at the point where it lay in the inside's own units (it takes the inside's scale), ⌥
+     * held at the release keeping it out. `"never"`: a root object always (D-D18: the notebook, the
+     * whiteboard, the calendar) — the widget offers itself to no container (no `Provides`).
+     */
+    readonly drop?: "into" | "never";
     readonly resizable?: boolean;
     readonly snap?: "source" | "target" | "both" | "none";
     /** Drop-REJECTING target: widgets dropped onto this one fly back (v1 iOS-card contract). */
@@ -63,15 +108,19 @@ export interface WidgetInteraction {
      * membership — never reparenting). Default false.
      */
     readonly sweepContained?: boolean;
+    /**
+     * The wheel TURNS it while a press holds it (design-015 §6's photo, D3t-a — the `WheelTurns` capability): the wheel on
+     * that pointer is the widget's, never the camera's; its deltas add up in the pointer's `PressWheel`. Default false.
+     */
+    readonly wheelTurns?: boolean;
     /**
      * Keyboard claim (design-007 §3.1, petitions I1/I4). `"exclusive"`: while a
-     * node inside this widget holds browser focus, the engine keymap and the
-     * adapter's Space pan modifier stand down — keys flow to the widget's own
-     * handlers (the engine stops competing; it never delivers behavior). The
-     * dom-widgets reflector marks the host `data-canvas-keyboard` + `tabindex=-1`
-     * so a click anywhere in the widget acquires focus, and plain wheel over the
-     * widget's scrollable content cedes to native scroll (ctrl/pinch stays
-     * canvas zoom always). Default `"shared"` — today's behavior, byte-identical.
+     * node inside this widget's claim holds browser focus, the engine keymap and
+     * the adapter's Space pan modifier stand down — keys flow to the widget's own
+     * handlers (the engine stops competing; it never delivers behavior). The claim
+     * is a `data-canvas-keyboard` host in screen space (the desk's one focused
+     * editor carries it), and plain wheel over its scrollable content cedes to
+     * native scroll (ctrl/pinch stays canvas zoom always). Default `"shared"`.
      */
     readonly keyboard?: "shared" | "exclusive";
     /**
@@ -93,20 +142,57 @@ export interface WidgetDef {
     };
     /** Conflict groups: group name → prop names. Ungrouped props → "props". */
     readonly groups?: Readonly<Record<string, readonly string[]>>;
-    readonly surface: WidgetSurface;
-    /** Framework component (opaque to core — the react package narrows it). */
-    readonly component: unknown;
-    /**
-     * GL only: a DOM chrome component portaled into the widget's CONTENT-plane
-     * host (P1), which stacks UNDER the GL canvas (P2) — v1's proven
-     * CardChrome-beneath-the-canvas sandwich. The island renders ONLY the 3D
-     * content; the card body (gradient, radius, ring, shadow, lift spring,
-     * hover/overlap glow) is DOM and shares the app's CSS with DOM widgets.
-     * Opaque to core — the react package narrows it. Ignored for dom-surface
-     * widgets (their component IS the chrome).
-     */
-    readonly chrome?: unknown;
-    readonly sizeMode?: SizeMode;
+    /**
+     * The KIND BINDING (design-015 §5.2, D-D16) — the widget's FACE: what the
+     * desk's renderer dispatches on through `widgetTypeFor`: the kind's program,
+     * its pick mirror, its opening. Opaque to core: it carries it and never reads
+     * it. Optional — a widget without one (a port, a test fixture) is a type the
+     * desk draws nothing for; since D5b there is no other face a widget can have.
+     */
+    readonly object?: unknown;
+    /**
+     * Which stratum of the desk instances lie in (design-015 §4.2, D-D4):
+     * `pads` under everything, `sheets` flat on the mat holding a desk, `things`
+     * above both. Equip stamps it as the runtime `Stratum` rider, and
+     * `compareStackOrder` ranks by it before sibling order, so pick order is paint
+     * order across kinds. An `object` that declares none is a `things`; any other
+     * widget that declares none gets no `Stratum` at all (and sorts as a thing).
+     */
+    readonly stratum?: DeskStratum;
+    /**
+     * An object that OPENS (design-015 §8, D4b): its kind declares an `open` binding — an open
+     * extent, an open motion, the held bar's tools — and `ops.open(entity)` picks it up into the
+     * hand (the double-tap, ⏎). A kind without one is refused by the op: a note is written where it
+     * lies, a mini mat is entered, a print has nothing to open. Refused without an `object` binding.
+     */
+    readonly openable?: boolean;
+    /**
+     * The held bar's tools of an object that opens (design-015 §8; D3t-a — widget/held-tools.ts): each a mode (the
+     * object's active tool in hand) or an action (an op), with its keys. The keymap and the bar reach them through the
+     * engine; `ops.useHeldTool` uses one. Refused on anything that does not open.
+     */
+    readonly heldTools?: readonly HeldToolDef[];
+    /** The mode in hand when the object is picked up, from its props (the board: its capped marker's ink). Default: the first mode, else none. */
+    readonly heldTool?: (props: Readonly<Record<string, unknown>>) => string;
+    /**
+     * The acts the SELECTION MENU offers for a selection of this type's objects (design-016 §5 · K-L2, K8a — widget/menu-actions.ts):
+     * each an id, a label, a glyph and an op; the menu shows one when every selected object's type declares it, and
+     * `ops.runMenuAction` runs it. A kind's own acts live here, never in app code over its type name.
+     */
+    readonly menu?: readonly MenuActionDef[];
+    /**
+     * What RIDES with the widget when a gesture moves it (design-015 D3t-c — the desk calendar's stuck notes): widgets of the same
+     * frame the move claim adds to its dragged set, so they move with it live and land in the SAME transaction (one undo step).
+     * Read from the world at the claim; a taped rider stays put, as a taped member of a selection does.
+     */
+    readonly riders?: (world: World, entity: Entity) => readonly Entity[];
+    /**
+     * The object's DATA prefabs (design-015 §5.1; D3t-a): durable children `ChildOf` it that are never widgets — the board's
+     * strokes. An engine catalog that registers the widget tracks them as it tracks the widget's own: their packs are stamped on
+     * a new document and gated at open, a guarded transaction resolves them, and one whose version moved migrates by its own
+     * `migrate` chain (doc/migrate.ts).
+     */
+    readonly data?: readonly Prefab[];
     readonly defaultSize?: {
         readonly w: number;
         readonly h: number;
@@ -115,13 +201,6 @@ export interface WidgetDef {
         readonly w: number;
         readonly h: number;
     };
-    /**
-     * GL only: the island repaints every frame while visible (design-004 §3
-     * animation contract — the EXPLICIT opt-in; plain `useFrame` inside a
-     * portal cannot be attributed to an island, so it never drives repaints;
-     * content-driven animation goes through `useIslandFrame`).
-     */
-    readonly animated?: boolean;
     readonly interaction?: WidgetInteraction;
     /**
      * Node-editor port schema (design-005 §2; design-001 §5.3): wires bind to
@@ -129,27 +208,7 @@ export interface WidgetDef {
      * the compatibility key list the connect gesture checks.
      */
     readonly ports?: readonly WidgetPortDecl[];
-    /**
-     * Palette/tray preview (design-005 §2 amendment, 2026-07-19). ENGINE-FREE
-     * BY CONTRACT: a preview renders with no world, no entity, no ops — a pure
-     * picture the host mounts inert (that is what makes it portable: trays,
-     * docs sites, a widget store). Authored at `defaultSize`; hosts scale.
-     * Three tiers, least effort first:
-     *  - absent            → the REAL component mounts with default props in
-     *                        the framework's preview sandbox (dom surfaces;
-     *                        truthful by construction);
-     *  - `{ props: {…} }`  → same sandbox mount with curated props;
-     *  - a component, or `{ component }` → author-owned preview (a static
-     *    mockup, a live self-ticking clock — the author's call). In P1 all
-     *    declared previews are DOM components — the sanctioned escape hatch
-     *    for GL widgets too (P2 adds the r3f snapshot pipeline).
-     * Opaque to core — the react package narrows it (`component` precedent).
-     */
-    readonly preview?: unknown;
-    readonly container?: {
-        readonly accepts: readonly string[];
-        readonly provides?: readonly string[];
-    };
+    readonly container?: WidgetContainerDef;
     /**
      * Provides-keys WITHOUT container semantics (nodeboard field finding): a
      * leaf that only offers itself to containers must not become a Container
@@ -192,6 +251,31 @@ export interface WidgetDef {
      * §6.4 cross-schema movement).
      */
     readonly migrate?: Readonly<Record<number, (prev: Record<string, unknown>) => Record<string, unknown>>>;
+    /**
+     * The widget's TRAY ENTRY (design-017 §8; K5a — K-L2: a plugin kind declares the same): a specimen of the object hangs on the
+     * pegboard tray, drawn by its own kind. No list in the engine names a kind — the catalog's widgets that carry an entry ARE the
+     * tray's contents. Only an object has one (a specimen is its face).
+     */
+    readonly tray?: TrayEntry;
+}
+/**
+ * A tray entry (design-017 §8): `label` — the specimen's name tag; `props` — the specimen's props over the widget's defaults: its FACE
+ * on the board (K5b — a note with a word on it, a print with a picture); `take` — what one taken off the board is made with (K5b,
+ * D-K5b.1): absent, the widget's own defaults (a taken note is blank, a taken calendar shows its today's month); `"face"`, the
+ * specimen's props; a record, those props (each valid as `props`'); `local` — K5b, D-K5b.3: the specimen (and a copy lifted off it) is
+ * drawn with its kind's DESK STATE (`ObjectKind.local` — a note's writing, a print's pictures, a pad's print), as its objects are, for a
+ * face that lives there; absent, a specimen is its kind's stateless drawing (K5a); `hang` — how it hangs (kernel `TrayHang`: its size on
+ * the board in CSS px, its pegs in pitches from its hang point, its accessory); `category`, then `order`, then the type — its place in
+ * the lattice law's order.
+ */
+export interface TrayEntry {
+    readonly label: string;
+    readonly props?: Readonly<Record<string, unknown>>;
+    readonly take?: "face" | Readonly<Record<string, unknown>>;
+    readonly local?: boolean;
+    readonly hang: TrayHang;
+    readonly order?: number;
+    readonly category?: string;
 }
 export interface WidgetGroup {
     readonly name: string;
@@ -205,11 +289,26 @@ export interface WidgetType {
     readonly prefab: Prefab;
     readonly groups: readonly WidgetGroup[];
     readonly propToGroup: Readonly<Record<string, string>>;
-    readonly surface: WidgetSurface;
-    readonly component: unknown;
-    /** GL widgets: DOM chrome under the canvas (see WidgetDef.chrome). */
-    readonly chrome: unknown;
-    readonly sizeMode: SizeMode;
+    /** The `object` kind binding (design-015 §5.2) — the face; opaque; `undefined` for a widget the desk draws nothing for. */
+    readonly object: unknown;
+    /**
+     * The desk stratum equip stamps as `Stratum` (design-015 §4.2): the declared
+     * one, `things` for an object that declared none, `undefined` (no rider) for
+     * a faceless widget that declared none.
+     */
+    readonly stratum: DeskStratum | undefined;
+    /** An object whose kind opens — `ops.open` picks it up (design-015 §8); false on every other widget. */
+    readonly openable: boolean;
+    /** The held bar's tools (design-015 §8, D3t-a); empty for anything that does not open. */
+    readonly heldTools: readonly HeldToolDef[];
+    /** The mode in hand at the pick-up, from the object's props; undefined = the first mode. */
+    readonly heldTool: ((props: Readonly<Record<string, unknown>>) => string) | undefined;
+    /** The selection menu's acts for this type's objects (K8a); empty when it declares none. */
+    readonly menu: readonly MenuActionDef[];
+    /** What rides with the widget when a gesture moves it (design-015 D3t-c); undefined = nothing. */
+    readonly riders: ((world: World, entity: Entity) => readonly Entity[]) | undefined;
+    /** The object's data prefabs (design-015 §5.1, D3t-a) — the catalog tracks them with the widget; empty for most. */
+    readonly data: readonly Prefab[];
     readonly defaultSize: {
         readonly w: number;
         readonly h: number;
@@ -218,23 +317,25 @@ export interface WidgetType {
         readonly w: number;
         readonly h: number;
     };
-    /** GL islands: repaint every visible frame (design-004 §3). */
-    readonly animated: boolean;
     /** Node-editor ports (empty when not a node). */
     readonly ports: readonly WidgetPortDecl[];
     /** Runtime capability tags the equip system stamps at projection. */
     readonly capabilityTags: readonly Tag[];
+    /** Normalized capability advertisement; never re-read from durable cells. */
+    readonly provides: readonly string[];
+    /** Fixed nested-frame binding and ingress/portal metadata, when a container. */
+    readonly container: WidgetContainerEntry | undefined;
     /** Keyboard claim (design-007): the dom layer reads THIS (registry truth), not the tag. */
     readonly keyboard: "shared" | "exclusive";
     /** Escape ownership under an exclusive claim ("release" = engine-reserved). */
     readonly keyboardEscape: "release" | "widget";
+    /** May instances be dropped INTO an accepting container (design-015 §9; `"never"` = a root object always, D-D18)? The drop system reads THIS. */
+    readonly drop: "into" | "never";
     readonly migrate: Readonly<Record<number, (prev: Record<string, unknown>) => Record<string, unknown>>>;
     /** Pre-attached behaviors, normalized (spawn tx for durable, equip for runtime). */
     readonly behaviors: readonly WidgetBehaviorEntry[];
-    /** Normalized author preview component (opaque; react narrows). null = none declared. */
-    readonly previewComponent: unknown;
-    /** Prop overrides for the default real-component preview mount (validated names). */
-    readonly previewProps?: Readonly<Record<string, unknown>>;
+    /** The tray entry (design-017 §8; K5a), validated and frozen; undefined = the widget hangs nothing on the tray. */
+    readonly tray: TrayEntry | undefined;
 }
 /** Stamped by the equip system once a projected widget carries its capability tags. */
 export declare const WidgetEquipped: Tag;
@@ -248,5 +349,7 @@ export declare const renames: {
     all(): WidgetRenameEntry[];
 };
 export declare function defineWidget(def: WidgetDef): WidgetType;
+/** What one taken off the tray is made with (design-017 §9; K5b, D-K5b.1): the entry's `take` — the face's props, its own, or none (the widget's defaults). */
+export declare function trayTakeProps(entry: TrayEntry): Readonly<Record<string, unknown>> | undefined;
 /** TEST-ONLY wipe (mirrors __resetPrefabsForTests; not on the barrel). */
 export declare function __resetWidgetsForTests(): void;

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

@@ -9,6 +9,18 @@
  * projections from this frame's sync() are visible by then.
  *
  * This generalizes the graybox demo's equipSceneBoxes into the engine.
+ *
+ * RIDERS take the same path — session-local facts derivable from the widget
+ * TYPE and needed on every peer's projection, including one that received the
+ * widget over the wire or restored it from a file, neither of which ran a spawn
+ * path (design-013 D4: never sync what every peer can compute from `PrefabId`):
+ * the desk `Stratum` (design-015 §4.2, D2a-core) and the type's runtime
+ * pre-attached behaviours (design-009 §6). Structural `ctx.addComponent` lands
+ * at the derive flush like the tags. Until design-015 D5b the six presentation
+ * facts (`SurfaceKind` … `TextureRef`, design-013 §5) rode here too; they left
+ * with the DOM/GPU presentation choice — an object presents on the desk and
+ * nowhere else, so there is no kind to name, no target to choose and no texture
+ * to reserve.
  */
-import { type System } from "@vibecook/strata-ecs";
-export declare function createWidgetEquipSystem(): System;
+import { type System, type World } from "@vibecook/strata-ecs";
+export declare function createWidgetEquipSystem(world: World): System;

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>;