@jamesyong42/infinite-canvas 1.2.0 → 1.3.0

package/dist/{hooks-DHShH86C.cjs → ecs-B4QrqfvQ.cjs}

@@ -1,7 +1,7 @@
-require("./WebGLWidgetLayer-BBMuwzHq.cjs");
+require("./hooks-CtP02JNt.cjs");
 let _jamesyong42_reactive_ecs = require("@jamesyong42/reactive-ecs");
 let react = require("react");
-//#region src/components.ts
+//#region src/ecs/components.ts
 /** Position, size, and rotation of an entity in local coordinates (world units). */
 const Transform2D = (0, _jamesyong42_reactive_ecs.defineComponent)("Transform2D", {
 	x: 0,
@@ -10,19 +10,57 @@ const Transform2D = (0, _jamesyong42_reactive_ecs.defineComponent)("Transform2D"
 	height: 100,
 	rotation: 0
 });
-/** Computed world-space bounding box. Read-only -- updated by the transform propagation system. */
-const WorldBounds = (0, _jamesyong42_reactive_ecs.defineComponent)("WorldBounds", {
-	worldX: 0,
-	worldY: 0,
-	worldWidth: 0,
-	worldHeight: 0
-});
 /** Rendering and hit-test ordering. Higher values render on top. */
 const ZIndex = (0, _jamesyong42_reactive_ecs.defineComponent)("ZIndex", { value: 0 });
-/** Parent entity reference. Used for nested containers and handle sync. */
-const Parent = (0, _jamesyong42_reactive_ecs.defineComponent)("Parent", { id: 0 });
+/**
+* Generic animated transition of `Transform2D.x` / `.y` over time.
+* Runtime-only: the tween component is auto-removed on completion,
+* and in-flight tweens are not serialized (the destination Transform2D
+* is what survives a save/load).
+*
+* Introduced for RFC-004 Phase 4 fly-back but designed to be reusable
+* for any future position-animation need (snap, drop-in, consume-pop).
+* Starting a new tween on an entity that already has one overwrites.
+*/
+const TransformTween = (0, _jamesyong42_reactive_ecs.defineComponent)("TransformTween", {
+	fromX: 0,
+	fromY: 0,
+	toX: 0,
+	toY: 0,
+	/** `performance.now()`-ish timestamp captured at tween start. */
+	startMs: 0,
+	/** Total duration in ms. */
+	durationMs: 250,
+	easing: "ease-out",
+	/**
+	* Discriminator so downstream systems can react per kind
+	* (e.g. `'flyback'`, `'snap'`, `'spawn'`). The tween system
+	* itself is kind-agnostic.
+	*/
+	kind: "generic"
+});
+/**
+* Container-hierarchy parenthood: the entity lives inside another
+* entity's sub-canvas. Read by `navigationFilterSystem` to filter the
+* active widget set by the current navigation frame.
+*
+* Container children have their own `Transform2D` in the container's
+* local coord space — **no coord accumulation** through this reference.
+* Replaces the old `Parent` component's container-hierarchy usage
+* (RFC-005).
+*/
+const ParentFrame = (0, _jamesyong42_reactive_ecs.defineComponent)("ParentFrame", { id: 0 });
 /** Child entity IDs. Used for nested containers and handle sync. */
 const Children = (0, _jamesyong42_reactive_ecs.defineComponent)("Children", { ids: [] });
+/**
+* Ordered list of the entities a container owns (RFC-004 § Phase 5).
+* Redundant with `ParentFrame` (the inverse relation) but materialised
+* so UI / compositor paths can cheaply read "give me this container's
+* children" without a reverse-index scan. `applyMutation` /
+* `revertMutation` keep the two in sync. Serialized; IDs are remapped
+* alongside `ParentFrame` on load.
+*/
+const ContainerChildren = (0, _jamesyong42_reactive_ecs.defineComponent)("ContainerChildren", { ids: [] });
 /** Marks an entity as a renderable widget with a type identifier and rendering surface. */
 const Widget = (0, _jamesyong42_reactive_ecs.defineComponent)("Widget", {
 	surface: "dom",
@@ -37,38 +75,100 @@ const WidgetBreakpoint = (0, _jamesyong42_reactive_ecs.defineComponent)("WidgetB
 	screenHeight: 0
 });
 /**
-* Marks an entity as an iOS-style card with a fixed preset size.
-* The `cardSystem` reconciles `Transform2D.width/height` from the preset
-* each tick, so cards cannot be resized freely — change `preset` instead.
+* Marks an entity as an iOS-style card with a fixed preset size, AND
+* opts the entity into the full card-shaped behavior bundle:
+*
+*   - DOM `<CardChrome>` slot (rounded body, hairline ring, shadow,
+*     CSS lift transition on Dragging)
+*   - drag-promote to the 'overlay' layer for DOM cards (so dragged
+*     DOM cards visually pop above the R3F canvas)
+*   - composition discard rect for R3F cards (so other R3F widgets
+*     are clipped out of the dragged card's screen rect — defends
+*     the chrome from being painted over)
+*   - drop-to-consume contracts (`accepts` / `provides`) — RFC-004.
+*
+* Widgets *without* `Card` get none of this — they render bare (no
+* chrome, no lift transition), and on drag they only get the
+* compositor's renderOrder bump if they're R3F (so they stack on
+* top of other R3F widgets they overlap).
+*
+* The `cardSystem` reconciles `Transform2D.width/height` from the
+* preset each tick, so cards cannot be resized freely — change
+* `preset` instead.
+*/
+const Card = (0, _jamesyong42_reactive_ecs.defineComponent)("Card", {
+	preset: "small",
+	/**
+	* CSS background for the chrome's surface (any valid background value;
+	* defaults to the dark iOS card colour). Picked up by the
+	* `<CardChrome>` component rendered for this entity.
+	*/
+	background: "#1C1C1E",
+	/**
+	* Drop-to-consume contract — what this card accepts as a *parent*.
+	* An incoming dragged card's `provides` must intersect this list
+	* for the consume mechanic to fire (RFC-004 § Phase 3). Empty
+	* array = card never consumes anything.
+	*/
+	accepts: [],
+	/**
+	* Drop-to-consume contract — what this card offers when dropped
+	* as a *child*. Empty array = card is never consumed by anything.
+	*/
+	provides: []
+});
+/**
+* Transient — set by the card-overlap pass on every card whose AABB
+* intersects the dragged card's AABB during drag. Layer 1 of the
+* two-layer overlap visual state (RFC-004 § Phase 3). Cleared on drag
+* end. Runtime-only — not serialized.
 */
-const Card = (0, _jamesyong42_reactive_ecs.defineComponent)("Card", { preset: "small" });
+const OverlapCandidate = (0, _jamesyong42_reactive_ecs.defineTag)("OverlapCandidate");
+/**
+* Transient — set on the single primary candidate (closest centre
+* distance) iff its `accepts` contract intersects the dragged card's
+* `provides` contract AND the optional `canAccept` gate passes.
+* Layer 2 of the two-layer overlap visual state. Cleared on drag end
+* or when match becomes false. Runtime-only — not serialized.
+*/
+const OverlapTarget = (0, _jamesyong42_reactive_ecs.defineTag)("OverlapTarget");
+/**
+* Per-candidate "hot point" for the position-dependent radial glow
+* (RFC-004 § Phase 3). `x` and `y` are normalized [0..1] local coords
+* within the overlapped card, pointing at the intersection centroid.
+* `strength` ramps between 0 and 1 for the fade-in / fade-out.
+* Runtime-only — not serialized.
+*/
+const CardOverlapHotPoint = (0, _jamesyong42_reactive_ecs.defineComponent)("CardOverlapHotPoint", {
+	x: .5,
+	y: .5,
+	strength: 0
+});
 /** Marks an entity as an enterable container (double-click/double-tap to enter). */
 const Container = (0, _jamesyong42_reactive_ecs.defineComponent)("Container", { enterable: true });
 /**
-* Rectangular interactable region anchored relative to the parent entity's WorldBounds.
-* Anchor values are in 0..1 space: 0 = parent min edge, 1 = parent max edge.
-* Widget bodies do NOT need Hitbox — their WorldBounds is already their hit area.
-* Hitbox is only for sub-entities (handles, ports) whose position is parent-relative.
+* Per-container persistent camera state. When the user navigates out of
+* a container, their current pan/zoom is snapshotted here; when they
+* navigate back in, it's restored. Serialized — containers remember
+* their view across save/load (RFC-004 § Phase 0c).
 */
-const Hitbox = (0, _jamesyong42_reactive_ecs.defineComponent)("Hitbox", {
-	anchorX: 0,
-	anchorY: 0,
-	width: 0,
-	height: 0
+const ContainerCamera = (0, _jamesyong42_reactive_ecs.defineComponent)("ContainerCamera", {
+	x: 0,
+	y: 0,
+	zoom: 1
 });
 /**
 * Declares what happens when this entity is hit, plus its hit-test priority.
-* Canonical layers: 0=canvas, 5=widget body, 10=edge handles, 15=corner handles, 20=reserved.
+* Canonical layers: 0=canvas, 5=widget body, 20=reserved.
+*
+* Resize corner/edge roles are emitted inline by `interaction.ts` from the
+* selected `Resizable` widget's Transform2D; they are NOT stored as
+* per-handle entities (RFC-005).
 */
 const InteractionRole = (0, _jamesyong42_reactive_ecs.defineComponent)("InteractionRole", {
 	layer: 0,
 	role: { type: "canvas" }
 });
-/**
-* Component on the parent entity listing the EntityIds of its spawned handle children.
-* Enables O(1) cascade destroy without a reverse-index scan of Parent components.
-*/
-const HandleSet = (0, _jamesyong42_reactive_ecs.defineComponent)("HandleSet", { ids: [] });
 /** Declares the cursor this entity requests when hovered and when active. */
 const CursorHint = (0, _jamesyong42_reactive_ecs.defineComponent)("CursorHint", {
 	hover: "default",
@@ -80,6 +180,32 @@ const Selectable = (0, _jamesyong42_reactive_ecs.defineTag)("Selectable");
 const Draggable = (0, _jamesyong42_reactive_ecs.defineTag)("Draggable");
 /** Marks an entity as resizable via edge/corner handles. */
 const Resizable = (0, _jamesyong42_reactive_ecs.defineTag)("Resizable");
+/**
+* Marks an entity that, when dragged, runs alignment-snap math against
+* the set of `SnapTarget` entities. Without this tag, dragging proceeds
+* with raw pointer deltas (no snapping). Independent of `SnapTarget`:
+* an entity can be a source without being a target (rare) or a target
+* without being a source (e.g. cards — they participate as references
+* for other widgets but never snap themselves).
+*
+* Multi-select drag: only the first selected entity's bounds drive the
+* snap calculation; followers receive the same correction delta. Tag a
+* follower-only entity with `SnapSource` if you also want it to lead a
+* single-entity drag, but be aware its geometry is ignored when it is
+* being dragged as part of a multi-select group.
+*/
+const SnapSource = (0, _jamesyong42_reactive_ecs.defineTag)("SnapSource");
+/**
+* Marks an entity whose bounds are usable as a snap reference when
+* another `SnapSource` entity is being dragged. References are further
+* filtered by `Active`, so only entities in the current navigation
+* frame can pull a drag — a `SnapTarget` inside a closed container
+* does not leak into a root-level drag. Visibility of the resulting
+* guide lines is controlled separately by the engine's
+* `snap.guidesVisible` config — this tag only governs participation
+* in the math.
+*/
+const SnapTarget = (0, _jamesyong42_reactive_ecs.defineTag)("SnapTarget");
 /** Prevents an entity from being moved or resized. */
 const Locked = (0, _jamesyong42_reactive_ecs.defineTag)("Locked");
 /** Indicates the entity is currently selected. */
@@ -101,18 +227,41 @@ const SelectionFrame = (0, _jamesyong42_reactive_ecs.defineTag)("SelectionFrame"
 const Active = (0, _jamesyong42_reactive_ecs.defineTag)("Active");
 /** Indicates the entity is within the visible viewport. Set by the cull system. */
 const Visible = (0, _jamesyong42_reactive_ecs.defineTag)("Visible");
+/**
+* Indicates the entity is `Active` but **outside** the visible viewport
+* (+overscan). The complement of `Visible` for Active entities — the cull
+* system maintains the invariant that every Active entity carries exactly
+* one of `Visible` or `Culled`.
+*
+* Render layers consume this to keep state cached without rendering: DOM
+* widgets may stay mounted-but-hidden for fast re-reveal, and the R3F
+* compositor (RFC-002) holds widget render targets in its Cold pool.
+*/
+const Culled = (0, _jamesyong42_reactive_ecs.defineTag)("Culled");
+const Layer = (0, _jamesyong42_reactive_ecs.defineComponent)("Layer", { name: "base" });
+const PreDragLayer = (0, _jamesyong42_reactive_ecs.defineComponent)("PreDragLayer", { name: "base" });
 //#endregion
-//#region src/resources.ts
+//#region src/ecs/resources.ts
 /**
 * Output sink for the cursor system. Written by cursorSystem each tick;
 * read by the RAF loop to apply style.cursor on the root container div.
 */
 const CursorResource = (0, _jamesyong42_reactive_ecs.defineResource)("Cursor", { cursor: "default" });
-/** Camera state: world-space position (x, y) and zoom level. Updated by pan/zoom gestures. */
+/**
+* Camera state: world-space position (x, y) and zoom level.
+*
+* `gesturing` is true while the user is actively manipulating the camera
+* (continuous wheel zoom, pinch, two-finger pan). Set/cleared by gesture
+* handlers via {@link LayoutEngine.setGesturing}; render layers can use it
+* to defer expensive work (e.g. the R3F compositor skips zoom-band
+* repaints while gesturing so a continuous pinch doesn't trigger a
+* repaint storm across every visible widget).
+*/
 const CameraResource = (0, _jamesyong42_reactive_ecs.defineResource)("Camera", {
 	x: 0,
 	y: 0,
-	zoom: 1
+	zoom: 1,
+	gesturing: false
 });
 /** Viewport dimensions in CSS pixels and device pixel ratio. Updated on resize. */
 const ViewportResource = (0, _jamesyong42_reactive_ecs.defineResource)("Viewport", {
@@ -132,57 +281,77 @@ const BreakpointConfigResource = (0, _jamesyong42_reactive_ecs.defineResource)("
 	normal: 500,
 	expanded: 1200
 });
-/** Navigation stack for hierarchical container traversal. */
+/**
+* Navigation stack for hierarchical container traversal. Always has at
+* least one frame (the root). The last element is the current frame;
+* `containerId === null` means the user is at the root canvas.
+*
+* Runtime-only view state — deliberately not serialized, so reloading a
+* saved canvas always drops the user at the root frame (RFC-004 § Phase 0c).
+*/
 const NavigationStackResource = (0, _jamesyong42_reactive_ecs.defineResource)("NavigationStack", {
-	frames: [{
-		containerId: null,
-		camera: {
-			x: 0,
-			y: 0,
-			zoom: 1
-		}
-	}],
+	frames: [{ containerId: null }],
 	changed: false
 });
 /**
+* Camera state for the root canvas. Persisted (serialized) so the root
+* view returns to its previous pan/zoom across navigation push/pop and
+* across save/load. Container frames use the `ContainerCamera` component
+* on the container entity instead (RFC-004 § Phase 0c).
+*/
+const RootCameraResource = (0, _jamesyong42_reactive_ecs.defineResource)("RootCamera", {
+	x: 0,
+	y: 0,
+	zoom: 1
+});
+/**
+* Built-in card preset sizes (iOS widget conventions — 155×155 tile).
+* Single source of truth consumed by:
+*   - {@link CardPresetsResource} — runtime lookup by the cardSystem.
+*   - `createCardWidget` / `createGeometryCardWidget` — widget-registration-
+*     time `defaultSize`, which must be known before the engine is built.
+*/
+const DEFAULT_CARD_PRESET_SIZES = {
+	small: {
+		width: 155,
+		height: 155
+	},
+	medium: {
+		width: 329,
+		height: 155
+	},
+	large: {
+		width: 329,
+		height: 345
+	},
+	xl: {
+		width: 329,
+		height: 535
+	}
+};
+/**
 * iOS-style card preset size map. Lookup happens by `Card.preset`; the
 * `cardSystem` stamps `Transform2D.width/height` from the resolved size.
 *
-* Defaults mirror iOS widget conventions — 155×155 tile + 19px gap.
 * Override at `createLayoutEngine({ cardPresets })` for tablet-scale or
 * custom design systems.
 */
 const CardPresetsResource = (0, _jamesyong42_reactive_ecs.defineResource)("CardPresets", {
-	presets: {
-		small: {
-			width: 155,
-			height: 155
-		},
-		medium: {
-			width: 329,
-			height: 155
-		},
-		large: {
-			width: 329,
-			height: 345
-		},
-		xl: {
-			width: 329,
-			height: 535
-		}
-	},
+	presets: { ...DEFAULT_CARD_PRESET_SIZES },
 	/** Gap between adjacent tiles (future tile-snap system reads this). */
 	gap: 19
 });
+/** ECS resource holding the SpatialIndex instance for viewport culling and hit testing. */
+const SpatialIndexResource = (0, _jamesyong42_reactive_ecs.defineResource)("SpatialIndex", { instance: null });
+const LayerOrderResource = (0, _jamesyong42_reactive_ecs.defineResource)("LayerOrder", { layers: [
+	"background",
+	"base",
+	"overlay"
+] });
 //#endregion
-//#region src/react/context.ts
+//#region src/react/context/engine-context.ts
 const EngineContext = (0, react.createContext)(null);
 const EngineProvider = EngineContext.Provider;
-const ContainerRefContext = (0, react.createContext)(null);
-const ContainerRefProvider = ContainerRefContext.Provider;
-function useContainerRef() {
-	return (0, react.useContext)(ContainerRefContext);
-}
 /**
 * Returns the LayoutEngine instance from the nearest InfiniteCanvas context.
 * Throws if used outside an InfiniteCanvas provider.
@@ -192,13 +361,8 @@ function useLayoutEngine() {
 	if (!engine) throw new Error("useLayoutEngine must be used within an <InfiniteCanvas>");
 	return engine;
 }
-const WidgetResolverContext = (0, react.createContext)(null);
-const WidgetResolverProvider = WidgetResolverContext.Provider;
-function useWidgetResolver() {
-	return (0, react.useContext)(WidgetResolverContext);
-}
 //#endregion
-//#region src/react/hooks.ts
+//#region src/react/hooks/ecs.ts
 function shallowEqual(a, b) {
 	const keysA = Object.keys(a);
 	const keysB = Object.keys(b);
@@ -445,6 +609,12 @@ Object.defineProperty(exports, "Card", {
 		return Card;
 	}
 });
+Object.defineProperty(exports, "CardOverlapHotPoint", {
+	enumerable: true,
+	get: function() {
+		return CardOverlapHotPoint;
+	}
+});
 Object.defineProperty(exports, "CardPresetsResource", {
 	enumerable: true,
 	get: function() {
@@ -463,10 +633,22 @@ Object.defineProperty(exports, "Container", {
 		return Container;
 	}
 });
-Object.defineProperty(exports, "ContainerRefProvider", {
+Object.defineProperty(exports, "ContainerCamera", {
 	enumerable: true,
 	get: function() {
-		return ContainerRefProvider;
+		return ContainerCamera;
+	}
+});
+Object.defineProperty(exports, "ContainerChildren", {
+	enumerable: true,
+	get: function() {
+		return ContainerChildren;
+	}
+});
+Object.defineProperty(exports, "Culled", {
+	enumerable: true,
+	get: function() {
+		return Culled;
 	}
 });
 Object.defineProperty(exports, "CursorHint", {
@@ -481,6 +663,12 @@ Object.defineProperty(exports, "CursorResource", {
 		return CursorResource;
 	}
 });
+Object.defineProperty(exports, "DEFAULT_CARD_PRESET_SIZES", {
+	enumerable: true,
+	get: function() {
+		return DEFAULT_CARD_PRESET_SIZES;
+	}
+});
 Object.defineProperty(exports, "Draggable", {
 	enumerable: true,
 	get: function() {
@@ -499,22 +687,22 @@ Object.defineProperty(exports, "EngineProvider", {
 		return EngineProvider;
 	}
 });
-Object.defineProperty(exports, "HandleSet", {
+Object.defineProperty(exports, "InteractionRole", {
 	enumerable: true,
 	get: function() {
-		return HandleSet;
+		return InteractionRole;
 	}
 });
-Object.defineProperty(exports, "Hitbox", {
+Object.defineProperty(exports, "Layer", {
 	enumerable: true,
 	get: function() {
-		return Hitbox;
+		return Layer;
 	}
 });
-Object.defineProperty(exports, "InteractionRole", {
+Object.defineProperty(exports, "LayerOrderResource", {
 	enumerable: true,
 	get: function() {
-		return InteractionRole;
+		return LayerOrderResource;
 	}
 });
 Object.defineProperty(exports, "Locked", {
@@ -529,10 +717,28 @@ Object.defineProperty(exports, "NavigationStackResource", {
 		return NavigationStackResource;
 	}
 });
-Object.defineProperty(exports, "Parent", {
+Object.defineProperty(exports, "OverlapCandidate", {
 	enumerable: true,
 	get: function() {
-		return Parent;
+		return OverlapCandidate;
+	}
+});
+Object.defineProperty(exports, "OverlapTarget", {
+	enumerable: true,
+	get: function() {
+		return OverlapTarget;
+	}
+});
+Object.defineProperty(exports, "ParentFrame", {
+	enumerable: true,
+	get: function() {
+		return ParentFrame;
+	}
+});
+Object.defineProperty(exports, "PreDragLayer", {
+	enumerable: true,
+	get: function() {
+		return PreDragLayer;
 	}
 });
 Object.defineProperty(exports, "Resizable", {
@@ -541,6 +747,12 @@ Object.defineProperty(exports, "Resizable", {
 		return Resizable;
 	}
 });
+Object.defineProperty(exports, "RootCameraResource", {
+	enumerable: true,
+	get: function() {
+		return RootCameraResource;
+	}
+});
 Object.defineProperty(exports, "Selectable", {
 	enumerable: true,
 	get: function() {
@@ -559,12 +771,36 @@ Object.defineProperty(exports, "SelectionFrame", {
 		return SelectionFrame;
 	}
 });
+Object.defineProperty(exports, "SnapSource", {
+	enumerable: true,
+	get: function() {
+		return SnapSource;
+	}
+});
+Object.defineProperty(exports, "SnapTarget", {
+	enumerable: true,
+	get: function() {
+		return SnapTarget;
+	}
+});
+Object.defineProperty(exports, "SpatialIndexResource", {
+	enumerable: true,
+	get: function() {
+		return SpatialIndexResource;
+	}
+});
 Object.defineProperty(exports, "Transform2D", {
 	enumerable: true,
 	get: function() {
 		return Transform2D;
 	}
 });
+Object.defineProperty(exports, "TransformTween", {
+	enumerable: true,
+	get: function() {
+		return TransformTween;
+	}
+});
 Object.defineProperty(exports, "ViewportResource", {
 	enumerable: true,
 	get: function() {
@@ -595,18 +831,6 @@ Object.defineProperty(exports, "WidgetData", {
 		return WidgetData;
 	}
 });
-Object.defineProperty(exports, "WidgetResolverProvider", {
-	enumerable: true,
-	get: function() {
-		return WidgetResolverProvider;
-	}
-});
-Object.defineProperty(exports, "WorldBounds", {
-	enumerable: true,
-	get: function() {
-		return WorldBounds;
-	}
-});
 Object.defineProperty(exports, "ZIndex", {
 	enumerable: true,
 	get: function() {
@@ -637,12 +861,6 @@ Object.defineProperty(exports, "useComponent", {
 		return useComponent;
 	}
 });
-Object.defineProperty(exports, "useContainerRef", {
-	enumerable: true,
-	get: function() {
-		return useContainerRef;
-	}
-});
 Object.defineProperty(exports, "useEntityComponents", {
 	enumerable: true,
 	get: function() {
@@ -697,11 +915,5 @@ Object.defineProperty(exports, "useTaggedEntities", {
 		return useTaggedEntities;
 	}
 });
-Object.defineProperty(exports, "useWidgetResolver", {
-	enumerable: true,
-	get: function() {
-		return useWidgetResolver;
-	}
-});
 
-//# sourceMappingURL=hooks-DHShH86C.cjs.map
+//# sourceMappingURL=ecs-B4QrqfvQ.cjs.map