@vibecook/ice 0.1.0 → 0.3.0

package/dist/types/packages/r3f/src/island-state.d.ts

@@ -39,14 +39,58 @@ export interface IslandRenderState {
      * every pass (5 Hot vs cap 4 froze the shapes card, 2026-07-12).
      */
     lastPaintSeq: number;
+    /**
+     * Animation time OWED to this island's `useIslandFrame` callbacks: every
+     * pass a Hot island is paint-eligible adds the pass dtMs; the paint that
+     * finally runs delivers the whole balance and zeroes it. Without this, a
+     * stagger-deferred island simply LOST the deferred passes' time — 5 Hot vs
+     * cap 4 ran every animation at 4/5 speed (2026-07-20 rate probe), violating
+     * design-004's "the cap changes cadence, never speed". Freeze semantics are
+     * preserved: frozen islands are not paint-eligible, so a stage hold still
+     * PAUSES animation rather than banking it.
+     */
+    pendingDtMs: number;
     /**
      * Composite-quad scale (lift-on-hold): scales the CARD on the canvas —
      * texture, rounded alpha corners and all — instead of the scene content
      * (which the card-sized frustum would crop into hard corners, 2026-07-12
      * field report). ≠1 also pops render order over neighbors.
+     *
+     * This is the DRAWN value: the compositor pass eases it toward
+     * `liftTarget` (dtMs-driven spring). GL widgets have no CSS transitions, so
+     * the DOM-lift parity (2026-07-13 field report: "GL lift snaps") lives in
+     * the pass, not in userland.
      */
     compositeScale: number;
+    /** Where the lift is headed; `setCompositeScale` retargets from the drawn value. */
+    liftTarget: number;
+    /** Drawn value at (re)target time — the ease runs liftFrom → liftTarget. */
+    liftFrom: number;
+    /** Accumulated pass dtMs since the last retarget; ≥ liftMs ⇒ settled. */
+    liftElapsedMs: number;
+    /** Transition duration in ms; 0 = snap (the pre-ease behavior). */
+    liftMs: number;
+    /**
+     * Composite-quad opacity channel (the lift's fade twin): the DRAWN value the
+     * pass eases toward `opacityTarget` and MULTIPLIES with the widget's durable
+     * `Opacity` cell — presentation-transient (chrome-grade, e.g. the drag-lift
+     * fade) stacked over the doc-level fact, never written to ECS.
+     */
+    compositeOpacity: number;
+    /** Where the fade is headed; `setCompositeOpacity` retargets from the drawn value. */
+    opacityTarget: number;
+    /** Drawn value at (re)target time — the ease runs opacityFrom → opacityTarget. */
+    opacityFrom: number;
+    /** Accumulated pass dtMs since the last retarget; ≥ opacityMs ⇒ settled. */
+    opacityElapsedMs: number;
+    /** Transition duration in ms; 0 = snap. */
+    opacityMs: number;
 }
