@vibecook/ice 0.1.0

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

@@ -0,0 +1,14 @@
+/**
+ * @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.
+ */
+export declare const REACT_VERSION = "0.0.0";
+export { WidgetHiddenContext, useBreakpoint, useSelected, useWidgetProps, useWorldComponent, } from "./hooks";
+export { WidgetRoot, type WidgetComponentProps, type WidgetHosts, type WidgetRootProps } from "./widget-root";
+export { EngineProvider, useCanvasEngine, useOps, useWorld, type EngineProviderProps, } from "./engine-context";
+export { useCommit, useUndoStatus, type Commit, type UndoStatus } from "./use-commit";
+export { useTool, useToolState } from "./use-tool";
+export { usePresencePeers, type PresencePeerView } from "./use-presence";
+export { attachKeymap, type KeymapEntry } from "./keymap";
+export { InfiniteCanvas, type InfiniteCanvasHandle, type InfiniteCanvasProps, } from "./infinite-canvas";

package/dist/types/packages/react/src/infinite-canvas.d.ts

@@ -0,0 +1,71 @@
+/**
+ * `<InfiniteCanvas>` — the one-line canvas mount (design-005 §5): planes +
+ * adapters + reflectors + portal root, wired in node-board's PROVEN boot order
+ * (apps/nodeboard/src/app.tsx). The app supplies a constructed {@link
+ * CanvasEngine} (via `createCanvasEngine`); this component owns only the DOM
+ * host, the reflector registrations, the pointer/keymap adapters, the rAF loop,
+ * and the viewport sync — everything that must live next to a real container.
+ *
+ * Boot order (registration order = reflector flush order, mirrored exactly):
+ *   host → planes → reflectors[ planeTransform · grid(P0) · wires(P0) ·
+ *   domWidgets(P1/P3) · chrome(P4) · cursor · remoteCursors(P5) ] →
+ *   pointer adapter → measurement (optional) → keymap → rAF loop → viewport RO.
+ *
+ * The dom-widgets reflector is BOTH a reflector and the host lookup WidgetRoot
+ * portals into; it is created before mount and stored in state so WidgetRoot
+ * renders once the hosts exist.
+ *
+ * Lifecycle: this component does NOT own the engine — it never calls
+ * `engine.dispose()` (the engine outlives the mount; the app owns it). Unmount
+ * detaches every adapter, unregisters every reflector, stops the loop, and
+ * disposes the host.
+ *
+ * Not handled here (by design):
+ *  - GL / R3F: the `@ice/r3f` wall forbids `@ice/react` importing three, so a
+ *    GL layer (GLViews) mounts APP-SIDE. Use {@link onReady} to receive the host
+ *    + planes and mount it yourself (like apps/glboard).
+ *  - Devtools: the import wall forbids `@ice/react` importing `@ice/devtools`.
+ *    Wire the panel app-side against `engine.engine` (also via {@link onReady}).
+ *  - Measurement: auto-sized widgets need a `MeasureQueue` passed to BOTH
+ *    `createCanvasEngine({ measureQueue })` (ingest side) and this component's
+ *    `measureQueue` prop (ResizeObserver side). Absent ⇒ measurement is skipped.
+ */
+import { type CanvasEngine, type MeasureQueue } from "@ice/core";
+import { type CanvasHost, type GLRoute, type GridConfig, type Planes } from "@ice/dom";
+import { type CSSProperties, type ReactElement, type ReactNode } from "react";
+/** Handed to {@link InfiniteCanvasProps.onReady} for app-side GL/devtools wiring. */
+export interface InfiniteCanvasHandle {
+    readonly engine: CanvasEngine;
+    readonly host: CanvasHost;
+    readonly planes: Planes;
+}
+export interface InfiniteCanvasProps {
+    /** A constructed engine (`createCanvasEngine(...)`); NOT disposed on unmount. */
+    readonly engine: CanvasEngine;
+    /**
+     * The ResizeObserver side of widget measurement. Pass the SAME queue given to
+     * `createCanvasEngine({ measureQueue })`. Absent ⇒ measurement skipped.
+     */
+    readonly measureQueue?: MeasureQueue;
+    /** Called once after the host/reflectors/loop are live (app-side GL/devtools). */
+    readonly onReady?: (handle: InfiniteCanvasHandle) => void;
+    /**
+     * Dot-grid tuning (theme dot color, spacing, fades). Applied live via the
+     * grid reflector's `configure` — changing it never re-boots the canvas
+     * (memoize in the caller to avoid redundant same-value redraws).
+     */
+    readonly grid?: Partial<GridConfig>;
+    /**
+     * GL pointer routing (event-time island pick — @ice/r3f's
+     * createGLPointerRouter). Provide from the FIRST render (a stub delegating
+     * to a ref is fine — the real router usually arrives in onReady); the prop
+     * is read through a ref, so later identity changes take effect without
+     * re-attaching the adapter.
+     */
+    readonly glRoute?: GLRoute;
+    readonly className?: string;
+    readonly style?: CSSProperties;
+    /** Overlays inside the viewport (toolbars, HUD) — rendered under the EngineProvider. */
+    readonly children?: ReactNode;
+}
+export declare function InfiniteCanvas({ engine, measureQueue, onReady, grid: gridConfig, glRoute, className, style, children, }: InfiniteCanvasProps): ReactElement;

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

