@vibecook/ice 0.10.0 → 0.14.0

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

@@ -0,0 +1,56 @@
+/**
+ * `<Desk>` — the one-line desk mount (design-015 §3, D5b): `@ice/dom`'s `createDeskHost` under
+ * React. This component owns the container element and the keymap; the host owns the layer, the
+ * adapters, the reflectors, the loop and the viewport sync. `<InfiniteCanvas>` became this BY
+ * DELETION (plan D-D0.6): no planes, no profile gate, no DOM widget portals, no chrome plane (the
+ * desk draws its own marks, design-015 §7), no measurement, no GL route, no `grid` prop (the
+ * desk's handle has `configureFadeIn`/`configureMat`).
+ *
+ * The desk arrives as an OPAQUE layer factory — `layer={deskLayer({ … })}` from `@vibecook/ice/desk`
+ * — typed structurally by `@ice/dom`; this package imports neither `@ice/desk` nor its handle.
+ * Memoize the factory in the caller: a new identity re-boots the mount.
+ *
+ * Lifecycle: the engine is NOT owned here (the app disposes it). Unmount disposes the host.
+ * Children render inside the container, above the canvas: the screen-space chrome (the selection
+ * menu, a dev panel) and nothing that moves with the camera (design-015 §2 law 2).
+ */
+import type { CanvasEngine } from "../../core/src/index";
+import { type CanvasHost, type LayerFactory, type LayerHandle, type WidgetFocusHandle } from "../../dom/src/index";
+import { type CSSProperties, type ReactElement, type ReactNode } from "react";
+import { type KeymapEntry } from "./keymap";
+/** Handed to {@link DeskProps.onReady} once the host is live (app-side devtools, the desk's handle). */
+export interface DeskHandle {
+    readonly engine: CanvasEngine;
+    readonly host: CanvasHost;
+    /** The mounted layer's handle, as the factory returned it (the desk's `DeskLayerHandle` under `deskLayer`). */
+    readonly layer: LayerHandle;
+    /**
+     * Programmatic focus release (design-007 §2.3): `blurFocus()`. Focus is VIEW state
+     * (design-007 §2.6) — it rides this handle, not `engine.ops` (a headless engine has none).
+     */
+    readonly focus: WidgetFocusHandle;
+}
+export interface DeskProps {
+    /** A constructed engine (`createCanvasEngine(...)`); NOT disposed on unmount. */
+    readonly engine: CanvasEngine;
+    /** The desk's layer factory (`deskLayer({ … })`), received opaquely. Memoize in the caller. */
+    readonly layer: LayerFactory;
+    /**
+     * Called once per mount after the host, the reflectors and the loop are live. What it starts that outlives the call — a
+     * listener, a wait, a join — it undoes in the cleanup it may return, which runs when the mount ends, before the host goes.
+     * An effect's contract: StrictMode's development double mount runs it for the mount it discards (K9).
+     */
+    readonly onReady?: (handle: DeskHandle) => void | (() => void);
+    /**
+     * Keymap overrides plumbed to {@link attachKeymap} (design-007 §5 M-d). An entry replaces a
+     * default by its `key|mod|shift` signature; conditional behaviour belongs INSIDE `run`. BOUND
+     * ONCE at mount, like the adapters: entries read live engine state at run time, never
+     * render-time values.
+     */
+    readonly keymapOverrides?: readonly KeymapEntry[];
+    readonly className?: string;
+    readonly style?: CSSProperties;
+    /** Screen-space chrome inside the viewport (the selection menu, a HUD) — rendered under the EngineProvider. */
+    readonly children?: ReactNode;
+}
+export declare function Desk({ engine, layer, onReady, keymapOverrides, className, style, children }: DeskProps): ReactElement;

package/dist/types/packages/react/src/engine-context.d.ts

@@ -7,7 +7,7 @@
  * ops + docs). Widgets never hand-roll store plumbing again: {@link useOps}
  * gives the engine-owned write paths, {@link useCommit} (its own module) the
  * sanctioned durable commit seam, and {@link useWorld} the read/observe escape
- * hatch. `<InfiniteCanvas>` provides this automatically; apps that mount
+ * hatch. `<Desk>` provides this automatically; apps that mount
  * WidgetRoot themselves wrap it in `<EngineProvider>`.
  */
 import { type CanvasEngine, type CanvasOps, type World } from "../../core/src/index";