+/**
+ * Default lift transition — the GL twin of the DOM card-lift idiom (180ms
+ * springy pop; the curve itself lives in the compositor pass).
+ */
+export declare const LIFT_DEFAULT_MS = 180;
 export interface IslandStateStore {
     /** Get-or-create (Cold, unpainted). */
     ensure(key: number): IslandRenderState;

package/dist/types/packages/r3f/src/preview-capture.d.ts

@@ -0,0 +1,19 @@
+import type { Texture, WebGLRenderer } from "three";
+export interface CapturePreviewOpts {
+    /** Types to capture (default: every registered gl-surface widget). */
+    readonly types?: readonly string[];
+    /**
+     * Shared IBL. Prefer the FACTORY form: PMREM textures live on the GPU of
+     * the renderer that generated them (no CPU image), so the app's main-canvas
+     * env is EMPTY on the capture renderer (field bug 2026-07-19 — black
+     * metals). The factory receives the capture renderer and builds the env
+     * there (e.g. `(gl) => new PMREMGenerator(gl).fromScene(new RoomEnvironment(), 0.04).texture`).
+     * A plain Texture is accepted for same-renderer/CPU-backed cases.
+     */
+    readonly environment?: Texture | ((gl: WebGLRenderer) => Texture | null) | null;
+    /** Pixel density of the capture (default: fit 512px on the long side, ≤2). */
+    readonly scale?: number;
+    /** Frames advanced before the capture (animations reach a live pose). */
+    readonly settleFrames?: number;
+}
+export declare function captureWidgetPreviews(opts?: CapturePreviewOpts): Promise<string[]>;

package/dist/types/packages/r3f/src/self-sustain.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Self-sustain scheduling for the demand loop (design-004 §3 animation-rate
+ * amendment, 2026-07-14).
+ *
+ * When the ONLY reason to run another frame is ambient animation (Hot islands
+ * or a stagger backlog), the loop no longer re-invalidates at native refresh:
+ * on a 120 Hz panel that was 5 always-Hot islands × 120 paints/sec ≈ 96 % GPU
+ * duty at idle — the fan. Instead the next pass is scheduled `1000/maxFps` ms
+ * after the last pass STARTED, so ambient animation runs at ~`maxFps` and the
+ * GPU idles between frames.
+ *
+ * What stays at native refresh:
+ *  - lift eases (`liftAnimating`) — 180 ms of interaction feedback;
+ *  - every EXTERNALLY invalidated frame (camera, drag, props dirt): the
+ *    bridge's `requestFrame` path is untouched, so interaction still runs at
+ *    display rate and Hot islands ride along uncapped while it lasts.
+ *
+ * The cap is approximate: the wake-up is a timeout and the actual frame lands
+ * on the next vsync after it. {@link RATE_CAP_SLACK_MS} pulls the timeout half
+ * a 120 Hz vsync early so the following vsync is the intended one, not one
+ * past it (naive `interval` scheduling on a 120 Hz grid yields 40 fps, not 60).
+ */
+/** Timeout lead so the post-timeout vsync lands on the target boundary. */
+export declare const RATE_CAP_SLACK_MS = 4;
+export interface SelfSustainStats {
+    readonly anyHot: boolean;
+    readonly pendingPaints: number;
+    readonly liftAnimating: boolean;
+}
+/**
+ * Decide how the demand loop continues after a pass.
+ *
+ * @param stats        The pass's self-sustain signals.
+ * @param elapsedMs    ms since the pass started (schedule anchor).
+ * @param maxFps       Animation rate cap; `Infinity` restores uncapped.
+ * @returns `"none"` (park), `"now"` (invalidate immediately), or the timeout
+ *          delay in ms before invalidating.
+ */
+export declare function selfSustainPlan(stats: SelfSustainStats, elapsedMs: number, maxFps: number): "none" | "now" | number;

package/dist/types/packages/r3f/src/use-island-frame.d.ts

@@ -20,5 +20,20 @@ export declare function useIslandInvalidate(): () => void;
  * corners together) and pops it over neighbors while ≠1. Scaling scene content
  * instead crops the corners at the card-sized frustum — the 2026-07-12
  * hard-corner field report. Resets to 1 on unmount.
+ *
+ * The scale EASES to each new value (default 180ms, the DOM card-lift
+ * spring — GL has no CSS transitions, so the compositor runs the curve;
+ * 2026-07-13 field report: "GL lift snaps while DOM lifts smooth").
+ * `durationMs: 0` snaps.
  */
-export declare function useIslandLift(scale: number): void;
+export declare function useIslandLift(scale: number, durationMs?: number): void;
+/**
+ * Composite-quad fade — the lift's opacity twin (e.g. the drag-lift 75 %
+ * fade): eases the quad's drawn opacity to `opacity` (default 180ms; 0
+ * snaps) and MULTIPLIES the widget's durable `Opacity` cell, so a transient
+ * fade stacks over a doc-level opacity instead of fighting it. The DOM
+ * chrome runs its own CSS `opacity … ease` transition — same duration/curve
+ * family, so card body and GL content fade in lockstep. Resets to 1 on
+ * unmount.
+ */
+export declare function useIslandOpacity(opacity: number, durationMs?: number): void;

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

