cubeforge 0.4.13 → 0.5.0

package/dist/index.d.ts

@@ -1,12 +1,12 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React from 'react';
 import React__default, { CSSProperties, ReactNode, ReactElement } from 'react';
-import { Plugin, EntityId, ECSWorld, ScriptUpdateFn, NavGrid, WorldSnapshot, EventBus, AccessibilityOptions } from '@cubeforge/core';
-export { AccessibilityOptions, AssetProgress, Component, DeltaSnapshot, ECSWorld, Ease, EntityId, GameTimer, HierarchyComponent, HierarchySystem, HotReloadablePlugin, MergedRect, NavGrid, Plugin, PreloadManifest, ScriptUpdateFn, SpatialHash, TimelineEntry, TransformComponent, TweenHandle, TweenOptions, TweenTimeline, Vec2Like, WorldSnapshot, WorldTransformComponent, alignment, announceToScreenReader, applyDeltaSnapshot, arrive, cohesion, createHierarchy, createTag, createTimeline, createTimer, createTransform, definePlugin, evade, findByTag, flee, getAccessibilityOptions, getDescendants, hmrClearState, hmrLoadState, hmrSaveState, hotReloadPlugin, mergeTileColliders, patrol, preloadManifest, pursuit, removeParent, seek, separation, setAccessibilityOptions, setParent, smoothPath, tween, wander } from '@cubeforge/core';
+import { Plugin, GameLoopMode, EntityId, ECSWorld, ScriptUpdateFn, NavGrid, WorldSnapshot, EventBus, AccessibilityOptions } from '@cubeforge/core';
+export { AccessibilityOptions, AssetProgress, Component, DeltaSnapshot, ECSWorld, Ease, EntityId, GameLoopMode, GameTimer, HierarchyComponent, HierarchySystem, HotReloadablePlugin, MergedRect, NavGrid, Plugin, PreloadManifest, ScriptUpdateFn, SpatialHash, TimelineEntry, TransformComponent, TweenHandle, TweenOptions, TweenTimeline, Vec2Like, WorldSnapshot, WorldTransformComponent, alignment, announceToScreenReader, applyDeltaSnapshot, arrive, cohesion, createHierarchy, createTag, createTimeline, createTimer, createTransform, definePlugin, evade, findByTag, flee, getAccessibilityOptions, getDescendants, hmrClearState, hmrLoadState, hmrSaveState, hotReloadPlugin, isReducedMotionPreferred, mergeTileColliders, patrol, preloadManifest, pursuit, removeParent, seek, separation, setAccessibilityOptions, setParent, setReducedMotionOverride, smoothPath, tween, wander } from '@cubeforge/core';
 import { Sampling, BlendMode, SpriteShape, AnimatorStateDefinition, AnimatorParamValue, GradientType, GradientStop, MaskShape, PostProcessEffect, PostProcessOptions } from '@cubeforge/renderer';
 export { AnimationClipDefinition, AnimationStateComponent, AnimatorComponent, AnimatorCondition, AnimatorParamValue, AnimatorStateDefinition, AnimatorTransition, BlendMode, CircleShapeComponent, GradientComponent, GradientStop, GradientType, LineShapeComponent, MagFilterValue, MaskComponent, MaskShape, NineSliceComponent, ParallaxLayerComponent, Particle, ParticlePoolComponent, PolygonShapeComponent, PostProcessEffect, PostProcessOptions, PostProcessStack, RenderLayer, RenderLayerManager, RenderSystem, Sampling, SpriteComponent, SpriteShape, SquashStretchComponent, TextComponent, TextureFilter, TextureFilterValue, TrailComponent, chromaticAberrationEffect, createCircleShape, createGradient, createLineShape, createMask, createNineSlice, createPolygonShape, createPostProcessStack, createRenderLayerManager, createSprite, defaultLayers, scanlineEffect, vignetteEffect } from '@cubeforge/renderer';
 import { CombineRule, ColliderShape, JointType } from '@cubeforge/physics';
-export { AxisLock, BVH, BoxColliderComponent, BroadPhaseAABB, BroadPhasePair, COLLISION_DYNAMIC_DYNAMIC, COLLISION_DYNAMIC_KINEMATIC, COLLISION_DYNAMIC_STATIC, COLLISION_KINEMATIC_KINEMATIC, COLLISION_KINEMATIC_STATIC, CapsuleColliderComponent, CharacterCollision, CharacterController, CharacterControllerConfig, CircleColliderComponent, ColliderShape, CollisionPair, CollisionPipeline, CollisionPipelineResult, CombineRule, CompoundColliderComponent, ContactManifold, ContactPoint, ConvexPolygonColliderComponent, ConvexShape, DEFAULT_ACTIVE_COLLISION_TYPES, DebugCircle, DebugLine, DebugPoint, DebugRenderBackend, DebugRenderColors, DebugRenderFlags, DebugRenderOutput, DebugRenderPipeline, EPAResult, Float64Pool, GJKContactManifold, GJKResult, HalfSpaceColliderComponent, HeightFieldColliderComponent, Island, IslandDetector, JointComponent, JointMotor, JointSnapshot, JointType, KahanSum, MotorMode, MoveResult, MultibodyArticulation, MultibodyLink, PhysicsBodySnapshot, PhysicsHooks, ObjectPool as PhysicsObjectPool, PhysicsSnapshot, PointProjection, QueryOpts, QueryShape, RaycastHit, RigidBodyComponent, SegmentColliderComponent, Spatial3, SpatialInertia3, SweepAndPrune, TOIBody, TOIResult, TriMeshColliderComponent, Triangle2D, TriangleColliderComponent, addForce, addForceAtPoint, addTorque, applyImpulse, applyImpulseAtPoint, applyTorqueImpulse, boxArea, boxShape, buildBVH, capsuleArea, capsuleShape, circleArea, circleShape, computeTOI, containsPoint, createCompoundCollider, createConvexPolygonCollider, createHalfSpaceCollider, createHeightFieldCollider, createJoint, createLink, createMultibody, createSegmentCollider, createTriMeshCollider, createTriangleCollider, dMath, deterministicAtan2, deterministicCos, deterministicSin, deterministicSqrt, epa, generateDeterministicPairs, gjk, gjkEpaQuery, intersectAABB, intersectRay, intersectShape, isDeterministicMode, kineticEnergy, overlapBox, overlapCircle, pairKey, polygonArea, polygonMassProperties, polygonShape, potentialEnergy, predictPosition, projectPoint, queryBVH, queryBVHCircle, raycast, raycastAll, recomputeMassFromColliders, resetAllPools, resetForces, resetTorques, resolveTOI, restoreSnapshot, setAdditionalMass, setDeterministicMode, setMassProperties, setNextKinematicPosition, setNextKinematicRotation, shapeCast, snapshotFromBytes, snapshotFromJSON, snapshotHash, snapshotToBytes, snapshotToJSON, sortEntities, sweepBox, takeSnapshot, triangleArea, triangleMassProperties, velocityAtPoint } from '@cubeforge/physics';
+export { AxisLock, BoxColliderComponent, COLLISION_DYNAMIC_DYNAMIC, COLLISION_DYNAMIC_KINEMATIC, COLLISION_DYNAMIC_STATIC, COLLISION_KINEMATIC_KINEMATIC, COLLISION_KINEMATIC_STATIC, CapsuleColliderComponent, CharacterCollision, CharacterController, CharacterControllerConfig, CircleColliderComponent, ColliderShape, CollisionPair, CollisionPipeline, CollisionPipelineResult, CombineRule, CompoundColliderComponent, ContactManifold, ContactPoint, ConvexPolygonColliderComponent, DEFAULT_ACTIVE_COLLISION_TYPES, DebugCircle, DebugLine, DebugPoint, DebugRenderBackend, DebugRenderColors, DebugRenderFlags, DebugRenderOutput, DebugRenderPipeline, HalfSpaceColliderComponent, HeightFieldColliderComponent, JointComponent, JointMotor, JointSnapshot, JointType, MotorMode, MoveResult, PhysicsBodySnapshot, PhysicsHooks, PhysicsSnapshot, PointProjection, QueryOpts, QueryShape, RaycastHit, RigidBodyComponent, SegmentColliderComponent, TriMeshColliderComponent, TriangleColliderComponent, addForce, addForceAtPoint, addTorque, applyImpulse, applyImpulseAtPoint, applyTorqueImpulse, boxArea, capsuleArea, circleArea, containsPoint, createCompoundCollider, createConvexPolygonCollider, createHalfSpaceCollider, createHeightFieldCollider, createJoint, createSegmentCollider, createTriMeshCollider, createTriangleCollider, intersectAABB, intersectRay, intersectShape, kineticEnergy, overlapBox, overlapCircle, polygonArea, polygonMassProperties, potentialEnergy, predictPosition, projectPoint, raycast, raycastAll, recomputeMassFromColliders, resetForces, resetTorques, restoreSnapshot, setAdditionalMass, setMassProperties, setNextKinematicPosition, setNextKinematicRotation, shapeCast, snapshotFromBytes, snapshotFromJSON, snapshotHash, snapshotToBytes, snapshotToJSON, sweepBox, takeSnapshot, triangleArea, triangleMassProperties, velocityAtPoint } from '@cubeforge/physics';
 import { InputManager, ActionBindings, InputContextName, PlayerInput, InputRecorderControls, TouchPoint, InputBufferOptions, InputBuffer, ComboDefinition } from '@cubeforge/input';
 export { ActionBindings, AxisBinding, BufferedAction, ComboDefinition, ComboDetector, ComboDetectorOptions, InputBuffer, InputBufferOptions, InputContextName, InputManager, InputMap, InputRecorderControls, InputRecording, InputRecording as InputRecordingData, PlayerInput, TouchPoint, createInputMap, createInputRecorder, createPlayerInput, globalInputContext } from '@cubeforge/input';
 import { AnimationClip } from '@cubeforge/gameplay';
