@vibecook/ice 0.11.0 → 0.14.0

package/dist/types/packages/devtools/src/dock.d.ts

@@ -1,24 +1,28 @@
 /**
- * The devtools dock — ONE draggable window hosting all three tools
- * (2026-07-13, James: "make the 3 tools into one draggable panel").
+ * The devtools dock — ONE draggable window hosting the tools
+ * (2026-07-13, James: "make the 3 tools into one draggable panel"; two since
+ * design-015 D5b — the GL metrics panel, the r3f stats mirror, left with the
+ * GL islands it read — and three again since design-016 K2: the `gpu` slot,
+ * the WebGPU desk's profiler, between the strip and the observer).
  *
- * strata's observer + profiler and our GL panel each mount `position: fixed`
- * into their own corner. The dock does NOT re-implement any of them (standing
- * rule: wrap first-party tools): it is a fixed, draggable shell with three
- * stacked slots; each tool mounts into its slot via its own `container`
- * option, and dock-scoped CSS de-windows them (`position: static`, full
- * width, no border/shadow) so they read as sections of one panel. Their own
- * behavior is untouched — the observer keeps its tabs/collapse/vertical
- * resize (its header drag goes inert: left/top are ignored at static), the
- * profiler + GL strips keep their click-to-expand.
+ * strata's observer + profiler each mount `position: fixed` into their own
+ * corner. The dock does NOT re-implement either (standing rule: wrap
+ * first-party tools): it is a fixed, draggable shell with stacked slots; each
+ * tool mounts into its slot via its own `container` option, and dock-scoped
+ * CSS de-windows them (`position: static`, full width, no border/shadow) so
+ * they read as sections of one panel. Their own behavior is untouched — the
+ * observer keeps its tabs/collapse/vertical resize (its header drag goes
+ * inert: left/top are ignored at static), the profiler strip keeps its
+ * click-to-expand.
  *
- * Slot order is fixed by the dock, not by mount order: profiler and GL are
- * one-line summary strips, the observer is the deep-dive — strips on top.
+ * Slot order is fixed by the dock, not by mount order: the profiler is a
+ * one-line summary strip, the observer is the deep-dive — the strip on top,
+ * the GPU's frames under it, the observer last.
  * Layout (x/y/width/open) persists to localStorage, same as the observer:
  * schema edits full-reload the page by design; the dock must stay put.
  */
 export type DockCorner = "tl" | "tr" | "bl" | "br";