@@ -27,7 +27,7 @@ export declare function useOps(): CanvasOps;
  * overlay-lifecycle sugar — the disposer releases on deactivate AND unmount,
  * so a crashed/unmounted overlay can never wedge the canvas backgrounded.
  * `engine` is an explicit param (not context): overlays typically render as
- * SIBLINGS of <InfiniteCanvas>, outside the provider.
+ * SIBLINGS of <Desk>, outside the provider.
  */
 export declare function useStageHold(engine: CanvasEngine, active: boolean, name: string): void;
 /**

package/dist/types/packages/react/src/frame-preview-boundary.d.ts

@@ -0,0 +1,19 @@
+import { Component, type ErrorInfo, type ReactElement, type ReactNode } from "react";
+export interface FramePreviewBoundaryProps {
+    readonly children: ReactNode;
+    readonly fallback?: ReactNode;
+    readonly onError?: (error: unknown, info: ErrorInfo) => void;
+}
+/** Isolates one author-owned instance preview from the rest of the canvas. */
+export declare class FramePreviewBoundary extends Component<FramePreviewBoundaryProps, {
+    readonly failed: boolean;
+}> {
+    state: {
+        failed: boolean;
+    };
+    static getDerivedStateFromError(): {
+        failed: boolean;
+    };
+    componentDidCatch(error: unknown, info: ErrorInfo): void;
+    render(): ReactElement | ReactNode;
+}

package/dist/types/packages/react/src/hooks.d.ts

@@ -1,6 +1,5 @@
 /**
- * React hooks over the engine's Tier-3 reactivity (design-005 §2 hooks;
- * design-004 §2 frozen-hidden rule).
+ * React hooks over the engine's Tier-3 reactivity (design-005 §2 hooks).
  *
  * Implemented directly on `world.reactive.observeValue` + `useSyncExternalStore`
  * rather than strata's own react module: core is react-free by law, so
@@ -8,14 +7,14 @@
  * lines. Value semantics are strata Tier-3: equality-suppressed, fired at
  * notify(), never during the tick.
  *
- * FROZEN-HIDDEN: a widget inside a hidden (culled-but-kept-mounted) host must
- * not re-render on doc edits — `useWidgetProps` reads {@link WidgetHiddenContext}
- * (provided per-portal by WidgetRoot) and suspends its subscription while
- * hidden, serving the last snapshot; on show it resubscribes and refreshes.
+ * These are the hooks of SCREEN-SPACE chrome (design-015 §2 law 2): a panel
+ * that shows the selected object's props, a bar that reads its behaviour
+ * state. Until design-015 D5b they also served the React faces of DOM widgets
+ * and carried the frozen-hidden rule (a culled-but-kept-mounted portal must
+ * not re-render) through `WidgetHiddenContext` and the mount store's freeze;
+ * both left with the portals. `ChromeOwnerContext` left with the profiles.
  */
 import { type AnyBehaviorDef, type Component, type Entity, type World } from "../../core/src/index";
-/** Per-portal hidden flag (WidgetRoot provides it; defaults to live). */
-export declare const WidgetHiddenContext: import("react").Context<boolean>;
 /**
  * Tier-3 component value subscription (equality-suppressed). Snapshot
  * STABILITY is load-bearing: strata's `get()` materializes a fresh object per
@@ -36,16 +35,12 @@ export declare function useWidgetProps<T extends Record<string, unknown>>(world:
  * `undefined` when the behavior is not attached, which is a legitimate render
  * state and not an error.
  *
- * READ-ONLY by construction. A face renders behavior state; it never writes it
+ * READ-ONLY by construction. Chrome renders behavior state; it never writes it
  * (Law 10) — writes go through `ctx` inside the behavior's own hooks, or
  * through `engine.behaviors.attach` / a transaction from an app handler.
  */
 export declare function useBehavior<T extends Record<string, unknown>>(world: World, entity: Entity, behavior: AnyBehaviorDef): T | undefined;