@@ -0,0 +1,42 @@
+/**
+ * The default keymap (design-005 §4 "Keymap"; design-003 §2 — NO system-side
+ * keyboard logic, every entry resolves to an `ops.*`/`docs.*` call).
+ *
+ * Locked defaults:
+ *   ⌫/Delete        → ops.deleteSelection
+ *   ⌘Z / Ctrl-Z     → docs.undo
+ *   ⇧⌘Z / ⇧Ctrl-Z   → docs.redo
+ *   ⌘D              → ops.duplicateSelection
+ *   ⌘A              → ops.selectAll
+ *   Esc             → ops.cancelActiveGestures
+ *   Arrows          → nudge the selection ±1px (⇧ = ±10px) — ONE tx per press
+ *   tool shortcuts  → ops.setTool (v/h/c + any registered tool's shortcut)
+ *
+ * Space-hold pan is ALREADY owned by the pointer adapter (design-003 §2) — it is
+ * NOT rebound here. A keystroke is IGNORED when the event target is editable
+ * (input/textarea/select/contenteditable) so typing into widget fields never
+ * triggers a shortcut. `mod` = ⌘ on macOS, Ctrl elsewhere (metaKey || ctrlKey).
+ *
+ * Overrides replace a default by its key-signature `key|mod|shift`; a signature
+ * with no default is added. A matched entry `preventDefault()`s (the target was
+ * already filtered to non-editable, so no typing is swallowed).
+ */
+import { type CanvasEngine } from "@ice/core";
+export interface KeymapEntry {
+    /** `event.key` to match (case-insensitive; e.g. "z", "Backspace", "ArrowUp"). */
+    readonly key: string;
+    /** Require ⌘/Ctrl (default false → must NOT be held). */
+    readonly mod?: boolean;
+    /** Require ⇧ (default false → must NOT be held). */
+    readonly shift?: boolean;
+    /** Resolve to an engine write path — no keyboard logic beyond dispatch. */
+    run(engine: CanvasEngine): void;
+}
+type KeyTarget = Pick<Window, "addEventListener" | "removeEventListener">;
+/**
+ * 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
+ * target — e.g. a headless environment with no `window`.
+ */
+export declare function attachKeymap(engine: CanvasEngine, target?: KeyTarget, overrides?: readonly KeymapEntry[]): () => void;
+export {};

