@jamesyong42/infinite-canvas 1.1.0 → 1.3.0

package/README.md

@@ -17,6 +17,7 @@ Build Figma-style infinite canvases in React -- drag, resize, snap, zoom, nested
 - **Undo / redo** -- Command buffer with grouped operations (an entire drag is one undo step)
 - **Hierarchical navigation** -- Enter and exit nested containers with camera state preservation
 - **ECS architecture** -- Extensible via custom components, tags, and systems with topologically-sorted scheduling
+- **Card widgets** -- iOS-style preset-sized tiles (small / medium / large / xl) with rounded corners, soft shadows, and lift-on-drag animation; DOM or R3F/PBR flavors via `createCardWidget` / `createGeometryCardWidget`
 - **Performance** -- SDF shaders for grid and selection chrome, RBush spatial indexing, viewport culling, per-system profiling
 - **Live ECS editor** -- Drop-in `<EcsDevtools>` panel for spawning, inspecting, and editing components and tags at runtime
 - **Dark mode** -- Full dark mode support across canvas, widgets, and UI chrome
@@ -215,6 +216,97 @@ Spawning is uniform: `engine.spawn(id, options)`. If `id` matches an archetype,
 | `parent` | Parent entity id for nesting. |
 | `rotation` | Initial rotation in radians. |
 
+The `interactive` field on `Archetype` accepts a boolean or an object. Pass `{ selectable, draggable, resizable, selectionFrame }` (any subset) when you want finer control. Cards that move, select, but never resize and render their own chrome: `{ selectable: true, draggable: true, resizable: false, selectionFrame: false }`. Omitted keys default to `false`, except `selectionFrame` which follows `selectable` (an entity you can select gets a frame unless you opt out).
+
+## Card Widgets
+
+**Card widgets** are fixed-size, non-resizable widgets that sit on an iOS-style preset grid. They ship with rounded corners, a soft drop shadow, a hairline ring, and a subtle lift animation while dragging. Use them when you want dashboard-style tiles rather than free-form resizable surfaces.
+
+```tsx
+import { createCardWidget } from '@jamesyong42/infinite-canvas';
+import { z } from 'zod';
+
+const schema = z.object({ label: z.string().default('Hi') });
+
+export const Greeting = createCardWidget<{ label: string }>({
+  type: 'greeting-card',
+  size: 'small',                 // 'small' | 'medium' | 'large' | 'xl'
+  schema,
+  defaultData: { label: 'Hi' },
+  render: ({ data }) => (
+    <div className="flex h-full w-full items-center justify-center bg-white">
+      {data.label}
+    </div>
+  ),
+});
+
+// Register both the widget and the matching archetype.
+const engine = createLayoutEngine({
+  widgets: [Greeting.widget],
+  archetypes: [Greeting.archetype],
+});
+engine.spawn('greeting-card', { at: { x: 50, y: 50 } });
+```
+
+Preset sizes (default, matching iOS widget conventions on a 19 px grid):
+
+| Preset | Width × Height |
+|--------|----------------|
+| `small`  | 155 × 155 |
+| `medium` | 329 × 155 |
+| `large`  | 329 × 345 |
+| `xl`     | 329 × 535 |
+
+Override per-engine via `createLayoutEngine({ cardPresets: { presets: { small: { width: 200, height: 200 } }, gap: 24 } })`. Omitted presets keep their defaults.
+
+Under the hood: the returned widget wraps your `render` in `<CardFrame>` (exported for manual composition), the archetype is non-resizable, and it bundles a `Card` component. A built-in `cardSystem` stamps `Transform2D.width/height` from `Card.preset` each tick — to change a card's size at runtime, update the preset: `engine.set(id, Card, { preset: 'large' })`. Reading the `Dragging` tag from the frame drives the lift affordance; you can read it elsewhere too via `useTag(entityId, Dragging)`.
+
+Cards also opt out of the engine-drawn selection + hover outline (`selectionFrame: false` in their archetype) — the iOS rounded chrome in `<CardFrame>` is the card's visual contract, so the standard blue frame would fight it. If you need a selected/hover affordance inside a card, read `useIsSelected(entityId)` / `useTag(entityId, /* Hovered tag */)` from within `render` and style accordingly.
+
+### 3D Card Widgets
+
+`createGeometryCardWidget` is the R3F counterpart — same preset sizes, non-resizable archetype, and drag-lift behavior, but the widget body is a three.js scene instead of DOM content. The helper pairs cleanly with PBR materials.
+
+```tsx
+import { createGeometryCardWidget } from '@jamesyong42/infinite-canvas';
+import { useFrame } from '@react-three/fiber';
+import { useRef } from 'react';
+import type { Mesh } from 'three';
+import { z } from 'zod';
+
+const schema = z.object({ color: z.string().default('#F5B8D0') });
+
+export const Sphere = createGeometryCardWidget<{ color: string }>({
+  type: 'sphere',
+  size: 'small',
+  schema,
+  defaultData: { color: '#F5B8D0' },
+  background: 'card',                 // or 'transparent' — the geometry floats over the canvas
+  geometry: ({ data, width }) => {
+    const ref = useRef<Mesh>(null);
+    useFrame((_, dt) => { if (ref.current) ref.current.rotation.y += dt * 0.3; });
+    return (
+      <group>
+        <pointLight position={[80, 80, 120]} intensity={160} distance={300} decay={1.4} />
+        <ambientLight intensity={0.3} />
+        <mesh ref={ref}>
+          <sphereGeometry args={[width * 0.32, 48, 48]} />
+          <meshStandardMaterial color={data.color} roughness={0.35} />
+        </mesh>
+      </group>
+    );
+  },
+});
+```
+
+`background` options:
+
+- `'card'` (default) — a rounded iOS-style card mesh sits behind the geometry in the same widget group.
+- `'transparent'` — no back plane; the geometry floats over whatever's behind the widget.
+- `{ color, roughness?, metalness? }` — card back with custom PBR parameters for tinted or glossy variants.
+
+**Lighting caveat.** All R3F widgets share a single `<Canvas>`, so lights and `envMap`s you declare inside one widget's render function affect every other 3D widget. Keep per-widget lights `pointLight`s with `distance` scoped to the widget's size, or add one shared `<Environment>` at the app level (if you control the R3F canvas). The helper itself adds no lights — declare what you need inside your `geometry` component.
+
 ## WebGL Widgets (R3F)
 
 Define an `R3FWidget<T>` with `surface: 'webgl'` to render 3D content via React Three Fiber. R3F widget views receive `{ entityId, width, height }` and render in local coordinates (origin at widget centre):