-/**
- * Selection membership (Tier-1 wake on Selected churn; O(1) snapshot).
- * Frozen-hidden like every widget hook: a selection change must not re-render
- * 256 hidden trees (review finding — design-004 §2 applies to ALL hooks).
- */
+/** Selection membership (Tier-1 wake on Selected churn; O(1) snapshot). */
 export declare function useSelected(world: World, entity: Entity): boolean;
 /** LOD tier (design-004 §8); "normal" until the breakpoint system stamps one. */
 export declare function useBreakpoint(world: World, entity: Entity): string;

package/dist/types/packages/react/src/index.d.ts

@@ -1,16 +1,23 @@
 /**
- * @ice/react — widget content layer: portals from one root + Tier-3 hooks.
- * Import wall: @ice/dom → @ice/core down only — never three/@react-three
- * (enforced). react/react-dom are peers.
+ * @ice/react — the React face of the desk (design-015 §3): `<Desk>` (wraps `@ice/dom`'s
+ * `createDeskHost`), EngineProvider + the Tier-3 hooks, the keymap, the screen-space selection
+ * menu and held bar, the tray's bar (design-018). Renderer-free: the desk arrives as an opaque layer factory.
+ * Import wall: @ice/dom → @ice/core down only — never three/desk (enforced). react/react-dom are peers.
+ *
+ * GONE at D5b (design-015 §1): `<InfiniteCanvas>` (→ `<Desk>`), `WidgetRoot` and the portals,
+ * `WidgetPreview` + the preview snapshots, the surface content seam, the two presentation
+ * profiles, `ChromeOwnerContext` and `WidgetHiddenContext`. One presentation (DK-D8).
  */
 export declare const REACT_VERSION = "0.0.0";
-export { WidgetHiddenContext, useBreakpoint, useSelected, useBehavior, useWidgetProps, useWorldComponent, } from "./hooks";
-export { WidgetRoot, type WidgetComponentProps, type WidgetHosts, type WidgetRootProps } from "./widget-root";
+export { useBreakpoint, useSelected, useBehavior, useWidgetProps, useWorldComponent } from "./hooks";
 export { EngineProvider, useCanvasEngine, useFrameFreeze, useOps, useStageHold, useWorld, type EngineProviderProps, } from "./engine-context";
 export { useCommit, useUndoStatus, type Commit, type UndoStatus } from "./use-commit";
-export { WidgetPreview, type WidgetPreviewProps } from "./widget-preview";
-export { getPreviewSnapshot, hasPreviewSnapshot, setPreviewSnapshot, subscribePreviewSnapshots, type PreviewImage, } from "./preview-snapshots";
 export { useTool, useToolState } from "./use-tool";
+export { useCanvasCatalog, useCanvasDiagnostics, useCanvasTools, useCurrentCanvas, useFramePreview, } from "./canvas-hooks";
+export { FramePreviewBoundary, type FramePreviewBoundaryProps, } from "./frame-preview-boundary";
 export { usePresencePeers, type PresencePeerView } from "./use-presence";
-export { attachKeymap, type KeymapEntry } from "./keymap";
-export { InfiniteCanvas, type GroundLayerFactory, type GroundLayerHandle, type InfiniteCanvasHandle, type InfiniteCanvasProps, } from "./infinite-canvas";
+export { attachKeymap, type KeymapEntry, nudgeSelection, toggleTape, unlessInert } from "./keymap";
+export { defaultSelectionActions, placeSelectionMenu, SELECTION_GLYPHS, SELECTION_MENU, type SelectionAction, SelectionMenu, type SelectionMenuAnchor, type SelectionMenuBox, type SelectionMenuProps, type SelectionMenuSource, type SelectionGlyph, type SelectionMenuAct, type SelectionMenuTool, type SelectionState, selectionTaped, } from "./selection-menu";
+export { DESK_TAPE, placeTrayBar, TRAY_BAR, TRAY_BAR_GLYPHS, TrayBar, type TrayBarAnchor, type TrayBarCategory, type TrayBarPlace, type TrayBarProps, type TrayBarSource, } from "./tray-bar";
+export { Desk, type DeskHandle, type DeskProps } from "./desk";
+export type { LayerContext, LayerFactory, LayerHandle } from "../../dom/src/index";

package/dist/types/packages/react/src/keymap.d.ts