package/dist/types/packages/react/src/use-commit.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `useCommit` + `useUndoStatus` — the sanctioned widget durable-write path and
+ * the undo/redo status subscription (design-005 §2 M6 field amendment,
+ * 2026-07-10: "widgets also need a SANCTIONED commit path").
+ *
+ * A widget commits a prop edit through {@link useCommit}: it resolves the
+ * CURRENT doc session (`engine.docs.current()`) and runs a
+ * {@link guardedTransaction} against that session's store — one transaction per
+ * call, eligibility-guarded, absolute writes only. The session is resolved at
+ * CALL time (not hook time) so a widget rendered doc-less that gains a doc later
+ * commits correctly without re-mounting.
+ */
+import { type GuardedTx, type GuardedTxOpts } from "@ice/core";
+/** A durable commit: run `fn` against the current doc session's store, one tx. */
+export type Commit = (fn: (tx: GuardedTx) => void, opts?: GuardedTxOpts) => void;
+/**
+ * The widget commit seam. The returned function throws with guidance when no
+ * document is attached (commits need a durable store — call
+ * `engine.docs.create()/open()/join()` first).
+ */
+export declare function useCommit(): Commit;
+export interface UndoStatus {
+    readonly canUndo: boolean;
+    readonly canRedo: boolean;
+}
+/**
+ * Undo/redo availability for the current document (drives toolbar
+ * disablement) — the design-005 §5 path: the `DurableUndoStatus` RESOURCE
+ * (strata plan-undo U2, re-exported through @ice/core) via
+ * `observeResource`. A resource subscription is WORLD-level, so it survives
+ * document swaps — no remount needed, the earlier onHistoryChange-per-store
+ * caveat is gone. Fires at notify(), equality-suppressed; snapshot identity
+ * is stable while the flags are unchanged.
+ */
+export declare function useUndoStatus(): UndoStatus;

package/dist/types/packages/react/src/use-presence.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `usePresencePeers` — the remote-collaborator roster (design-005 §5:
+ * "Not(Local) presence query").
+ *
+ * Queries `PresencePeer` entities that are NOT `Local` (the local peer carries
+ * `Local`, auto-applied by the ephemeral store and never transmitted) and pairs
+ * each with its `PresenceInfo` (name/color). Wakes on Tier-1 query membership
+ * churn (`observeQuery`) — peers joining/leaving. The snapshot is
+ * MEMBERSHIP-KEYED: identity stays stable across unrelated re-renders, and info
+ * is sampled when membership changes (steady-state presence info is set once at
+ * join; a mid-session rename reflects on the next membership change).
+ */
+import { type Entity } from "@ice/core";
+export interface PresencePeerView {
+    readonly entity: Entity;
+    /** The peer's `PresenceInfo` (strata "string" fields are nullable until set). */
+    readonly info: {
+        readonly name: string | null;
+        readonly color: string | null;
+    } | undefined;
+}
+/** Remote presence peers (excludes the local peer); stable identity by membership. */
+export declare function usePresencePeers(): readonly PresencePeerView[];

package/dist/types/packages/react/src/use-tool.d.ts

@@ -0,0 +1,4 @@
+/** `[activeToolId, setTool]`. `setTool` routes through `ops.setTool`. */
+export declare function useTool(): [string, (id: string) => void];
+/** Sugar: is tool `id` the active one? (toolbar button pressed-state). */
+export declare function useToolState(id: string): boolean;

package/dist/types/packages/react/src/widget-root.d.ts