@@ -23,7 +23,7 @@ interface GameControls {
     resume(): void;
     reset(): void;
 }
-interface GameProps {
+interface GameProps$1 {
     width?: number;
     height?: number;
     /** Pixels per second squared downward (default 980) */
@@ -60,11 +60,45 @@ interface GameProps {
     sampling?: Sampling;
     /** Custom plugins to register after core systems. Each plugin's systems run after Render. */
     plugins?: Plugin[];
+    /**
+     * Loop mode (default 'realtime'):
+     * - 'realtime' — continuous 60fps tick. Use for action games, anything with
+     *   continuous motion or physics.
+     * - 'onDemand' — sleeps until input arrives or a component calls markDirty().
+     *   Use for puzzle games, turn-based games, visual novels, level editors, or any
+     *   scene where nothing changes unless the user acts. Saves battery and CPU.
+     */
+    mode?: GameLoopMode;
     style?: CSSProperties;
     className?: string;
     children?: React__default.ReactNode;
 }
-declare function Game({ width, height, gravity, debug, devtools, scale, deterministic, seed, asyncAssets, sampling, onReady, plugins, style, className, children, }: GameProps): react_jsx_runtime.JSX.Element;
+declare function Game({ width, height, gravity, debug, devtools, scale, deterministic, seed, asyncAssets, sampling, onReady, plugins, mode, style, className, children, }: GameProps$1): react_jsx_runtime.JSX.Element;
+
+type GameProps = React__default.ComponentProps<typeof Game>;
+/**
+ * Stage is an alias for {@link Game} tuned for static, puzzle, turn-based, and
+ * editor-style scenes. It defaults to:
+ *
+ * - `mode="onDemand"` — the loop sleeps until input arrives or a component calls
+ *   `engine.loop.markDirty()`. Saves battery and CPU.
+ * - `gravity={0}` — no downward acceleration. Most non-action scenes don't need it.
+ *
+ * Every other prop behaves identically to `<Game>`. Use `<Stage>` when you're
+ * building something that isn't an action game: a level editor, a card game, a
+ * match-3 puzzle, a visual novel, a node-graph tool, etc.
+ *
+ * @example
+ * ```tsx
+ * <Stage width={800} height={600}>
+ *   <Entity>
+ *     <Transform x={100} y={100} />
+ *     <Sprite src="card.png" width={80} height={120} />
+ *   </Entity>
+ * </Stage>
+ * ```
+ */
+declare function Stage(props: GameProps): react_jsx_runtime.JSX.Element;
 
 interface WorldProps {
     /** Gravitational acceleration in pixels/s² (default inherited from Game) */
@@ -183,10 +217,6 @@ interface RigidBodyProps {
     mass?: number;
     gravityScale?: number;
     isStatic?: boolean;
-    /** @deprecated Use restitution on BoxCollider/CircleCollider instead */
-    bounce?: number;
-    /** @deprecated Use friction on BoxCollider/CircleCollider instead */
-    friction?: number;
     vx?: number;
     vy?: number;
     /** Prevent any horizontal movement — velocity.x is zeroed every frame */
@@ -220,7 +250,7 @@ interface RigidBodyProps {
     /** Extra velocity solver iterations for constraints involving this body. Default 0 */
     additionalSolverIterations?: number;
 }
-declare function RigidBody({ mass, gravityScale, isStatic, bounce, friction, vx, vy, lockX, lockY, lockRotation, ccd, angularVelocity, angularDamping, linearDamping, density, restitution, dominance, isKinematic, enabled, maxLinearVelocity, maxAngularVelocity, additionalSolverIterations, }: RigidBodyProps): null;
+declare function RigidBody({ mass, gravityScale, isStatic, vx, vy, lockX, lockY, lockRotation, ccd, angularVelocity, angularDamping, linearDamping, density, restitution, dominance, isKinematic, enabled, maxLinearVelocity, maxAngularVelocity, additionalSolverIterations, }: RigidBodyProps): null;
 
 interface BoxColliderProps {
     width: number;
@@ -750,8 +780,30 @@ interface TilemapProps {
      * row-run (legacy behaviour).
      */
     mergeColliders?: boolean;
+    /**
+     * Array of tile GIDs (global IDs) to treat as solid, regardless of layer.
+     * When set, only tiles whose GID is in this array generate colliders in
+     * the collision layer. Without this, ALL non-zero tiles in the collision
+     * layer produce colliders.
+     */
+    solidTiles?: number[];
+    /**
+     * When true, also scan visual layers for tiles whose GID matches
+     * `solidTiles` and auto-generate colliders from them — no separate
+     * collision layer required. Default: false.
+     */
+    autoColliders?: boolean;
+    /**
+     * Per-tile-GID collider properties. Keys are tile GIDs.
+     * Example: `{ 6: { isTrigger: true }, 7: { oneWay: true } }`
+     */
+    tileColliderProps?: Record<number, {
+        isTrigger?: boolean;
+        oneWay?: boolean;
+        layer?: string;
+    }>;
 }
-declare function Tilemap({ src, onSpawnObject, layerFilter, zIndex, collisionLayer, triggerLayer: triggerLayerName, onTileProperty, navGrid, mergeColliders, }: TilemapProps): React__default.ReactElement | null;
+declare function Tilemap({ src, onSpawnObject, layerFilter, zIndex, collisionLayer, triggerLayer: triggerLayerName, onTileProperty, navGrid, mergeColliders, solidTiles, autoColliders, tileColliderProps: _tileColliderProps, }: TilemapProps): React__default.ReactElement | null;
 
 interface ParallaxLayerProps {
     /** Image URL to use as the background layer */
@@ -1832,6 +1884,100 @@ interface SceneManagerControls {
  */
 declare function useSceneManager(initialScene: string): SceneManagerControls;
 
+type TransitionEffect = {
+    type: 'fade';
+    duration?: number;
+    color?: string;
+} | {
+    type: 'wipe';
+    duration?: number;
+    direction?: 'left' | 'right' | 'up' | 'down';
+    color?: string;
+} | {
+    type: 'circle-close';
+    duration?: number;
+    color?: string;
+} | {
+    type: 'instant';
+};
+interface SceneTransitionControls {
+    /** Currently active scene (after transition completes). */
+    current: string;
+    /** Full scene stack. */
+    stack: string[];
+    /** Push scene with transition. */
+    push(scene: string, transition?: TransitionEffect): void;
+    /** Pop top scene with transition. Returns popped scene name. */
+    pop(transition?: TransitionEffect): string | undefined;
+    /** Replace current scene with transition. */
+    replace(scene: string, transition?: TransitionEffect): void;
+    /** Reset to a single scene with transition. */
+    reset(scene: string, transition?: TransitionEffect): void;
+    /** Transition progress 0–1 (0 = no overlay, 1 = fully covered). */
+    progress: number;
+    /** Current transition phase. */
+    phase: 'idle' | 'out' | 'in';
+    /** Active transition effect (for overlay rendering). */
+    activeTransition: TransitionEffect | null;
+}
+/**
+ * Scene manager with built-in visual transitions.
+ *
+ * @example
+ * const scenes = useSceneTransition('gameplay')
+ * scenes.push('pause', { type: 'fade', duration: 0.4, color: '#000' })
+ * scenes.replace('gameOver', { type: 'circle-close', duration: 0.6 })
+ *
+ * // Render the overlay component to see transitions:
+ * <SceneTransitionOverlay controls={scenes} />
+ */
+declare function useSceneTransition(initialScene: string, defaultTransition?: TransitionEffect): SceneTransitionControls;
+
+interface SceneTransitionOverlayProps {
+    controls: SceneTransitionControls;
+}
+/**
+ * Renders the visual overlay during scene transitions.
+ * Place this as a sibling after your scene content, inside the Game wrapper.
+ *
+ * @example
+ * const scenes = useSceneTransition('gameplay')
+ *
+ * <div style={{ position: 'relative' }}>
+ *   {scenes.current === 'gameplay' && <GameplayScene />}
+ *   {scenes.current === 'pause' && <PauseMenu />}
+ *   <SceneTransitionOverlay controls={scenes} />
+ * </div>
+ */
+declare function SceneTransitionOverlay({ controls }: SceneTransitionOverlayProps): React__default.DetailedReactHTMLElement<{
+    style: {
+        position: "absolute";
+        inset: number;
+        backgroundColor: string;
+        WebkitMaskImage: `radial-gradient(circle ${number}vmax at 50% 50%, transparent 100%, black 100%)`;
+        maskImage: `radial-gradient(circle ${number}vmax at 50% 50%, transparent 100%, black 100%)`;
+        pointerEvents: "none";
+        zIndex: number;
+    };
+}, HTMLElement> | React__default.DetailedReactHTMLElement<{
+    style: React__default.CSSProperties;
+}, HTMLElement> | null;
+
+/**
+ * Freeze gameplay for a short duration — physics and scripts stop
+ * but the last frame stays rendered. Creates impactful collision feedback.
+ *
+ * @example
+ * const hitstop = useHitstop()
+ *
+ * useCollisionEnter(() => {
+ *   hitstop.freeze(0.08) // 80ms freeze on hit
+ * })
+ */
+declare function useHitstop(): {
+    freeze: (seconds: number) => void;
+};
+
 /**
  * Returns a stable `InputBuffer` instance that persists across renders.
  *
@@ -2000,6 +2146,956 @@ interface SquashStretchControls {
  */
 declare function useSquashStretch(): SquashStretchControls;
 
+interface HistoryOptions {
+    /** Maximum number of snapshots to keep. Oldest entries are evicted. Default 50. */
+    capacity?: number;
+    /**
+     * When true, `Ctrl/Cmd+Z` triggers undo and `Ctrl/Cmd+Shift+Z` (or `Ctrl+Y`) triggers
+     * redo. Listens on `window`. Default false — users are expected to wire their own
+     * UI and shortcuts.
+     */
+    bindKeyboardShortcuts?: boolean;
+}
+interface HistoryControls {
+    /** Capture the current world state and push it onto the history stack. */
+    push(): void;
+    /** Revert to the previous snapshot. No-op if there's nothing to undo. */
+    undo(): void;
+    /** Re-apply a snapshot that was undone. No-op if there's nothing to redo. */
+    redo(): void;
+    /** Clear the entire history stack. */
+    clear(): void;
+    /** True if `undo()` would do anything. */
+    canUndo: boolean;
+    /** True if `redo()` would do anything. */
+    canRedo: boolean;
+    /** Number of snapshots currently stored. */
+    length: number;
+}
+/**
+ * Undo/redo for the entire ECS world, backed by the snapshot system.
+ *
+ * The typical pattern is "commit then push" — after the user completes a logical
+ * action (move a piece, paint a tile, rotate a shape), call `push()` to capture
+ * the new state. `undo()` rewinds to the previous push, `redo()` replays forward.
+ *
+ * In onDemand loop mode, undo/redo automatically re-render by calling
+ * `engine.loop.markDirty()`.
+ *
+ * @example
+ * ```tsx
+ * function PuzzleBoard() {
+ *   const history = useHistory({ capacity: 100, bindKeyboardShortcuts: true })
+ *
+ *   const onMove = (from, to) => {
+ *     applyMove(from, to)
+ *     history.push() // commit the move so it can be undone
+ *   }
+ *
+ *   return (
+ *     <>
+ *       <Board onMove={onMove} />
+ *       <button disabled={!history.canUndo} onClick={history.undo}>Undo</button>
+ *       <button disabled={!history.canRedo} onClick={history.redo}>Redo</button>
+ *     </>
+ *   )
+ * }
+ * ```
+ */
+declare function useHistory(options?: HistoryOptions): HistoryControls;
+
+interface SelectOptions {
+    /** If true, add to the current selection instead of replacing it. */
+    additive?: boolean;
+}
+interface SelectionControls {
+    /** The currently selected entity IDs, in selection order. */
+    selected: EntityId[];
+    /** Select one entity. Pass `{ additive: true }` to add to existing selection. */
+    select(id: EntityId, opts?: SelectOptions): void;
+    /** Remove an entity from the selection. */
+    deselect(id: EntityId): void;
+    /** Toggle an entity's selection state. */
+    toggle(id: EntityId): void;
+    /** Clear the entire selection. */
+    clear(): void;
+    /** True if the given entity is currently selected. */
+    isSelected(id: EntityId): boolean;
+}
+interface SelectionProps {
+    /** Initial selection when the provider mounts. */
+    initial?: EntityId[];
+    /** Called every time the selection changes. */
+    onChange?: (selected: EntityId[]) => void;
+    children?: ReactNode;
+}
+/**
+ * Provides a selection state to descendants. Works with {@link TransformHandles}
+ * to render drag-to-move/resize/rotate handles, or with any custom UI.
+ *
+ * @example
+ * ```tsx
+ * <Stage>
+ *   <Selection>
+ *     <Entity>
+ *       <Sprite src="card.png" width={80} height={120} />
+ *     </Entity>
+ *     <TransformHandles />
+ *   </Selection>
+ * </Stage>
+ * ```
+ */
+declare function Selection({ initial, onChange, children }: SelectionProps): react_jsx_runtime.JSX.Element;
+/**
+ * Reads and mutates the selection state from inside a {@link Selection} provider.
+ *
+ * @example
+ * ```tsx
+ * function Card({ id }: { id: number }) {
+ *   const { select, isSelected } = useSelection()
+ *   return <button onClick={() => select(id)}>{isSelected(id) ? '✓' : ''} Card</button>
+ * }
+ * ```
+ */
+declare function useSelection(): SelectionControls;
+
+interface TransformHandlesProps {
+    /** Whether to show the rotation handle above the top edge. Default true. */
+    showRotationHandle?: boolean;
+    /** Whether corner/edge handles can resize the entity (by scaling). Default true. */
+    showResizeHandles?: boolean;
+    /** Whether dragging the body translates the entity. Default true. */
+    enableTranslate?: boolean;
+    /** Color of the selection outline and handles. Default '#4fc3f7'. */
+    color?: string;
+    /** Handle size in CSS pixels. Default 10. */
+    handleSize?: number;
+}
+/**
+ * Renders interactive resize/rotate/move handles for every entity currently in the
+ * {@link Selection} context. Handles are positioned via a DOM overlay on top of the
+ * game canvas, so they respect CSS cursors (e.g. `nwse-resize`) and are fully
+ * styleable.
+ *
+ * Dragging the body translates, dragging corners/edges scales, and dragging the
+ * handle above the top edge rotates. In onDemand loop mode every mutation calls
+ * `markDirty()` so the canvas re-renders.
+ *
+ * @example
+ * ```tsx
+ * <Stage>
+ *   <Selection initial={[cardId]}>
+ *     <Entity>…</Entity>
+ *     <TransformHandles />
+ *   </Selection>
+ * </Stage>
+ * ```
+ */
+declare function TransformHandles({ showRotationHandle, showResizeHandles, enableTranslate, color, handleSize, }: TransformHandlesProps): react_jsx_runtime.JSX.Element | null;
+
+interface SnapOptions {
+    /**
+     * Grid cell size in world units. If set, points are snapped to the nearest
+     * multiple of `grid`. Can be a single number (uniform) or `{ x, y }`.
+     */
+    grid?: number | {
+        x: number;
+        y: number;
+    };
+    /**
+     * When true, snap to the edges/centers of other entities that have a Sprite or
+     * collider within `threshold` distance. Default false.
+     */
+    snapToEntities?: boolean;
+    /**
+     * Maximum distance in world units at which entity-edge snapping triggers.
+     * Default 8.
+     */
+    threshold?: number;
+    /**
+     * Entity IDs to exclude from entity snapping (e.g. the entity being dragged).
+     */
+    exclude?: EntityId[];
+}
+interface SnapResult {
+    x: number;
+    y: number;
+    /** True if the returned point was snapped (to grid or to an entity). */
+    snapped: boolean;
+    /** 'grid' | 'entity' | null, describing which snap fired. */
+    source: 'grid' | 'entity' | null;
+}
+interface SnapControls {
+    /** Snap a world-space point to the nearest grid cell and/or nearby entity edge. */
+    snap(x: number, y: number): SnapResult;
+    /** Snap just to the grid, ignoring any entity edges. */
+    snapToGrid(x: number, y: number): {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Returns snap helpers for puzzle games, level editors, and tile-based placement.
+ *
+ * @example
+ * ```tsx
+ * function DraggablePiece() {
+ *   const { snap } = useSnap({ grid: 32, snapToEntities: true, threshold: 6 })
+ *   const onDrag = (x: number, y: number) => {
+ *     const result = snap(x, y)
+ *     piece.x = result.x
+ *     piece.y = result.y
+ *   }
+ *   // …
+ * }
+ * ```
+ */
+declare function useSnap(options?: SnapOptions): SnapControls;
+
+interface EditableTextProps {
+    /** Current text value. */
+    value: string;
+    /** Called on every keystroke with the new value. */
+    onChange: (next: string) => void;
+    /** Called when the user presses Enter (single-line mode) or Ctrl+Enter (multiline). */
+    onSubmit?: (value: string) => void;
+    /** Called when the input loses focus. */
+    onBlur?: (value: string) => void;
+    /** Width of the input in world units. Default 200. */
+    width?: number;
+    /** Height of the input in world units. Default 40. */
+    height?: number;
+    /** Font size in world units. Default 16. */
+    fontSize?: number;
+    /** CSS font family. Default 'inherit'. */
+    fontFamily?: string;
+    /** Text color. Default '#ffffff'. */
+    color?: string;
+    /** Background color. Default 'transparent'. */
+    background?: string;
+    /** Border. Default 'none'. */
+    border?: string;
+    /** Padding in CSS pixels. Default 4. */
+    padding?: number;
+    /** Text alignment. Default 'left'. */
+    align?: 'left' | 'center' | 'right';
+    /** Placeholder text when empty. */
+    placeholder?: string;
+    /** Maximum number of characters. */
+    maxLength?: number;
+    /** If true, renders a `<textarea>` instead of an `<input>`. */
+    multiline?: boolean;
+    /** If true, the input auto-focuses when mounted. */
+    autoFocus?: boolean;
+    /** Disable the input. */
+    disabled?: boolean;
+}
+/**
+ * A canvas-positioned editable text field backed by a real HTML `<input>` or
+ * `<textarea>` overlaid on the game canvas. Position follows the entity's
+ * Transform and the active Camera2D every frame.
+ *
+ * Essential for word games, name entry, level editor labels, form-shaped UIs,
+ * and anywhere you'd otherwise try to reinvent text input inside WebGL.
+ *
+ * @example
+ * ```tsx
+ * function NameCard({ name, setName }: { name: string; setName: (s: string) => void }) {
+ *   return (
+ *     <Entity>
+ *       <Transform x={100} y={100} />
+ *       <EditableText
+ *         value={name}
+ *         onChange={setName}
+ *         width={220}
+ *         height={40}
+ *         background="#1e2a3a"
+ *         color="#e0e7f1"
+ *         placeholder="Your name"
+ *         autoFocus
+ *       />
+ *     </Entity>
+ *   )
+ * }
+ * ```
+ */
+declare function EditableText({ value, onChange, onSubmit, onBlur, width, height, fontSize, fontFamily, color, background, border, padding, align, placeholder, maxLength, multiline, autoFocus, disabled, }: EditableTextProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Snapshot utilities that capture the current canvas to an image. Useful for:
+ * - "Save your creation" / "Share" features in puzzle games and editors
+ * - Thumbnails of user-created levels
+ * - Automated test fixtures
+ * - Social media share cards
+ *
+ * All helpers work with both WebGL2 and Canvas 2D contexts (the underlying
+ * `canvas.toBlob` / `canvas.toDataURL` APIs are context-agnostic).
+ *
+ * **Important**: For WebGL contexts, you must call these helpers *immediately*
+ * after the render tick, while the framebuffer still contains the rendered
+ * frame. Between frames the browser may clear the WebGL drawing buffer.
+ */
+interface ExportOptions {
+    /** Image MIME type. Default 'image/png'. */
+    type?: 'image/png' | 'image/jpeg' | 'image/webp';
+    /** Quality (0–1) for jpeg/webp. Ignored for png. Default 0.92. */
+    quality?: number;
+    /**
+     * Optional region to crop, in CSS pixels relative to the canvas top-left.
+     * If omitted, the whole canvas is exported.
+     */
+    region?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /**
+     * Scale multiplier. 1 = source resolution. 2 = double (useful for HiDPI exports).
+     * Default 1.
+     */
+    scale?: number;
+}
+/**
+ * Capture the current canvas content to a Blob. Resolves to `null` if the browser
+ * refuses the encode (very rare — usually only on dead contexts).
+ *
+ * Must be called immediately after a render tick for WebGL canvases. In onDemand
+ * loop mode, call `engine.loop.markDirty()` and then export from within the next
+ * `requestAnimationFrame` to guarantee a fresh frame.
+ *
+ * @example
+ * ```ts
+ * const blob = await exportToBlob(engine.canvas, { type: 'image/png' })
+ * if (blob) {
+ *   const url = URL.createObjectURL(blob)
+ *   window.open(url)
+ * }
+ * ```
+ */
+declare function exportToBlob(canvas: HTMLCanvasElement, options?: ExportOptions): Promise<Blob | null>;
+/**
+ * Capture the current canvas content to a base64 data URL. Synchronous.
+ *
+ * @example
+ * ```ts
+ * const dataUrl = exportToDataURL(engine.canvas, { type: 'image/jpeg', quality: 0.8 })
+ * const img = new Image()
+ * img.src = dataUrl
+ * ```
+ */
+declare function exportToDataURL(canvas: HTMLCanvasElement, options?: ExportOptions): string;
+/**
+ * Capture the canvas and trigger a browser download. Convenience wrapper around
+ * {@link exportToBlob} + an anchor click.
+ *
+ * @example
+ * ```ts
+ * await downloadCanvas(engine.canvas, 'my-puzzle.png')
+ * ```
+ */
+declare function downloadCanvas(canvas: HTMLCanvasElement, filename: string, options?: ExportOptions): Promise<void>;
+
+interface A11yNodeProps {
+    /**
+     * Accessible label read by screen readers. Required — this is what the user
+     * will hear when the element is focused.
+     */
+    label: string;
+    /** Optional longer description (maps to aria-description). */
+    description?: string;
+    /**
+     * ARIA role. Defaults to 'button' if `onActivate` is provided, else 'presentation'.
+     * Common values: 'button', 'checkbox', 'link', 'img', 'listitem', 'option'.
+     */
+    role?: string;
+    /**
+     * Called when the user activates the element (click, Enter, or Space).
+     * If provided, the element becomes keyboard focusable and gains role='button'.
+     */
+    onActivate?: (entityId: EntityId) => void;
+    /** Controls tab order. Default 0 (natural order), or -1 to skip. */
+    tabIndex?: number;
+    /** ARIA pressed state for toggle buttons. */
+    pressed?: boolean;
+    /** ARIA checked state for checkboxes/switches. */
+    checked?: boolean;
+    /** ARIA disabled state. */
+    disabled?: boolean;
+    /** ARIA selected state for list options. */
+    selected?: boolean;
+    /** Override the element's bounding box in world units. If omitted, derived from Sprite/BoxCollider/CircleCollider. */
+    bounds?: {
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Mirrors the parent {@link Entity} into a focusable, screen-reader-friendly
+ * DOM element positioned over the canvas. Enables keyboard navigation and
+ * accessibility for puzzle games, turn-based games, and any scene where the
+ * canvas content has meaningful structure.
+ *
+ * The element is visually hidden (clipped to 1px) but focusable and in the
+ * document flow, so screen readers announce it and Tab cycles through it. When
+ * focused, it dispatches `onActivate(entityId)` on click, Enter, or Space.
+ *
+ * @example
+ * ```tsx
+ * <Entity>
+ *   <Transform x={100} y={100} />
+ *   <Sprite src="red-pawn.png" width={48} height={48} />
+ *   <A11yNode
+ *     label="Red pawn at E4"
+ *     description="Press Enter to select"
+ *     onActivate={(id) => selectPawn(id)}
+ *   />
+ * </Entity>
+ * ```
+ */
+declare function A11yNode({ label, description, role, onActivate, tabIndex, pressed, checked, disabled, selected, bounds, }: A11yNodeProps): react_jsx_runtime.JSX.Element | null;
+
+interface VectorPathProps {
+    /**
+     * SVG path data (the `d` attribute). Supports the full SVG path syntax including
+     * cubic and quadratic beziers, arcs, and close commands.
+     *
+     * Coordinates are in world units relative to the parent entity's Transform.
+     *
+     * @example `M0,0 C10,-20 40,-20 50,0`
+     */
+    d: string;
+    /** Stroke color. Default '#ffffff'. */
+    stroke?: string;
+    /** Stroke width in world units. Default 2. */
+    strokeWidth?: number;
+    /** Stroke dash pattern, e.g. '4 2'. */
+    strokeDasharray?: string;
+    /** Line cap style. Default 'round'. */
+    strokeLinecap?: 'butt' | 'round' | 'square';
+    /** Line join style. Default 'round'. */
+    strokeLinejoin?: 'miter' | 'round' | 'bevel';
+    /** Fill color. Default 'none' (no fill). */
+    fill?: string;
+    /** Fill rule. Default 'nonzero'. */
+    fillRule?: 'nonzero' | 'evenodd';
+    /** Opacity (0–1). Default 1. */
+    opacity?: number;
+    /** Hide the path. */
+    visible?: boolean;
+}
+/**
+ * A vector path (cubic/quadratic beziers, arcs, polylines) positioned in world
+ * space and rendered as a DOM SVG overlay above the game canvas.
+ *
+ * Follows the parent {@link Entity}'s Transform and the active {@link Camera2D}
+ * every frame, so zoom/pan work automatically. Accepts the full SVG path syntax
+ * in the `d` prop.
+ *
+ * **Trade-off**: Because this is a DOM overlay (not a WebGL draw), paths do not
+ * participate in the post-process stack (vignette, scanlines, chromatic
+ * aberration, etc.) and always render above all sprites. If you need paths to
+ * be affected by post-FX or z-ordered with sprites, rasterize your artwork into
+ * an image and use `<Sprite>` instead.
+ *
+ * @example
+ * ```tsx
+ * <Entity>
+ *   <Transform x={100} y={100} />
+ *   <VectorPath
+ *     d="M 0 0 C 20 -40, 60 -40, 80 0 S 140 40, 160 0"
+ *     stroke="#4fc3f7"
+ *     strokeWidth={3}
+ *     fill="none"
+ *   />
+ * </Entity>
+ * ```
+ */
+declare function VectorPath({ d, stroke, strokeWidth, strokeDasharray, strokeLinecap, strokeLinejoin, fill, fillRule, opacity, visible, }: VectorPathProps): react_jsx_runtime.JSX.Element | null;
+
+interface GridOptions<T> {
+    /** Number of columns. */
+    width: number;
+    /** Number of rows. */
+    height: number;
+    /**
+     * Default cell value. Can be a plain value (each cell shares the reference) or a
+     * factory `(x, y) => T` called for each cell during initialization.
+     */
+    fill: T | ((x: number, y: number) => T);
+}
+interface GridCell<T> {
+    x: number;
+    y: number;
+    value: T;
+}
+interface GridControls<T> {
+    width: number;
+    height: number;
+    /** Read a cell value. Returns undefined for out-of-bounds coords. */
+    get(x: number, y: number): T | undefined;
+    /** Write a cell value. No-op for out-of-bounds coords. */
+    set(x: number, y: number, value: T): void;
+    /** True if (x, y) is within the grid bounds. */
+    inBounds(x: number, y: number): boolean;
+    /** Swap the values of two cells. */
+    swap(ax: number, ay: number, bx: number, by: number): void;
+    /** Iterate over every cell. */
+    forEach(cb: (cell: GridCell<T>) => void): void;
+    /** Find the first cell matching a predicate. */
+    find(pred: (cell: GridCell<T>) => boolean): GridCell<T> | undefined;
+    /** Count the cells matching a predicate. */
+    count(pred: (cell: GridCell<T>) => boolean): number;
+    /**
+     * Return the 4-neighborhood (N/E/S/W) or 8-neighborhood (including diagonals)
+     * of a cell, as `{ x, y, value }` entries. Out-of-bounds neighbors are omitted.
+     */
+    neighbors(x: number, y: number, diagonal?: boolean): GridCell<T>[];
+    /** Reset every cell to a new value (or factory). */
+    fill(value: T | ((x: number, y: number) => T)): void;
+    /** Deep-copy the grid as a 2D array `arr[y][x]`. */
+    toArray(): T[][];
+    /** Replace the entire grid contents from a 2D array. */
+    fromArray(arr: T[][]): void;
+}
+/**
+ * A reactive 2D board state for puzzle and turn-based games. Calls to `set`,
+ * `swap`, `fill`, and `fromArray` trigger a re-render and call
+ * `engine.loop.markDirty()`, so in onDemand mode the canvas updates automatically.
+ *
+ * The underlying storage is a flat array indexed `y * width + x`.
+ *
+ * @example
+ * ```tsx
+ * type Tile = 'empty' | 'wall' | 'box'
+ *
+ * function Sokoban() {
+ *   const board = useGrid<Tile>({ width: 10, height: 10, fill: 'empty' })
+ *   board.set(1, 1, 'wall')
+ *   const walls = board.count((c) => c.value === 'wall')
+ *   // render by iterating board.forEach(...)
+ * }
+ * ```
+ */
+declare function useGrid<T>({ width, height, fill }: GridOptions<T>): GridControls<T>;
+
+interface TurnSystemOptions<P> {
+    /** Ordered list of player identifiers. Must contain at least one. */
+    players: P[];
+    /** Index of the player who starts. Default 0. */
+    initialIndex?: number;
+    /** Called every time the active player changes, *after* the change is applied. */
+    onTurnStart?: (info: {
+        player: P;
+        index: number;
+        turn: number;
+    }) => void;
+    /** Called just before the active player changes. */
+    onTurnEnd?: (info: {
+        player: P;
+        index: number;
+        turn: number;
+    }) => void;
+    /**
+     * When non-zero, `nextTurn()` delays the player switch by this many seconds.
+     * Useful for letting AI moves animate before the control is handed back.
+     * Default 0 (instant).
+     */
+    aiDelay?: number;
+}
+interface TurnSystemControls<P> {
+    /** The currently active player. */
+    activePlayer: P;
+    /** The index of the currently active player. */
+    activeIndex: number;
+    /** Turn counter — increments every time the active player changes. Starts at 0. */
+    turn: number;
+    /** Advance to the next player in the list. Wraps around at the end. */
+    nextTurn(): void;
+    /** Go back to the previous player. */
+    prevTurn(): void;
+    /** Jump directly to a specific player by index or identifier. */
+    skipTo(target: number | P): void;
+    /** Reset the system to its initial state. */
+    reset(): void;
+    /** True while an `aiDelay` is pending between `nextTurn()` being called and the switch. */
+    isPending: boolean;
+}
+/**
+ * Turn manager for turn-based games (chess, cards, strategy). Tracks the active
+ * player, fires lifecycle callbacks, and supports an optional delay before
+ * handing control back — useful when an AI player makes a move and you want the
+ * animation to finish before the next player can act.
+ *
+ * @example
+ * ```tsx
+ * function Chess() {
+ *   const turns = useTurnSystem<'white' | 'black'>({
+ *     players: ['white', 'black'],
+ *     aiDelay: 0.5,
+ *     onTurnStart: ({ player }) => console.log(`${player}'s move`),
+ *   })
+ *
+ *   const onMoveMade = () => {
+ *     // apply the move...
+ *     turns.nextTurn()
+ *   }
+ * }
+ * ```
+ */
+declare function useTurnSystem<P>({ players, initialIndex, onTurnStart, onTurnEnd, aiDelay, }: TurnSystemOptions<P>): TurnSystemControls<P>;
+
+interface HoverableOptions {
+    /** Override the entity ID to hit-test. Defaults to the surrounding <Entity> context. */
+    entityId?: EntityId;
+    /**
+     * Custom bounds in world units. If omitted, derived from Sprite → BoxCollider →
+     * CircleCollider on the target entity.
+     */
+    bounds?: {
+        width: number;
+        height: number;
+    };
+    /** Called once when the pointer enters the entity. */
+    onEnter?: (id: EntityId) => void;
+    /** Called once when the pointer leaves the entity. */
+    onLeave?: (id: EntityId) => void;
+    /** Disable hover tracking entirely. */
+    disabled?: boolean;
+}
+interface HoverableControls {
+    /** True while the pointer is over the entity's bounding box. */
+    isHovered: boolean;
+}
+/**
+ * Reactive "is the pointer over this entity?" state. Hit-tests against the
+ * entity's Sprite / BoxCollider / CircleCollider bounds every pointermove,
+ * respecting the active Camera2D zoom and pan.
+ *
+ * Calls `engine.loop.markDirty()` on state change, so in onDemand mode the
+ * canvas re-renders automatically (useful for "highlight under cursor" effects).
+ *
+ * @example
+ * ```tsx
+ * function Card() {
+ *   const { isHovered } = useHoverable({
+ *     onEnter: (id) => console.log('enter', id),
+ *   })
+ *   return (
+ *     <Entity>
+ *       <Transform x={100} y={100} />
+ *       <Sprite src="card.png" width={80} height={120} opacity={isHovered ? 1 : 0.8} />
+ *     </Entity>
+ *   )
+ * }
+ * ```
+ */
+declare function useHoverable(options?: HoverableOptions): HoverableControls;
+
+interface DraggableOptions {
+    /** Override the entity ID to drag. Defaults to the surrounding <Entity> context. */
+    entityId?: EntityId;
+    /**
+     * A "tag" string that droppables can filter on via their `accepts` list.
+     * E.g. `tag: 'card'` + droppable `accepts: ['card', 'token']`.
+     */
+    tag?: string;
+    /** Constrain dragging to a world-space rectangle. */
+    bounds?: {
+        minX: number;
+        minY: number;
+        maxX: number;
+        maxY: number;
+    };
+    /**
+     * Optional snap control from {@link useSnap}. While dragging, the entity's
+     * position will be passed through `snap.snap(x, y)` before being written back.
+     */
+    snap?: SnapControls;
+    /** Called when the drag begins. */
+    onDragStart?: (info: {
+        entityId: EntityId;
+        x: number;
+        y: number;
+    }) => void;
+    /** Called on every pointermove during the drag. */
+    onDrag?: (info: {
+        entityId: EntityId;
+        x: number;
+        y: number;
+    }) => void;
+    /** Called when the drag ends (pointerup). */
+    onDragEnd?: (info: {
+        entityId: EntityId;
+        x: number;
+        y: number;
+        droppedOn: EntityId | null;
+    }) => void;
+    /** Disable dragging. */
+    disabled?: boolean;
+}
+interface DraggableControls {
+    /** True while a drag is in progress on this entity. */
+    isDragging: boolean;
+    /** Current world-space position of the dragged entity. */
+    position: {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Pointer-driven drag for an entity. Attach to any entity with a Transform and
+ * a Sprite/BoxCollider/CircleCollider (for hit-testing the initial grab).
+ *
+ * On pointerdown over the entity's bounds, dragging begins. Subsequent
+ * pointermoves update the entity's Transform. On pointerup, the drag ends and
+ * the `droppedOn` field of {@link onDragEnd} reports which {@link useDroppable}
+ * (if any) is under the pointer.
+ *
+ * @example
+ * ```tsx
+ * function Card() {
+ *   const snap = useSnap({ grid: 32 })
+ *   const { isDragging } = useDraggable({ snap, tag: 'card' })
+ *   return (
+ *     <Entity>
+ *       <Transform x={100} y={100} />
+ *       <Sprite src="card.png" width={64} height={96} opacity={isDragging ? 0.6 : 1} />
+ *     </Entity>
+ *   )
+ * }
+ * ```
+ */
+declare function useDraggable(options?: DraggableOptions): DraggableControls;
+interface DroppableOptions {
+    /** Override the entity ID acting as the drop zone. Defaults to <Entity> context. */
+    entityId?: EntityId;
+    /**
+     * Tags this zone will accept. If omitted, accepts any drag. If set, only drags
+     * whose `useDraggable` was configured with a matching `tag` can land here.
+     */
+    accepts?: string[];
+    /** Override the drop-zone bounds in world units. */
+    bounds?: {
+        width: number;
+        height: number;
+    };
+    /** Called when an acceptable drag is released over this zone. */
+    onDrop?: (info: {
+        droppedEntityId: EntityId;
+        x: number;
+        y: number;
+    }) => void;
+    /** Called when an acceptable drag enters the zone. */
+    onEnter?: (info: {
+        droppedEntityId: EntityId;
+    }) => void;
+    /** Called when an acceptable drag leaves the zone. */
+    onLeave?: (info: {
+        droppedEntityId: EntityId;
+    }) => void;
+    /** Disable this drop zone. */
+    disabled?: boolean;
+}
+interface DroppableControls {
+    /** True while an acceptable drag is hovering over this zone. */
+    isOver: boolean;
+    /** The entity ID of the drag currently hovering, or null. */
+    hoveredBy: EntityId | null;
+}
+/**
+ * A drop zone for drag-and-drop. Pair with {@link useDraggable} to build
+ * puzzle games, card games, inventory systems, level editors, and more.
+ *
+ * @example
+ * ```tsx
+ * function Foundation() {
+ *   const { isOver } = useDroppable({
+ *     accepts: ['card'],
+ *     onDrop: ({ droppedEntityId }) => placeCard(droppedEntityId),
+ *   })
+ *   return (
+ *     <Entity>
+ *       <BoxCollider width={80} height={120} />
+ *       <Sprite color={isOver ? '#4fc3f7' : '#333'} width={80} height={120} />
+ *     </Entity>
+ *   )
+ * }
+ * ```
+ */
+declare function useDroppable(options?: DroppableOptions): DroppableControls;
+
+interface FocusableOptions {
+    /** Called when this entity gains keyboard focus. */
+    onFocus?: (id: EntityId) => void;
+    /** Called when this entity loses keyboard focus. */
+    onBlur?: (id: EntityId) => void;
+    /** Called when the user activates this entity (Enter/Space). */
+    onActivate?: (id: EntityId) => void;
+    /** If true and nothing else is focused when this mounts, take initial focus. */
+    autoFocus?: boolean;
+}
+/**
+ * Register an entity as keyboard-focusable. Pair with {@link useKeyboardFocus}
+ * and optionally {@link FocusRing} for a full accessible keyboard navigation
+ * flow. Arrow keys move focus to the spatially-nearest registered entity in
+ * the arrow's direction; Enter and Space trigger `onActivate`.
+ *
+ * @example
+ * ```tsx
+ * function Card({ id }: { id: number }) {
+ *   useFocusable({ onActivate: () => selectCard(id) })
+ *   return <Entity id={id}>…</Entity>
+ * }
+ * ```
+ */
+declare function useFocusable(options?: FocusableOptions): void;
+interface KeyboardFocusControls {
+    /** The currently focused entity ID, or null. */
+    focused: EntityId | null;
+    /** Manually set focus to a specific entity. */
+    focus(id: EntityId | null): void;
+    /** Move focus to the next registered entity (insertion order). */
+    next(): void;
+    /** Move focus to the previous registered entity. */
+    prev(): void;
+    /** Move focus in a world-space direction using spatial nearest-neighbor. */
+    move(direction: 'up' | 'down' | 'left' | 'right'): void;
+    /** Activate the currently focused entity (fires its `onActivate`). */
+    activate(): void;
+}
+/**
+ * Keyboard-driven focus navigation across all {@link useFocusable} entities in
+ * the scene. Arrow keys move focus spatially (nearest neighbor in the arrow's
+ * direction), Tab/Shift+Tab cycles through registration order, and Enter/Space
+ * activates the focused entity.
+ *
+ * @example
+ * ```tsx
+ * function Board() {
+ *   useKeyboardFocus() // arrow keys automatically move between cards
+ *   return (
+ *     <>
+ *       <FocusRing />
+ *       <Card id={1} />
+ *       <Card id={2} />
+ *     </>
+ *   )
+ * }
+ * ```
+ */
+declare function useKeyboardFocus(): KeyboardFocusControls;
+
+interface FocusRingProps {
+    /** Ring color. Default '#4fc3f7'. */
+    color?: string;
+    /** Ring width in CSS pixels. Default 3. */
+    width?: number;
+    /** Extra padding around the entity bounds in CSS pixels. Default 4. */
+    padding?: number;
+    /** Border radius in CSS pixels. Default 4. */
+    borderRadius?: number;
+    /** Show a pulsing animation. Default true. */
+    pulse?: boolean;
+}
+/**
+ * Visual indicator of the currently keyboard-focused entity. Pairs with
+ * {@link useKeyboardFocus} and {@link useFocusable} to provide a full sighted
+ * keyboard navigation experience.
+ *
+ * Renders as a DOM overlay outline that tracks the focused entity's Transform
+ * and bounds. Respects `prefers-reduced-motion` (disables the pulse when set).
+ *
+ * @example
+ * ```tsx
+ * <Stage>
+ *   <FocusRing color="#4fc3f7" />
+ *   {/* cards that use useFocusable() *\/}
+ * </Stage>
+ * ```
+ */
+declare function FocusRing({ color, width, padding, borderRadius, pulse, }: FocusRingProps): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Scene save/load helpers. Thin wrappers around the ECS snapshot API that
+ * handle JSON serialization and localStorage persistence for editors,
+ * "save your creation" features, and quick dev-time checkpoints.
+ *
+ * For full-featured game saves that include non-ECS state (audio settings,
+ * progression flags, player profiles), use {@link useSave} or {@link useIDBSave}
+ * from `cubeforge`.
+ */
+interface SceneSaveOptions {
+    /** Pretty-print the JSON output. Default false. */
+    pretty?: boolean;
+}
+/**
+ * Serialize the entire ECS world to a JSON string. The returned string can be
+ * passed back to {@link loadScene} to restore the exact same state.
+ *
+ * @example
+ * ```ts
+ * const json = saveScene(engine)
+ * localStorage.setItem('my-level', json)
+ * ```
+ */
+declare function saveScene(engine: EngineState, options?: SceneSaveOptions): string;
+/**
+ * Restore the ECS world from a JSON string previously produced by
+ * {@link saveScene}. Clears the current world state before applying. In
+ * onDemand loop mode, automatically calls `markDirty()` to re-render.
+ *
+ * Throws if the input isn't valid JSON or doesn't match the snapshot shape.
+ *
+ * @example
+ * ```ts
+ * const json = localStorage.getItem('my-level')
+ * if (json) loadScene(engine, json)
+ * ```
+ */
+declare function loadScene(engine: EngineState, json: string): void;
+/**
+ * Save the current scene to `localStorage` under the given key. Returns true
+ * on success, false if the browser rejected the write (quota exceeded,
+ * incognito mode, or localStorage unavailable).
+ *
+ * @example
+ * ```ts
+ * if (saveSceneToLocalStorage(engine, 'my-game:autosave')) {
+ *   toast.show('Saved!')
+ * }
+ * ```
+ */
+declare function saveSceneToLocalStorage(engine: EngineState, key: string, options?: SceneSaveOptions): boolean;
+/**
+ * Load a scene previously saved with {@link saveSceneToLocalStorage}. Returns
+ * true if a scene was found and successfully loaded, false otherwise.
+ *
+ * @example
+ * ```ts
+ * if (!loadSceneFromLocalStorage(engine, 'my-game:autosave')) {
+ *   // No autosave — start fresh
+ *   seedInitialScene(engine)
+ * }
+ * ```
+ */
+declare function loadSceneFromLocalStorage(engine: EngineState, key: string): boolean;
+/**
+ * Delete a saved scene from localStorage. Returns true if anything was deleted.
+ */
+declare function deleteSavedScene(key: string): boolean;
+/**
+ * List all scene keys saved via {@link saveSceneToLocalStorage} that match a
+ * prefix. Useful for implementing a "load slot" picker.
+ *
+ * @example
+ * ```ts
+ * const slots = listSavedScenes('my-game:')
+ * // → ['my-game:slot1', 'my-game:slot2', 'my-game:autosave']
+ * ```
+ */
+declare function listSavedScenes(prefix?: string): string[];
+
 declare function playClip(world: ECSWorld, entityId: EntityId, clipName: string): void;
 declare function setAnimationState(world: ECSWorld, entityId: EntityId, stateName: string): void;
 declare function setAnimatorParam(world: ECSWorld, entityId: EntityId, name: string, value: AnimatorParamValue): void;
@@ -2106,4 +3202,4 @@ declare function useRemotePlayer(config: {
     opts?: RemotePlayerOptions;
 }): RemotePlayerControls;
 
-export { type AccessibilityControls, AnimatedSprite, type AnimatedSpriteProps, Animation, type AnimationSet, Animator, AssetLoader, type BoundInputMap, BoxCollider, Camera2D, type CameraControls, type CameraLookaheadOptions, CameraZone, CapsuleCollider, Checkpoint, Circle, CircleCollider, type ComboDetectorResult, CompoundCollider, ConvexCollider, type CoordinateHelpers, type CoroutineControls, type CoroutineFactory, type CoroutineYield, Entity, Game, type GameControls, type GamepadState, type GestureHandlers, type GestureOptions, Gradient, type HMRControls, HalfSpaceCollider, HeightFieldCollider, type InputContextControls, Joint, Line, Mask, MovingPlatform, type NetworkSyncOptions, NineSlice, ParallaxLayer, ParticleEmitter, type ParticlePreset, type PauseControls, type PinchEvent, Polygon, type PreloadState, type ProfilerData, type RemotePlayerControls, type RemotePlayerOptions, RigidBody, type SceneManagerControls, ScreenFlash, type ScreenFlashHandle, Script, SegmentCollider, type SnapshotControls, Sprite, type SpriteAtlas, SquashStretch, type SquashStretchControls, type SwipeEvent, Text, type TiledLayer, type TiledObject, Tilemap, type TimerControls, type TouchControls, Trail, Transform, TriMeshCollider, TriangleCollider, type VirtualInputState, VirtualJoystick, type VirtualJoystickProps, type Waypoint, World, createAtlas, defineAnimations, definePrefab, playClip, setAnimationState, setAnimatorParam, useAccessibility, useAudioListener, useCamera, useCameraLookahead, useComboDetector, useCoordinates, useCoroutine, useDestroyEntity, useEntity, useEvent, useEvents, useGame, useGamepad, useGamepadHaptics, useGestures, useHMR, useInput, useInputBuffer, useInputContext, useInputMap, useInputRecorder, useLocalMultiplayer, useNetworkSync, useParent, usePause, usePlayerInput, usePostProcess, usePreload, useProfiler, useRemotePlayer, useSceneManager, useSnapshot, useSquashStretch, useTimer, useTouch, useVirtualInput, useWebGLPostProcess, useWorldQuery, wait, waitFrames, waitUntil };
+export { A11yNode, type A11yNodeProps, type AccessibilityControls, AnimatedSprite, type AnimatedSpriteProps, Animation, type AnimationSet, Animator, AssetLoader, type BoundInputMap, BoxCollider, Camera2D, type CameraControls, type CameraLookaheadOptions, CameraZone, CapsuleCollider, Checkpoint, Circle, CircleCollider, type ComboDetectorResult, CompoundCollider, ConvexCollider, type CoordinateHelpers, type CoroutineControls, type CoroutineFactory, type CoroutineYield, type DraggableControls, type DraggableOptions, type DroppableControls, type DroppableOptions, EditableText, type EditableTextProps, Entity, type ExportOptions, FocusRing, type FocusRingProps, type FocusableOptions, Game, type GameControls, type GamepadState, type GestureHandlers, type GestureOptions, Gradient, type GridCell, type GridControls, type GridOptions, type HMRControls, HalfSpaceCollider, HeightFieldCollider, type HistoryControls, type HistoryOptions, type HoverableControls, type HoverableOptions, type InputContextControls, Joint, type KeyboardFocusControls, Line, Mask, MovingPlatform, type NetworkSyncOptions, NineSlice, ParallaxLayer, ParticleEmitter, type ParticlePreset, type PauseControls, type PinchEvent, Polygon, type PreloadState, type ProfilerData, type RemotePlayerControls, type RemotePlayerOptions, RigidBody, type SceneManagerControls, type SceneSaveOptions, type SceneTransitionControls, SceneTransitionOverlay, ScreenFlash, type ScreenFlashHandle, Script, SegmentCollider, type SelectOptions, Selection, type SelectionControls, type SelectionProps, type SnapControls, type SnapOptions, type SnapResult, type SnapshotControls, Sprite, type SpriteAtlas, SquashStretch, type SquashStretchControls, Stage, type SwipeEvent, Text, type TiledLayer, type TiledObject, Tilemap, type TimerControls, type TouchControls, Trail, Transform, TransformHandles, type TransformHandlesProps, type TransitionEffect, TriMeshCollider, TriangleCollider, type TurnSystemControls, type TurnSystemOptions, VectorPath, type VectorPathProps, type VirtualInputState, VirtualJoystick, type VirtualJoystickProps, type Waypoint, World, createAtlas, defineAnimations, definePrefab, deleteSavedScene, downloadCanvas, exportToBlob, exportToDataURL, listSavedScenes, loadScene, loadSceneFromLocalStorage, playClip, saveScene, saveSceneToLocalStorage, setAnimationState, setAnimatorParam, useAccessibility, useAudioListener, useCamera, useCameraLookahead, useComboDetector, useCoordinates, useCoroutine, useDestroyEntity, useDraggable, useDroppable, useEntity, useEvent, useEvents, useFocusable, useGame, useGamepad, useGamepadHaptics, useGestures, useGrid, useHMR, useHistory, useHitstop, useHoverable, useInput, useInputBuffer, useInputContext, useInputMap, useInputRecorder, useKeyboardFocus, useLocalMultiplayer, useNetworkSync, useParent, usePause, usePlayerInput, usePostProcess, usePreload, useProfiler, useRemotePlayer, useSceneManager, useSceneTransition, useSelection, useSnap, useSnapshot, useSquashStretch, useTimer, useTouch, useTurnSystem, useVirtualInput, useWebGLPostProcess, useWorldQuery, wait, waitFrames, waitUntil };