@@ -260,6 +352,71 @@ engine.spawn('my-3d', { at: { x: 100, y: 100 } });
 
 WebGL widgets get a transparent R3F canvas layered between the grid and DOM layers. The R3F camera is synced with the engine camera every frame.
 
+## Pointer Events
+
+Both DOM and R3F widgets dispatch pointer events naturally — write `onClick`, `onPointerOver`, `onPointerEnter` etc. the way you would in any React or R3F app. The canvas's engine state machine (drag, select, resize, marquee, double-click navigation) runs on the same event after your handlers, so the two layers compose without you wiring anything.
+
+To opt a specific event out of engine semantics — e.g. a button inside a widget that should not start a drag — call `stopPropagation()` from your handler. Native HTML interactives (`<button>`, `<input>`, `<textarea>`, `<select>`, `[contenteditable]`) opt out automatically.
+
+### DOM widget
+
+```tsx
+function MyDomWidget({ entityId }: DomWidgetProps) {
+  return (
+    <div>
+      <span>drag me anywhere — engine handles it</span>
+
+      <button onClick={(e) => { e.stopPropagation(); doThing(); }}>
+        clicking me runs doThing(), no drag
+      </button>
+    </div>
+  );
+}
+```
+
+`e.stopPropagation()` on the React synthetic event halts both widget-internal bubbling and the canvas-level engine call.
+
+### R3F widget
+
+```tsx
+function MyR3FWidget({ entityId, width, height }: R3FWidgetProps) {
+  const [hover, setHover] = useState(false);
+  return (
+    <group>
+      {/* Drag handle: no stopPropagation — engine starts a drag normally. */}
+      <mesh
+        onPointerOver={() => setHover(true)}
+        onPointerOut={() => setHover(false)}>
+        <planeGeometry args={[width, height]} />
+        <meshBasicMaterial color={hover ? 'lightblue' : 'white'} />
+      </mesh>
+
+      {/* Button mesh: stopPropagation halts R3F bubble + nativeEvent halts engine. */}
+      <mesh
+        position={[0, 0, 1]}
+        onClick={(e) => {
+          e.stopPropagation();              // halts R3F bubble within widget
+          e.nativeEvent.stopPropagation();  // halts engine drag/select
+          doThing();
+        }}>
+        <boxGeometry args={[40, 20, 5]} />
+        <meshStandardMaterial color="orange" />
+      </mesh>
+    </group>
+  );
+}
+```
+
+R3F's `event.stopPropagation()` only halts further dispatch within the widget's own scene. To prevent the canvas-level engine routing from firing too — for example, a clickable mesh that should never start a drag — additionally call `event.nativeEvent.stopPropagation()`. The standard DOM idiom: stop the native event, the bus never sees it.
+
+`event.point`, `event.uv`, `event.face`, `event.intersections` are populated by a widget-local raycast against the widget's own scene with widget-local coordinates — `event.point.x = 0` is the widget centre, not the canvas centre.
+
+### Hover and capture
+
+Cross-widget hover transitions (cursor moves from widget A's mesh into widget B's mesh) fire `onPointerLeave` on A's last hit and `onPointerEnter` on B's first hit automatically. Within a widget, R3F handles enter/leave between meshes natively.
+
+When the engine takes a drag (`capture-drag`), `capture-resize`, or `passthrough-track-drag` directive, the bus calls `setPointerCapture` on the canvas container. While captured, R3F's mesh-level events suspend — the engine owns the pointer until release. This matches the native browser pointer-capture model, so existing R3F patterns like `setPointerCapture` on a mesh continue to work for widget-internal drags that don't conflict with engine semantics.
+
 ## Configuration
 
 ### Grid
@@ -525,20 +682,25 @@ z:3  UI chrome
 | `InteractionRole` | Interaction behavior (drag, select, resize, etc.) |
 | `HandleSet` | Child handle entity references |
 | `CursorHint` | Cursor style on hover/active |
+| `Card` | Marks an iOS-style card; carries the preset (`small`/`medium`/`large`/`xl`) |
 
 ### ECS Tags
 
-`Selectable` `Draggable` `Resizable` `Locked` `Selected` `Active` `Visible`
+`Selectable` `Draggable` `Resizable` `SelectionFrame` `Locked` `Selected` `Dragging` `Active` `Visible`
+
+- `Dragging` — transient state tag (parallels `Selected`): added when the drag dead zone is crossed, removed on pointer up or cancel. Read via `useTag(entityId, Dragging)` to drive drag-time affordances.
+- `SelectionFrame` — opts an entity into the engine-drawn selection + hover outline. Granted automatically to Selectable entities via the archetype's `interactive` caps; widgets that render their own chrome (e.g. cards) opt out.
 
 ### Systems (execution order)
 