@@ -0,0 +1,33 @@
+/**
+ * WidgetRoot — portals from ONE app root (design-004 §2).
+ *
+ * Portal-list membership (mount/unmount/evict) is owned HERE, by React,
+ * subscribed to the engine's mount store via `useSyncExternalStore`; the
+ * imperative dom-widgets reflector owns only the host DIVs. Eviction is
+ * decided engine-side (LRU derive) and merely consumed. Each mounted entry
+ * portals its widget type's component (from the defineWidget registry) into
+ * the host's content element; hidden entries stay mounted (React state
+ * preserved — cull ≠ unmount) inside a `WidgetHiddenContext` so their prop
+ * subscriptions freeze (design-004 §2).
+ *
+ * A host div may not exist yet on the very first snapshot after mount (the
+ * host reflector runs in the same post-notify pass, ordered by reflector
+ * registration) — entries without a host render nothing this pass and pick
+ * up on the next notification.
+ */
+import { type Entity, type World, type WidgetMountStore } from "@ice/core";
+import { type ReactElement } from "react";
+export interface WidgetHosts {
+    /** The dom-widgets reflector's lookup (content element per entity). */
+    hostFor(entity: Entity): HTMLElement | undefined;
+}
+export interface WidgetRootProps {
+    readonly world: World;
+    readonly store: WidgetMountStore;
+    readonly hosts: WidgetHosts;
+}
+export interface WidgetComponentProps {
+    readonly entity: Entity;
+    readonly world: World;
+}
+export declare function WidgetRoot({ world, store, hosts }: WidgetRootProps): ReactElement;

package/package.json

@@ -0,0 +1,112 @@
+{
+  "name": "@vibecook/ice",
+  "version": "0.1.0",
+  "description": "ICE — infinite canvas engine. Figma-grade infinite-canvas UX as a framework: defineWidget turns React/R3F components into canvas citizens — selectable, movable, resizable, wired into node graphs, CRDT-synced, undoable per gesture.",
+  "license": "MIT",
+  "author": "James Yong <me@jamesyong42.com>",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jamesyong-42/infinite-canvas-engine.git"
+  },
+  "homepage": "https://jamesyong-42.github.io/infinite-canvas-engine/",
+  "bugs": "https://github.com/jamesyong-42/infinite-canvas-engine/issues",
+  "keywords": [
+    "infinite-canvas",
+    "canvas",
+    "whiteboard",
+    "node-editor",
+    "ecs",
+    "crdt",
+    "local-first",
+    "collaboration",
+    "loro",
+    "react",
+    "r3f",
+    "three",
+    "gestures"
+  ],
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/types/packages/ice/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/packages/ice/src/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./kernel": {
+      "types": "./dist/types/packages/ice/src/kernel.d.ts",
+      "default": "./dist/kernel.js"
+    },
+    "./dom": {
+      "types": "./dist/types/packages/ice/src/dom.d.ts",
+      "default": "./dist/dom.js"
+    },
+    "./react": {
+      "types": "./dist/types/packages/ice/src/react.d.ts",
+      "default": "./dist/react.js"
+    },
+    "./r3f": {
+      "types": "./dist/types/packages/ice/src/r3f.d.ts",
+      "default": "./dist/r3f.js"
+    },
+    "./devtools": {
+      "types": "./dist/types/packages/ice/src/devtools.d.ts",
+      "default": "./dist/devtools.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@vibecook/strata-ecs": "0.5.0",
+    "loro-crdt": "^1.13.6",
+    "rbush": "^3.0.1"
+  },
+  "peerDependencies": {
+    "@react-three/fiber": ">=9",
+    "react": ">=18",
+    "react-dom": ">=18",
+    "three": ">=0.160.0"
+  },
+  "peerDependenciesMeta": {
+    "@react-three/fiber": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    },
+    "three": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@react-three/fiber": "^9",
+    "@types/rbush": "^3.0.3",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "@types/three": "^0.185.0",
+    "react": "^19",
+    "react-dom": "^19",
+    "three": "^0.185.0",
+    "@ice/core": "0.0.0",
+    "@ice/dom": "0.0.0",
+    "@ice/kernel": "0.0.0",
+    "@ice/r3f": "0.0.0",
+    "@ice/devtools": "0.0.0",
+    "@ice/react": "0.0.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsup && tsc -p tsconfig.dts.json"
+  }
+}