@vibecook/ice 0.11.0 → 0.14.0

package/dist/types/packages/core/src/systems/nav-tap.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The ENTER GESTURE (design-015 §9; D2b) — a double-tap on a `Container` asks to enter it, a
+ * double-tap on the bare frame asks to leave. `ctl:behave`, after `selectBehavior`: the first
+ * tap SELECTS at once (the prototype's click), the second — the same target, within
+ * `multiTapWindowMs`, within `multiTapSlopPx` — is the gesture. Detected from two INSTANT
+ * taps (each Recognized at count 1) held in `NavTapMemo`, not from a `MultiTap(2)` opt-in on
+ * the target: that machinery parks the first tap Pending for the whole window, so a plain
+ * click on a container would select 280 ms late — a latency the prototype never had (its
+ * first click selected, its dblclick entered). `MultiTap` stays what it is for widgets that
+ * want a counted tap.
+ *
+ * The op itself is NOT run here: `enterContainer` spawns, writes tags and rebuilds the index —
+ * structural writes, illegal mid-tick. The gesture writes the one-tick `NavIntent` fact and the
+ * facade applies it once `engine.step` returns (nav-geometry.ts). A tap on a PART (`DownPart`)
+ * is the app's and never counts; a tap while a flight drives is not a double-tap's first half
+ * (the flight yields to nothing but a camera gesture).
+ */
+import type { Entity, System, World } from "@vibecook/strata-ecs";
+/** The last instant tap: its target (0 = the bare frame), where and when — the double-tap's first half. */
+export declare const NavTapMemo: import("@vibecook/strata-ecs").Resource<import("@vibecook/strata-ecs").ValueOf<{
+    readonly target: import("@vibecook/strata-ecs").FieldSpec<"eid", true>;
+    readonly x: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly y: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly at: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    /** Bumps per tap seen; 0 = no memo. */
+    readonly seq: import("@vibecook/strata-ecs").FieldSpec<"u32", true>;
+}>, {
+    readonly target: import("@vibecook/strata-ecs").FieldSpec<"eid", true>;
+    readonly x: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly y: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    readonly at: import("@vibecook/strata-ecs").FieldSpec<"f64", true>;
+    /** Bumps per tap seen; 0 = no memo. */
+    readonly seq: import("@vibecook/strata-ecs").FieldSpec<"u32", true>;
+}>;
+export interface NavTapOpts {
+    /** Is this entity a container the engine may enter (the facade's catalog-backed test)? Default: the `Container` tag. */
+    readonly isContainer?: (entity: Entity) => boolean;
+    /**
+     * Is this entity an object that OPENS (design-015 §8, D4b — the facade's catalog-backed test: its widget type
+     * declares `openable`)? A double-tap on one asks to pick it up (`HeldIntent`), not to enter it. Default: nothing opens.
+     */
+    readonly isOpenable?: (entity: Entity) => boolean;
+}
+export declare function createNavTap(world: World, opts?: NavTapOpts): System;

package/dist/types/packages/core/src/systems/press-wheel.d.ts

@@ -0,0 +1,11 @@
+/**
+ * THE WHEEL OF A HOLDING PRESS (design-015 §6's photo; D3t-a — PHOTO.md: "wheel while holding turns the print about the
+ * finger"). While a local pointer's press holds a widget that declares `interaction.wheelTurns` (its `WheelTurns`
+ * capability — a recognizer of the press captures it), the wheel on that pointer is the WIDGET's: this system stamps the
+ * one-tick `WheelHandled` (both wheel consumers skip it — the camera never zooms under a carried print) and adds the tick's
+ * deltas to the pointer's `PressWheel`, a running sum a reflector can still read after the tick, when `PointerWheel` has been
+ * zeroed. The sum starts at the press's first wheel and leaves with the press. The head of `react`, beside the held input:
+ * the ingest's facts are flushed by then and what this stamps flushes before `ctl`.
+ */
+import type { System, World } from "@vibecook/strata-ecs";
+export declare function createPressWheel(world: World): System;

package/dist/types/packages/core/src/systems/tray.d.ts

@@ -0,0 +1,108 @@
+/**
+ * TRAY INPUT (design-016 §7; design-017 §4 — K3) — the pegboard drawer's share of the pointer, beside the hand's (systems/held.ts)
+ * and in its vocabulary. Right after `heldInput` at the head of `react`: the ingest's one-tick tags are flushed by then (a press is
+ * visible), and what this stamps flushes before `ctl`, so the recognizers and both wheel consumers never hear of what the tray
+ * takes. PICKING does not hear it either way — it runs in this same phase, before the stamp lands (a tag is a structural write,
+ * applied at the phase boundary) — so it reads `Tray.open` itself and answers the bare canvas for every local pointer while the
+ * drawer is out (l1-pick; K9 law #1: without that, the DOM-at-event-time halves read a live hit THROUGH the drawer). While an
+ * object is in hand the tray stands aside (the hand's frame never draws it).
+ *
+ *  - CLOSED, the drawer takes no pointer (design-018 §5, R2 — the lip's handle, its hover and its press retired): a press at the
+ *    bottom centre is the desk's like any other. What opens the drawer is the app's — the `a` key, and the DOM bar (`<TrayBar>`,
+ *    @ice/react), whose down never reaches the canvas as a press. Only a wheel stream it took while out stays its own (below).
+ *  - OPEN, the desk is INERT: every local pointer gets the one-tick `HandledByWidget` and `WheelHandled`, each tick, as the hand's
+ *    do — so "the wheel never moves the camera" is not a rule the camera keeps; it is a fact the camera never hears about. Over the
+ *    drawer the wheel scrolls it (`dy`; the OS's momentum arrives as deltas and is applied as it comes — no inertia of ours; ⌘/ctrl
+ *    and a pinch are swallowed) and a press-drag scrolls it; past an end the rest is the band's `stretch` (a reversal unwinds it
+ *    first), which lets go once the scroll input has been quiet `letGoMs` — or (K9) once a FADING tail has pushed it `fadeDeltas`
+ *    shrinking deltas, the rest of that tail spent (the OS's momentum no longer holds it for its second). A click on the dimmed desk — pressed and released there,
+ *    unmoved — closes it. Shut, the wheel stays the tray's until it has been quiet `letGoMs` (K9): a flick's momentum still
+ *    arriving as the drawer shuts never zooms the desk.
+ *  - K5b, TAKING ONE (design-017 §9): a press on a SPECIMEN is `TrayPress specimen` — its type, the grab point across the object as the
+ *    board draws it (kernel `specimenFit`), the specimen's centre on screen. Past the slop its COPY lifts (`Tray.take` and the pointer:
+ *    the renderer's flux draws it; the specimen stays hung); a press on a specimen never scrolls the board. Out of the drawer's open
+ *    rect the copy is HANDED to the desk: the drawer slides away (`open` false), `handed` bumps (that tick `take` still names it, where
+ *    it left — what the renderer's ghost grows out of — and it clears the tick after), and the one-tick `TrayIntent` asks the
+ *    facade for `ops.insertByDrag` after the step — the insert ghost under the same grab point, its synthetic down this pointer's, the
+ *    ordinary drag from there. The press becomes `carry`: released back over the drawer as drawn — still sliding away, its open rect
+ *    the desk's once it has shut (K9) — the ghost's gesture is CANCELLED
+ *    (`CancelRequest` — the ctl sweep reads it this tick, before the release can commit) and it flies home. Released inside the drawer,
+ *    or the drawer shut under it (Esc, the key), the take is put back: nothing was made, nothing enters undo.
+ *
+ * Where the drawer is comes through the SEAM `TrayPoseSlot` beside `heldPose`: the renderer's word on the drawer as it DREW it this
+ * frame (its rect mid-slide, the scroll range its layout gives), so a hit and the clamp agree with the pixels. Nothing here reads a
+ * kind or a pixel; opening a drawer cancels every gesture in flight (`CancelRequest`, read by the `ctl:spawn` sweep this tick).
+ */
+import type { Entity, System, TickSystem, World } from "@vibecook/strata-ecs";
+import type { DropPlacementPolicy } from "./l3-drop";
+import { type WidgetType } from "../widget/define-widget";
+/**
+ * The drawer ON SCREEN as the renderer drew it this frame, CSS px: its outline box (top-left, width, full height — the part below
+ * the view included), the slide `p` (0 closed … 1 open), the scroll range `max` the laid content gives, the board's `pitch`, and
+ * the `scroll` as DRAWN — the fact's plus the band's shown pull — so a board point under the pointer is the one on screen. K9: the
+ * `face`, the board's height the drawer shows inside its rim — the range is the content's foot plus a pitch less it (kernel
+ * `trayScrollMax`), so the lay can clamp the scroll in the tick a new foot or face moves the range; absent, nothing clamps it.
+ * design-018 R4: the `head`, how far under its top nothing of the board's content shows (the renderer's clear HEADER, where a host lays
+ * the category chips) — a specimen scrolled under it is never hovered or taken there: a press there is the board's; absent, 0.
+ */
+export interface TrayScreenFrame {
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+    readonly p: number;
+    readonly max: number;
+    readonly pitch: number;
+    readonly scroll: number;
+    readonly face?: number;
+    readonly head?: number;
+}
+/** The pose seam: the renderer's word on where the drawer is — `undefined` before its first frame. */
+export interface TrayPoseSource {
+    frame(): TrayScreenFrame | undefined;
+}
+/** The stack's slot for the pose source — a mutable box, so the renderer can arrive after install (as `heldPose`). */
+export interface TrayPoseSlot {
+    current: TrayPoseSource | null;
+}
+/** The tray's input numbers (design-017 §7): a click's slop, how long the scroll input must be quiet before the band lets go — and (K9, D-K9-c.3) how many shrinking deltas in a row a fading tail pushes the band before it lets go. (design-018 §5: the lip's drag, handle and pad retired with it.) */
+export declare const TRAY_INPUT: {
+    readonly slopPx: 4;
+    readonly letGoMs: 120;
+    readonly fadeDeltas: 3;
+};
+/** The tray's specimens (K5a): the tray entity's children tagged `Specimen`, in sibling order. */
+export declare function specimensOf(world: World, tray: Entity): Entity[];
+/** A delta down the board into scroll ∈ [0, max], the rest into the band; a delta back unwinds the band first. */
+export declare function scrollBy(scroll: number, stretch: number, d: number, max: number): {
+    readonly scroll: number;
+    readonly stretch: number;
+};
+export declare function createTrayInput(world: World, opts: {
+    readonly pose: TrayPoseSlot;
+}): System;
+/** The catalog's object types that carry a tray entry — the tray's contents (K-L2: no list here names a kind); the registry's in an unbound world. The lay hangs those the current frame takes (K9). */
+export declare function hungTypes(world: World): WidgetType[];
+/**
+ * THE TRAY'S LAY (design-017 §8; K5a) — the specimens in the world: one RUNTIME entity per object type whose widget carries a tray
+ * entry (`hungTypes`), `ChildOf` the tray entity (the root of its runtime canvas), `PrefabId` its type, `Position`/`Size` where the
+ * lattice law lays it (kernel `layTray`) across the drawer AS THE RENDERER DREW IT (the pose seam's width and pitch), its entry's
+ * props over the widget's defaults, spawned `Specimen` and already `WidgetEquipped` (nothing stamps it; the spatial index never
+ * takes it). Laid once the renderer has said how wide the drawer is; re-laid when that width, the pitch or the entries change (a
+ * kind registered), a specimen whose kind left destroyed; after a reset the new tray entity is laid afresh. `TrayContent` records
+ * what was laid — the content's foot is the renderer's scroll range. A tick system: its spawns are the scheduler's, once a frame.
+ * K9 (S10, D-K9-c.2): when that range MOVES — a lay (the width, the kinds) or the drawer's face (the view's height) — a scroll past its
+ * new end with nothing stretching is clamped to it in the same tick, so no frame draws blank board past the content and the next wheel
+ * starts from the end; only on a move, so the rig's door (`scrollTray`) still takes any value until the range next moves.
+ * K9 (S13, D-K9-c.4): it hangs what the CURRENT frame takes — inside an entered container its ingress, at the root its canvas's
+ * placement, the authority a drop's commit asks (`placement`) — so no specimen offers a take the frame would refuse; entering or
+ * leaving re-lays it (the drawer is shut then: the desk is inert while it is out). Without a policy, every hung type.
+ * design-018 §6 (R2) — THE FILTER: of those it lays only the entries of the category the drawer shows (`Tray.category`, "" all); a
+ * change of it re-lays, and the board starts again at its top — the scroll and the band zeroed. A category the frame hangs none of
+ * (its last entry gone with the frame, or an id no entry names) falls back to all. What the frame could hang before the filter — its
+ * categories in the lay's order and their counts — is recorded in `TrayContent.present` (the ops' `trayCategories`: a host's chips).
+ */
+export declare function createTrayLay(world: World, opts: {
+    readonly pose: TrayPoseSlot;
+    readonly placement?: DropPlacementPolicy | undefined;
+}): TickSystem;

package/dist/types/packages/core/src/systems/zoom-through.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The ZOOM-THROUGH (design-015 §9, design-013 Q13 → ON; PORTAL.md §8 — D2b). `ctl:behave`,
+ * after `cameraControl`: on a frame whose wheel zoomed (`WheelZoomStep`, D2a-core's one-tick
+ * fact — pans never cut, and the touch pinch is not recorded there, D-D2a.6), when no flight
+ * drives and the settings say so —
+ *
+ * - a zoom IN: the topmost Active container (paint order) whose face has come in whole
+ *   (presence 1) AND covers the whole viewport by `in` CSS px is entered as a CUT nobody can
+ *   see: the view already IS its inside, and the cut lands on the camera the inside was
+ *   rendering under (`transition: "cut"`).
+ * - a zoom OUT: when the current frame's own face — under the parent camera the inside
+ *   renders as it does now, the continuity solve — no longer covers the view by `out` px, the
+ *   frame is left as a cut onto that parent camera.
+ *
+ * Both are asked through the one-tick `NavIntent` fact (ops are structural — illegal mid-tick;
+ * the facade applies it right after the step) with `redress` set: the entered desk was DRESSED
+ * for its arrival as a face (`from` = the arrival's zoom), the left desk for the camera it was
+ * cut at (`from` = the camera's zoom) — the renderer re-dresses over its own ramp and hands the
+ * lamp over on it (`NavRedress`, written by the applier). The faces come through the nav
+ * geometry seam (the drawn face, the gate's answer, the cover test), else core's static rect.
+ */
+import type { Entity, TickSystem, World } from "@vibecook/strata-ecs";
+import { type NavGeometrySlot } from "../nav/nav-geometry";
+export interface ZoomThroughOpts {
+    /** The nav geometry seam the faces are read through (the interaction stack's slot). */
+    readonly navGeometry?: NavGeometrySlot;
+    /** Is this entity a container the engine may enter (the facade's catalog-backed test)? Default: any `Container`. */
+    readonly isContainer?: (entity: Entity) => boolean;
+}
+export declare function createZoomThrough(world: World, opts?: ZoomThroughOpts): TickSystem;

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

@@ -8,6 +8,8 @@
  * Built-ins ship as configs of this same primitive:
  *  - select: tap/longPress/drag; canvas drag → marquee (pan on touch /
  *    space / middle-button — device conventions, honored ABOVE tool policy).
+ *    A shift-held canvas drag takes `route.canvasDragShift` (design-015 §9,
+ *    D2a-core), which defaults to the tool's own `canvasDrag`.
  *  - pan: hand cursor; every drag pans.
  *  - connect: crosshair; widget/port drags connect (design-003 §5.8).
  *  - draw(widgetType): factory — canvas drag creates ONE widget from the
@@ -24,6 +26,14 @@ export type WidgetDragRoute = "move" | "pan" | "connect" | "none";
 export interface ToolRoute {
     /** Drag starting on empty canvas (after device overrides: touch/space/middle → pan). */
     readonly canvasDrag?: CanvasDragRoute;
+    /**
+     * The same drag with SHIFT held (design-015 §9, D-D11 — D2a-core): the desk's
+     * select tool pans the bare mat and draws its marquee on shift —
+     * `{ canvasDrag: "pan", canvasDragShift: "marquee" }`. Omitted: the tool's
+     * own `canvasDrag`, so shift changes nothing (every tool before this field).
+     * The device conventions (touch / space / middle → pan) still sit above it.
+     */
+    readonly canvasDragShift?: CanvasDragRoute;
     /** Drag starting on a widget body. */
     readonly widgetDrag?: WidgetDragRoute;
     /** Drag starting on a port entity ("connect" | "none"). */

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;