@@ -8,9 +8,14 @@
  *   ⇧⌘Z / ⇧Ctrl-Z   → docs.redo
  *   ⌘D              → ops.duplicateSelection
  *   ⌘A              → ops.selectAll
- *   Esc             → ops.cancelActiveGestures
- *   Arrows          → nudge the selection ±1px (⇧ = ±10px) — ONE tx per press
+ *   Esc             → closes the pegboard tray first (design-017 §4), else ops.cancelActiveGestures
+ *   Arrows          → nudge the selection ±1px (⇧ = ±10px) — ONE tx per press; a TAPED widget
+ *                     never moves (design-015 §5.1 — `Locked`, D4a), its untaped companions do
+ *   ⇧⌘L / ⇧Ctrl-L   → tape the selection down, or lift the tape when all of it is taped
+ *                     (*Marks on the Mat*'s keys, D4a) — `ops.setLocked`, one transaction
  *   tool shortcuts  → ops.setTool (v/h/c + any registered tool's shortcut)
+ *   in hand         → the held object's own tools first (design-015 §8, D3t-a): its type's
+ *                     `heldTools` keys → ops.useHeldTool — and only while it is held
  *
  * Space-hold pan is ALREADY owned by the pointer adapter (design-003 §2) — it is
  * NOT rebound here. `mod` = ⌘ on macOS, Ctrl elsewhere (metaKey || ctrlKey).
@@ -41,6 +46,12 @@
  * design-003 §4.4) and preventDefaults it before gate 1 can let it through.
  */
 import { type CanvasEngine } from "../../core/src/index";
+/**
+ * The desk's keys go quiet while it is inert — an object in hand (D4b) or the pegboard tray open (design-017 §4): what would delete,
+ * copy, nudge or gather on the inert desk does nothing. Exported for an app's OWN keys (K9 S3: the desk app's `w`, `m`, Tab and its
+ * ⇧ arrows — which replace the entries here — made, walked and nudged objects under the open drawer and moved a notebook in hand).
+ */
+export declare const unlessInert: (run: (engine: CanvasEngine) => void) => (engine: CanvasEngine) => void;
 export interface KeymapEntry {
     /** `event.key` to match (case-insensitive; e.g. "z", "Backspace", "ArrowUp"). */
     readonly key: string;
@@ -52,6 +63,14 @@ export interface KeymapEntry {
     run(engine: CanvasEngine): void;
 }
 type KeyTarget = Pick<Window, "addEventListener" | "removeEventListener">;
+/**
+ * One nudge = one gesture-equivalent transaction (absolute Position writes). A taped widget (`Locked`) is passed
+ * over — the tape holds it as it holds against a drag (design-015 §5.1, D4a). Exported so an app can bind its own
+ * step (the desk's ⇧ nudge is one lattice cell, 20).
+ */
+export declare function nudgeSelection(engine: CanvasEngine, dx: number, dy: number): void;
+/** ⇧⌘L: tape the selection down — or, when every selected widget is taped, lift the tape (one transaction). */
+export declare function toggleTape(engine: CanvasEngine): void;
 /**
  * Attach the default keymap (plus `overrides`) to `target` (default: `window`).
  * Returns a detach function. No-op (returns a no-op detach) when there is no

package/dist/types/packages/react/src/selection-menu.d.ts

@@ -0,0 +1,171 @@
+/**
+ * `<SelectionMenu>` — the desk's selection menu (design-015 §7, *Marks on the Mat*'s "ink bar"; D4a):
+ * the ONE piece of DOM beside the focused editor that the desk keeps (design-015 §2's law), in SCREEN
+ * space — one element tree, one plain transform, never a camera's. It is placed from the anchor the
+ * desk publishes (`source`, structurally the desk handle's `selection`: the marks' box around the
+ * selection as DRAWN — the brackets 6 px out, the union 10 px out), 10 px above it, centred; it flips
+ * below when it would cross the top ruler's band (or the view's top) and keeps 16 px from the sides.
+ * It steps aside for any gesture (a drag, a vellum, a pan, a pinch) — and while a note is being written
+ * (the one focused editor has the keys) — in 90 ms, and comes back 200 ms after (180 ms in). Its acts are an app-extensible list: ICE ships Duplicate (gone
+ * when the selection is all tape — "a copy of a taped thing is not taped"), Tape it down / Lift the tape,
+ * More (every act with its key), and Delete alone past a rule, colourless until the pointer arms it red;
+ * an app adds its own (VibeField: Send to agent, first). The glyphs are DESIGN.md §13's drawings and the
+ * page's six, inline SVG, currentColor. The ink is the whiteboard tray's (94 % ink, cream glyphs, brass
+ * hairlines, the lamp's shadow falling lower left) — CSS custom properties an app may re-point.
+ *
+ * `@ice/react` never imports the desk: the source is read structurally, as the ground layer is.
+ */
+import { type CanvasEngine } from "../../core/src/index";
+import { type ReactElement, type ReactNode } from "react";
+/** A screen rect, CSS px. */
+export interface SelectionMenuBox {
+    readonly x0: number;
+    readonly y0: number;
+    readonly x1: number;
+    readonly y1: number;
+}
+/** What the menu is placed from — the desk handle's `selection.anchor()`, mirrored structurally. */
+export interface SelectionMenuAnchor {
+    /** The marks' box around the selection on screen (null: nothing selected, or none of it drawn). */
+    readonly box: SelectionMenuBox | null;
+    readonly count: number;
+    /** Every selected object is taped. */
+    readonly locked: boolean;
+    /** A gesture is on: the menu steps aside. */
+    readonly gesturing: boolean;
+    /** A note is being written (the one focused editor): the menu steps aside as for a gesture. */
+    readonly editing?: boolean;
+    readonly view: {
+        readonly width: number;
+        readonly height: number;
+    };
+    /** The rulers printed along the top and left (their margin and band, CSS px), or null. */
+    readonly rulers: {
+        readonly margin: number;
+        readonly band: number;
+    } | null;
+    /**
+     * An object is IN HAND (design-015 §8, D4b): the menu travels to the foot of the view and changes role (M1) — one element,
+     * not a second toolbar — Send stays first, the kind's tools take the middle, Done ends the bar. `landing`: the object is
+     * flying home — the bar steps aside and comes back above the object 200 ms after it lands. `active` (D3t-a): the mode in
+     * hand — core's `HeldTool` — the one slot marked.
+     */
+    readonly held?: {
+        readonly tools: readonly SelectionMenuTool[];
+        readonly active?: string;
+        readonly landing: boolean;
+        readonly settled: boolean;
+    };
+    /**
+     * The selection's KIND ACTS (design-016 K8a — the desk's `MenuSlot`s, mirrored structurally): what every selected object's type
+     * declares (`defineObject({ menu })`); the menu shows them first among its acts and runs one through `ops.runMenuAction`.
+     */
+    readonly menu?: readonly SelectionMenuAct[];
+}
+/** A kind's act as the desk publishes it (its `MenuSlot`, mirrored structurally — K8a): plain data; the op stays on the widget type. */
+export interface SelectionMenuAct {
+    readonly id: string;
+    readonly label: string;
+    readonly glyph?: SelectionGlyph;
+    readonly keys?: string;
+}
+/**
+ * A glyph the bar draws (K8a — core's `HeldGlyph`, mirrored structurally): a NAME of its set (`SELECTION_GLYPHS`), or a tool's OWN
+ * drawing — SVG path data in the 24-unit box, stroked 2 units in the bar's ink (`currentColor`) as the set's are, or filled.
+ */
+export type SelectionGlyph = string | {
+    readonly path: string;
+    readonly fill?: boolean;
+};
+/**
+ * A slot of the held bar as the desk publishes it (its `HeldSlot`, mirrored structurally — D3t-a): a `mode` (pressed, it
+ * becomes the tool in hand) or an `action` (pressed, it runs its op), both through `ops.useHeldTool`; no `kind` = declared
+ * only, shown dim and inert. `swatch`: a colour shown instead of the glyph (a marker's ink). `glyph` (K8a): a name of the bar's
+ * set or the tool's own drawing — a plugin kind's tool draws its own; a name the bar does not draw is MARKED missing (its label's
+ * initial, `data-glyph-missing`, one console error), never drawn as another glyph.
+ */
+export interface SelectionMenuTool {
+    readonly id: string;
+    readonly label: string;
+    readonly kind?: "mode" | "action";
+    readonly hint?: string;
+    readonly glyph?: SelectionGlyph;
+    readonly swatch?: string;
+}
+/** The anchor's source — the desk handle's `selection` (anchor + a subscription that fires when it moves). */
+export interface SelectionMenuSource {
+    anchor(): SelectionMenuAnchor;
+    subscribe(listener: () => void): () => void;
+}
+/** What an act is told about the selection. */
+export interface SelectionState {
+    readonly count: number;
+    readonly locked: boolean;
+}
+export interface SelectionAction {
+    readonly id: string;
+    /** Its name — the button's accessible label and its tip; may read the selection ("Lift the tape"). */
+    readonly label: string | ((s: SelectionState) => string);
+    /** A glyph from `SELECTION_GLYPHS` by name, or any node — or one read off the selection (the lock opens when it is taped). */
+    readonly glyph: string | ReactNode | ((s: SelectionState) => string | ReactNode);
+    /** The key that does the same, shown in the tip and in More (e.g. "⌘D"). */
+    readonly keys?: string;
+    /** `lead` sits first (the app's own act — Send), `main` in the middle, `end` alone past a rule (Delete). */
+    readonly place?: "lead" | "main" | "end";
+    /** `danger`: colourless until the pointer arms it red. */
+    readonly tone?: "danger";
+    /** A text button (the lead act's label beside its glyph). */
+    readonly text?: boolean;
+    /** Shown for this selection (default: always). */
+    readonly when?: (s: SelectionState) => boolean;
+    /** Pressed-looking (the lock turns solid cream while the selection is taped). */
+    readonly on?: (s: SelectionState) => boolean;
+    run(engine: CanvasEngine, s: SelectionState): void;
+}
+/**
+ * The menu's numbers (*Marks on the Mat* §14): 40 tall, 10 above the marks, 16 from the sides, 8 from the view's top and foot;
+ * away 90 ms, back 200 ms after, in 180 ms. The held bar (§8, D4b): centred in the 72 px band at the foot, the travel 340 ms.
+ */
+export declare const SELECTION_MENU: {
+    readonly height: 40;
+    readonly gap: 10;
+    readonly margin: 16;
+    readonly edge: 8;
+    readonly awayMs: 90;
+    readonly backMs: 200;
+    readonly inMs: 180;
+    readonly outMs: 120;
+    readonly foot: 72;
+    readonly travelMs: 340;
+};
+/**
+ * Where the menu goes (desk.js `positionMenu`, number for number): centred on the anchor, `gap` above it; below it when
+ * there is no room above (under the top ruler's band) and more below; `margin` from the sides, `edge` from the top and foot.
+ * `sheet` = the height of an open sheet that must fit too. Null when there is nothing to anchor to. With an object IN HAND
+ * (D4b) the bar sits centred in the band at the foot of the view, whatever the selection's box.
+ */
+export declare function placeSelectionMenu(anchor: SelectionMenuAnchor, size: {
+    readonly w: number;
+    readonly h: number;
+}, sheet?: number): {
+    readonly x: number;
+    readonly y: number;
+    readonly below: boolean;
+} | null;
+/** DESIGN.md §13's drawings the bar uses and the six *Marks on the Mat* adds — 24-unit boxes, one 2-unit stroke, currentColor. */
+export declare const SELECTION_GLYPHS: Readonly<Record<string, ReactNode>>;
+/** ICE's own acts, in the bar's order: Duplicate (not for tape), Tape it down / Lift the tape, More, and Delete past a rule. */
+export declare function defaultSelectionActions(): SelectionAction[];
+/** The desk's INK as CSS custom properties — the menu's and, since design-018 §5, the tray bar's (`<TrayBar>`): one set of values; an app re-points them on either island. */
+export declare const DESK_INK = "--ice-menu-ink:rgb(16 9 4 / .94);--ice-menu-ink-solid:rgb(16 9 4);--ice-menu-cream:rgb(255 237 215);--ice-menu-cream-rgb:255 237 215;--ice-menu-brass:rgb(196 165 116);--ice-menu-hair:rgb(196 165 116 / .24);--ice-menu-rule:rgb(196 165 116 / .34);--ice-menu-danger:rgb(255 69 58);--ice-menu-danger-bg:rgb(255 69 58 / .16);--ice-menu-shadow:-1px 2px 3px rgb(14 26 10 / .25),-8px 14px 32px rgb(14 26 10 / .38)";
+export interface SelectionMenuProps {
+    /** Where to go — the desk handle's `selection`. */
+    readonly source: SelectionMenuSource;
+    /** The acts, in the bar's order within their places (default: `defaultSelectionActions()`); an app prepends its own. */
+    readonly actions?: readonly SelectionAction[];
+    /** The engine the acts run on (default: the `EngineProvider`'s — the one `<Desk>` is mounted under). */
+    readonly engine?: CanvasEngine;
+}
+export declare function SelectionMenu({ source, actions, engine: given }: SelectionMenuProps): ReactElement | null;
+/** Is every selected widget taped? (for an app's own acts) */
+export declare function selectionTaped(engine: CanvasEngine): boolean;

package/dist/types/packages/react/src/tray-bar.d.ts

@@ -0,0 +1,124 @@
+/**
+ * `<TrayBar>` — the pegboard drawer's HANDLE and its FILTERS (design-018 §5–§6, R4; ICE M22): DOM in screen space, the selection menu's
+ * sibling (design-015 §2 law 2 — never under the camera). The drawer stays the renderer's (design-017 §1); its handle and its filters
+ * are chrome, two islands under one root.
+ *
+ * THE PILL, in the desk's ink (`DESK_INK`, the same custom properties an app re-points): closed, a 40 px pill centred 16 px above the
+ * view's foot — the pegboard glyph (three staggered stadium holes) and the word Objects, titled "Objects (A)", `aria-expanded`; open, the
+ * same pill rides the drawer's top edge, its bottom 10 px above the board — `min(vh − 16, drawer.y − 10)`, written as the desk publishes
+ * each frame of the slide, so it follows the drawer exactly — its glyph a close ×.
+ *
+ * THE CHIPS (R4 — James: "design the filters nicely at that empty safe top space"): LABEL TAPE stuck on the board in the drawer's clear
+ * HEADER (the anchor's `drawer.header`, where nothing of the board's content shows), centred on the drawer's centre line and in the
+ * header, following the drawer every frame of its slide and fading in over its last part — All, then the frame's categories in the
+ * lay's order, in the specimens' own tag language (`DESK_TAPE`: the embosser's near-black tape and its raised pale capitals, the desk's
+ * `MARKS.label`), the chosen one CREAM tape with ink letters (the desk's "chosen is cream" — the menu's `data-on`), `aria-pressed`, in a
+ * `role="toolbar"`; past the header's width they scroll inside it, each end fading where more tape lies beyond. By night the tape steps
+ * back as the tags do (`night`, the anchor's).
+ * Both step aside while an object is IN HAND (the held bar has the view's foot then) and while the drawer has nothing to offer.
+ *
+ * Its pointer is chrome's: `data-canvas-interactive` flags the downs on the pill and on the chips, so the tray's input never takes one (a
+ * chip never closes the drawer as a click on the dimmed desk would) and the desk's tap never lends the object under it the editor — the
+ * header's bare board beside the chips stays the drawer's. Its keys: Enter and Space act on a focused button and ←/→ (Home/End) walk
+ * the chips, before the page's own listeners — the keymap keeps `a` and Esc; a pointer's click leaves no focus behind, so Space still
+ * pans and ⏎ is still the desk's. No rAF of its own: it moves only when the desk drew a frame that moved the drawer (idle-zero).
+ *
+ * `@ice/react` never imports the desk: the source is the desk handle's `tray` door, read structurally.
+ */
+import { type ReactElement } from "react";
+/** A category chip as the door lists it (core's `TrayCategory`, mirrored structurally): its id, its label, how many entries it holds. */
+export interface TrayBarCategory {
+    readonly id: string;
+    readonly label: string;
+    readonly count: number;
+}
+/** What the bar is placed from — the desk handle's `tray.anchor()` (`TrayAnchor`), mirrored structurally. */
+export interface TrayBarAnchor {
+    /** The drawer is out (the fact — its slide may still be on its way). */
+    readonly open: boolean;
+    /**
+     * The drawer's outline as drawn this frame (CSS px) and its slide — null before its first frame, or hidden — and its HEADER: the clear
+     * band under its edge (from `y`, `h` high) where nothing of the board's content shows, the chips' place.
+     */
+    readonly drawer: {
+        readonly x: number;
+        readonly y: number;
+        readonly w: number;
+        readonly p: number;
+        readonly header: {
+            readonly y: number;
+            readonly h: number;
+        };
+    } | null;
+    readonly view: {
+        readonly width: number;
+        readonly height: number;
+    };
+    /** The theme's night, 0 day … 1 the Moon: the tape steps back by it as the specimens' tags do. */
+    readonly night: number;
+    /** An object is in hand: the held bar has the view's foot — the bar steps aside. */
+    readonly held: boolean;
+    /** How many entries the drawer's frame hangs (0: nothing to offer — the bar steps aside). */
+    readonly entries: number;
+    /** The category shown ("" all) and the frame's categories in the lay's order. */
+    readonly category: string;
+    readonly categories: readonly TrayBarCategory[];
+}
+/** The bar's source — the desk handle's `tray` door: the anchor, a subscription that fires after each frame that moved it, and the acts. */
+export interface TrayBarSource {
+    anchor(): TrayBarAnchor;
+    subscribe(listener: () => void): () => void;
+    toggle(): boolean;
+    category(id?: string): string;
+}
+/**
+ * The bar's numbers (design-018 §5, R4): the pill 40 tall, 16 above the view's foot closed, 10 above the board open, 16 from the view's
+ * sides; away 90 ms, back in 180. The header's chips keep 12 in from the drawer's sides and fade in over the slide's last part — from
+ * `p` 0.6 to 1, a smoothstep (D-R4.6).
+ */
+export declare const TRAY_BAR: {
+    readonly height: 40;
+    readonly foot: 16;
+    readonly ride: 10;
+    readonly margin: 16;
+    readonly awayMs: 90;
+    readonly inMs: 180;
+    readonly headInset: 12;
+    readonly headFrom: 0.6;
+};
+/** Where the bar goes: the pill's top edge (CSS px), and the HEADER strip the chips lie centred in — with its opacity (null: no drawer drawn). */
+export interface TrayBarPlace {
+    readonly y: number;
+    readonly head: {
+        readonly x: number;
+        readonly y: number;
+        readonly w: number;
+        readonly h: number;
+        readonly opacity: number;
+    } | null;
+}
+/**
+ * Where the bar goes. The pill: its bottom `min(vh − foot, drawer.y − ride)`, so it waits at the foot while the drawer's edge is below it
+ * and rides the edge from there, one continuous motion. The chips: the drawer's header as drawn, `headInset` in from its sides, at the
+ * slide's `smoothstep(headFrom, 1, p)` — one motion with the board, arriving as it does.
+ */
+export declare function placeTrayBar(a: TrayBarAnchor, height?: number): TrayBarPlace;
+/** The bar's two drawings (24-unit boxes, currentColor): the PEGBOARD — three staggered stadium holes, a board's punched slots — and the close ×. */
+export declare const TRAY_BAR_GLYPHS: {
+    readonly pegboard: import("react").JSX.Element;
+    readonly close: import("react").JSX.Element;
+};
+/**
+ * The LABEL TAPE (design-018 R4) as custom properties an app re-points, as it does the ink's: the specimens' own tags — the embosser's
+ * near-black tape and the pale plastic of its raised capitals (the desk's `MARKS.label`, the marks pass's `tagMarks`) — the CHOSEN tape,
+ * cream with ink letters, and the capitals' face (the page's mono stack, `--vf-font-mono`, as the tags' glyph atlas draws them).
+ */
+export declare const DESK_TAPE = "--ice-tape:#17181b;--ice-tape-letters-rgb:236 235 228;--ice-tape-chosen:#efe9da;--ice-tape-chosen-ink:rgb(16 9 4);--ice-tape-font:var(--vf-font-mono,ui-monospace,\"SF Mono\",Menlo,monospace)";
+export interface TrayBarProps {
+    /** The drawer's door — the desk handle's `tray`. */
+    readonly source: TrayBarSource;
+    /** The button's word (default "Objects") and the key named in its tip (default "A" — the app's toggle). */
+    readonly label?: string;
+    readonly keys?: string;
+}
+export declare function TrayBar({ source, label, keys }: TrayBarProps): ReactElement;