-export type DockSlotId = "profiler" | "gl" | "observer";
+export type DockSlotId = "profiler" | "gpu" | "observer";
 export interface DockOptions {
     /** Where the dock mounts (default: document.body). */
     readonly container?: HTMLElement;

package/dist/types/packages/devtools/src/gpu-panel.d.ts

@@ -0,0 +1,105 @@
+/**
+ * The GPU panel — the WebGPU desk's frames as its GPU saw them (design-016 §4.5, K2), the dock's `gpu` slot: what the "ice gl"
+ * panel was for the r3f islands until design-015 D5b, rebuilt for the desk's profiler.
+ *
+ * Pure DOM, strata's visual language (the observer's and the profiler's palette and type, so the dock reads as one toolset).
+ * Fed by pushes of `GpuPanelFrame` + `GpuPanelStats` — STRUCTURAL MIRRORS of `@ice/desk`'s `GpuFrameReport` and
+ * `GpuProfileStats` (devtools cannot import desk under the walls — `nobody-imports-desk`; this is how `GlPanelStats`
+ * mirrored r3f's `GlFrameStats`). apps/desk holds the two in step: its typecheck asserts desk's are assignable to these.
+ *
+ *   head      the GPU SPAN's p50 (THE headline: first pass begun → last pass ended), p95 · max, a sparkline against the budget
+ *   warning   timestamps quantised to 100 µs — and the Chrome switch that turns it off
+ *   frame     span / busy (the span less the GPU's waits) / encode / desk flush bars against the budget, p50 · p95 · max
+ *   passes    the last timed frame's passes on its span (they overlap on a tiler, and the GPU waits between them: the sum is not the frame — both shown)
+ *   calls     draws · instances · pipelines · bind groups · passes · submits · writes · upload bytes
+ *   by kind   draws and instances by the kind that drew (a run of notes is ONE instanced draw)
+ *   uploads   the frame's bytes by label · memory: live GPU bytes by label (the ledger), textures / buffers
+ *   capture   "capture N frames" → a Chrome trace-event JSON, saved (Perfetto / chrome://tracing)
+ *
+ * All values land via `textContent` (never innerHTML with data). Rendering is throttled: pushes arrive per frame, the DOM
+ * refreshes at ~8 Hz.
+ */
+/** Mirror of `@ice/desk` `PassTime`. */
+export interface GpuPanelPass {
+    readonly label: string;
+    readonly begin: number;
+    readonly end: number;
+}
+/** Mirror of `@ice/desk` `GpuFrameReport` (structural — see the header). */
+export interface GpuPanelFrame {
+    readonly frame: number;
+    readonly span: number | null;
+    readonly sum: number | null;
+    readonly busy: number | null;
+    readonly passes: readonly GpuPanelPass[];
+    readonly counts: {
+        readonly draws: number;
+        readonly instances: number;
+        readonly pipelines: number;
+        readonly bindGroups: number;
+        readonly passes: number;
+        readonly submits: number;
+        readonly writes: number;
+        readonly uploadBytes: number;
+    };
+    readonly byKind: Readonly<Record<string, {
+        readonly draws: number;
+        readonly instances: number;
+    }>>;
+    readonly uploads: Readonly<Record<string, {
+        readonly writes: number;
+        readonly bytes: number;
+    }>>;
+    readonly cpu: {
+        readonly encode: number;
+        readonly flush: number | null;
+    };
+    readonly memory: {
+        readonly byLabel: Readonly<Record<string, {
+            readonly bytes: number;
+            readonly textures: number;
+            readonly buffers: number;
+        }>>;
+        readonly textures: number;
+        readonly buffers: number;
+        readonly total: number;
+    } | null;
+    readonly quantised: boolean | null;
+}
+/** Mirror of `@ice/desk` `Rolling`. */
+export interface GpuPanelRolling {
+    readonly n: number;
+    readonly p50: number;
+    readonly p95: number;
+    readonly max: number;
+}
+/** Mirror of `@ice/desk` `GpuProfileStats` (the fields the panel reads). */
+export interface GpuPanelStats {
+    readonly frames: number;
+    readonly span: GpuPanelRolling | null;
+    readonly busy: GpuPanelRolling | null;
+    readonly encode: GpuPanelRolling | null;
+    readonly flush: GpuPanelRolling | null;
+    readonly quantised: boolean | null;
+    readonly unquantise: string;
+    readonly dropped: number;
+}
+export interface GpuPanelOptions {
+    readonly container?: HTMLElement;
+    /** The frame budget, ms — the bars' and the sparkline's reference (default 16.7). */
+    readonly budgetMs?: number;
+    /** Start with the detail body open (default true: the dock opens to read it). */
+    readonly expanded?: boolean;
+    /** "capture N frames": the host's capture (a trace-event JSON) — the panel saves what it answers. Absent: no button. */
+    readonly capture?: (frames: number) => Promise<unknown>;
+    /** The frames a capture asks for (default 120). */
+    readonly captureFrames?: number;
+}
+export interface GpuPanel {
+    push(frame: GpuPanelFrame, stats?: GpuPanelStats): void;
+    readonly el: HTMLElement;
+    dispose(): void;
+}
+export declare const fmtMs: (ms: number | null | undefined) => string;
+export declare const fmtBytes: (b: number) => string;
+export declare function createGpuPanel(opts?: GpuPanelOptions): GpuPanel;

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

@@ -1,10 +1,11 @@
 /**
  * @ice/devtools — strata's observer panel + FPS profiler, engine-flavored
- * (describe/durable/ephemeral/reflect-lane glue). Reads the world outside the
- * tick; never a reflector, never writes ECS. Nobody imports us
- * (depcruise-enforced leaf).
+ * (describe/durable/ephemeral/reflect-lane glue), and the GPU panel the WebGPU
+ * desk's profiler feeds (design-016 K2). Reads the world outside the tick;
+ * never a reflector, never writes ECS. Nobody imports us (depcruise-enforced
+ * leaf).
  */
 export declare const DEVTOOLS_VERSION = "0.1.0";
 export { attachDevtools, engineDescribe, type DevtoolsEngine, type DevtoolsHandle, type DevtoolsOpts, } from "./attach";
 export { createDock, type Dock, type DockCorner, type DockOptions, type DockSlotId } from "./dock";
-export { createGlPanel, type GlPanel, type GlPanelCorner, type GlPanelOptions, type GlPanelStats } from "./gl-panel";
+export { createGpuPanel, fmtBytes, fmtMs, type GpuPanel, type GpuPanelFrame, type GpuPanelOptions, type GpuPanelPass, type GpuPanelRolling, type GpuPanelStats, } from "./gpu-panel";

package/dist/types/packages/dom/src/desk-host.d.ts

@@ -0,0 +1,91 @@
+/**
+ * `createDeskHost` — the vanilla mount (design-015 §3, D-D15; D5b). What `<InfiniteCanvas>` did
+ * for the hybrid, with the hybrid gone: ONE container, the desk's layer in it, and this package's
+ * screen-space half around it — the pointer adapter (L0's one producer), the rAF loop, the OS
+ * cursor, the room's other people (the remote cursors), the focus driver, the viewport sync.
+ * `@ice/react`'s `<Desk>` wraps it; an app without React mounts it directly.
+ *
+ * THE DESK ARRIVES AS AN OPAQUE LAYER FACTORY. This package never imports `@ice/desk` (the wall
+ * `nobody-imports-desk`): the factory's context and its handle are typed STRUCTURALLY here —
+ * exactly as `<InfiniteCanvas ground={groundCompose(…)}>` received the ground — and
+ * `@ice/desk`'s `deskLayer(opts)` (its src/host/) returns a function assignable to {@link LayerFactory}.
+ * The context carries the interaction stack's seams the renderer fills (the frame pick, the nav
+ * geometry, the held pose — design-014 B3b, design-015 §8–§9) and the marquee buffer it draws.
+ *
+ * Boot order (registration order = reflector flush order): host → layer → reflectors [ layer ·
+ * cursor · remoteCursors ] → pointer adapter → focus → viewport (one layout read, then a
+ * ResizeObserver, and the device's ratio read before every step) → rAF loop. `dispose` undoes it in reverse. The engine is NOT owned here — it
+ * outlives the mount (the app disposes it). A layer factory that throws leaves nothing claimed on
+ * the engine: it runs before any registration, and only the local host is undone.
+ */
+import { type CanvasEngine, type EngineGpu, type InteractionStack, type ReflectorDef, type World } from "../../core/src/index";
+import { type CanvasHost } from "./host";
+import { type WidgetFocusHandle } from "./widget-focus";
+/**
+ * What the host needs of a mounted layer: its drawing reflector and its teardown. The desk's own
+ * handle (`@ice/desk`'s `DeskLayerHandle`) carries far more; an app keeps that through its
+ * own factory wrapper, or reads it off {@link DeskHost.layer} typed as the factory returned it.
+ */
+export interface LayerHandle {
+    readonly reflector: ReflectorDef & {
+        available(): boolean;
+    };
+    dispose(): void;
+}
+/** The mount context a layer factory receives: the host, the world and the seams the renderer fills. */
+export interface LayerContext {
+    readonly host: CanvasHost;
+    readonly world: World;
+    /** The frame pick slot (design-014, B3b): the renderer sets its hit test here at mount, clears it at dispose. */
+    readonly framePick: InteractionStack["framePick"];
+    /** The nav geometry slot (design-015 §9, D2b): the renderer's word on its containers' drawn faces. */
+    readonly navGeometry: InteractionStack["navGeometry"];
+    /** The held pose slot (design-015 §8, D4b): where the object in hand is on screen, as drawn. */
+    readonly heldPose: InteractionStack["heldPose"];
+    /** The tray pose slot (design-017 §4, K3): where the pegboard drawer is on screen, as drawn. */
+    readonly trayPose: InteractionStack["trayPose"];
+    /** The presentation transition coordinator: the layer registers the `ground` plane so a nav flight can prepare. */
+    readonly transitions: CanvasEngine["transitions"];
+    /** The engine's catalog: the object types whose kinds the layer registers. */
+    readonly catalog: CanvasEngine["catalog"];
+    /** The marquee's preview, out of the ECS (design-003 §5.7): the vellum the marks draw (design-015 D4a). */
+    readonly readMarquee: () => InteractionStack["marqueeBuffer"];
+    /** The one spatial index (design-015 §2.5; D6): the renderer's cull rides it with a hysteresis margin — no per-entity rect test on a pan. */
+    readonly spatial: InteractionStack["index"];
+    /** The engine's device (`engine.compositorDevice`), when the app passed one (design-015 D7): the layer draws with it — ONE device per engine. */
+    readonly gpu?: EngineGpu;
+    /**
+     * The frame gate's sleep (K7a, `@ice/core` frame-control.ts): the layer registers when it is next due (`wakeWhen`), wakes a
+     * sleeping loop for what it hears outside a step (`wake` — an asset landing, a theme, a pin), and asks whether the step in
+     * progress is a registered time's alone (`settled` — then it ticks only what is due).
+     */
+    readonly frame?: Pick<CanvasEngine["engine"]["frame"], "wake" | "wakeWhen" | "settled">;
+}
+export type LayerFactory<H extends LayerHandle = LayerHandle> = (ctx: LayerContext) => H;
+export interface DeskHostOptions<H extends LayerHandle = LayerHandle> {
+    /** The viewport element; styled, not created, by the host. */
+    readonly container: HTMLElement;
+    /** A constructed engine (`createCanvasEngine(...)`); NOT disposed by the host. */
+    readonly engine: CanvasEngine;
+    /** The desk — `deskLayer({ … })` from `@vibecook/ice/desk` (`@ice/desk`'s src/host/), received opaquely. */
+    readonly layer: LayerFactory<H>;
+    /**
+     * The loop SLEEPS when the engine is quiet (K7a — design-015 §11.4: a desk at rest costs the main thread nothing): no frame
+     * until an input, a write, an arrival or a registered time wakes it. Default true; false steps every frame, as before K7a.
+     */
+    readonly sleep?: boolean;
+}
+export interface DeskHost<H extends LayerHandle = LayerHandle> {
+    readonly engine: CanvasEngine;
+    readonly host: CanvasHost;
+    /** The mounted layer's handle, as the factory returned it. */
+    readonly layer: H;
+    /**
+     * The focus driver (design-007 §2.3): `blurFocus()` releases whatever keyboard claim holds
+     * focus. Focus is VIEW state (design-007 §2.6) — it rides the mount, not `engine.ops`.
+     */
+    readonly focus: WidgetFocusHandle;
+    /** Stop the loop, detach every adapter, unregister every reflector, dispose the layer and the host. Idempotent. */
+    dispose(): void;
+}
+export declare function createDeskHost<H extends LayerHandle>(opts: DeskHostOptions<H>): DeskHost<H>;

package/dist/types/packages/dom/src/host.d.ts

@@ -1,24 +1,23 @@
 /**
- * The DOM canvas host (design-004 §1, host pipeline — M3 slice).
- *
- * M3 stands up ONE content plane: an absolutely-positioned div whose single CSS
- * transform (written by the plane-transform reflector) applies the camera to
- * every world-positioned child at once (design-002 §5 `planeTransform`; kernel
- * `planeCssTransform`). The full six-plane model (background/content/overlay/
- * chrome/HUD/nav + the FBO compositor) arrives in M6 — this file is deliberately
- * the minimum that lets a reflector paint into a camera-transformed space.
+ * The canvas host (design-004 §1, host pipeline; SCREEN SPACE ONLY since design-015 D5b).
  *
  * The container is styled to be a stable, gesture-clean viewport: `relative` so
- * the absolute plane anchors to it, `overflow:hidden` to clip the infinite
- * plane, `touch-action:none` + `user-select:none` so browser scroll/zoom and
- * text selection never fight the interaction stack.
+ * absolutely-positioned children (the desk's canvas, the one focused editor, the
+ * remote-cursor plane, the app's screen-space chrome) anchor to it,
+ * `overflow:hidden` to clip them, `touch-action:none` + `user-select:none` so
+ * browser scroll/zoom and text selection never fight the interaction stack.
+ *
+ * THE CONTENT PLANE IS GONE (design-015 §2 law 2). Until D5b the host also made
+ * one camera-transformed `<div>` — M3's "content plane", the P1 every DOM
+ * widget mounted in, carrying the camera as ONE CSS transform written by the
+ * plane-transform reflector (kernel `planeCssTransform`, gone since D7). No DOM element
+ * carries a camera transform any more: everything under the camera is the
+ * desk renderer's, and the DOM that remains is screen-space.
  */
 export interface CanvasHost {
     /** The app-provided viewport element (styled, not created, by the host). */
     readonly container: HTMLElement;
-    /** The single camera-transformed plane; world-positioned children mount here. */
-    readonly contentPlane: HTMLDivElement;
-    /** Remove the plane and clear the inline styles the host wrote. */
+    /** Clear the inline styles the host wrote. */
     dispose(): void;
 }
 export declare function createCanvasHost(container: HTMLElement): CanvasHost;

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

@@ -1,19 +1,21 @@
 /**
- * @ice/dom — DOM planes, pointer adapters (events→queue ONLY), built-in DOM reflectors.
- * Import wall: @ice/core + @ice/kernel down only — never react/three (enforced).
+ * @ice/dom — SCREEN SPACE ONLY (design-015 §3, D-D15; D5b): the canvas host, the pointer
+ * adapter (events → queue ONLY), the rAF loop, input ownership + the editor's focus, the OS
+ * cursor + the room's remote cursors, and `createDeskHost` — the vanilla mount that takes the
+ * desk as an opaque layer factory.
+ * Import wall: @ice/core + @ice/kernel down only — never react/three/desk (enforced).
+ *
+ * GONE at D5b — the WORLD-SPACE half (design-015 §1): the content and lifted planes, the
+ * plane-transform reflector, the DOM widget hosts + writeback, the L1 source canvas
+ * (`layoutsubtree`), the Widget Surface contract, measurement, the graybox and the P4 chrome
+ * reflectors, and the pointer adapter's GL route. No DOM under the camera (DK-D2).
  */
 export declare const DOM_VERSION = "0.0.0";
 export { createCanvasHost, type CanvasHost } from "./host";
-export { createPlanes, type Planes } from "./planes";
-export { createPlaneTransformReflector, type CameraPlanes } from "./reflectors/plane-transform";
-export { createGrayboxReflector } from "./reflectors/graybox";
-export { createDomWidgetsReflector, type DomWidgetsHost, type DomWidgetsReflector, } from "./reflectors/dom-widgets";
+export { createDeskHost, type DeskHost, type DeskHostOptions, type LayerContext, type LayerFactory, type LayerHandle, } from "./desk-host";
 export { startRafLoop } from "./loop";
-export { attachPointerAdapter, type GLRoute, type GLRouteVerdict, type PointerAdapterOpts } from "./pointer-adapter";
+export { attachPointerAdapter } from "./pointer-adapter";
 export { CLAIM_OWNS_ESCAPE, KEYBOARD_CLAIM_ATTR, isEditableTarget, keyboardClaimOf, wheelCede, type KeyboardClaim, } from "./input-ownership";
 export { FOCUS_PROXY_ATTR, attachWidgetFocus, type FocusHostLookup, type WidgetFocusHandle, } from "./widget-focus";
 export { createCursorReflector } from "./reflectors/cursor";
 export { createRemoteCursorsReflector, type RemoteCursorsReflector } from "./reflectors/remote-cursors";
-export { createChromeReflector } from "./reflectors/chrome";
-export { attachMeasureAdapter, type MeasureAdapter } from "./measure-adapter";
-export { wireMeasurement, type MeasureWiringHosts, type MeasureWiringOpts } from "./measure-wiring";

package/dist/types/packages/dom/src/loop.d.ts

@@ -26,6 +26,23 @@
  * not restart it. Recovery needed a fresh `startRafLoop`. The next frame is now
  * scheduled in a `finally`, so a faulting frame is loud but survivable — the
  * throw still reaches the browser's error handler; only the death is gone.
+ *
+ * BEFORE EACH STEP (2026-09-27, ICE M21 K1): an optional `beforeStep` — where a host reads what the
+ * platform changes without an event it can hear (the device's ratio: `createDeskHost`). It runs
+ * only for a step that runs (never while parked), and inside the same `try`, so a throwing hook is
+ * as survivable as a throwing step.
+ *
+ * THE SLEEP (2026-09-27, ICE M21 K7a — `@ice/core`'s frame-control.ts): with `sleep`, the loop asks
+ * the frame gate after every step when the next one is due, and SLEEPS when it is not the next
+ * frame — no rAF queued, and a timer only when a registered wake names a time (a flight, a caret's
+ * blink, a layer let go). A wake (an input, a write from outside a step, a document's or a room's
+ * arrival, a desk's flux) restarts it in the next frame; so does a freeze, whose settle walk needs
+ * steps. A desk at rest then costs the main thread nothing at all (design-015 §11.4). Without
+ * `sleep` the loop steps every frame, as it always did.
  */
 import type { Engine } from "../../core/src/index";
-export declare function startRafLoop(engine: Engine): () => void;
+export interface RafLoopOptions {
+    /** Sleep when the engine is quiet (K7a): no frame scheduled until a wake or a registered time. Default false. */
+    readonly sleep?: boolean;
+}
+export declare function startRafLoop(engine: Engine, beforeStep?: (now: number) => void, opts?: RafLoopOptions): () => void;

package/dist/types/packages/dom/src/pointer-adapter.d.ts

@@ -43,9 +43,10 @@
  * canvas fact at all — that is the design, not a gap.
  *
  * Hover-time amendment (design-002 §8, 2026-07-18): down/move facts ALSO carry
- * `overInteractive` — the same `crossesInteractive` check, run at hover time,
- * OR'd with the GL router's hover verdict — so the world can telegraph the
- * opt-out BEFORE a down (cursor affordances). It never gates gestures:
+ * `overInteractive` — the same `crossesInteractive` check, run at hover time —
+ * so the world can telegraph the opt-out BEFORE a down (cursor affordances).
+ * (Until design-015 D5b the GL router's hover verdict was OR'd in; the GL
+ * route left with the islands it picked.) It never gates gestures:
  * `surfaceHandled` stays down-only and keeps its exact meaning. During a
  * container-captured drag every event retargets to the container, so
  * `overInteractive` reads false mid-gesture — correct: the gesture owns the
@@ -53,29 +54,4 @@
  */
 import { type InputQueue } from "../../core/src/index";
 import type { CanvasHost } from "./host";
-/**
- * The router GL path's adapter seam (design-004 §4). The GL plane is
- * `pointer-events: none` — its events land HERE, and the injected router
- * (built by @ice/r3f; the adapter stays ECS-free) performs the synchronous
- * point-pick + island raycast + synthetic dispatch at event time. Returning
- * `true` means island content claimed the event (stopPropagation'd or held
- * under island capture): the fact still lands — flagged `surfaceHandled`, so
- * recognizers skip it via `HandledByWidget` — the same contract as the
- * native-interactive opt-out.
- */
-export type GLRoute = (kind: "down" | "move" | "up" | "cancel", screenX: number, screenY: number, native: PointerEvent) => boolean | GLRouteVerdict;
-/**
- * The richer GL verdict (hover-time amendment, 2026-07-18): `handled` keeps the
- * boolean's exact meaning (island content claimed the event); `overInteractive`
- * adds the hover fact — the pick chain holds claim-capable content (a mesh with
- * a down/click handler), so a down HERE would be the island's. Plain `boolean`
- * returns stay legal (≡ `{ handled }`), so existing routes never break.
- */
-export interface GLRouteVerdict {
-    readonly handled: boolean;
-    readonly overInteractive?: boolean;
-}
-export interface PointerAdapterOpts {
-    readonly glRoute?: GLRoute;
-}
-export declare function attachPointerAdapter(host: CanvasHost, queue: InputQueue, opts?: PointerAdapterOpts): () => void;
+export declare function attachPointerAdapter(host: CanvasHost, queue: InputQueue): () => void;

package/dist/types/packages/dom/src/widget-focus.d.ts

@@ -9,19 +9,19 @@
  * world (there is no Focus resource; design-007 §2.2 demoted it, and despawn
  * integrity is free: removing the node resets `activeElement`).
  *
- * Acquisition is DOM-at-event-time, not a world system: for DOM widgets the
- * browser's own event targeting IS the pick (the down target sits inside the
- * claiming host), and for GL widgets the claim lives on the DOM-chrome host
- * under the pointer (the GL plane is `pointer-events:none`, so the down lands
- * on the chrome — design-007 §2.5's proxy path). A capture-phase listener
- * keeps ordering deterministic across browsers (Safari's click-focus quirks):
+ * Acquisition is DOM-at-event-time, not a world system: the browser's own event
+ * targeting IS the pick (the down target sits inside the claiming host — since
+ * design-015 D5b that host is screen-space chrome, never a widget under the
+ * camera; the desk's one focused editor acquires focus on its own, the same
+ * principle). A capture-phase listener keeps ordering deterministic across
+ * browsers (Safari's click-focus quirks):
  *
  *  - down on a natively-focusable node inside the claim (textarea, canvas
  *    with tabindex, the declared proxy itself) → the browser's own mousedown
  *    focus is correct; the driver does nothing.
- *  - down anywhere else inside the claim → the driver focuses the widget's
+ *  - down anywhere else inside the claim → the driver focuses the claim's
  *    declared `[data-canvas-focus]` proxy when one exists, else the host
- *    (the reflector gave it `tabindex="-1"`), with `preventScroll` — and
+ *    (which carries `tabindex="-1"`), with `preventScroll` — and
  *    `preventDefault()`s the pointerdown so the native focus fixup cannot
  *    fight the choice. Canceling a pointerdown suppresses only the compat
  *    mouse events (focus fixup + text selection — the container is already
@@ -38,16 +38,20 @@ import type { Entity } from "../../core/src/index";
 import type { CanvasHost } from "./host";
 /** The widget-declared focus target (a proxy descendant): `<div data-canvas-focus tabIndex={-1}>`. */
 export declare const FOCUS_PROXY_ATTR = "data-canvas-focus";
-/** Resolves an entity to its host's content element (the dom-widgets reflector's `hostFor`). */
+/**
+ * Resolves an entity to a claiming host's content element — what `focusWidget` walks from. The
+ * dom-widgets reflector was the one lookup until design-015 D5b; a host that keeps per-entity
+ * DOM (none in the engine today) may still hand one in.
+ */
 export interface FocusHostLookup {
     hostFor(entity: Entity): HTMLElement | undefined;
 }
 export interface WidgetFocusHandle {
     /**
      * Programmatically focus a claiming widget (its proxy, else its host).
-     * Returns false when the entity has no mounted host or no keyboard claim —
-     * only `keyboard: "exclusive"` widgets are focusable (declaration drives
-     * focusability; design-007 §3.1).
+     * Returns false when the entity has no host in the lookup (always, without
+     * one) or no keyboard claim — only `keyboard: "exclusive"` widgets are
+     * focusable (declaration drives focusability; design-007 §3.1).
      */
     focusWidget(entity: Entity): boolean;
     /** Blur whatever claim currently holds focus. False when none does. */
@@ -55,4 +59,4 @@ export interface WidgetFocusHandle {
     /** Remove the acquisition listener. */
     detach(): void;
 }
-export declare function attachWidgetFocus(host: CanvasHost, lookup: FocusHostLookup): WidgetFocusHandle;
+export declare function attachWidgetFocus(host: CanvasHost, lookup?: FocusHostLookup): WidgetFocusHandle;

package/dist/types/packages/ice/src/desk-engine.d.ts

@@ -0,0 +1,2 @@
+/** `@vibecook/ice/desk/engine` — the raw-WebGPU engine the desk draws with (design-015 §4.1). */
+export * from "../../desk/src/engine/index";

package/dist/types/packages/ice/src/desk-kit.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `@vibecook/ice/desk/kit` — the desk's render kit (design-016 §5): what a kind's pass is written against besides the
+ * engine — the slot's view and its mat (`MatPass`), the lamp and its light, the shared WGSL by name (`kitWgsl`), a
+ * container's inside, the host services a kind is lent (text, print, blobs), and the one physics every object shares.
+ */
+export * from "../../desk/src/kit/index";

package/dist/types/packages/ice/src/desk-objects.d.ts

@@ -0,0 +1,5 @@
+/**
+ * `@vibecook/ice/desk/objects` — the six reference object kinds (design-015 §6), their own package since design-016 K4b
+ * (`@ice/objects`): built on the desk's public entries alone, as a plugin kind is.
+ */
+export * from "../../objects/src/index";

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

@@ -0,0 +1,5 @@
+/**
+ * `@vibecook/ice/desk` — the desk (design-015 §3): the renderer, the host half (`deskLayer`,
+ * the one focused editor, the text raster), `defineObject`, the kind registry, the theme.
+ */
+export * from "../../desk/src/index";