@jamesyong42/infinite-canvas 1.2.0 → 1.4.0

package/dist/index-DSdbSQ_t.d.cts

@@ -0,0 +1,1451 @@
+import * as _$_jamesyong42_reactive_ecs0 from "@jamesyong42/reactive-ecs";
+import { ComponentInit, ComponentType, EntityId, SystemDef, TagType, Unsubscribe, World } from "@jamesyong42/reactive-ecs";
+
+//#region src/ecs/components.d.ts
+/** Position, size, and rotation of an entity in local coordinates (world units). */
+declare const Transform2D: _$_jamesyong42_reactive_ecs0.ComponentType<{
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  rotation: number;
+}>;
+/** Rendering and hit-test ordering. Higher values render on top. */
+declare const ZIndex: _$_jamesyong42_reactive_ecs0.ComponentType<{
+  value: number;
+}>;
+/** Easing curves supported by `transformTweenSystem` (RFC-004 § Phase 2). */
+type TweenEasing = 'linear' | 'ease-out' | 'ease-in-out' | 'spring';
+/**
+ * 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.
+ */
+declare const TransformTween: _$_jamesyong42_reactive_ecs0.ComponentType<{
+  fromX: number;
+  fromY: number;
+  toX: number;
+  toY: number; /** `performance.now()`-ish timestamp captured at tween start. */
+  startMs: number; /** Total duration in ms. */
+  durationMs: number;
+  easing: TweenEasing;
+  /**
+   * Discriminator so downstream systems can react per kind
+   * (e.g. `'flyback'`, `'snap'`, `'spawn'`). The tween system
+   * itself is kind-agnostic.
+   */
+  kind: string;
+}>;
+/**
+ * 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).
+ */
+declare const ParentFrame: _$_jamesyong42_reactive_ecs0.ComponentType<{
+  id: EntityId;
+}>;
+/** Child entity IDs. Used for nested containers and handle sync. */
+declare const Children: _$_jamesyong42_reactive_ecs0.ComponentType<{
+  ids: EntityId[];
+}>;
+/**
+ * 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.
+ */
+declare const ContainerChildren: _$_jamesyong42_reactive_ecs0.ComponentType<{
+  ids: EntityId[];
+}>;
+/** Marks an entity as a renderable widget with a type identifier and rendering surface. */
+declare const Widget$1: _$_jamesyong42_reactive_ecs0.ComponentType<{
+  surface: "dom" | "webgl" | "webview";
+  type: string;
+}>;
+/** Arbitrary application data attached to a widget entity. Access via useWidgetData(). */
+declare const WidgetData: _$_jamesyong42_reactive_ecs0.ComponentType<{
+  data: Record<string, unknown>;
+}>;
+/** Computed responsive breakpoint based on screen-space size. Read-only. */
+declare const WidgetBreakpoint: _$_jamesyong42_reactive_ecs0.ComponentType<{
+  current: "micro" | "compact" | "normal" | "expanded" | "detailed";
+  screenWidth: number;
+  screenHeight: number;
+}>;
+/** iOS-style card size presets. Actual dimensions live in CardPresetsResource. */
+type CardPreset = 'small' | 'medium' | 'large' | 'xl';
+/**
+ * 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.
+ */
+declare const Card: _$_jamesyong42_reactive_ecs0.ComponentType<{
+  preset: CardPreset;
+  /**
+   * 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: string;
+  /**
+   * 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: readonly string[];
+  /**
+   * Drop-to-consume contract — what this card offers when dropped
+   * as a *child*. Empty array = card is never consumed by anything.
+   */
+  provides: readonly string[];
+}>;
+/**
+ * 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.
+ */
+declare const OverlapCandidate: _$_jamesyong42_reactive_ecs0.TagType;
+/**
+ * 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.
+ */
+declare const OverlapTarget: _$_jamesyong42_reactive_ecs0.TagType;
+/**
+ * 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.
+ */
+declare const CardOverlapHotPoint: _$_jamesyong42_reactive_ecs0.ComponentType<{
+  x: number;
+  y: number;
+  strength: number;
+}>;
+/** Marks an entity as an enterable container (double-click/double-tap to enter). */
+declare const Container: _$_jamesyong42_reactive_ecs0.ComponentType<{
+  enterable: boolean;
+}>;
+/**
+ * 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).
+ */
+declare const ContainerCamera: _$_jamesyong42_reactive_ecs0.ComponentType<{
+  x: number;
+  y: number;
+  zoom: number;
+}>;
+/** Resize handle positions — 4 edges + 4 corners. */
+type ResizeHandlePos = 'n' | 's' | 'e' | 'w' | 'ne' | 'nw' | 'se' | 'sw';
+/** Discriminated union of interaction roles an entity can fulfil. */
+type InteractionRoleType = {
+  type: 'drag';
+} | {
+  type: 'select';
+} | {
+  type: 'resize';
+  handle: ResizeHandlePos;
+} | {
+  type: 'rotate';
+} | {
+  type: 'connect';
+} | {
+  type: 'canvas';
+};
+type InteractionRoleData = {
+  /** Hit-test priority — higher wins when multiple entities contain the point. */layer: number; /** Discriminated role + role-specific data. */
+  role: InteractionRoleType;
+};
+/**
+ * Declares what happens when this entity is hit, plus its hit-test priority.
+ * 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).
+ */
+declare const InteractionRole: _$_jamesyong42_reactive_ecs0.ComponentType<InteractionRoleData>;
+/** CSS cursor values the canvas may request. */
+type CSSCursor = 'default' | 'grab' | 'grabbing' | 'crosshair' | 'n-resize' | 's-resize' | 'e-resize' | 'w-resize' | 'ne-resize' | 'nw-resize' | 'se-resize' | 'sw-resize';
+type CursorHintData = {
+  /** Cursor when this entity is hovered in idle state. */hover: CSSCursor; /** Cursor while this entity is being dragged/resized. */
+  active: CSSCursor;
+};
+/** Declares the cursor this entity requests when hovered and when active. */
+declare const CursorHint: _$_jamesyong42_reactive_ecs0.ComponentType<CursorHintData>;
+/** Marks an entity as selectable by click or marquee. */
+declare const Selectable: _$_jamesyong42_reactive_ecs0.TagType;
+/** Marks an entity as draggable via pointer interaction. */
+declare const Draggable: _$_jamesyong42_reactive_ecs0.TagType;
+/** Marks an entity as resizable via edge/corner handles. */
+declare const Resizable: _$_jamesyong42_reactive_ecs0.TagType;
+/**
+ * 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.
+ */
+declare const SnapSource: _$_jamesyong42_reactive_ecs0.TagType;
+/**
+ * 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.
+ */
+declare const SnapTarget: _$_jamesyong42_reactive_ecs0.TagType;
+/** Prevents an entity from being moved or resized. */
+declare const Locked: _$_jamesyong42_reactive_ecs0.TagType;
+/** Indicates the entity is currently selected. */
+declare const Selected: _$_jamesyong42_reactive_ecs0.TagType;
+/**
+ * Indicates the entity is currently being dragged by the user.
+ * Added after the drag dead-zone is crossed; removed on pointer up/cancel.
+ * Renderers read this to apply transient drag affordances (e.g. scale/shadow lift).
+ */
+declare const Dragging: _$_jamesyong42_reactive_ecs0.TagType;
+/**
+ * Entities with this tag get the engine-drawn selection + hover outline frame.
+ * Granted automatically to Selectable entities unless explicitly disabled via
+ * `Archetype.interactive.selectionFrame: false`. Widgets that render their own
+ * selected/hover chrome (e.g. iOS-style cards) opt out.
+ */
+declare const SelectionFrame: _$_jamesyong42_reactive_ecs0.TagType;
+/** Indicates the entity is currently being interacted with (drag, resize). */
+declare const Active: _$_jamesyong42_reactive_ecs0.TagType;
+/** Indicates the entity is within the visible viewport. Set by the cull system. */
+declare const Visible: _$_jamesyong42_reactive_ecs0.TagType;
+/**
+ * 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.
+ */
+declare const Culled: _$_jamesyong42_reactive_ecs0.TagType;
+/**
+ * Named DOM stacking layer a widget renders into. Three layers are
+ * rendered out of the box by `<InfiniteCanvas>`:
+ *
+ *   `'background'` — DOM widgets behind everything user-content.
+ *   `'base'`       — default; DOM widgets and R3F card chrome.
+ *   `'overlay'`    — DOM widgets and R3F chrome promoted above the R3F
+ *                    canvas (e.g. dragged widget, future tooltips).
+ *
+ * Per-widget `ZIndex` continues to control intra-layer ordering;
+ * `Layer.name` picks which layer container the widget mounts into.
+ *
+ * R3F widgets always render through the R3F canvas regardless of layer
+ * — `Layer.name` only controls where their CSS chrome / interaction
+ * surface mounts.
+ */
+type LayerName = 'background' | 'base' | 'overlay';
+type LayerData = {
+  name: LayerName;
+};
+declare const Layer: _$_jamesyong42_reactive_ecs0.ComponentType<LayerData>;
+//#endregion
+//#region src/ecs/math.d.ts
+interface Vec2 {
+  x: number;
+  y: number;
+}
+interface Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+interface AABB {
+  minX: number;
+  minY: number;
+  maxX: number;
+  maxY: number;
+}
+/** Convert a Rect to AABB */
+declare function rectToAABB(r: Rect): AABB;
+/** Convert AABB to Rect */
+declare function aabbToRect(a: AABB): Rect;
+/** Test if two AABBs overlap */
+declare function intersectsAABB(a: AABB, b: AABB): boolean;
+/** Test if a point is inside an AABB */
+declare function pointInAABB(px: number, py: number, a: AABB): boolean;
+/** Convert screen coordinates to world coordinates */
+declare function screenToWorld(screenX: number, screenY: number, camera: {
+  x: number;
+  y: number;
+  zoom: number;
+}): Vec2;
+/** Convert world coordinates to screen coordinates */
+declare function worldToScreen(worldX: number, worldY: number, camera: {
+  x: number;
+  y: number;
+  zoom: number;
+}): Vec2;
+/** Clamp a value between min and max */
+declare function clamp(value: number, min: number, max: number): number;
+//#endregion
+//#region src/ecs/spatial/SpatialIndex.d.ts
+interface SpatialEntry extends AABB {
+  entityId: EntityId;
+}
+/**
+ * Spatial index backed by an R-tree (rbush).
+ * Stores world-space AABBs for fast viewport culling and hit testing.
+ */
+declare class SpatialIndex {
+  private tree;
+  private entries;
+  upsert(entityId: EntityId, bounds: AABB): void;
+  remove(entityId: EntityId): void;
+  /** Query all entries intersecting the given AABB */
+  search(bounds: AABB): SpatialEntry[];
+  /** Find the topmost entity at a point (by z-order — caller sorts) */
+  searchPoint(x: number, y: number, tolerance?: number): SpatialEntry[];
+  clear(): void;
+  get size(): number;
+}
+//#endregion
+//#region src/ecs/resources.d.ts
+/**
+ * A single frame in the navigation stack. `containerId === null` is the
+ * root canvas; any other value is the entity id of the container whose
+ * sub-canvas the user is currently inside. Camera state lives on a
+ * `ContainerCamera` component per container (or `RootCameraResource`
+ * for the root frame), not in the stack itself — see RFC-004 § Phase 0c.
+ */
+interface NavigationFrame {
+  containerId: EntityId | null;
+}
+/** Data shape for the CursorResource. */
+type CursorResourceData = {
+  cursor: CSSCursor;
+};
+/**
+ * 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.
+ */
+declare const CursorResource: _$_jamesyong42_reactive_ecs0.ResourceType<CursorResourceData>;
+/**
+ * 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).
+ */
+declare const CameraResource: _$_jamesyong42_reactive_ecs0.ResourceType<{
+  x: number;
+  y: number;
+  zoom: number;
+  gesturing: boolean;
+}>;
+/** Viewport dimensions in CSS pixels and device pixel ratio. Updated on resize. */
+declare const ViewportResource: _$_jamesyong42_reactive_ecs0.ResourceType<{
+  width: number;
+  height: number;
+  dpr: number;
+}>;
+/** Minimum and maximum zoom levels. */
+declare const ZoomConfigResource: _$_jamesyong42_reactive_ecs0.ResourceType<{
+  min: number;
+  max: number;
+}>;
+/** Screen-space pixel thresholds for responsive breakpoints (micro/compact/normal/expanded/detailed). */
+declare const BreakpointConfigResource: _$_jamesyong42_reactive_ecs0.ResourceType<{
+  micro: number;
+  compact: number;
+  normal: number;
+  expanded: number;
+}>;
+/**
+ * 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).
+ */
+declare const NavigationStackResource: _$_jamesyong42_reactive_ecs0.ResourceType<{
+  frames: NavigationFrame[];
+  changed: boolean;
+}>;
+/** Shape shared by `ContainerCamera` components and `RootCameraResource`. */
+type FrameCameraState = {
+  x: number;
+  y: number;
+  zoom: number;
+};
+/**
+ * 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).
+ */
+declare const RootCameraResource: _$_jamesyong42_reactive_ecs0.ResourceType<FrameCameraState>;
+/** Responsive breakpoint name derived from a widget's screen-space size. */
+type Breakpoint = 'micro' | 'compact' | 'normal' | 'expanded' | 'detailed';
+/**
+ * iOS-style card preset size map. Lookup happens by `Card.preset`; the
+ * `cardSystem` stamps `Transform2D.width/height` from the resolved size.
+ *
+ * Override at `createLayoutEngine({ cardPresets })` for tablet-scale or
+ * custom design systems.
+ */
+declare const CardPresetsResource: _$_jamesyong42_reactive_ecs0.ResourceType<{
+  presets: {
+    small: {
+      width: number;
+      height: number;
+    };
+    medium: {
+      width: number;
+      height: number;
+    };
+    large: {
+      width: number;
+      height: number;
+    };
+    xl: {
+      width: number;
+      height: number;
+    };
+  }; /** Gap between adjacent tiles (future tile-snap system reads this). */
+  gap: number;
+}>;
+/** ECS resource holding the SpatialIndex instance for viewport culling and hit testing. */
+declare const SpatialIndexResource: _$_jamesyong42_reactive_ecs0.ResourceType<{
+  instance: SpatialIndex | null;
+}>;
+/**
+ * Render-layer order, low → high. `<InfiniteCanvas>` mounts a DOM
+ * container for each entry; widgets render into the container that
+ * matches their `Layer.name`. Per-widget `ZIndex` controls intra-layer
+ * ordering. RFC-003.
+ *
+ * Default: `['background', 'base', 'overlay']`. Out-of-the-box the
+ * three names map to fixed DOM positions in `<InfiniteCanvas>`'s
+ * stacking sandwich: background and base sit beneath the R3F canvas
+ * (zIndex < 1), overlay sits above it (zIndex 2). Custom layer names
+ * are not yet rendered by the default `<InfiniteCanvas>`.
+ */
+type LayerOrderData = {
+  layers: LayerName[];
+};
+declare const LayerOrderResource: _$_jamesyong42_reactive_ecs0.ResourceType<LayerOrderData>;
+//#endregion
+//#region src/ecs/spatial/snap.d.ts
+/**
+ * Snap guide computation for alignment during drag operations.
+ * Implements Figma-style snapping:
+ * 1. Edge/center alignment guides
+ * 2. Equal spacing snap + indicators
+ */
+interface SnapGuide {
+  /** Axis this guide aligns on */
+  axis: 'x' | 'y';
+  /** World-space coordinate of the alignment line */
+  position: number;
+  /** What kind of alignment */
+  type: 'edge' | 'center';
+}
+interface EqualSpacingIndicator {
+  /** Axis along which the equal gaps run */
+  axis: 'x' | 'y';
+  /** The equal gap value (world units) */
+  gap: number;
+  /** Pairs of (from, to) marking each equal gap segment */
+  segments: {
+    from: number;
+    to: number;
+  }[];
+  /** Position on the perpendicular axis (for rendering) */
+  perpPosition: number;
+}
+interface SnapResult {
+  /** Snap-corrected delta (world units). Apply to entity position. */
+  snapDx: number;
+  snapDy: number;
+  /** Active alignment guide lines to render */
+  guides: SnapGuide[];
+  /** Equal spacing indicators */
+  spacings: EqualSpacingIndicator[];
+}
+interface EntityBounds {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+/**
+ * Compute snap guides for a dragged entity against reference entities.
+ */
+declare function computeSnapGuides(dragged: EntityBounds, references: EntityBounds[], threshold: number): SnapResult;
+//#endregion
+//#region src/profiler/Profiler.d.ts
+/**
+ * Multi-layer performance profiler.
+ *
+ * Tracks three independent rendering concerns:
+ *
+ *   1. ECS tick — systems, visibility, entity counts. Driven by `engine.tick()`.
+ *   2. WebGL engine pass — the library's grid + selection renderers. Runs
+ *      inside the rAF loop immediately after each ECS tick, so samples share
+ *      the ECS ring and carry matched tick ids.
+ *   3. R3F canvas — the user's 3D widgets inside the shared `<Canvas>`. Runs
+ *      continuously at rAF cadence regardless of engine ticks, so it has its
+ *      own ring.
+ *
+ * All methods are no-ops when disabled — zero cost for production builds.
+ * User Timing API marks are emitted when enabled so traces line up with
+ * Chrome DevTools' Performance panel.
+ */
+interface TickSample {
+  tick: number;
+  timestamp: number;
+  /** Total tick duration (ms) = ECS tick + WebGL engine pass. */
+  totalMs: number;
+  ecs: {
+    /** Per-system durations (ms). */systems: Record<string, number>; /** Visible entity computation (ms). */
+    visibilityMs: number; /** Entity counts at this frame. */
+    entityCount: number;
+    visibleCount: number;
+  };
+  webgl: {
+    /** Grid renderer pass duration (ms). */gridMs: number; /** Selection + hover + snap-guide render pass duration (ms). */
+    selectionMs: number; /** Total `renderer.info.render.calls` across all passes this tick. */
+    drawCalls: number; /** Total `renderer.info.render.triangles` across all passes this tick. */
+    triangles: number; /** Selection frames drawn this tick. */
+    selectionFrames: number; /** Snap guides drawn this tick. */
+    snapGuides: number; /** Equal-spacing indicators drawn this tick. */
+    spacingIndicators: number; /** DOM slot.transform writes this tick (from changes.positionsChanged). */
+    domPositionsUpdated: number;
+  };
+}
+/** Per-phase widget count snapshot for the compositor state machine (RFC-002). */
+interface R3FPhaseHistogram {
+  hot: number;
+  warm: number;
+  cold: number;
+  waking: number;
+  dormant: number;
+}
+interface R3FSample {
+  timestamp: number;
+  /** Delta since the previous R3F frame (ms). */
+  dtMs: number;
+  /** three.js renderer.info snapshot. */
+  drawCalls: number;
+  triangles: number;
+  points: number;
+  lines: number;
+  programs: number;
+  geometries: number;
+  textures: number;
+  activeWidgets: number;
+  /**
+   * Number of per-widget FBO repaints this frame. Zero before the compositor
+   * lands (RFC-002 Phase 4); zero on idle frames once it has.
+   */
+  widgetsRepainted: number;
+  /** Total bytes consumed by the widget render-target pool. */
+  fboBytes: number;
+  /** Compositor state-machine phase histogram across all R3F widgets. */
+  phases: R3FPhaseHistogram;
+  /** GPU time spent on per-widget paints this frame (ms). Optional — populated only when timestamp queries are available (WebGL `WEBGL_timer_query` or WebGPU). */
+  gpuPaintMs?: number;
+  /** GPU time spent on the composition pass this frame (ms). Optional — same caveat as `gpuPaintMs`. */
+  gpuCompositeMs?: number;
+}
+interface FrameTimeStats {
+  avg: number;
+  p50: number;
+  p95: number;
+  p99: number;
+  max: number;
+}
+interface EcsStats {
+  fps: number;
+  frameTime: FrameTimeStats;
+  systemAvg: Record<string, number>;
+  systemP95: Record<string, number>;
+  /** Avg frame time as % of 16.67ms (60 fps). */
+  budgetUsed: number;
+  sampleCount: number;
+}
+interface WebGLStats {
+  /** Tick cadence — matches ECS since both fire together. */
+  fps: number;
+  /** Avg combined pass time (ms) and percentile breakdown. */
+  frameTime: FrameTimeStats;
+  /** Avg combined pass time as % of 16.67ms budget. */
+  budgetUsed: number;
+  gridAvg: number;
+  gridP95: number;
+  selectionAvg: number;
+  selectionP95: number;
+  avgDrawCalls: number;
+  avgTriangles: number;
+  avgSelectionFrames: number;
+  avgSnapGuides: number;
+  avgDomUpdates: number;
+  sampleCount: number;
+}
+interface R3FStats {
+  fps: number;
+  frameTime: FrameTimeStats;
+  avgDrawCalls: number;
+  avgTriangles: number;
+  /** Latest snapshots — these don't average meaningfully. */
+  programs: number;
+  geometries: number;
+  textures: number;
+  activeWidgets: number;
+  /** Avg per-widget repaints per frame across the sample window. */
+  avgWidgetsRepainted: number;
+  /** Latest FBO pool memory usage (bytes). */
+  fboBytes: number;
+  /** Latest phase histogram across the R3F widget set. */
+  phases: R3FPhaseHistogram;
+  /** Avg GPU paint time per frame (ms). Undefined if no samples carried timestamps. */
+  avgGpuPaintMs?: number;
+  /** Avg GPU composition time per frame (ms). */
+  avgGpuCompositeMs?: number;
+  sampleCount: number;
+}
+interface ProfilerStats {
+  ecs: EcsStats;
+  webgl: WebGLStats;
+  r3f: R3FStats;
+}
+/** What's being timed inside the library's WebGL engine pass. */
+type WebGLPass = 'grid' | 'selection' | 'snap-guides';
+declare class Profiler {
+  private enabled;
+  private tickRing;
+  private tickWrite;
+  private tickFilled;
+  private r3fRing;
+  private r3fWrite;
+  private r3fFilled;
+  private frameStart;
+  private currentSystems;
+  private visibilityMs;
+  private currentTick;
+  /** Enable/disable profiling. When disabled, all methods are no-ops. */
+  setEnabled(on: boolean): void;
+  isEnabled(): boolean;
+  /** Call at the start of engine.tick(). */
+  beginFrame(tick: number): void;
+  /** Call around each ECS system execution. */
+  beginSystem(name: string): void;
+  endSystem(name: string): void;
+  beginVisibility(): void;
+  endVisibility(): void;
+  /** Call right before the named engine WebGL pass renders. */
+  beginWebGL(pass: WebGLPass): void;
+  /**
+   * Call right after the named engine WebGL pass renders.
+   *
+   * The WebGL pass runs AFTER endFrame has flushed the tick sample to the
+   * ring, so we mutate the most-recent ring entry in place instead of
+   * writing to scratch state (which would be wiped by the next beginFrame
+   * before ever being read).
+   */
+  endWebGL(pass: WebGLPass): void;
+  /**
+   * Record WebGL engine pass counters for the current tick. `drawCalls` and
+   * `triangles` should be the totals from `renderer.info.render` accumulated
+   * across all engine passes in this tick (grid + selection). Callers must
+   * reset `renderer.info` at the start of the tick (with `autoReset=false`)
+   * so these values cover both passes.
+   *
+   * Called from the rAF loop AFTER engine.tick() / endFrame, so it targets
+   * the most-recent ring sample directly (see {@link endWebGL}).
+   */
+  recordWebGLStats(stats: {
+    drawCalls: number;
+    triangles: number;
+    selectionFrames: number;
+    snapGuides: number;
+    spacingIndicators: number;
+    domPositionsUpdated: number;
+  }): void;
+  /** Returns the most recently pushed tick sample, or null if the ring is empty. */
+  private getMostRecentTickSample;
+  /** Call at the end of engine.tick() — flushes a TickSample to the ring. */
+  endFrame(entityCount: number, visibleCount: number): void;
+  /**
+   * Push one R3F frame sample. Called from the R3F canvas via a probe
+   * component that has access to `useThree`.
+   */
+  recordR3FFrame(sample: Omit<R3FSample, 'timestamp'>): void;
+  /** Get the last N tick samples (newest first). */
+  getSamples(count?: number): TickSample[];
+  /** Get the last N R3F samples (newest first). */
+  getR3FSamples(count?: number): R3FSample[];
+  /** Compute rolling statistics across all three layers. */
+  getStats(): ProfilerStats;
+  private getEcsStats;
+  private getWebGLStats;
+  private getR3FStats;
+  /** Clear all collected data. */
+  clear(): void;
+}
+//#endregion
+//#region src/ecs/schema.d.ts
+/**
+ * Minimal Standard Schema v1 type definition.
+ *
+ * Compatible with Zod 3.24+, Valibot, ArkType, and any other library that
+ * implements the spec at https://standardschema.dev. We do not depend on any
+ * validator — users bring their own.
+ *
+ * Today we only carry the type parameter for `T`. Runtime validation via
+ * `validate()` is wired in by features that need it (inspector, serialization).
+ */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+  readonly '~standard': StandardSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1 {
+  interface Props<Input = unknown, Output = Input> {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+    readonly types?: Types<Input, Output>;
+  }
+  type Result<Output> = SuccessResult<Output> | FailureResult;
+  interface SuccessResult<Output> {
+    readonly value: Output;
+    readonly issues?: undefined;
+  }
+  interface FailureResult {
+    readonly issues: ReadonlyArray<Issue>;
+  }
+  interface Issue {
+    readonly message: string;
+    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+  }
+  interface PathSegment {
+    readonly key: PropertyKey;
+  }
+  interface Types<Input = unknown, Output = Input> {
+    readonly input: Input;
+    readonly output: Output;
+  }
+  type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema['~standard']['types']>['output'];
+}
+//#endregion
+//#region src/ecs/engine/widget-binding.d.ts
+/** Rendering surface for a widget. */
+type WidgetSurface = 'dom' | 'webgl';
+/**
+ * Drop-to-consume interaction handlers for a widget type (RFC-004 § Phase 1).
+ *
+ * All fields are optional. A widget that sets `accepts` on its `Card`
+ * component should typically also supply `onReceiveChild` so it can
+ * actually do something on consume; a widget that sets `provides`
+ * rarely needs `onDroppedOnParent` unless it wants to veto or run
+ * side effects.
+ *
+ * Handlers live on the widget *type* (not the entity) so `Card` data
+ * stays serializable and one handler triple drives every instance of
+ * the widget type.
+ */
+interface WidgetInteractionHandlers {
+  /**
+   * Parent-side: called on drop when a child lands on this widget.
+   * Return `{ consume: true }` to accept the drop; the optional
+   * `mutation` payload is passed to `applyMutation` / `revertMutation`
+   * so undo can be symmetric.
+   */
+  onReceiveChild?(ctx: {
+    parent: EntityId;
+    child: EntityId;
+    world: World;
+  }): {
+    consume: boolean;
+    mutation?: unknown;
+  };
+  /**
+   * Child-side: called on drop when this widget is being dropped
+   * onto a parent. Optional side effects and optional veto.
+   */
+  onDroppedOnParent?(ctx: {
+    child: EntityId;
+    parent: EntityId;
+    world: World;
+  }): {
+    veto: boolean;
+  } | undefined;
+  /**
+   * Parent-side runtime gate on top of the static `accepts` /
+   * `provides` intersection — e.g. "container is full, refuse further
+   * children." Returning `false` blocks the consume before
+   * `onReceiveChild` is called.
+   */
+  canAccept?(ctx: {
+    parent: EntityId;
+    child: EntityId;
+    world: World;
+  }): boolean;
+  /**
+   * Apply the mutation returned by `onReceiveChild` (forward path).
+   * Called by `ConsumeCommand.execute`.
+   */
+  applyMutation?(world: World, mutation: unknown): void;
+  /**
+   * Reverse the mutation (undo path). Called by `ConsumeCommand.undo`.
+   */
+  revertMutation?(world: World, mutation: unknown): void;
+}
+/**
+ * Framework-free widget contract used by the engine.
+ *
+ * The React layer (see `react/widgets/registry.ts`) extends this with a
+ * `component` field to carry the rendered React component. The engine never
+ * reads that field — it only needs the metadata here — which keeps the
+ * `ecs/` layer free of React imports.
+ */
+interface WidgetBinding<T = Record<string, unknown>> {
+  /** Unique widget type id. Matches `Widget { type }` on spawned entities. */
+  type: string;
+  /** Rendering surface; defaults to `'dom'`. */
+  surface?: WidgetSurface;
+  /**
+   * Standard Schema v1-compatible schema for the widget's data.
+   * Use Zod 3.24+, Valibot, ArkType, or any other conforming validator.
+   * The schema's output type drives the widget's data type.
+   */
+  schema: StandardSchemaV1<any, T>;
+  /** Default data shape for new instances. Merged with user-supplied data at spawn. */
+  defaultData: T;
+  /** Default world-space size at spawn. */
+  defaultSize: {
+    width: number;
+    height: number;
+  };
+  /** Minimum world-space size when resizing. */
+  minSize?: {
+    width: number;
+    height: number;
+  };
+  /**
+   * Optional drop-to-consume handlers. Only meaningful for `Card`-tagged
+   * widgets; non-card widgets don't participate in the consume mechanic
+   * so any handlers here are dead code for them.
+   */
+  interaction?: WidgetInteractionHandlers;
+}
+/** Simple in-memory registry of widget bindings. */
+interface WidgetRegistry<W extends WidgetBinding = WidgetBinding> {
+  register(def: W): void;
+  get(type: string): W | null;
+  getAll(): W[];
+}
+declare function createWidgetRegistry<W extends WidgetBinding = WidgetBinding>(defs?: W[]): WidgetRegistry<W>;
+//#endregion
+//#region src/react/widgets/registry.d.ts
+/**
+ * Props passed to every DOM widget component. The component is mounted
+ * inside a sized `WidgetSlot` div — size via CSS or layout — and renders
+ * normal React/HTML.
+ *
+ * Pointer events work natively (RFC-006): `onClick`, `onPointerOver`,
+ * focus, native form inputs, contenteditable, drag-and-drop API — all
+ * dispatched by the browser's event path and reach widget children
+ * before they bubble to the canvas-level `PointerEventBus`.
+ *
+ * To opt out of engine routing (drag / select / resize) for an event,
+ * call `e.stopPropagation()` from inside the widget. `<button>`,
+ * `<input>`, `<textarea>`, `<select>`, and `[contenteditable]` opt out
+ * automatically — the bus skips engine routing when the event target
+ * matches one of those native interactive selectors.
+ */
+interface DomWidgetProps {
+  entityId: EntityId;
+}
+/**
+ * Props passed to every R3F widget component. Rendered in widget-local
+ * coords — the origin is the widget centre, X right, Y up — and the
+ * component declares its own Three.js scene through R3F primitives.
+ *
+ * Pointer events on `<mesh>` / `<group>` work natively (RFC-006):
+ * `onClick`, `onPointerOver`, `onPointerOut`, `onPointerEnter`,
+ * `onPointerLeave`, `onPointerMove`, `onPointerDown`, `onPointerUp`,
+ * `onPointerMissed`, `event.point` / `event.uv` / `event.intersections`,
+ * R3F's `event.stopPropagation()` and `setPointerCapture` — all
+ * dispatched by a custom EventManager that raycasts the widget's
+ * own scene with widget-local coords.
+ *
+ * To opt out of engine routing (drag / select / resize) for an event,
+ * additionally call `event.nativeEvent.stopPropagation()` to prevent
+ * the canvas-container `PointerEventBus` from receiving it.
+ */
+interface R3FWidgetProps {
+  entityId: EntityId;
+  /** Widget width in world units. */
+  width: number;
+  /** Widget height in world units. */
+  height: number;
+}
+/** A DOM-rendered widget. The component is wrapped in a sized div — size via CSS. */
+interface DomWidget<T = Record<string, unknown>> extends WidgetBinding<T> {
+  surface?: 'dom';
+  component: React.ComponentType<DomWidgetProps>;
+}
+/**
+ * An R3F (React Three Fiber) widget. The component receives local-space
+ * width/height. Card-shaped chrome / lift / drag-promote / compositor
+ * discard are all opted in via the `Card` ECS component on the spawned
+ * entity (typically declared in the widget's archetype) — see
+ * `createGeometryCardWidget` for the convenience wrapper.
+ */
+interface R3FWidget<T = Record<string, unknown>> extends WidgetBinding<T> {
+  surface: 'webgl';
+  component: React.ComponentType<R3FWidgetProps>;
+}
+/** Either kind of widget. */
+type Widget<T = Record<string, unknown>> = DomWidget<T> | R3FWidget<T>;
+/** Narrows to the R3F variant. */
+declare function isR3FWidget<T>(widget: Widget<T>): widget is R3FWidget<T>;
+//#endregion
+//#region src/ecs/archetype.d.ts
+/**
+ * An archetype is a recipe for creating an entity: it declares which components
+ * and tags the entity should have on spawn. Archetypes may reference a widget
+ * type (for visible entities) or stand alone (for logic-only entities).
+ *
+ * The engine auto-generates a default archetype for every registered widget
+ * that does not have an explicit one — so simple widgets don't need to ship
+ * an archetype at all. Write an archetype only when you need to bundle extra
+ * behaviour (Container, Locked, custom components) with a widget.
+ */
+interface Archetype {
+  /** Unique archetype id. Pass this to `engine.spawn(id, ...)`. */
+  id: string;
+  /**
+   * The widget type this archetype renders as. Required for visible entities;
+   * omit for logic-only entities that have no view.
+   */
+  widget?: string;
+  /** Extra components added on spawn, beyond Transform2D / Widget / WidgetData / ZIndex. */
+  components?: ComponentInit[];
+  /** Extra tags added on spawn, beyond the interactive defaults. */
+  tags?: TagType[];
+  /**
+   * Which interaction capabilities to grant on spawn.
+   *
+   * - `true` (default) / `undefined`: add Selectable, Draggable, Resizable,
+   *   SelectionFrame, SnapSource, and SnapTarget — the full bundle.
+   * - `false`: add none (backdrops, decorations, locked entities).
+   * - object form: pick and choose — e.g. iOS-style cards use
+   *   `{ selectable: true, draggable: true, resizable: false,
+   *      selectionFrame: false, snapSource: false, snapTarget: true }`
+   *   so they can be moved and selected but never resized, render their
+   *   own chrome instead of the engine-drawn frame, don't snap to
+   *   neighbours when dragged, but do serve as references that other
+   *   widgets snap to.
+   *
+   * Omitted interaction keys default to `false`. `selectionFrame` is an
+   * exception: if omitted, it follows `selectable` (an entity you can
+   * select gets a frame unless you explicitly opt out).
+   *
+   * NOTE for upgraders from earlier versions: `interactive: true` now
+   * additionally grants `SnapSource` and `SnapTarget`, so widgets using
+   * the default bundle will start participating in alignment-snap math
+   * during drag. If you previously relied on snap being a no-op for
+   * these widgets, switch to the object form and set both to `false`.
+   */
+  interactive?: boolean | {
+    selectable?: boolean;
+    draggable?: boolean;
+    resizable?: boolean;
+    selectionFrame?: boolean; /** Dragging this entity invokes alignment-snap math. Default false in the object form. */
+    snapSource?: boolean; /** Bounds participate as references for other entities' snap math. Default false in the object form. */
+    snapTarget?: boolean;
+  };
+  /** Overrides the widget's defaultSize. */
+  defaultSize?: {
+    width: number;
+    height: number;
+  };
+}
+/**
+ * Options for `engine.spawn(archetypeId, opts)`.
+ * All fields are optional — defaults come from the archetype + widget.
+ */
+interface SpawnOptions {
+  /** World-space position. Defaults to { x: 0, y: 0 }. */
+  at?: {
+    x: number;
+    y: number;
+  };
+  /** World-space size. Falls back to archetype.defaultSize → widget.defaultSize. */
+  size?: {
+    width: number;
+    height: number;
+  };
+  /** Initial rotation in radians. Default 0. */
+  rotation?: number;
+  /** Data patch merged into the widget's defaultData. */
+  data?: Record<string, unknown>;
+  /** Z-order. Default 0. */
+  zIndex?: number;
+  /** Parent container entity — writes `ParentFrame` on spawn so the child
+   *  lives in the container's sub-canvas frame. */
+  parent?: EntityId;
+}
+/** Simple in-memory archetype registry. */
+interface ArchetypeRegistry {
+  register(archetype: Archetype): void;
+  get(id: string): Archetype | null;
+  getAll(): Archetype[];
+}
+declare function createArchetypeRegistry(archetypes?: Archetype[]): ArchetypeRegistry;
+//#endregion
+//#region src/ecs/commands.d.ts
+interface Command {
+  execute(world: World): void;
+  undo(world: World): void;
+}
+declare class CommandBuffer {
+  private undoStack;
+  private redoStack;
+  private currentGroup;
+  /** Start grouping commands (e.g., on pointerdown). All commands until endGroup() are one undo step. */
+  beginGroup(): void;
+  /** Execute a command and record it for undo. */
+  execute(command: Command, world: World): void;
+  /** Close the current group — all commands since beginGroup() become one undo step. */
+  endGroup(): void;
+  /** Undo the last command group. */
+  undo(world: World): boolean;
+  /** Redo the last undone command group. */
+  redo(world: World): boolean;
+  canUndo(): boolean;
+  canRedo(): boolean;
+  clear(): void;
+  get undoSize(): number;
+  get redoSize(): number;
+}
+declare class MoveCommand implements Command {
+  private entityIds;
+  private dx;
+  private dy;
+  private transformType;
+  private beforePositions;
+  private afterPositions;
+  private captured;
+  constructor(entityIds: EntityId[], dx: number, dy: number, transformType: ComponentType<{
+    x: number;
+    y: number;
+  }>);
+  execute(world: World): void;
+  undo(world: World): void;
+}
+declare class ResizeCommand implements Command {
+  private entityId;
+  private before;
+  private after;
+  private transformType;
+  constructor(entityId: EntityId, before: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  }, after: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  }, transformType: ComponentType<{
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  }>);
+  execute(world: World): void;
+  undo(world: World): void;
+}
+/**
+ * Snapshot of an entity's full component + tag state, suitable for
+ * reconstruction via {@link rehydrateEntity} on undo.
+ */
+interface EntitySnapshot {
+  entityId: EntityId;
+  components: Array<{
+    type: ComponentType<unknown>;
+    data: unknown;
+  }>;
+  tags: TagType[];
+}
+/**
+ * Capture an entity's complete current state. Used by `ConsumeCommand`
+ * so `undo` can fully reconstitute a destroyed child. Relies on
+ * `world.getComponentsOf(entity)` / `world.getTagsOf(entity)` so no
+ * external type registries need to be threaded through.
+ */
+declare function snapshotEntity(world: World, entity: EntityId): EntitySnapshot;
+/**
+ * Recreate an entity's state from a snapshot. Uses the same
+ * `EntityId` captured in the snapshot if the world allows
+ * reassignment; otherwise creates a fresh id and returns it.
+ */
+declare function rehydrateEntity(world: World, snapshot: EntitySnapshot): EntityId;
+/**
+ * Drop-to-consume command (RFC-004 § Phase 4). Undo / redo are
+ * fully supported by:
+ *  - capturing a full entity snapshot of the child at construction time,
+ *  - delegating the forward mutation to the parent widget's
+ *    `applyMutation` handler,
+ *  - delegating the reverse mutation to `revertMutation`.
+ *
+ * Handlers are supplied at construction time (captured from the widget
+ * registry in the interaction runtime's pointerup path), so the
+ * command doesn't need to know about the registry shape itself.
+ */
+declare class ConsumeCommand implements Command {
+  readonly parentId: EntityId;
+  readonly childId: EntityId;
+  readonly childSnapshot: EntitySnapshot;
+  readonly mutation: unknown;
+  private readonly applyMutation;
+  private readonly revertMutation;
+  /**
+   * The entity id we currently target for destroy. Starts as the
+   * initial `childId` captured at construction; updated to the fresh
+   * id returned by `rehydrateEntity` on undo so that a subsequent
+   * `redo()` destroys the rehydrated entity (not a stale id from a
+   * previous execute cycle).
+   */
+  private currentChildId;
+  constructor(parentId: EntityId, childId: EntityId, childSnapshot: EntitySnapshot, mutation: unknown, applyMutation: ((world: World, mutation: unknown) => void) | undefined, revertMutation: ((world: World, mutation: unknown) => void) | undefined);
+  execute(world: World): void;
+  undo(world: World): void;
+}
+declare class SetComponentCommand<T> implements Command {
+  private entityId;
+  private type;
+  private before;
+  private after;
+  constructor(entityId: EntityId, type: ComponentType<T>, before: Partial<T>, after: Partial<T>);
+  execute(world: World): void;
+  undo(world: World): void;
+}
+//#endregion
+//#region src/ecs/engine/types.d.ts
+/** Directive returned by pointer handlers indicating how the canvas should handle capture. */
+type PointerDirective = {
+  action: 'passthrough';
+} | {
+  action: 'passthrough-track-drag';
+} | {
+  action: 'capture-drag';
+} | {
+  action: 'capture-resize';
+  handle: ResizeHandlePos;
+} | {
+  action: 'capture-marquee';
+};
+/** Keyboard modifier state captured alongside pointer events. */
+interface Modifiers {
+  shift: boolean;
+  ctrl: boolean;
+  alt: boolean;
+  meta: boolean;
+}
+/**
+ * A visible entity with its computed frame-local bounds and display metadata.
+ *
+ * Bounds are copied from the entity's `Transform2D` — post-RFC-004 Phase 0b,
+ * every entity's Transform2D is already in its frame's local coord system,
+ * so there is no distinct "world" space to translate into.
+ */
+interface VisibleEntity {
+  entityId: EntityId;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  breakpoint: Breakpoint;
+  zIndex: number;
+  surface: string;
+  widgetType: string;
+}
+/** Per-frame change flags indicating what changed during the last tick. */
+interface FrameChanges {
+  positionsChanged: EntityId[];
+  breakpointsChanged: EntityId[];
+  /**
+   * Entities whose `ZIndex` component value changed during the last
+   * tick. Consumed by `<InfiniteCanvas>` to write `el.style.zIndex` on
+   * each slot so R3F cards (which intentionally skip the `Layer`
+   * re-bucket path during drag) still stack correctly when their
+   * `ZIndex` is bumped — without this, a dragged R3F card's CSS chrome
+   * retains its drag-start DOM order and hides beneath sibling
+   * chromes whose intrinsic ZIndex was lower.
+   */
+  zIndicesChanged: EntityId[];
+  entered: EntityId[];
+  exited: EntityId[];
+  cameraChanged: boolean;
+  navigationChanged: boolean;
+  selectionChanged: boolean;
+  /**
+   * True when at least one entity's `Layer` component value changed
+   * during the last tick. Render layers consume this to re-bucket
+   * widget slots into their target layer container — see RFC-003 §
+   * dragPromoteSystem and `<InfiniteCanvas>`'s bucket memo.
+   */
+  layersChanged: boolean;
+}
+/** Configuration options for `createLayoutEngine()`. */
+interface LayoutEngineConfig<W extends WidgetBinding = Widget> {
+  /** Maximum entity count (default: 10000). */
+  maxEntities?: number;
+  /** Minimum and maximum zoom levels. */
+  zoom?: {
+    min: number;
+    max: number;
+  };
+  /** Screen-space pixel thresholds for responsive breakpoints. */
+  breakpoints?: {
+    micro: number;
+    compact: number;
+    normal: number;
+    expanded: number;
+  };
+  /** Snap alignment configuration. */
+  snap?: {
+    /** Run alignment-snap math during drag. Default true. */enabled?: boolean; /** Threshold in world pixels. Default 5. Zoom-corrected at use site. */
+    threshold?: number;
+    /**
+     * Render the magenta guide lines and equal-spacing indicators while
+     * snap math is active. Default true. Independent of `enabled` —
+     * you can run snap math without showing chrome (e.g. screenshot
+     * mode) or vice versa for demos.
+     */
+    guidesVisible?: boolean;
+  };
+  /** Widget definitions available to `spawn()`. */
+  widgets?: W[];
+  /** Archetype definitions available to `spawn()`. */
+  archetypes?: Archetype[];
+  /**
+   * Override the default iOS-style card preset sizes (small/medium/large/xl).
+   * Partial — unspecified presets keep their built-in defaults.
+   */
+  cardPresets?: {
+    presets?: Partial<Record<CardPreset, {
+      width: number;
+      height: number;
+    }>>;
+    gap?: number;
+  };
+}
+/**
+ * The core layout engine. Manages the ECS world, camera, input, undo/redo,
+ * spatial indexing, and frame lifecycle for an infinite canvas.
+ */
+interface LayoutEngine<W extends WidgetBinding = Widget> {
+  /** The underlying ECS world. Use for direct component/tag/resource access. */
+  readonly world: World;
+  createEntity(inits?: ComponentInit[]): EntityId;
+  spawn(id: string, opts?: SpawnOptions): EntityId;
+  spawnAtCameraCenter(id: string, opts?: Omit<SpawnOptions, 'at'>): EntityId;
+  destroyEntity(id: EntityId): void;
+  registerWidget(widget: W): void;
+  getWidget(type: string): W | null;
+  getWidgets(): W[];
+  registerArchetype(archetype: Archetype): void;
+  getArchetype(id: string): Archetype | null;
+  get<T>(entity: EntityId, type: ComponentType<T>): T | undefined;
+  set<T>(entity: EntityId, type: ComponentType<T>, data: Partial<T>): void;
+  has(entity: EntityId, type: ComponentType | TagType): boolean;
+  addComponent<T>(entity: EntityId, type: ComponentType<T>, data?: T): void;
+  removeComponent(entity: EntityId, type: ComponentType): void;
+  addTag(entity: EntityId, type: TagType): void;
+  removeTag(entity: EntityId, type: TagType): void;
+  getSchemaFor(entity: EntityId): StandardSchemaV1 | undefined;
+  registerSystem(system: SystemDef): void;
+  removeSystem(name: string): void;
+  getCamera(): {
+    x: number;
+    y: number;
+    zoom: number;
+    gesturing: boolean;
+  };
+  panBy(dx: number, dy: number): void;
+  panTo(worldX: number, worldY: number): void;
+  zoomAtPoint(screenX: number, screenY: number, delta: number): void;
+  zoomTo(zoom: number): void;
+  zoomToFit(entityIds?: EntityId[], padding?: number): void;
+  /** Mark the camera as actively manipulated (continuous wheel / pinch / pan). */
+  setGesturing(active: boolean): void;
+  setViewport(width: number, height: number, dpr?: number): void;
+  /**
+   * @deprecated RFC-008 Phase 3d retired the canvas's runtime use of these
+   * methods — `InputManager` now drives the engine via `beginDrag` /
+   * `beginResize` / `beginMarquee` etc. Kept as a backwards-compat shim
+   * for tests and external integrations that still drive the state
+   * machine via screen coordinates. Will be removed in a future release.
+   */
+  handlePointerDown(screenX: number, screenY: number, button: number, modifiers: Modifiers): PointerDirective;
+  /** @deprecated See {@link LayoutEngine.handlePointerDown}. */
+  handlePointerMove(screenX: number, screenY: number, modifiers: Modifiers): PointerDirective;
+  /** @deprecated See {@link LayoutEngine.handlePointerDown}. */
+  handlePointerUp(): PointerDirective;
+  /** @deprecated See {@link LayoutEngine.handlePointerDown}. */
+  handlePointerCancel(): void;
+  /**
+   * Topmost interactable entity at a screen-space point. Same hit-test
+   * the pointer state machine uses, exposed for callers that need to
+   * resolve coords without firing pointer side-effects — RFC-006's
+   * `PointerEventBus` (double-click) and the R3F `EventRouter`.
+   */
+  pickAt(screenX: number, screenY: number): EntityId | null;
+  /**
+   * Rich variant of `pickAt` — returns the topmost interactable entity
+   * AND its `InteractionRoleData` (role + layer). The role discriminates
+   * between `'drag'`, `'select'`, `'resize'` (with `handle`), `'rotate'`,
+   * `'connect'`, `'canvas'` so the InputManager's `drag-start` handler
+   * can branch into the right engine entry point (`beginResize` for
+   * resize hotspots, `beginDrag` otherwise). Same hit-test as `pickAt`.
+   */
+  hitTest(screenX: number, screenY: number): {
+    entityId: EntityId;
+    role: InteractionRoleData;
+  } | null;
+  beginDrag(entity: EntityId, worldX: number, worldY: number): void;
+  updateDrag(entity: EntityId, worldX: number, worldY: number): void;
+  endDrag(entity: EntityId, opts: {
+    cancelled: boolean;
+  }): void;
+  getDraggingEntity(): EntityId | null;
+  /**
+   * Cancel whatever interaction is in progress — drag, resize, marquee,
+   * tracking, or fly-back. Used by the InputManager pipeline's `cancel`
+   * engine handler so a native `pointercancel` (system dialog, palm
+   * rejection, etc.) leaves no orphaned state behind.
+   */
+  cancelInteraction(): void;
+  beginResize(entity: EntityId, handle: ResizeHandlePos, worldX: number, worldY: number): boolean;
+  updateResize(entity: EntityId, worldX: number, worldY: number): void;
+  endResize(entity: EntityId, opts: {
+    cancelled: boolean;
+  }): void;
+  isResizing(): boolean;
+  getResizingEntity(): EntityId | null;
+  beginMarquee(worldX: number, worldY: number): void;
+  updateMarquee(worldX: number, worldY: number): void;
+  endMarquee(): void;
+  isMarqueeActive(): boolean;
+  getSelectedEntities(): EntityId[];
+  /**
+   * Add `entity` to the selection. `additive=false` clears every other
+   * `Selected` first; `additive=true` toggles `entity` and leaves the
+   * rest untouched. Mirrors the legacy click-to-select semantics that
+   * Phase 3d's `tap` and `drag-start` engine handlers will drive.
+   */
+  selectEntity(entity: EntityId, additive: boolean): void;
+  clearSelection(): void;
+  getHoveredEntity(): EntityId | null;
+  setHoveredEntity(entity: EntityId | null): void;
+  /**
+   * Run the engine's hit-test for a screen-space point and update both
+   * `hoveredEntity` and the internal resize-handle cursor cache so the
+   * cursor can switch between the 8 RFC-005 resize hotspots within a
+   * single selected widget. No-op while a drag / resize / marquee /
+   * fly-back is in progress.
+   */
+  updateHover(screenX: number, screenY: number): void;
+  enterContainer(entity: EntityId): void;
+  exitContainer(): void;
+  getActiveContainer(): EntityId | null;
+  getNavigationDepth(): number;
+  execute(command: Command): void;
+  beginCommandGroup(): void;
+  endCommandGroup(): void;
+  undo(): boolean;
+  redo(): boolean;
+  canUndo(): boolean;
+  canRedo(): boolean;
+  markDirty(): void;
+  tick(): void;
+  flushIfDirty(): boolean;
+  getVisibleEntities(): VisibleEntity[];
+  getFrameChanges(): FrameChanges;
+  getSpatialIndex(): SpatialIndex;
+  getSnapGuides(): SnapGuide[];
+  getEqualSpacing(): EqualSpacingIndicator[];
+  setSnapEnabled(on: boolean): void;
+  setSnapThreshold(worldPx: number): void;
+  getSnapGuidesVisible(): boolean;
+  setSnapGuidesVisible(on: boolean): void;
+  readonly profiler: Profiler;
+  onFrame(handler: () => void): Unsubscribe;
+  destroy(): void;
+}
+//#endregion
+//#region src/ecs/engine/LayoutEngine.d.ts
+/**
+ * Creates a new LayoutEngine instance with the given configuration.
+ * This is the main entry point for the infinite canvas library.
+ */
+declare function createLayoutEngine<W extends WidgetBinding = WidgetBinding>(config?: LayoutEngineConfig<W>): LayoutEngine<W>;
+//#endregion
+export { FrameCameraState as $, Visible as $t, createWidgetRegistry as A, CursorHintData as At, WebGLPass as B, OverlapCandidate as Bt, R3FWidget as C, CardPreset as Ct, WidgetInteractionHandlers as D, ContainerChildren as Dt, isR3FWidget as E, ContainerCamera as Et, ProfilerStats as F, InteractionRoleType as Ft, SnapResult as G, Selectable as Gt, EntityBounds as H, ParentFrame as Ht, R3FPhaseHistogram as I, Layer as It, BreakpointConfigResource as J, SnapSource as Jt, computeSnapGuides as K, Selected as Kt, R3FSample as L, LayerData as Lt, EcsStats as M, Dragging as Mt, FrameTimeStats as N, InteractionRole as Nt, WidgetRegistry as O, Culled as Ot, Profiler as P, InteractionRoleData as Pt, CursorResourceData as Q, TweenEasing as Qt, R3FStats as R, LayerName as Rt, DomWidgetProps as S, CardOverlapHotPoint as St, Widget as T, Container as Tt, EqualSpacingIndicator as U, Resizable as Ut, WebGLStats as V, OverlapTarget as Vt, SnapGuide as W, ResizeHandlePos as Wt, CardPresetsResource as X, Transform2D as Xt, CameraResource as Y, SnapTarget as Yt, CursorResource as Z, TransformTween as Zt, Archetype as _, screenToWorld as _t, Modifiers as a, SpatialIndexResource as at, createArchetypeRegistry as b, CSSCursor as bt, Command as c, SpatialIndex as ct, EntitySnapshot as d, Vec2 as dt, Widget$1 as en, LayerOrderData as et, MoveCommand as f, aabbToRect as ft, snapshotEntity as g, rectToAABB as gt, rehydrateEntity as h, pointInAABB as ht, LayoutEngineConfig as i, RootCameraResource as it, StandardSchemaV1 as j, Draggable as jt, WidgetSurface as k, CursorHint as kt, CommandBuffer as l, AABB as lt, SetComponentCommand as m, intersectsAABB as mt, FrameChanges as n, WidgetData as nn, NavigationFrame as nt, PointerDirective as o, ViewportResource as ot, ResizeCommand as p, clamp as pt, Breakpoint as q, SelectionFrame as qt, LayoutEngine as r, ZIndex as rn, NavigationStackResource as rt, VisibleEntity as s, ZoomConfigResource as st, createLayoutEngine as t, WidgetBreakpoint as tn, LayerOrderResource as tt, ConsumeCommand as u, Rect as ut, ArchetypeRegistry as v, worldToScreen as vt, R3FWidgetProps as w, Children as wt, DomWidget as x, Card as xt, SpawnOptions as y, Active as yt, TickSample as z, Locked as zt };
+//# sourceMappingURL=index-DSdbSQ_t.d.cts.map