-1. `transformPropagate` -- Propagate transforms down hierarchy, compute WorldBounds
-2. `handleSync` -- Synchronize resize handle entities with parent widgets
-3. `hitboxWorldBounds` -- Compute world-space hitbox bounds
-4. `navigationFilter` -- Filter entities to active navigation layer
-5. `cull` -- Mark viewport-visible entities
-6. `breakpoint` -- Compute responsive breakpoints
-7. `sort` -- Z-index ordering
+1. `card` -- Stamp Transform2D size from Card preset
+2. `transformPropagate` -- Propagate transforms down hierarchy, compute WorldBounds
+3. `handleSync` -- Synchronize resize handle entities with parent widgets
+4. `hitboxWorldBounds` -- Compute world-space hitbox bounds
+5. `navigationFilter` -- Filter entities to active navigation layer
+6. `cull` -- Mark viewport-visible entities
+7. `breakpoint` -- Compute responsive breakpoints
+8. `sort` -- Z-index ordering
 
 ## Performance Profiling
 

package/dist/advanced.cjs

@@ -1,176 +1,157 @@
-'use strict';
-
-var chunkFUPKRQB2_cjs = require('./chunk-FUPKRQB2.cjs');
-var chunk2KBYGER3_cjs = require('./chunk-2KBYGER3.cjs');
-
-// src/serialization.ts
-function serializeWorld(world, componentTypes, tagTypes, camera, navigationFrames) {
-  const entities = [];
-  const allEntities = world.query();
-  for (const entityId of allEntities) {
-    const components = {};
-    const tags = [];
-    for (const type of componentTypes) {
-      const data = world.getComponent(entityId, type);
-      if (data !== void 0) {
-        components[type.name] = structuredClone(data);
-      }
-    }
-    for (const type of tagTypes) {
-      if (world.hasTag(entityId, type)) {
-        if (type.name !== "Active" && type.name !== "Visible") {
-          tags.push(type.name);
-        }
-      }
-    }
-    if (Object.keys(components).length > 0 || tags.length > 0) {
-      entities.push({ id: entityId, components, tags });
-    }
-  }
-  return {
-    version: 1,
-    entities,
-    resources: {
-      camera: { ...camera },
-      navigationStack: structuredClone(navigationFrames)
-    }
-  };
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_hooks = require("./hooks-CtP02JNt.cjs");
+const require_ecs = require("./ecs-B4QrqfvQ.cjs");
+//#region src/ecs/serialization.ts
+/**
+* Serializes all entities, components, and tags to a JSON-compatible document.
+* Requires registries of known component and tag types for enumeration.
+*/
+function serializeWorld(world, componentTypes, tagTypes, camera, rootCamera) {
+	const entities = [];
+	const allEntities = world.query();
+	for (const entityId of allEntities) {
+		const components = {};
+		const tags = [];
+		for (const type of componentTypes) {
+			if (type.name === "PreDragLayer" || type.name === "TransformTween" || type.name === "CardOverlapHotPoint") continue;
+			const data = world.getComponent(entityId, type);
+			if (data !== void 0) components[type.name] = structuredClone(data);
+		}
+		for (const type of tagTypes) if (world.hasTag(entityId, type)) {
+			if (type.name !== "Active" && type.name !== "Visible" && type.name !== "Culled" && type.name !== "OverlapCandidate" && type.name !== "OverlapTarget") tags.push(type.name);
+		}
+		if (Object.keys(components).length > 0 || tags.length > 0) entities.push({
+			id: entityId,
+			components,
+			tags
+		});
+	}
+	return {
+		version: 1,
+		entities,
+		resources: {
+			camera: { ...camera },
+			rootCamera: { ...rootCamera }
+		}
+	};
 }
+/**
+* Restores entities from a serialized document into the world.
+* Clears existing state first and remaps entity IDs automatically.
+*/
 function deserializeWorld(world, doc, componentTypes, tagTypes) {
-  if (doc.version !== 1) {
-    throw new Error(`Unsupported canvas document version: ${doc.version}. Expected version 1.`);
-  }
-  const compByName = /* @__PURE__ */ new Map();
-  for (const t of componentTypes) compByName.set(t.name, t);
-  const tagByName = /* @__PURE__ */ new Map();
-  for (const t of tagTypes) tagByName.set(t.name, t);
-  for (const entityId of world.query()) {
-    world.destroyEntity(entityId);
-  }
-  const idMap = /* @__PURE__ */ new Map();
-  for (const entry of doc.entities) {
-    const newId = world.createEntity();
-    idMap.set(entry.id, newId);
-    for (const [compName, data] of Object.entries(entry.components)) {
-      const type = compByName.get(compName);
-      if (type) {
-        world.addComponent(newId, type, data);
-      }
-    }
-    for (const tagName of entry.tags) {
-      const type = tagByName.get(tagName);
-      if (type) {
-        world.addTag(newId, type);
-      }
-    }
-  }
-  for (const [_oldId, newId] of idMap) {
-    const parent = world.getComponent(newId, chunk2KBYGER3_cjs.Parent);
-    if (parent && idMap.has(parent.id)) {
-      const mappedId = idMap.get(parent.id);
-      if (mappedId !== void 0) {
-        world.setComponent(newId, chunk2KBYGER3_cjs.Parent, { id: mappedId });
-      }
-    }
-    const children = world.getComponent(newId, chunk2KBYGER3_cjs.Children);
-    if (children) {
-      world.setComponent(newId, chunk2KBYGER3_cjs.Children, {
-        ids: children.ids.map((id) => idMap.get(id) ?? id)
-      });
-    }
-    const handleSet = world.getComponent(newId, chunk2KBYGER3_cjs.HandleSet);
-    if (handleSet) {
-      world.setComponent(newId, chunk2KBYGER3_cjs.HandleSet, {
-        ids: handleSet.ids.map((id) => idMap.get(id) ?? id)
-      });
-    }
-  }
+	if (doc.version !== 1) throw new Error(`Unsupported canvas document version: ${doc.version}. Expected version 1.`);
+	const compByName = /* @__PURE__ */ new Map();
+	for (const t of componentTypes) compByName.set(t.name, t);
+	const tagByName = /* @__PURE__ */ new Map();
+	for (const t of tagTypes) tagByName.set(t.name, t);
+	for (const entityId of world.query()) world.destroyEntity(entityId);
+	const idMap = /* @__PURE__ */ new Map();
+	for (const entry of doc.entities) {
+		const newId = world.createEntity();
+		idMap.set(entry.id, newId);
+		for (const [compName, data] of Object.entries(entry.components)) {
+			const type = compByName.get(compName);
+			if (type) world.addComponent(newId, type, data);
+		}
+		for (const tagName of entry.tags) {
+			const type = tagByName.get(tagName);
+			if (type) world.addTag(newId, type);
+		}
+	}
+	for (const [_oldId, newId] of idMap) {
+		const parent = world.getComponent(newId, require_ecs.ParentFrame);
+		if (parent && idMap.has(parent.id)) {
+			const mappedId = idMap.get(parent.id);
+			if (mappedId !== void 0) world.setComponent(newId, require_ecs.ParentFrame, { id: mappedId });
+		}
+		const children = world.getComponent(newId, require_ecs.Children);
+		if (children) world.setComponent(newId, require_ecs.Children, { ids: children.ids.map((id) => idMap.get(id) ?? id) });
+		const containerChildren = world.getComponent(newId, require_ecs.ContainerChildren);
+		if (containerChildren) {
+			const mapped = [];
+			for (const id of containerChildren.ids) {
+				const remapped = idMap.get(id);
+				if (remapped !== void 0) mapped.push(remapped);
+			}
+			world.setComponent(newId, require_ecs.ContainerChildren, { ids: mapped });
+		}
+	}
+	const live = doc.resources.camera;
+	world.setResource(require_ecs.CameraResource, {
+		x: live.x,
+		y: live.y,
+		zoom: live.zoom,
+		gesturing: false
+	});
+	world.setResource(require_ecs.RootCameraResource, { ...doc.resources.rootCamera });
 }
+/**
+* Serializes a subset of entities (e.g., for copy/paste).
+* Recursively includes children of the specified entities.
+*/
 function serializeEntities(world, entityIds, componentTypes, tagTypes) {
-  const result = [];
-  const visited = /* @__PURE__ */ new Set();
-  function visit(entityId) {
-    if (visited.has(entityId)) return;
-    visited.add(entityId);
-    const components = {};
-    const tags = [];
-    for (const type of componentTypes) {
-      const data = world.getComponent(entityId, type);
-      if (data !== void 0) {
-        components[type.name] = structuredClone(data);
-      }
-    }
-    for (const type of tagTypes) {
-      if (world.hasTag(entityId, type)) {
-        if (type.name !== "Active" && type.name !== "Visible") {
-          tags.push(type.name);
-        }
-      }
-    }
-    result.push({ id: entityId, components, tags });
-    const children = components.Children;
-    if (children?.ids) {
-      for (const childId of children.ids) {
-        visit(childId);
-      }
-    }
-  }
-  for (const id of entityIds) {
-    visit(id);
-  }
-  return result;
+	const result = [];
+	const visited = /* @__PURE__ */ new Set();
+	function visit(entityId) {
+		if (visited.has(entityId)) return;
+		visited.add(entityId);
+		const components = {};
+		const tags = [];
+		for (const type of componentTypes) {
+			if (type.name === "PreDragLayer" || type.name === "TransformTween" || type.name === "CardOverlapHotPoint") continue;
+			const data = world.getComponent(entityId, type);
+			if (data !== void 0) components[type.name] = structuredClone(data);
+		}
+		for (const type of tagTypes) if (world.hasTag(entityId, type)) {
+			if (type.name !== "Active" && type.name !== "Visible" && type.name !== "Culled") tags.push(type.name);
+		}
+		result.push({
+			id: entityId,
+			components,
+			tags
+		});
+		const children = components.Children;
+		if (children?.ids) for (const childId of children.ids) visit(childId);
+	}
+	for (const id of entityIds) visit(id);
+	return result;
 }
-
-Object.defineProperty(exports, "GridRenderer", {
-  enumerable: true,
-  get: function () { return chunkFUPKRQB2_cjs.GridRenderer; }
-});
-Object.defineProperty(exports, "Profiler", {
-  enumerable: true,
-  get: function () { return chunkFUPKRQB2_cjs.Profiler; }
-});
-Object.defineProperty(exports, "SelectionOverlaySlot", {
-  enumerable: true,
-  get: function () { return chunkFUPKRQB2_cjs.SelectionOverlaySlot; }
-});
-Object.defineProperty(exports, "SelectionRenderer", {
-  enumerable: true,
-  get: function () { return chunkFUPKRQB2_cjs.SelectionRenderer; }
-});
-Object.defineProperty(exports, "SpatialIndex", {
-  enumerable: true,
-  get: function () { return chunkFUPKRQB2_cjs.SpatialIndex; }
-});
-Object.defineProperty(exports, "SpatialIndexResource", {
-  enumerable: true,
-  get: function () { return chunkFUPKRQB2_cjs.SpatialIndexResource; }
-});
-Object.defineProperty(exports, "WebGLWidgetLayer", {
-  enumerable: true,
-  get: function () { return chunkFUPKRQB2_cjs.WebGLWidgetLayer; }
-});
-Object.defineProperty(exports, "WebGLWidgetSlot", {
-  enumerable: true,
-  get: function () { return chunkFUPKRQB2_cjs.WebGLWidgetSlot; }
-});
-Object.defineProperty(exports, "WidgetSlot", {
-  enumerable: true,
-  get: function () { return chunkFUPKRQB2_cjs.WidgetSlot; }
-});
-Object.defineProperty(exports, "computeSnapGuides", {
-  enumerable: true,
-  get: function () { return chunkFUPKRQB2_cjs.computeSnapGuides; }
-});
-Object.defineProperty(exports, "ContainerRefProvider", {
-  enumerable: true,
-  get: function () { return chunk2KBYGER3_cjs.ContainerRefProvider; }
-});
-Object.defineProperty(exports, "EngineProvider", {
-  enumerable: true,
-  get: function () { return chunk2KBYGER3_cjs.EngineProvider; }
-});
+//#endregion
+exports.Compositor = require_hooks.Compositor;
+exports.CompositorContext = require_hooks.CompositorContext;
+exports.ContainerRefProvider = require_hooks.ContainerRefProvider;
+exports.EngineProvider = require_ecs.EngineProvider;
+exports.GridRenderer = require_hooks.GridRenderer;
+exports.Profiler = require_hooks.Profiler;
+exports.ProfilerProbe = require_hooks.ProfilerProbe;
+exports.R3FAnimationSignal = require_hooks.R3FAnimationSignal;
+exports.R3FManager = require_hooks.R3FManager;
+exports.R3FRenderBudget = require_hooks.R3FRenderBudget;
+exports.R3FRenderState = require_hooks.R3FRenderState;
+exports.ResourceRegistry = require_hooks.ResourceRegistry;
+exports.SelectionOverlaySlot = require_hooks.SelectionOverlaySlot;
+exports.SelectionRenderer = require_hooks.SelectionRenderer;
+exports.SpatialIndex = require_hooks.SpatialIndex;
+exports.SpatialIndexResource = require_ecs.SpatialIndexResource;
+exports.VirtualWidget = require_hooks.VirtualWidget;
+exports.WebGLManager = require_hooks.WebGLManager;
+exports.WidgetRenderTargetPool = require_hooks.WidgetRenderTargetPool;
+exports.WidgetSlot = require_hooks.WidgetSlot;
+exports.WidgetStateMachine = require_hooks.WidgetStateMachine;
+exports.ZOOM_BANDS = require_hooks.ZOOM_BANDS;
+exports.computeSnapGuides = require_hooks.computeSnapGuides;
 exports.deserializeWorld = deserializeWorld;
+exports.isOutOfBand = require_hooks.isOutOfBand;
+exports.selectBand = require_hooks.selectBand;
 exports.serializeEntities = serializeEntities;
 exports.serializeWorld = serializeWorld;
-//# sourceMappingURL=advanced.cjs.map
+exports.useCompositor = require_hooks.useCompositor;
+exports.useSharedGeometry = require_hooks.useSharedGeometry;
+exports.useSharedMaterial = require_hooks.useSharedMaterial;
+exports.useSharedTexture = require_hooks.useSharedTexture;
+exports.useWidgetAnimation = require_hooks.useWidgetAnimation;
+exports.useWidgetInvalidate = require_hooks.useWidgetInvalidate;
+exports.useWidgetPhase = require_hooks.useWidgetPhase;
+
 //# sourceMappingURL=advanced.cjs.map

package/dist/advanced.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/serialization.ts"],"names":["Parent","Children","HandleSet"],"mappings":"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","file":"advanced.cjs","sourcesContent":["import type { ComponentType, EntityId, TagType, World } from '@jamesyong42/reactive-ecs';\nimport { Children, HandleSet, Parent } from './components.js';\nimport type { NavigationFrame } from './resources.js';\n\n// === Serialization Types ===\n\n/** JSON-serializable snapshot of the canvas state, including all entities and camera. */\nexport interface CanvasDocument {\n\tversion: number;\n\tentities: SerializedEntity[];\n\tresources: {\n\t\tcamera: { x: number; y: number; zoom: number };\n\t\tnavigationStack: NavigationFrame[];\n\t};\n}\n\n/** A single serialized entity with its components and tags. */\nexport interface SerializedEntity {\n\tid: EntityId;\n\tcomponents: Record<string, unknown>;\n\ttags: string[];\n}\n\n// === Serialize/Deserialize ===\n\n/**\n * Serializes all entities, components, and tags to a JSON-compatible document.\n * Requires registries of known component and tag types for enumeration.\n */\nexport function serializeWorld(\n\tworld: World,\n\tcomponentTypes: ComponentType[],\n\ttagTypes: TagType[],\n\tcamera: { x: number; y: number; zoom: number },\n\tnavigationFrames: NavigationFrame[],\n): CanvasDocument {\n\tconst entities: SerializedEntity[] = [];\n\n\t// Get all entity IDs (use a broad query)\n\tconst allEntities = world.query();\n\n\tfor (const entityId of allEntities) {\n\t\tconst components: Record<string, unknown> = {};\n\t\tconst tags: string[] = [];\n\n\t\tfor (const type of componentTypes) {\n\t\t\tconst data = world.getComponent(entityId, type);\n\t\t\tif (data !== undefined) {\n\t\t\t\tcomponents[type.name] = structuredClone(data);\n\t\t\t}\n\t\t}\n\n\t\tfor (const type of tagTypes) {\n\t\t\tif (world.hasTag(entityId, type)) {\n\t\t\t\t// Skip runtime-only tags (Active, Visible — they're recomputed)\n\t\t\t\tif (type.name !== 'Active' && type.name !== 'Visible') {\n\t\t\t\t\ttags.push(type.name);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\tif (Object.keys(components).length > 0 || tags.length > 0) {\n\t\t\tentities.push({ id: entityId, components, tags });\n\t\t}\n\t}\n\n\treturn {\n\t\tversion: 1,\n\t\tentities,\n\t\tresources: {\n\t\t\tcamera: { ...camera },\n\t\t\tnavigationStack: structuredClone(navigationFrames),\n\t\t},\n\t};\n}\n\n/**\n * Restores entities from a serialized document into the world.\n * Clears existing state first and remaps entity IDs automatically.\n */\nexport function deserializeWorld(\n\tworld: World,\n\tdoc: CanvasDocument,\n\tcomponentTypes: ComponentType[],\n\ttagTypes: TagType[],\n): void {\n\tif (doc.version !== 1) {\n\t\tthrow new Error(`Unsupported canvas document version: ${doc.version}. Expected version 1.`);\n\t}\n\n\t// Build lookup maps\n\tconst compByName = new Map<string, ComponentType>();\n\tfor (const t of componentTypes) compByName.set(t.name, t);\n\n\tconst tagByName = new Map<string, TagType>();\n\tfor (const t of tagTypes) tagByName.set(t.name, t);\n\n\t// Destroy all existing entities\n\tfor (const entityId of world.query()) {\n\t\tworld.destroyEntity(entityId);\n\t}\n\n\t// First pass: create entities and build old-to-new ID mapping\n\tconst idMap = new Map<EntityId, EntityId>();\n\n\tfor (const entry of doc.entities) {\n\t\tconst newId = world.createEntity();\n\t\tidMap.set(entry.id as EntityId, newId);\n\n\t\tfor (const [compName, data] of Object.entries(entry.components)) {\n\t\t\tconst type = compByName.get(compName);\n\t\t\tif (type) {\n\t\t\t\tworld.addComponent(newId, type, data);\n\t\t\t}\n\t\t}\n\n\t\tfor (const tagName of entry.tags) {\n\t\t\tconst type = tagByName.get(tagName);\n\t\t\tif (type) {\n\t\t\t\tworld.addTag(newId, type);\n\t\t\t}\n\t\t}\n\t}\n\n\t// Second pass: remap cross-reference components (Parent, Children, HandleSet)\n\tfor (const [_oldId, newId] of idMap) {\n\t\tconst parent = world.getComponent(newId, Parent);\n\t\tif (parent && idMap.has(parent.id)) {\n\t\t\tconst mappedId = idMap.get(parent.id);\n\t\t\tif (mappedId !== undefined) {\n\t\t\t\tworld.setComponent(newId, Parent, { id: mappedId });\n\t\t\t}\n\t\t}\n\n\t\tconst children = world.getComponent(newId, Children);\n\t\tif (children) {\n\t\t\tworld.setComponent(newId, Children, {\n\t\t\t\tids: children.ids.map((id: EntityId) => idMap.get(id) ?? id),\n\t\t\t});\n\t\t}\n\n\t\tconst handleSet = world.getComponent(newId, HandleSet);\n\t\tif (handleSet) {\n\t\t\tworld.setComponent(newId, HandleSet, {\n\t\t\t\tids: handleSet.ids.map((id: EntityId) => idMap.get(id) ?? id),\n\t\t\t});\n\t\t}\n\t}\n}\n\n/**\n * Serializes a subset of entities (e.g., for copy/paste).\n * Recursively includes children of the specified entities.\n */\nexport function serializeEntities(\n\tworld: World,\n\tentityIds: EntityId[],\n\tcomponentTypes: ComponentType[],\n\ttagTypes: TagType[],\n): SerializedEntity[] {\n\tconst result: SerializedEntity[] = [];\n\tconst visited = new Set<EntityId>();\n\n\tfunction visit(entityId: EntityId) {\n\t\tif (visited.has(entityId)) return;\n\t\tvisited.add(entityId);\n\n\t\tconst components: Record<string, unknown> = {};\n\t\tconst tags: string[] = [];\n\n\t\tfor (const type of componentTypes) {\n\t\t\tconst data = world.getComponent(entityId, type);\n\t\t\tif (data !== undefined) {\n\t\t\t\tcomponents[type.name] = structuredClone(data);\n\t\t\t}\n\t\t}\n\n\t\tfor (const type of tagTypes) {\n\t\t\tif (world.hasTag(entityId, type)) {\n\t\t\t\tif (type.name !== 'Active' && type.name !== 'Visible') {\n\t\t\t\t\ttags.push(type.name);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\tresult.push({ id: entityId, components, tags });\n\n\t\t// Recurse into children. components.Children is typed as unknown via\n\t\t// the Record<string, unknown> shape, so narrow through a cast.\n\t\tconst children = components.Children as { ids?: EntityId[] } | undefined;\n\t\tif (children?.ids) {\n\t\t\tfor (const childId of children.ids) {\n\t\t\t\tvisit(childId);\n\t\t\t}\n\t\t}\n\t}\n\n\tfor (const id of entityIds) {\n\t\tvisit(id);\n\t}\n\n\treturn result;\n}\n"]}
+{"version":3,"file":"advanced.cjs","names":["ParentFrame","Children","ContainerChildren","CameraResource","RootCameraResource"],"sources":["../src/ecs/serialization.ts"],"sourcesContent":["import type { ComponentType, EntityId, TagType, World } from '@jamesyong42/reactive-ecs';\nimport { Children, ContainerChildren, ParentFrame } from './components.js';\nimport type { FrameCameraState } from './resources.js';\nimport { CameraResource, RootCameraResource } from './resources.js';\n\n// === Serialization Types ===\n\n/**\n * JSON-serializable snapshot of the canvas state, including all entities,\n * the current camera, and the persisted root-frame camera.\n *\n * The navigation stack is **not** serialized — reloading a canvas always\n * drops the user at the root frame (RFC-004 § Phase 0c). Per-container\n * camera state is persisted via the `ContainerCamera` component on each\n * container entity (serialized as part of its component set).\n */\nexport interface CanvasDocument {\n\tversion: number;\n\tentities: SerializedEntity[];\n\tresources: {\n\t\t/** Current live camera (whatever frame the user was in at serialize time). */\n\t\tcamera: FrameCameraState;\n\t\t/** Persisted root-frame camera — restored on load. */\n\t\trootCamera: FrameCameraState;\n\t};\n}\n\n/** A single serialized entity with its components and tags. */\nexport interface SerializedEntity {\n\tid: EntityId;\n\tcomponents: Record<string, unknown>;\n\ttags: string[];\n}\n\n// === Serialize/Deserialize ===\n\n/**\n * Serializes all entities, components, and tags to a JSON-compatible document.\n * Requires registries of known component and tag types for enumeration.\n */\nexport function serializeWorld(\n\tworld: World,\n\tcomponentTypes: ComponentType[],\n\ttagTypes: TagType[],\n\tcamera: FrameCameraState,\n\trootCamera: FrameCameraState,\n): CanvasDocument {\n\tconst entities: SerializedEntity[] = [];\n\n\t// Get all entity IDs (use a broad query)\n\tconst allEntities = world.query();\n\n\tfor (const entityId of allEntities) {\n\t\tconst components: Record<string, unknown> = {};\n\t\tconst tags: string[] = [];\n\n\t\tfor (const type of componentTypes) {\n\t\t\t// Skip runtime-only components: `PreDragLayer` is recomputed by\n\t\t\t// dragPromoteSystem on the next Dragging flip; `TransformTween`\n\t\t\t// is an in-flight animation that should not be paused / resumed\n\t\t\t// across reloads (the destination `Transform2D` persists instead);\n\t\t\t// `CardOverlapHotPoint` is drag-scoped visual state with no\n\t\t\t// meaning outside an active drag.\n\t\t\tif (\n\t\t\t\ttype.name === 'PreDragLayer' ||\n\t\t\t\ttype.name === 'TransformTween' ||\n\t\t\t\ttype.name === 'CardOverlapHotPoint'\n\t\t\t) {\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tconst data = world.getComponent(entityId, type);\n\t\t\tif (data !== undefined) {\n\t\t\t\tcomponents[type.name] = structuredClone(data);\n\t\t\t}\n\t\t}\n\n\t\tfor (const type of tagTypes) {\n\t\t\tif (world.hasTag(entityId, type)) {\n\t\t\t\t// Skip runtime-only tags: Active/Visible/Culled are recomputed\n\t\t\t\t// by the cull pipeline; OverlapCandidate/OverlapTarget are\n\t\t\t\t// drag-scoped and meaningless outside an active drag.\n\t\t\t\tif (\n\t\t\t\t\ttype.name !== 'Active' &&\n\t\t\t\t\ttype.name !== 'Visible' &&\n\t\t\t\t\ttype.name !== 'Culled' &&\n\t\t\t\t\ttype.name !== 'OverlapCandidate' &&\n\t\t\t\t\ttype.name !== 'OverlapTarget'\n\t\t\t\t) {\n\t\t\t\t\ttags.push(type.name);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\tif (Object.keys(components).length > 0 || tags.length > 0) {\n\t\t\tentities.push({ id: entityId, components, tags });\n\t\t}\n\t}\n\n\treturn {\n\t\tversion: 1,\n\t\tentities,\n\t\tresources: {\n\t\t\tcamera: { ...camera },\n\t\t\trootCamera: { ...rootCamera },\n\t\t},\n\t};\n}\n\n/**\n * Restores entities from a serialized document into the world.\n * Clears existing state first and remaps entity IDs automatically.\n */\nexport function deserializeWorld(\n\tworld: World,\n\tdoc: CanvasDocument,\n\tcomponentTypes: ComponentType[],\n\ttagTypes: TagType[],\n): void {\n\tif (doc.version !== 1) {\n\t\tthrow new Error(`Unsupported canvas document version: ${doc.version}. Expected version 1.`);\n\t}\n\n\t// Build lookup maps\n\tconst compByName = new Map<string, ComponentType>();\n\tfor (const t of componentTypes) compByName.set(t.name, t);\n\n\tconst tagByName = new Map<string, TagType>();\n\tfor (const t of tagTypes) tagByName.set(t.name, t);\n\n\t// Destroy all existing entities\n\tfor (const entityId of world.query()) {\n\t\tworld.destroyEntity(entityId);\n\t}\n\n\t// First pass: create entities and build old-to-new ID mapping\n\tconst idMap = new Map<EntityId, EntityId>();\n\n\tfor (const entry of doc.entities) {\n\t\tconst newId = world.createEntity();\n\t\tidMap.set(entry.id as EntityId, newId);\n\n\t\tfor (const [compName, data] of Object.entries(entry.components)) {\n\t\t\tconst type = compByName.get(compName);\n\t\t\tif (type) {\n\t\t\t\tworld.addComponent(newId, type, data);\n\t\t\t}\n\t\t}\n\n\t\tfor (const tagName of entry.tags) {\n\t\t\tconst type = tagByName.get(tagName);\n\t\t\tif (type) {\n\t\t\t\tworld.addTag(newId, type);\n\t\t\t}\n\t\t}\n\t}\n\n\t// Second pass: remap cross-reference components (ParentFrame, Children,\n\t// ContainerChildren).\n\tfor (const [_oldId, newId] of idMap) {\n\t\tconst parent = world.getComponent(newId, ParentFrame);\n\t\tif (parent && idMap.has(parent.id)) {\n\t\t\tconst mappedId = idMap.get(parent.id);\n\t\t\tif (mappedId !== undefined) {\n\t\t\t\tworld.setComponent(newId, ParentFrame, { id: mappedId });\n\t\t\t}\n\t\t}\n\n\t\tconst children = world.getComponent(newId, Children);\n\t\tif (children) {\n\t\t\tworld.setComponent(newId, Children, {\n\t\t\t\tids: children.ids.map((id: EntityId) => idMap.get(id) ?? id),\n\t\t\t});\n\t\t}\n\n\t\tconst containerChildren = world.getComponent(newId, ContainerChildren);\n\t\tif (containerChildren) {\n\t\t\t// Drop ids that didn't round-trip (child was destroyed before save\n\t\t\t// and still lingered in the list) rather than falling back to the\n\t\t\t// raw pre-save id — that id may have been recycled to an unrelated\n\t\t\t// entity by the post-load world and would leak into the container's\n\t\t\t// child count / navigation target list.\n\t\t\tconst mapped: EntityId[] = [];\n\t\t\tfor (const id of containerChildren.ids) {\n\t\t\t\tconst remapped = idMap.get(id);\n\t\t\t\tif (remapped !== undefined) mapped.push(remapped);\n\t\t\t}\n\t\t\tworld.setComponent(newId, ContainerChildren, { ids: mapped });\n\t\t}\n\t}\n\n\t// Restore camera resources. `gesturing` resets to false on load — it's\n\t// transient interaction state, not persisted view state.\n\tconst live = doc.resources.camera;\n\tworld.setResource(CameraResource, { x: live.x, y: live.y, zoom: live.zoom, gesturing: false });\n\tworld.setResource(RootCameraResource, { ...doc.resources.rootCamera });\n\n\t// NavigationStack is deliberately not restored — users always return\n\t// to the root frame on load (RFC-004 § Phase 0c).\n}\n\n/**\n * Serializes a subset of entities (e.g., for copy/paste).\n * Recursively includes children of the specified entities.\n */\nexport function serializeEntities(\n\tworld: World,\n\tentityIds: EntityId[],\n\tcomponentTypes: ComponentType[],\n\ttagTypes: TagType[],\n): SerializedEntity[] {\n\tconst result: SerializedEntity[] = [];\n\tconst visited = new Set<EntityId>();\n\n\tfunction visit(entityId: EntityId) {\n\t\tif (visited.has(entityId)) return;\n\t\tvisited.add(entityId);\n\n\t\tconst components: Record<string, unknown> = {};\n\t\tconst tags: string[] = [];\n\n\t\tfor (const type of componentTypes) {\n\t\t\t// Skip runtime-only components: `PreDragLayer` is recomputed by\n\t\t\t// dragPromoteSystem on the next Dragging flip; `TransformTween`\n\t\t\t// is an in-flight animation that should not be paused / resumed\n\t\t\t// across reloads (the destination `Transform2D` persists instead);\n\t\t\t// `CardOverlapHotPoint` is drag-scoped visual state with no\n\t\t\t// meaning outside an active drag.\n\t\t\tif (\n\t\t\t\ttype.name === 'PreDragLayer' ||\n\t\t\t\ttype.name === 'TransformTween' ||\n\t\t\t\ttype.name === 'CardOverlapHotPoint'\n\t\t\t) {\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tconst data = world.getComponent(entityId, type);\n\t\t\tif (data !== undefined) {\n\t\t\t\tcomponents[type.name] = structuredClone(data);\n\t\t\t}\n\t\t}\n\n\t\tfor (const type of tagTypes) {\n\t\t\tif (world.hasTag(entityId, type)) {\n\t\t\t\tif (type.name !== 'Active' && type.name !== 'Visible' && type.name !== 'Culled') {\n\t\t\t\t\ttags.push(type.name);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\tresult.push({ id: entityId, components, tags });\n\n\t\t// Recurse into children. components.Children is typed as unknown via\n\t\t// the Record<string, unknown> shape, so narrow through a cast.\n\t\tconst children = components.Children as { ids?: EntityId[] } | undefined;\n\t\tif (children?.ids) {\n\t\t\tfor (const childId of children.ids) {\n\t\t\t\tvisit(childId);\n\t\t\t}\n\t\t}\n\t}\n\n\tfor (const id of entityIds) {\n\t\tvisit(id);\n\t}\n\n\treturn result;\n}\n"],"mappings":"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"}