@jamesyong42/infinite-canvas 1.2.0 → 1.3.0

package/README.md

@@ -352,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

package/dist/advanced.cjs

@@ -1,23 +1,24 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_WebGLWidgetLayer = require("./WebGLWidgetLayer-BBMuwzHq.cjs");
-const require_hooks = require("./hooks-DHShH86C.cjs");
-//#region src/serialization.ts
+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, navigationFrames) {
+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") tags.push(type.name);
+			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,
@@ -30,7 +31,7 @@ function serializeWorld(world, componentTypes, tagTypes, camera, navigationFrame
 		entities,
 		resources: {
 			camera: { ...camera },
-			navigationStack: structuredClone(navigationFrames)
+			rootCamera: { ...rootCamera }
 		}
 	};
 }
@@ -59,16 +60,31 @@ function deserializeWorld(world, doc, componentTypes, tagTypes) {
 		}
 	}
 	for (const [_oldId, newId] of idMap) {
-		const parent = world.getComponent(newId, require_hooks.Parent);
+		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_hooks.Parent, { id: mappedId });
+			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 children = world.getComponent(newId, require_hooks.Children);
-		if (children) world.setComponent(newId, require_hooks.Children, { ids: children.ids.map((id) => idMap.get(id) ?? id) });
-		const handleSet = world.getComponent(newId, require_hooks.HandleSet);
-		if (handleSet) world.setComponent(newId, require_hooks.HandleSet, { ids: handleSet.ids.map((id) => idMap.get(id) ?? id) });
 	}
+	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).
@@ -83,11 +99,12 @@ function serializeEntities(world, entityIds, componentTypes, tagTypes) {
 		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") tags.push(type.name);
+			if (type.name !== "Active" && type.name !== "Visible" && type.name !== "Culled") tags.push(type.name);
 		}
 		result.push({
 			id: entityId,
@@ -101,20 +118,40 @@ function serializeEntities(world, entityIds, componentTypes, tagTypes) {
 	return result;
 }
 //#endregion
+exports.Compositor = require_hooks.Compositor;
+exports.CompositorContext = require_hooks.CompositorContext;
 exports.ContainerRefProvider = require_hooks.ContainerRefProvider;
-exports.EngineProvider = require_hooks.EngineProvider;
-exports.GridRenderer = require_WebGLWidgetLayer.GridRenderer;
-exports.Profiler = require_WebGLWidgetLayer.Profiler;
-exports.SelectionOverlaySlot = require_WebGLWidgetLayer.SelectionOverlaySlot;
-exports.SelectionRenderer = require_WebGLWidgetLayer.SelectionRenderer;
-exports.SpatialIndex = require_WebGLWidgetLayer.SpatialIndex;
-exports.SpatialIndexResource = require_WebGLWidgetLayer.SpatialIndexResource;
-exports.WebGLWidgetLayer = require_WebGLWidgetLayer.WebGLWidgetLayer;
-exports.WebGLWidgetSlot = require_WebGLWidgetLayer.WebGLWidgetSlot;
-exports.WidgetSlot = require_WebGLWidgetLayer.WidgetSlot;
-exports.computeSnapGuides = require_WebGLWidgetLayer.computeSnapGuides;
+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;
+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,"file":"advanced.cjs","names":["Parent","Children","HandleSet"],"sources":["../src/serialization.ts"],"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"],"mappings":"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"}
+{"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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"}

package/dist/advanced.d.cts