@@ -22,6 +22,27 @@ export declare function EngineProvider({ engine, children }: EngineProviderProps
 export declare function useCanvasEngine(): CanvasEngine;
 /** The engine-owned write paths (design-005 §4): setTool, deleteSelection, etc. */
 export declare function useOps(): CanvasOps;
+/**
+ * Take a stage background hold while `active` (ce.stage, 2026-07-19): the
+ * 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.
+ */
+export declare function useStageHold(engine: CanvasEngine, active: boolean, name: string): void;
+/**
+ * Freeze the engine while `active` (ce.frame, 2026-08-04) — {@link useStageHold}'s
+ * stricter sibling, same lifecycle sugar: the effect cleanup IS the thaw, so an
+ * overlay that unmounts (or crashes) can never wedge the engine parked.
+ *
+ * WHICH ONE. A stage hold quiets discretionary rendering over a world that
+ * keeps stepping — right for chrome that RECEDES the canvas, where undo,
+ * collab and tweens must still land visibly behind a partial overlay. A freeze
+ * stops the loop outright — right for chrome that COVERS the canvas, where
+ * every frame behind it is work nobody can see. Reaching for a freeze under a
+ * partial overlay will look broken: the canvas is a photograph until thaw.
+ */
+export declare function useFrameFreeze(engine: CanvasEngine, active: boolean, name: string): void;
 /**
  * Escape hatch — the raw {@link World} for READS and Tier-3 OBSERVATION only.
  * Mutation goes through {@link useOps}/{@link useCommit} (a gesture-claimed,

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

@@ -6,9 +6,11 @@
 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 { 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 { usePresencePeers, type PresencePeerView } from "./use-presence";
 export { attachKeymap, type KeymapEntry } from "./keymap";
-export { InfiniteCanvas, type InfiniteCanvasHandle, type InfiniteCanvasProps, } from "./infinite-canvas";
+export { InfiniteCanvas, type GroundLayerFactory, type GroundLayerHandle, type InfiniteCanvasHandle, type InfiniteCanvasProps, } from "./infinite-canvas";

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

@@ -7,7 +7,7 @@
  * 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) ·
+ *   host → planes → reflectors[ planeTransform · ground(P0, app-injected) ·
  *   domWidgets(P1/P3) · chrome(P4) · cursor · remoteCursors(P5) ] →
  *   pointer adapter → measurement (optional) → keymap → rAF loop → viewport RO.
  *
@@ -24,14 +24,19 @@
  *  - 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).
+ *  - The GROUND layer (P0: dot grid, wires, snap guides — @ice/ground, three's
+ *    WebGPURenderer) rides the same wall: pass its factory through the OPAQUE
+ *    {@link InfiniteCanvasProps.ground} prop (`ground={ground({...})}`); this
+ *    component types it structurally and never imports the package. No factory
+ *    ⇒ no ground layer (headless/test boots).
  *  - 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 CanvasEngine, type GridConfig, type MeasureQueue, type ReflectorDef, type WirePreviewBuffer, type World } from "@ice/core";
+import { type CanvasHost, type GLRoute, 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 {
@@ -39,6 +44,27 @@ export interface InfiniteCanvasHandle {
     readonly host: CanvasHost;
     readonly planes: Planes;
 }
+/**
+ * STRUCTURAL mirror of `@ice/ground`'s GroundLayer/GroundFactory (the
+ * `WidgetDef.component`-style opaque seam: react never imports the package —
+ * the wall forbids three here). `@ice/ground.ground(...)` returns a function
+ * assignable to this type.
+ */
+export interface GroundLayerHandle {
+    readonly reflector: ReflectorDef & {
+        available(): boolean;
+    };
+    configureGrid(cfg: Partial<GridConfig>): void;
+    dispose(): void;
+}
+export type GroundLayerFactory = (ctx: {
+    readonly host: {
+        readonly container: HTMLElement;
+        readonly contentPlane: HTMLElement;
+    };
+    readonly world: World;
+    readonly readWirePreview: () => WirePreviewBuffer;
+}) => GroundLayerHandle;
 export interface InfiniteCanvasProps {
     /** A constructed engine (`createCanvasEngine(...)`); NOT disposed on unmount. */
     readonly engine: CanvasEngine;
@@ -49,10 +75,18 @@ export interface InfiniteCanvasProps {
     readonly measureQueue?: MeasureQueue;
     /** Called once after the host/reflectors/loop are live (app-side GL/devtools). */
     readonly onReady?: (handle: InfiniteCanvasHandle) => void;
+    /**
+     * The P0 ground layer (dot grid, wires, snap guides — one WebGPU canvas).
+     * Pass `ground(opts)` from `@ice/ground`; received opaquely (see
+     * {@link GroundLayerFactory}). Memoize in the caller — a new identity
+     * re-boots the canvas mount effect. Absent ⇒ no ground layer renders.
+     */
+    readonly ground?: GroundLayerFactory;
     /**
      * 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).
+     * ground layer's `configureGrid` — changing it never re-boots the canvas
+     * (memoize in the caller to avoid redundant same-value redraws). No-op
+     * when {@link ground} is absent.
      */
     readonly grid?: Partial<GridConfig>;
     /**
@@ -68,4 +102,4 @@ export interface InfiniteCanvasProps {
     /** 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;
+export declare function InfiniteCanvas({ engine, measureQueue, onReady, ground, grid: gridConfig, glRoute, className, style, children, }: InfiniteCanvasProps): ReactElement;

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

@@ -0,0 +1,17 @@
+/**
+ * The GL preview snapshot store (design-005 §2 preview contract, P2 —
+ * 2026-07-19). react stays three-free by LAW, so the capture pipeline lives
+ * in @ice/r3f and meets `<WidgetPreview>` HERE, at a dumb data seam: a
+ * module-level map of widget type → captured image, with subscription so an
+ * open palette re-renders the moment a capture lands.
+ *
+ * `PreviewImage` accepts a canvas alongside ImageBitmap so tests (and any
+ * app-side prebuilt-cache policy — the P3 seam) can inject without a GPU.
+ */
+export type PreviewImage = ImageBitmap | HTMLCanvasElement;
+export declare function setPreviewSnapshot(type: string, image: PreviewImage): void;
+export declare function getPreviewSnapshot(type: string): PreviewImage | undefined;
+export declare function hasPreviewSnapshot(type: string): boolean;
+export declare function subscribePreviewSnapshots(listener: () => void): () => void;
+/** TEST-ONLY wipe (not on the barrel). */
+export declare function __resetPreviewSnapshotsForTests(): void;

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

@@ -0,0 +1,14 @@
+import { type CSSProperties, type ReactElement, type ReactNode } from "react";
+/** TEST-ONLY sandbox wipe (mirrors __resetWidgetsForTests; not on the barrel). */
+export declare function __resetPreviewSandboxForTests(): void;
+export interface WidgetPreviewProps {
+    readonly type: string;
+    /** The available box; the preview renders aspect-FITTED inside it. */
+    readonly width: number;
+    readonly height: number;
+    /** App silhouette shown when no preview path applies (or one throws). */
+    readonly fallback?: ReactNode;
+    readonly className?: string;
+    readonly style?: CSSProperties;
+}
+export declare function WidgetPreview({ type, width, height, fallback, className, style }: WidgetPreviewProps): ReactElement;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibecook/ice",
-  "version": "0.1.0",
+  "version": "0.3.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>",
@@ -26,70 +26,51 @@
     "three",
     "gestures"
   ],
-  "files": [
-    "dist"
-  ],
+  "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"
-    },
+    ".": { "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" },
+    "./ground": { "types": "./dist/types/packages/ice/src/ground.d.ts", "default": "./dist/ground.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"
+  "engines": { "node": ">=20" },
+  "publishConfig": { "access": "public" },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsup && tsc -p tsconfig.dts.json",
+    "prepack": "pnpm run build"
   },
   "dependencies": {
-    "@vibecook/strata-ecs": "0.5.0",
-    "loro-crdt": "^1.13.6",
+    "@vibecook/strata-ecs": "0.11.0",
+    "loro-crdt": "^1.13.8",
+    "stats-gl": "^4.2.3",
     "rbush": "^3.0.1"
   },
   "peerDependencies": {
     "@react-three/fiber": ">=9",
-    "react": ">=18",
-    "react-dom": ">=18",
+    "react": ">=19",
+    "react-dom": ">=19",
     "three": ">=0.160.0"
   },
   "peerDependenciesMeta": {
-    "@react-three/fiber": {
-      "optional": true
-    },
-    "react": {
-      "optional": true
-    },
-    "react-dom": {
-      "optional": true
-    },
-    "three": {
-      "optional": true
-    }
+    "@react-three/fiber": { "optional": true },
+    "react": { "optional": true },
+    "react-dom": { "optional": true },
+    "three": { "optional": true }
   },
   "devDependencies": {
+    "@ice/core": "workspace:*",
+    "@ice/devtools": "workspace:*",
+    "@ice/dom": "workspace:*",
+    "@ice/kernel": "workspace:*",
+    "@ice/r3f": "workspace:*",
+    "@ice/react": "workspace:*",
     "@react-three/fiber": "^9",
     "@types/rbush": "^3.0.3",
     "@types/react": "^19",
@@ -97,16 +78,6 @@
     "@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"
+    "three": "^0.185.0"
   }
-}
+}