@vibecook/ice 0.1.0 → 0.2.0

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,14 @@ 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;
 /**
  * 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, 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.2.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>",
@@ -52,6 +52,10 @@
       "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"
@@ -65,14 +69,15 @@
     "access": "public"
   },
   "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": {
@@ -99,11 +104,11 @@
     "react-dom": "^19",
     "three": "^0.185.0",
     "@ice/core": "0.0.0",
+    "@ice/devtools": "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"
+    "@ice/react": "0.0.0",
+    "@ice/kernel": "0.0.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",