@@ -1,99 +1,215 @@
-import { A as NavigationFrame, C as computeSnapGuides, G as FrameTimeStats, J as R3FSample, K as Profiler, L as R3FWidgetProps, Q as WebGLStats, W as EcsStats, X as TickSample, Y as R3FStats, Z as WebGLPass, l as SpatialIndex, n as LayoutEngine, o as SpatialIndexResource, q as ProfilerStats } from "./engine-CCjuFMC-.cjs";
-import { c as ContainerRefProvider, i as SelectionRenderer, l as EngineProvider, s as GridRenderer, u as ResolvedWidget } from "./SelectionRenderer-CR2PBQwx.cjs";
+import { $ as FrameCameraState, B as WebGLPass, F as ProfilerStats, I as R3FPhaseHistogram, K as computeSnapGuides, L as R3FSample, M as EcsStats, N as FrameTimeStats, P as Profiler, R as R3FStats, U as EqualSpacingIndicator, V as WebGLStats, W as SnapGuide, at as SpatialIndexResource, ct as SpatialIndex, r as LayoutEngine, z as TickSample } from "./index-DSdbSQ_t.cjs";
+import { A as SelectionConfig, B as ContainerRefProvider, C as useCompositor, D as SnapGuideConfig, F as ResolvedWidget, N as GridConfig, P as GridRenderer, R as EngineProvider, S as CompositorWidgetEntry, T as ResourceRegistry, _ as R3FRenderState, a as VirtualWidget, b as CompositorContext, c as useSharedTexture, d as useWidgetPhase, f as R3FAnimationSignal, g as R3FRenderBudgetData, h as R3FRenderBudget, i as WidgetStateMachine, j as SelectionRenderer, k as SelectionBounds, l as useWidgetAnimation, m as R3FPhase, n as isOutOfBand, o as useSharedGeometry, p as R3FPaintedAt, r as selectBand, s as useSharedMaterial, t as ZOOM_BANDS, u as useWidgetInvalidate, v as R3FRenderStateData, w as WidgetRenderTargetPool, x as CompositorContextValue, y as Compositor } from "./index-B7B1tRPl.cjs";
 import { ComponentType, EntityId, TagType, World } from "@jamesyong42/reactive-ecs";
 import * as _$react from "react";
 import * as _$react_jsx_runtime0 from "react/jsx-runtime";
+import * as THREE from "three";
 
-//#region src/react/SelectionOverlaySlot.d.ts
+//#region src/ecs/serialization.d.ts
+/**
+ * JSON-serializable snapshot of the canvas state, including all entities,
+ * the current camera, and the persisted root-frame camera.
+ *
+ * The navigation stack is **not** serialized — reloading a canvas always
+ * drops the user at the root frame (RFC-004 § Phase 0c). Per-container
+ * camera state is persisted via the `ContainerCamera` component on each
+ * container entity (serialized as part of its component set).
+ */
+interface CanvasDocument {
+  version: number;
+  entities: SerializedEntity[];
+  resources: {
+    /** Current live camera (whatever frame the user was in at serialize time). */camera: FrameCameraState; /** Persisted root-frame camera — restored on load. */
+    rootCamera: FrameCameraState;
+  };
+}
+/** A single serialized entity with its components and tags. */
+interface SerializedEntity {
+  id: EntityId;
+  components: Record<string, unknown>;
+  tags: string[];
+}
+/**
+ * Serializes all entities, components, and tags to a JSON-compatible document.
+ * Requires registries of known component and tag types for enumeration.
+ */
+declare function serializeWorld(world: World, componentTypes: ComponentType[], tagTypes: TagType[], camera: FrameCameraState, rootCamera: FrameCameraState): CanvasDocument;
+/**
+ * Restores entities from a serialized document into the world.
+ * Clears existing state first and remaps entity IDs automatically.
+ */
+declare function deserializeWorld(world: World, doc: CanvasDocument, componentTypes: ComponentType[], tagTypes: TagType[]): void;
+/**
+ * Serializes a subset of entities (e.g., for copy/paste).
+ * Recursively includes children of the specified entities.
+ */
+declare function serializeEntities(world: World, entityIds: EntityId[], componentTypes: ComponentType[], tagTypes: TagType[]): SerializedEntity[];
+//#endregion
+//#region src/react/overlays/SelectionOverlaySlot.d.ts
 interface SelectionOverlaySlotProps {
   entityId: EntityId;
   slotRef: (entityId: EntityId, el: HTMLDivElement | null) => void;
 }
 /**
- * DOM overlay for WebGL widgets — provides selection frame and pointer
- * interaction (select, drag, resize) without rendering widget content.
+ * DOM chrome overlay for R3F widgets — renders the selection frame /
+ * card decoration and positions itself at the widget's world AABB.
+ *
+ * Decoration only. Pointer events bypass this wrapper
+ * (`pointer-events: none`) so they reach the R3F canvas underneath,
+ * where the `EventRouter` raycasts the widget's local scene (RFC-006).
+ * Engine semantics — drag, select, resize, double-click — are dispatched
+ * by the canvas-level `PointerEventBus` after the widget's R3F handlers
+ * have had a chance to call `event.stopPropagation()`.
  */
 declare const SelectionOverlaySlot: _$react.MemoExoticComponent<({
   entityId,
   slotRef
 }: SelectionOverlaySlotProps) => _$react_jsx_runtime0.JSX.Element>;
 //#endregion
