@vibecook/ice 0.11.0 → 0.14.0

package/README.md

@@ -1,9 +1,9 @@
 # @vibecook/ice
 
-**ICE — infinite canvas engine.** Figma-grade infinite-canvas UX as a framework:
-`defineWidget` turns React (or React-Three-Fiber) components into canvas
-citizens — selectable, movable, resizable, snappable, wired into node graphs,
-synced over CRDT, undoable per gesture.
+**ICE — infinite canvas engine.** Figma-grade infinite-canvas UX as a framework — THE DESK:
+every object under the camera drawn by one WebGPU renderer from a CRDT-synced ECS world, the
+DOM in screen space. `defineObject` turns a GPU object kind into a canvas citizen — selectable,
+movable, resizable, snappable, nested in mini mats, synced over CRDT, undoable per gesture.
 
 Built on [`@vibecook/strata-ecs`](https://www.npmjs.com/package/@vibecook/strata-ecs):
 an archetype ECS with reactivity and opt-in Loro-CRDT durable + presence layers.
@@ -11,74 +11,108 @@ an archetype ECS with reactivity and opt-in Loro-CRDT durable + presence layers.
 **Docs:** <https://vibefield.github.io/infinite-canvas-engine/> ·
 **Source:** <https://github.com/vibefield/infinite-canvas-engine>
 
+> **0.14.0 (design-015 D5b, 2026-09-26) breaks:** the DOM/R3F widget hybrid is deleted — no `three`,
+> no `@react-three/fiber`, no presentation profiles, no React widget faces. `<InfiniteCanvas>` is
+> `<Desk>`; `defineWidget`'s `surface`/`component`/`chrome`/`animated`/`preview`/`instancePreview`/
+> `sizeMode` are refused; the entries `./r3f`, `./r3f/webgpu`, `./ground*` are gone and
+> `./desk`, `./desk/engine`, `./desk/objects` are new. The full list is the changelog's
+> `### Removed`. (The published 0.11.0 still describes the old surface.)
+
 ```sh
 pnpm add @vibecook/ice react react-dom     # react/react-dom are optional peers
 ```
 
 ```tsx
-import { createCanvasEngine, defineWidget, p } from "@vibecook/ice";
-import { EngineProvider, InfiniteCanvas, attachKeymap, useCommit, useWidgetProps } from "@vibecook/ice/react";
+import { createCanvasEngine } from "@vibecook/ice";
+import { deskLayer, inkRaster, penFaces } from "@vibecook/ice/desk";
+import { DESK_ENGINE, DESK_OBJECTS, deskPalette, deskTheme } from "@vibecook/ice/desk/objects";
+import { Desk, EngineProvider } from "@vibecook/ice/react";
 import { createRoot } from "react-dom/client";
 
-const Sticky = defineWidget({
-  type: "sticky",
-  surface: "dom",
-  props: { text: p.string({ default: "Write something…" }) },
-  component: StickyView,
-  defaultSize: { w: 220, h: 160 },
-  interaction: { selectable: true, movable: true, resizable: true, snap: "both" },
-});
-
-function StickyView({ entity, world }) {
-  const props = useWidgetProps(world, entity, "sticky");
-  const commit = useCommit(); // one commit call = one undo step, synced to every peer
-  return (
-    <textarea
-      value={props.text}
-      onChange={(e) => commit((tx) => tx.edit(entity).set(Sticky.groups[0].component, { text: e.target.value }))}
-    />
-  );
-}
-
-const engine = createCanvasEngine({ widgets: [Sticky] });
+// The desk's preset: the six objects, the desk's select tool (a bare-mat drag pans, shift draws the
+// marquee), a plain wheel zooming about the pointer, the scale-free zoom and the zoom-through.
+const engine = createCanvasEngine(DESK_ENGINE);
 engine.docs.create(); // a local-first document
-engine.ops.spawnWidget("sticky", { x: 120, y: 120 });
-attachKeymap(engine); // ⌫ · ⌘Z · ⌘D · ⌘A · Esc · arrows · v/h/c
+engine.ops.spawnWidget("desk.note", { x: 120, y: 120, props: { text: "Write something…" } });
+
+// The desk is an OPAQUE layer factory: the renderer, its kinds, the theme, the text raster.
+const layer = deskLayer({
+  theme: deskTheme("light"), palette: deskPalette("light"),   // the shipped default palette — or your own tokens
+  objects: [...DESK_OBJECTS], docs: engine.docs,
+  text: inkRaster({ faces: penFaces({ caveat: caveatUrl, "caveat-bold": caveatBoldUrl, kalam: kalamUrl }) }),   // YOUR URLs for the hands' fonts (Caveat, Kalam — OFL; apps/desk/assets/fonts)
+});
 
 createRoot(document.getElementById("root")).render(
   <EngineProvider engine={engine}>
-    <InfiniteCanvas engine={engine} />
+    <Desk engine={engine} layer={layer} />   {/* mounts the desk, the adapters, the keymap */}
   </EngineProvider>,
 );
 ```
 
-Everything above ships working out of the box: click/shift-click selection,
-marquee, drag with snap guides, eight resize handles, wheel pan + anchored
-zoom, containers with consume/fly-back, a node editor (ports + wires),
-per-gesture undo, gesture-aware autosave, and live presence when you
-`docs.join()` a room.
+Everything above ships working out of the box: click/shift-click selection, the
+vellum marquee, drag with snap guides drawn as lasers, resize grips, wheel zoom
+about the pointer and bare-mat pan, mini mats you fly into and out of, a note you
+write on in place, pick-up into the hand, per-gesture undo, gesture-aware autosave,
+and live presence when you `docs.join()` a room.
 
 ## Entry points
 
 | Import | Contents |
 | --- | --- |
 | `@vibecook/ice` | The headless engine: `createCanvasEngine`, `defineWidget`, `defineTool`, `definePrefab`, the props DSL `p`, the doc kit, presence, and the full ECS vocabulary. |
-| `@vibecook/ice/react` | `<InfiniteCanvas>`, `<EngineProvider>`, hooks (`useCommit`, `useWidgetProps`, `useSelected`, `useUndoStatus`, `usePresencePeers`, …), `attachKeymap`. |
-| `@vibecook/ice/r3f` | GL widget islands + virtual-texture compositor, `<GLViews>`, `useIslandFrame`, the GL pointer router. Peers: `three`, `@react-three/fiber`. |
-| `@vibecook/ice/dom` | DOM planes, adapters, and reflectors — for custom shells without React. |
-| `@vibecook/ice/ground` | The P0 ground stratum as one WebGPU canvas (grid, wires, snap guides) with automatic WebGL2 fallback. Passed to `<InfiniteCanvas ground={…}>`. Peer: `three`. |
-| `@vibecook/ice/devtools` | `attachDevtools(engine)` — live pointers/gestures, planes, sovereignty, and loop tabs. |
-| `@vibecook/ice/kernel` | Pure math: coordinates, spatial index, snap, wire geometry, zoom bands. Zero dependencies beyond `rbush`. |
+| `@vibecook/ice/desk` | The desk: `deskLayer`, the kind contract (`defineObject`, `ObjectKind`, `KindProgram`, `ObjectHost`), the provides-keys (`DESK_OBJECT`, `CONTAINABLE`, `PINNABLE`), the ONE editor a kind leases, the text raster, the theme, the renderer (`Ground`) — no kind of its own. |
+| `@vibecook/ice/desk/engine` | The raw-WebGPU engine: the device (`acquire`, `adopt`), the `Surface` type (the swap chain itself is `surface()` in `/desk`), shader composition (`compose`, `compile`), pipelines and bind groups, render targets (`Target`, `beginPass`, `readback`), `defineStruct`. No pass ships here — the passes are the desk's. |
+| `@vibecook/ice/desk/objects` | The six reference object kinds: note · mini mat · notebook · whiteboard · calendar · photo (`DESK_OBJECTS`) — each its world half, its pass, its WGSL and its DOM half (the note's body, the calendar's input), the kinds' registry (`DESK_KINDS`), the preset (`DESK_ENGINE`) and the default palette; built on `/desk`, `/desk/kit` and `/desk/engine` alone, exactly as a plugin kind is. |
+| `@vibecook/ice/desk/kit` | The render kit a kind is written against: the slot's view and its mat (`MatPass`), the lamp and its light, the shared WGSL by name (`kitWgsl`), a container's inside, the service keys a kind lends and uses (`serviceKey`, `TEXT_RASTER`, `PRINT_RASTER`, `BLOB_STORE`, `PICTURE_DECODER`), a container's face law and chip finishes, the one physics every object shares. |
+| `@vibecook/ice/react` | `<Desk>`, `<EngineProvider>`, hooks (`useCommit`, `useWidgetProps`, `useSelected`, `useUndoStatus`, `usePresencePeers`, …), `attachKeymap`, `<SelectionMenu>`, `<TrayBar>` (the pegboard drawer's handle and its category chips — design-018). |
+| `@vibecook/ice/dom` | Screen space only: the canvas host, the pointer adapter, the rAF loop, input ownership, the cursors, `createDeskHost` — for custom shells without React. |
+| `@vibecook/ice/devtools` | `attachDevtools(engine)` — strata's observer + profiler in one draggable dock, and the desk's GPU slot (fed by `/desk`'s `handle.profiler()`). |
+| `@vibecook/ice/kernel` | Pure math: coordinates, spatial index, snap, wire geometry, the flight maths. Zero dependencies beyond `rbush`. |
+
+## A plugin kind
+
+Whatever a built-in kind does, a plugin kind declares the same way, against `@vibecook/ice/desk` and `/desk/kit` alone — no list
+in the engine names a kind (the six reference kinds in `/desk/objects` are built exactly so):
+
+```ts
+import { CONTAINABLE, DESK_OBJECT, defineObject } from "@vibecook/ice/desk";
+import { PAPER_FINISH, service, serviceKey, TEXT_RASTER } from "@vibecook/ice/desk/kit";
+
+const CHIME = serviceKey<Chime>("clock.chime");   // a service of its own: typed by its key, matched by its name
+
+export const Clock = defineObject({
+  type: "acme.clock", version: 1, props: { /* p.* */ },
+  kind: clockKind,                          // its world half (resolve · record · hit · chip → { finish: PAPER_FINISH, … }) and its pass
+  provides: [DESK_OBJECT, CONTAINABLE],     // it lies on the desk, and a mini mat holds it
+  menu: [{ id: "wind", label: "Wind it", glyph: { path: "M12 5v7l4 2" }, run: (api) => { /* api.setProps(e, …) */ } }],
+  host: {
+    lend: (h) => [service(CHIME, makeChime(h.use(TEXT_RASTER)))],   // what only a browser makes; any kind `use`s it
+    text: (h) => [{ part: "clock.label", tap: (t) => labelLease(h, t) }],   // a part that leases the desk's ONE editor
+  },
+});
+```
 
-React, `react-dom`, `three`, and `@react-three/fiber` are **optional** peer
-dependencies — install only what your surfaces use. The core entry is fully
-headless.
+- **Services** — `serviceKey`/`service`: `KindHost.use(KEY)` in the world half, `ObjectDomHost.use(KEY)` in the DOM half;
+  `deskLayer({ services })` lends more from the host. A name lent twice is a mount error; a service whose work lands later calls
+  its lend host's `wake()` (the desk's loop sleeps at rest — nothing is polled).
+- **Text** — the ONE focused editor is the desk's; a `TextPart` with `tap` is routed every tap and answers an `EditorLease`; one
+  without is leased by the kind's own half (`h.editor.lend(lease)`).
+- **Placement** — by what an object `provides`: `DESK_OBJECT` (the desk canvas), `CONTAINABLE` (a mini mat), `PINNABLE` (a
+  calendar's day); a driver asks `h.provides(KEY)`.
+- **Being a container** — `ObjectKind.face` and `faceLaw: { radius, chips, finishes }`; a child's `chip()` names its finish.
+- **Held tools and menu acts** — a tool's `glyph` is a name of the bar's set or its own `{ path }`; `menu` acts show for a
+  selection of the kind and run through `ops.runMenuAction`.
+- **Stills** — `handle.pinAsset(entity, asset)` pins the kind's own `ctx.asset`.
+
+React and `react-dom` are **optional** peer dependencies — the core, desk and dom
+entries are React-free; `three` is imported nowhere.
 
 ## Limits
 
 Measured, not estimated. The bench source in `packages/core/bench/` is the source
 of truth; [`docs/benchmarks.md`](https://github.com/vibefield/infinite-canvas-engine/blob/main/docs/benchmarks.md)
-records the full output (Apple M1 Max, 2026-07-15).
+records the full output (Apple M1 Max, 2026-07-15; the sections measured on the deleted
+hybrid are marked historical).
 
 **Collaboration is the tightest ceiling — plan shared boards around ~3,000
 objects.** A local-only document scales to ~100k, but a collaboratively-edited one
@@ -100,11 +134,6 @@ TODO: a general layout engine (beyond `ops.arrange`), rich text, comments/thread
 and permissions. strata has no authority model, so multi-user trust is the
 application's to own.
 
-**Not yet built**: an engine-level focus model for widget keyboard exclusivity and
-wheel/scroll opt-out. Native form controls already work — the keymap ignores
-keystrokes targeting an `input`, `textarea`, `select`, or `contenteditable` — but a
-widget wanting arrow keys or its own scrolling has no engine contract yet.
-
 **The substrate is pre-1.0**: `@vibecook/strata-ecs` minor versions may break APIs.
 
 [Changelog](https://github.com/vibefield/infinite-canvas-engine/blob/main/CHANGELOG.md)