-//#region src/react/WidgetSlot.d.ts
+//#region src/react/widgets/WidgetSlot.d.ts
 interface WidgetSlotProps {
   entityId: EntityId;
   slotRef: (entityId: EntityId, el: HTMLDivElement | null) => void;
 }
+/**
+ * Wrapper for a DOM widget — owns the slot's positioning, registers its
+ * ref with the rAF batcher, and renders the user's widget component.
+ *
+ * Pointer routing lives in the canvas-level `PointerEventBus` (RFC-006).
+ * The slot does not call the engine; user widget React handlers run on
+ * the natural DOM event path and bubble to the bus, which decides
+ * whether to invoke engine semantics. Authors call `e.stopPropagation()`
+ * from inside their widget to opt out of engine drag/select.
+ */
 declare const WidgetSlot: _$react.MemoExoticComponent<({
   entityId,
   slotRef
 }: WidgetSlotProps) => _$react_jsx_runtime0.JSX.Element>;
 //#endregion
-//#region src/react/webgl/WebGLWidgetLayer.d.ts
-interface WebGLWidgetLayerProps {
-  engine: LayoutEngine;
-  entities: EntityId[];
-  resolve: (entityId: EntityId) => ResolvedWidget | null;
-}
-declare function WebGLWidgetLayer({
-  engine,
-  entities,
-  resolve
-}: WebGLWidgetLayerProps): _$react_jsx_runtime0.JSX.Element;
-//#endregion
-//#region src/react/webgl/WebGLWidgetSlot.d.ts
-interface WebGLWidgetSlotProps {
-  entityId: EntityId;
-  component: React.ComponentType<R3FWidgetProps>;
+//#region src/webgl/WebGLManager.d.ts
+/** Construction options for {@link WebGLManager}. */
+interface WebGLManagerOptions {
+  /** Grid rendering config. Pass `false` to disable the grid entirely. */
+  grid?: Partial<GridConfig> | false;
+  /** Selection overlay config (outline color, handle size, etc.). */
+  selection?: Partial<SelectionConfig>;
+  /** Snap guide overlay config (color, line width, alpha). */
+  snapGuides?: Partial<SnapGuideConfig>;
 }
-/**
- * Positions a Three.js Group at the entity's world-space center.
- * The widget component renders in local space: origin at center,
- * X right, Y up, dimensions = (width, height) in world units.
- */
-declare function WebGLWidgetSlot({
-  entityId,
-  component: WidgetComponent
-}: WebGLWidgetSlotProps): _$react_jsx_runtime0.JSX.Element | null;
-//#endregion
-//#region src/serialization.d.ts
-/** JSON-serializable snapshot of the canvas state, including all entities and camera. */
-interface CanvasDocument {
-  version: number;
-  entities: SerializedEntity[];
-  resources: {
-    camera: {
-      x: number;
-      y: number;
-      zoom: number;
-    };
-    navigationStack: NavigationFrame[];
+/** Per-frame input passed to {@link WebGLManager.render}. */
+interface WebGLFrameInput {
+  camera: {
+    x: number;
+    y: number;
+    zoom: number;
   };
-}
-/** A single serialized entity with its components and tags. */
-interface SerializedEntity {
-  id: EntityId;
-  components: Record<string, unknown>;
-  tags: string[];
+  /** Selection outlines + 8 resize handles + hover. */
+  selection: {
+    bounds: SelectionBounds[];
+    hovered: SelectionBounds | null;
+  };
+  /**
+   * Alignment guides + equal-spacing indicators. Independent of
+   * `selection` — guides display whenever the engine is computing
+   * snap math, regardless of whether anything is selected. Set
+   * `visible: false` to skip the snap-guide pass entirely (the
+   * guides are still computed by the engine; only the render is
+   * suppressed).
+   */
+  snap: {
+    guides: SnapGuide[];
+    spacings: EqualSpacingIndicator[];
+    visible: boolean;
+  };
+  /** Optional — if supplied, the manager records per-pass timings + GL info. */
+  profiler?: Profiler;
+  /** Forwarded into the profiler sample (count of DOM slot transform writes this tick). */
+  domPositionsUpdated?: number;
 }
 /**
- * Serializes all entities, components, and tags to a JSON-compatible document.
- * Requires registries of known component and tag types for enumeration.
+ * Top-level coordinator for the library's vanilla-WebGL layer.
+ *
+ * Owns a single `THREE.WebGLRenderer` and drives the built-in renderers
+ * (dot grid, selection overlay, snap guides) through it. This replaces
+ * the previous pattern where `GridRenderer` owned the renderer and
+ * `SelectionRenderer` piggy-backed on it via an implicit side-effect —
+ * a manager makes the sharing explicit and gives {@link InfiniteCanvas}
+ * a single surface to talk to instead of three.
  */
-declare function serializeWorld(world: World, componentTypes: ComponentType[], tagTypes: TagType[], camera: {
-  x: number;
-  y: number;
-  zoom: number;
-}, navigationFrames: NavigationFrame[]): CanvasDocument;
+declare class WebGLManager {
+  private renderer;
+  private grid;
+  private selection;
+  private snapGuides;
+  constructor(canvas: HTMLCanvasElement, opts?: WebGLManagerOptions);
+  /** Resize the drawing buffer. Call on mount and ResizeObserver events. */
+  setSize(width: number, height: number, dpr?: number): void;
+  /** Update grid visuals (colors, spacings, fade ranges, etc.). */
+  setGridConfig(config: Partial<GridConfig>): void;
+  /** Update selection overlay visuals (outline color, handle size, etc.). */
+  setSelectionConfig(config: Partial<SelectionConfig>): void;
+  /** Update snap-guide visuals (color, line width, alpha). */
+  setSnapGuideConfig(config: Partial<SnapGuideConfig>): void;
+  /** Render one frame: grid → selection → snap guides, in stacking order. */
+  render(input: WebGLFrameInput): void;
+  /** Release GL resources — call on unmount. */
+  dispose(): void;
+  /** Escape hatch if an advanced consumer needs the underlying three renderer. */
+  getWebGLRenderer(): THREE.WebGLRenderer;
+}
+//#endregion
+//#region src/r3f/ProfilerProbe.d.ts
 /**
- * Restores entities from a serialized document into the world.
- * Clears existing state first and remaps entity IDs automatically.
+ * Reports one R3F frame sample per animation frame to the engine profiler.
+ * Reads `renderer.info` from three.js — draw calls / triangles / memory /
+ * programs — which is maintained by R3F's default render loop regardless
+ * of whether we opt in. Only samples when the profiler is enabled.
  */
-declare function deserializeWorld(world: World, doc: CanvasDocument, componentTypes: ComponentType[], tagTypes: TagType[]): void;
+declare function ProfilerProbe({
+  engine,
+  widgetCount
+}: {
+  engine: LayoutEngine;
+  widgetCount: number;
+}): null;
+//#endregion
+//#region src/r3f/R3FManager.d.ts
+interface R3FManagerProps {
+  engine: LayoutEngine;
+  entities: EntityId[];
+  resolve: (entityId: EntityId) => ResolvedWidget | null;
+  /**
+   * Optional R3F nodes mounted at the Canvas root as siblings of the
+   * Compositor (so they live in the Canvas's default scene, not inside
+   * any widget portal). Canonical use: drei's `<Environment>` — the
+   * Compositor's `sharedEnv` propagation logic checks the root scene
+   * before iterating widget scenes, so a root-level env stays alive
+   * across widget navigation (RFC-004 Phase 5 follow-up).
+   */
+  r3fRoot?: _$react.ReactNode;
+  /**
+   * Late-bound handle for the R3F event manager. RFC-008's `R3FRouter`
+   * (constructed in `InfiniteCanvas`) reads this ref to dispatch into
+   * R3F's mesh handlers from the InputManager pipeline. The factory
+   * writes the produced manager into `.current` once R3F invokes it.
+   */
+  eventManagerRef?: _$react.MutableRefObject<any>;
+}
 /**
- * Serializes a subset of entities (e.g., for copy/paste).
- * Recursively includes children of the specified entities.
+ * Top-level coordinator for the R3F (React Three Fiber) rendering layer.
+ *
+ * Mounts a single `<Canvas>` and lets the {@link Compositor} drive the
+ * render loop — each R3F widget paints into its own `WebGLRenderTarget`
+ * via {@link VirtualWidget} and a final composition pass samples those
+ * textures into the visible canvas (RFC-002 Phase 4).
  */
-declare function serializeEntities(world: World, entityIds: EntityId[], componentTypes: ComponentType[], tagTypes: TagType[]): SerializedEntity[];
+declare function R3FManager({
+  engine,
+  entities,
+  resolve,
+  r3fRoot,
+  eventManagerRef
+}: R3FManagerProps): _$react_jsx_runtime0.JSX.Element;
 //#endregion
-export { type CanvasDocument, ContainerRefProvider, type EcsStats, EngineProvider, type FrameTimeStats, GridRenderer, Profiler, type ProfilerStats, type R3FSample, type R3FStats, SelectionOverlaySlot, SelectionRenderer, type SerializedEntity, SpatialIndex, SpatialIndexResource, type TickSample, type WebGLPass, type WebGLStats, WebGLWidgetLayer, WebGLWidgetSlot, WidgetSlot, computeSnapGuides, deserializeWorld, serializeEntities, serializeWorld };
+export { type CanvasDocument, Compositor, CompositorContext, type CompositorContextValue, type CompositorWidgetEntry, ContainerRefProvider, type EcsStats, EngineProvider, type FrameTimeStats, GridRenderer, Profiler, ProfilerProbe, type ProfilerStats, R3FAnimationSignal, R3FManager, type R3FPaintedAt, type R3FPhase, type R3FPhaseHistogram, R3FRenderBudget, type R3FRenderBudgetData, R3FRenderState, type R3FRenderStateData, type R3FSample, type R3FStats, ResourceRegistry, SelectionOverlaySlot, SelectionRenderer, type SerializedEntity, SpatialIndex, SpatialIndexResource, type TickSample, VirtualWidget, type WebGLFrameInput, WebGLManager, type WebGLManagerOptions, type WebGLPass, type WebGLStats, WidgetRenderTargetPool, WidgetSlot, WidgetStateMachine, ZOOM_BANDS, computeSnapGuides, deserializeWorld, isOutOfBand, selectBand, serializeEntities, serializeWorld, useCompositor, useSharedGeometry, useSharedMaterial, useSharedTexture, useWidgetAnimation, useWidgetInvalidate, useWidgetPhase };
 //# sourceMappingURL=advanced.d.cts.map

package/dist/advanced.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"advanced.d.cts","names":[],"sources":["../src/react/SelectionOverlaySlot.tsx","../src/react/WidgetSlot.tsx","../src/react/webgl/WebGLWidgetLayer.tsx","../src/react/webgl/WebGLWidgetSlot.tsx","../src/serialization.ts"],"mappings":";;;;;;;UAMU,yBAAA;EACT,QAAA,EAAU,QAAA;EACV,OAAA,GAAU,QAAA,EAAU,QAAA,EAAU,EAAA,EAAI,cAAA;AAAA;;;AARuB;;cAmB7C,oBAAA,EAGe,OAAA,CAHK,mBAAA;EAAA,QAAA;EAAA;AAAA,GAG9B,yBAAA,KAAyB,oBAAA,CAAA,GAAA,CAAA,OAAA;;;UCflB,eAAA;EACT,QAAA,EAAU,QAAA;EACV,OAAA,GAAU,QAAA,EAAU,QAAA,EAAU,EAAA,EAAI,cAAA;AAAA;AAAA,cAOtB,UAAA,EAA4E,OAAA,CAAlE,mBAAA;EAAA,QAAA;EAAA;AAAA,GAAmD,eAAA,KAAe,oBAAA,CAAA,GAAA,CAAA,OAAA;;;UCgG/E,qBAAA;EACT,MAAA,EAAQ,YAAA;EACR,QAAA,EAAU,QAAA;EACV,OAAA,GAAU,QAAA,EAAU,QAAA,KAAa,cAAA;AAAA;AAAA,iBAGlB,gBAAA,CAAA;EAAmB,MAAA;EAAQ,QAAA;EAAU;AAAA,GAAW,qBAAA,GAAqB,oBAAA,CAAA,GAAA,CAAA,OAAA;;;UC7G3E,oBAAA;EACT,QAAA,EAAU,QAAA;EACV,SAAA,EAAW,KAAA,CAAM,aAAA,CAAc,cAAA;AAAA;;AHX0B;;;;iBGmB1C,eAAA,CAAA;EAAkB,QAAA;EAAU,SAAA,EAAW;AAAA,GAAmB,oBAAA,GAAoB,oBAAA,CAAA,GAAA,CAAA,OAAA;;;;UCZ7E,cAAA;EAChB,OAAA;EACA,QAAA,EAAU,gBAAA;EACV,SAAA;IACC,MAAA;MAAU,CAAA;MAAW,CAAA;MAAW,IAAA;IAAA;IAChC,eAAA,EAAiB,eAAA;EAAA;AAAA;;UAKF,gBAAA;EAChB,EAAA,EAAI,QAAA;EACJ,UAAA,EAAY,MAAA;EACZ,IAAA;AAAA;;;;AJDD;iBIUgB,cAAA,CACf,KAAA,EAAO,KAAA,EACP,cAAA,EAAgB,aAAA,IAChB,QAAA,EAAU,OAAA,IACV,MAAA;EAAU,CAAA;EAAW,CAAA;EAAW,IAAA;AAAA,GAChC,gBAAA,EAAkB,eAAA,KAChB,cAAA;;;;;iBA6Ca,gBAAA,CACf,KAAA,EAAO,KAAA,EACP,GAAA,EAAK,cAAA,EACL,cAAA,EAAgB,aAAA,IAChB,QAAA,EAAU,OAAA;;;;;iBAsEK,iBAAA,CACf,KAAA,EAAO,KAAA,EACP,SAAA,EAAW,QAAA,IACX,cAAA,EAAgB,aAAA,IAChB,QAAA,EAAU,OAAA,KACR,gBAAA"}
+{"version":3,"file":"advanced.d.cts","names":[],"sources":["../src/ecs/serialization.ts","../src/react/overlays/SelectionOverlaySlot.tsx","../src/react/widgets/WidgetSlot.tsx","../src/webgl/WebGLManager.ts","../src/r3f/ProfilerProbe.tsx","../src/r3f/R3FManager.tsx"],"mappings":"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"}