incanto 0.1.0

package/dist/2d.d.ts

@@ -0,0 +1,642 @@
+import { s as JsonObject } from "./schema-CcoWb32N.js";
+import { C as RendererStats, S as GameStats, T as Node, b as Scheduler, l as PropSchema, n as BehaviorCtor, v as Engine, w as Scene$1 } from "./behavior-BAQq7HGM.js";
+import { t as LoadSceneOptions } from "./loader-Mo0KghCv.js";
+import { t as ParticleSim } from "./particle-sim-CbN4YUuH.js";
+import { Group, Mesh, Object3D, Scene, Texture } from "three";
+import * as RapierNs from "@dimforge/rapier2d-compat";
+
+//#region src/2d/assets.d.ts
+type AssetStatus = "loading" | "ready" | "error";
+interface TextureLoadCallbacks {
+  onLoad?: () => void;
+  onError?: (error: unknown) => void;
+}
+interface SheetInfo {
+  texture: Texture;
+  frameWidth: number;
+  frameHeight: number;
+}
+/**
+* String-keyed asset registry for the 2D layer (Phaser's loader model).
+*
+* Scene JSON declares assets under stable keys; node props reference them as
+* `"$key"`. The texture loader is injectable so tests run headless.
+*/
+declare class AssetStore2D {
+  private readonly entries;
+  private readonly loader;
+  constructor(loader?: (url: string, callbacks?: TextureLoadCallbacks) => Texture);
+  /** Load (or extend with) a scene's `assets` declarations. Hard-validates each entry. */
+  load(assets: Record<string, JsonObject>): void;
+  /** Load status of a declared asset KEY (no '$'), or undefined if unknown. */
+  status(key: string): AssetStatus | undefined;
+  getTexture(ref: string): Texture;
+  getSheet(ref: string): SheetInfo;
+  private resolve;
+}
+//#endregion
+//#region src/2d/nodes/node-2d.d.ts
+/**
+* Base of every 2D node. Convention (Phaser/Godot prior):
+* **1 unit = 1 px, +y DOWN, (0,0) top-left, positive rotation = clockwise.**
+* Internally mapped onto three's y-up space by negating y and the z-spin.
+*/
+declare class Node2D extends Node {
+  static override readonly typeName: string;
+  static readonly props: PropSchema;
+  /** Legacy alias: old 2D scenes (and `zIndex`-trained agents) keep loading —
+  * `zIndex` resolves to `renderOrder` at load. The schema exposes only
+  * `renderOrder` so 2D and 3D share ONE render-order name. */
+  static readonly propAliases: Record<string, string>;
+  /** Pixels, y-down. */
+  position: number[];
+  /** Degrees, clockwise. */
+  rotation: number;
+  scale: number[];
+  /** Draw order among 2D drawables (higher = on top); matches 3D `renderOrder`. */
+  renderOrder: number;
+  visible: boolean;
+  private _object2D;
+  /** @internal The backing three object (lazily created). */
+  _ensureObject2D(): Object3D;
+  /** @internal Override point. */
+  protected _createObject2D(): Object3D;
+  /** @internal Push JSON props onto the backing object. Called every frame. */
+  _syncObject2D(_assets: AssetStore2D | null): void;
+  override free(): void;
+}
+//#endregion
+//#region src/2d/nodes/bodies-2d.d.ts
+/**
+* Shared base for physics-backed 2D nodes. Colliders are NODE PROPS:
+* `{shape:'rect', size:[w,h]}` · `{shape:'circle', radius}` ·
+* `{shape:'capsule', radius, height}` — never child shape nodes.
+*/
+declare class PhysicsBody2D extends Node2D {
+  static override readonly props: PropSchema;
+  /** The unified collision model: every collider participant can emit these. */
+  static override readonly signals: readonly string[];
+  collider: JsonObject;
+  /** Loader hook: bad collider shapes fail at LOAD, not at physics start. */
+  static validateJson(node: Node): void;
+  /** @internal Set by Physics2D when the body is created. */
+  _physics: Physics2D | null;
+}
+/** Immovable collider (ground, walls, platforms). */
+declare class StaticBody2D extends PhysicsBody2D {
+  static override readonly typeName: string;
+}
+/**
+* Sensor volume. Emits `triggerEnter(other)` / `triggerExit(other)` — the
+* unified collision model (solid bodies emit the same signals on contact).
+*/
+declare class Area2D extends PhysicsBody2D {
+  static override readonly typeName: string;
+}
+/** Dynamic simulated body. */
+declare class RigidBody2D extends PhysicsBody2D {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  mass: number;
+  gravityScale: number;
+  fixedRotation: boolean;
+  friction: number;
+  restitution: number;
+  /** px/s, y-down. Read back every step; write to launch. */
+  linearVelocity: number[];
+}
+/**
+* Kinematic body on Rapier's character controller. Gravity is NOT applied
+* automatically (Godot semantics) — integrate `velocity` yourself, then call
+* `moveAndSlide()` from `fixedUpdate`.
+*/
+declare class CharacterBody2D extends PhysicsBody2D {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  /** px/s, y-down (up = -y). */
+  velocity: number[];
+  /** Keep contact on slopes/steps while not moving upward. */
+  snapToGround: boolean;
+  /** Max climbable slope angle. */
+  slopeLimitDeg: number;
+  /** @internal Updated by Physics2D.moveAndSlide. */
+  _grounded: boolean;
+  moveAndSlide(): void;
+  isOnFloor(): boolean;
+}
+//#endregion
+//#region src/2d/physics/physics-2d.d.ts
+type Rapier = typeof RapierNs;
+interface Physics2DOptions {
+  /** px/s², y-down. Default: scene `physics.gravity`, else [0, 980]. */
+  gravity?: [number, number];
+}
+/**
+* Enable 2D physics for an engine. Dynamically imports Rapier (compat build,
+* wasm inlined) so games without physics never pay its bundle cost.
+*/
+declare function enablePhysics2D(engine: Engine, opts?: Physics2DOptions): Promise<Physics2D>;
+/**
+* Per-engine 2D physics world (y-down pixel space, consistent with Node2D).
+* Each fixedUpdate: sync tree → step world → write back → drain trigger events.
+*/
+declare class Physics2D {
+  private readonly R;
+  private readonly engine;
+  /** Render collider outlines in the GAME view (renderers pick this up). */
+  debugDraw: boolean;
+  readonly dimension = "2d";
+  private readonly unregisterDebug;
+  private readonly warnedNoCollider;
+  private readonly entries;
+  private readonly byColliderHandle;
+  private readonly world;
+  private readonly events;
+  private readonly kcc;
+  private readonly disconnect;
+  private lastDt;
+  private readonly optsGravity;
+  private lastScene;
+  constructor(R: Rapier, engine: Engine, opts?: Physics2DOptions);
+  /** @internal Driven by engine.fixedUpdated. */
+  step(dt: number): void;
+  /** @internal Called by CharacterBody2D.moveAndSlide (during tree fixedUpdate). */
+  moveAndSlide(node: CharacterBody2D): void;
+  /** Rapier debug segments, scaled back to pixels. Null while debugDraw is off. */
+  debugLines(): Float32Array | null;
+  dispose(): void;
+  private syncBodies;
+  private ensureEntry;
+}
+//#endregion
+//#region src/2d/create-game.d.ts
+/** Minimal keyboard event source (window, or anything shaped like it). */
+interface KeyboardTarget {
+  addEventListener: (t: string, cb: (e: KeyboardEvent) => void) => void;
+  removeEventListener: (t: string, cb: (e: KeyboardEvent) => void) => void;
+}
+interface CreateGame2DOptions {
+  canvas: HTMLCanvasElement;
+  /** Scene JSON (cloned internally — the same object can boot many games). */
+  scene: unknown;
+  /** Behavior classes to register (hot-replace tolerant). */
+  behaviors?: Record<string, BehaviorCtor>;
+  /**
+  * Auto-register the built-in `incanto/gameplay` behaviors (Health, Pickup,
+  * ScoreKeeper, …) — default true (batteries-included). They register BEFORE
+  * `behaviors`, so a same-named user behavior always wins. Set false to ship
+  * none of them.
+  */
+  gameplay?: boolean;
+  /**
+  * Keyboard source (default: window when available). `false` disables.
+  * Bound keys preventDefault; editable elements are ignored (see InputMap).
+  */
+  keyboard?: KeyboardTarget | false;
+  /** 'auto' (default): enable Rapier iff the tree has physics bodies. */
+  physics?: "auto" | boolean;
+  /**
+  * On-screen touch controls for the scene's `"touch"` input declarations:
+  * 'auto' (default) shows them on coarse-pointer devices, true forces them,
+  * false disables. They overlay `touchContainer` (default: the canvas's
+  * parent element — give it position: relative).
+  */
+  touch?: "auto" | boolean;
+  touchContainer?: HTMLElement;
+  /** @internal Test seam — replaces `document` for the touch overlay. */
+  _touchDoc?: {
+    createElement(tag: string): HTMLElement;
+  };
+  /**
+  * Mount the runtime debug overlay (`incanto/debug` — explorer/inspector/
+  * logs). Default: false (off), and there is NO URL/query toggle — a deployed
+  * build must never be switchable on by end users. Opt in via `debug`, gated
+  * to development, e.g. `debug: import.meta.env.VITE_INCANTO_DEBUG === '1'`.
+  */
+  debug?: boolean;
+  /** @internal Test seam — replaces `document` for the debug overlay. */
+  _debugDoc?: {
+    createElement(tag: string): HTMLElement;
+  };
+  seed?: number;
+  fixedHz?: number;
+  /** Renderer extras (pixelRatio, antialias, custom asset store). */
+  pixelRatio?: number;
+  antialias?: boolean;
+  resolveScene?: LoadSceneOptions["resolveScene"];
+  /** @internal Test seam — replaces the Renderer2D construction. */
+  _rendererFactory?: (engine: Engine, canvas: HTMLCanvasElement) => GameRenderer;
+  /** @internal Test seam — replaces the rAF scheduler. */
+  _scheduler?: Scheduler;
+}
+/** What createGame needs from a renderer (stats is optional for test stubs). */
+interface GameRenderer {
+  dispose(): void;
+  stats?(): RendererStats;
+}
+interface Game2D {
+  engine: Engine;
+  scene: Scene$1;
+  renderer: GameRenderer;
+  physics: Physics2D | null;
+  /** Engine + renderer perf counters in one read (fps/nodes/triangles/…). */
+  stats(): GameStats;
+  /** Tear the whole game down (renderer, loop, scene, listeners). */
+  dispose(): void;
+}
+/**
+* The one-call boot every game was hand-rolling: register → load (engine
+* attached, so onReady can use this.rng/this.log) → physics (auto-detected) →
+* input → renderer → start. The returned `dispose()` is the one-call
+* teardown for SPA unmounts. Audio unlocks on the first user gesture.
+*/
+declare function createGame2D(opts: CreateGame2DOptions): Promise<Game2D>;
+//#endregion
+//#region src/2d/library-sprite.d.ts
+interface SpriteFromLibraryResult {
+  /** Scene `assets{}` entry — put it under your chosen key. */
+  asset: JsonObject;
+  /** AnimatedSprite2D props (sheet/autoplay/animations) — ready to paste. */
+  props: JsonObject;
+}
+/**
+* Turn a library sprite-animation JSON into a scene-ready spritesheet asset
+* declaration + AnimatedSprite2D props. `autoplay` defaults to the first
+* LOOPING animation (idle-like), falling back to the first one.
+*/
+declare function spriteFromLibraryMeta(meta: unknown, opts: {
+  url: string;
+  assetKey: string;
+  autoplay?: string;
+}): SpriteFromLibraryResult;
+//#endregion
+//#region src/2d/nodes/sprite-2d.d.ts
+interface ResolvedSpriteTexture {
+  texture: Texture;
+  width: number;
+  height: number;
+}
+/**
+* A textured quad. The drawable is an inner mesh child of the node's backing
+* object, so node children never inherit the texture-size scaling.
+*/
+declare class Sprite2D extends Node2D {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  /** `'$assetKey'` texture reference. Empty = hidden. */
+  texture: string;
+  /** [0,0] = top-left on the origin … [1,1] = bottom-right on the origin. */
+  anchor: number[];
+  flipX: boolean;
+  flipY: boolean;
+  tint: string;
+  opacity: number;
+  private quadMesh;
+  /** @internal The drawable quad (lazily created, attached under the backing object). */
+  _quad(): Mesh;
+  protected override _createObject2D(): Object3D;
+  /** Override point: AnimatedSprite2D substitutes its frame window here. */
+  protected resolveTexture(assets: AssetStore2D | null): ResolvedSpriteTexture | null;
+  override _syncObject2D(assets: AssetStore2D | null): void;
+}
+//#endregion
+//#region src/2d/nodes/animated-sprite-2d.d.ts
+interface AnimationDef {
+  /**
+  * Two numbers = inclusive [start, end] frame RANGE.
+  * Any other length = explicit frame list.
+  */
+  frames: number[];
+  fps: number;
+  loop?: boolean;
+}
+/**
+* Spritesheet animation: pure-JSON animation map, frame selection via a UV
+* window on the node's own texture clone. Frames advance in `update(dt)` —
+* deterministic and headless-testable.
+*/
+declare class AnimatedSprite2D extends Sprite2D {
+  static override readonly typeName: string;
+  static override readonly signals: readonly string[];
+  static override readonly props: PropSchema;
+  /** `'$assetKey'` of a spritesheet asset. */
+  sheet: string;
+  animations: Record<string, AnimationDef>;
+  autoplay: string;
+  playing: boolean;
+  /** Absolute frame index within the sheet. */
+  currentFrame: number;
+  currentAnimation: string;
+  private frameList;
+  private frameIndex;
+  private frameTime;
+  private ownTexture;
+  private loadedSheetRef;
+  play(name: string): void;
+  stop(): void;
+  override onReady(): void;
+  override update(dt: number): void;
+  protected override resolveTexture(assets: AssetStore2D | null): ResolvedSpriteTexture | null;
+}
+//#endregion
+//#region src/2d/nodes/camera-2d.d.ts
+/**
+* 2D camera: its `position` is the view CENTER. `follow` tracks a node path
+* with exponential smoothing; `limits [minX,minY,maxX,maxY]` clamp the view
+* rect inside a world region (applied by the renderer via `clampedCenter`).
+*/
+declare class Camera2D extends Node2D {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  /** NodePath of a Node2D to track. */
+  follow: string;
+  /** 0 = snap; 0.85–0.95 = smooth chase (per-frame retention at 60fps). */
+  smoothing: number;
+  zoom: number;
+  /** [minX, minY, maxX, maxY] world px; empty = unlimited. */
+  limits: number[];
+  current: boolean;
+  /** `zoom` clamped to a positive floor — 0/negative zoom must never produce NaN views. */
+  get effectiveZoom(): number;
+  override update(dt: number): void;
+  /** View center after clamping the (vw×vh)/zoom view rect inside `limits`. */
+  clampedCenter(vw: number, vh: number): {
+    x: number;
+    y: number;
+  };
+}
+//#endregion
+//#region src/2d/nodes/character-controller-2d.d.ts
+/**
+* Preset controller: drives its PARENT CharacterBody2D from the engine
+* InputMap — JSON-only games get a playable character with zero TypeScript.
+*
+* - `platformer`: x movement + gravity (from the scene `physics.gravity[1]`,
+*   default 980) + jump (`jumpHeight` px → impulse √(2·g·h))
+* - `topDown`: full-axis movement, no gravity
+*/
+declare class CharacterController2D extends Node {
+  static override readonly typeName: string;
+  static readonly props: PropSchema;
+  mode: string;
+  maxSpeed: number;
+  /** Pixels (platformer mode). */
+  jumpHeight: number;
+  moveAction: string;
+  jumpAction: string;
+  override onReady(): void;
+  override fixedUpdate(dt: number): void;
+}
+//#endregion
+//#region src/2d/nodes/color-rect-2d.d.ts
+/**
+* A solid-colored rectangle — no texture, no asset file. The prototyping
+* workhorse: paddles, walls, platforms, flashes, fade overlays. Swap in a
+* Sprite2D when art arrives.
+*/
+declare class ColorRect2D extends Node2D {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  /** [width, height] in world px. */
+  size: number[];
+  color: string;
+  opacity: number;
+  /** [0,0] = top-left on the origin … [1,1] = bottom-right on the origin. */
+  anchor: number[];
+  private quadMesh;
+  /** @internal The drawable quad (lazily created under the backing object). */
+  _quad(): Mesh;
+  override _syncObject2D(assets: AssetStore2D | null): void;
+}
+//#endregion
+//#region src/2d/nodes/label.d.ts
+/**
+* CanvasTexture-backed text (zero deps, WebGL-safe). Re-rasterizes only when
+* text props change. Headless-safe: without a DOM it simply stays hidden —
+* all prop/serialization logic still works.
+*/
+declare class Label extends Node2D {
+  static override readonly typeName: string;
+  static override readonly props: PropSchema;
+  text: string;
+  fontSize: number;
+  color: string;
+  font: string;
+  /** 'left' | 'center' | 'right' — anchor of the text block on the node origin. */
+  align: string;
+  private quadMesh;
+  private canvas;
+  private lastKey;
+  /** @internal */
+  _quad(): Mesh;
+  override _syncObject2D(assets: AssetStore2D | null): void;
+  private rasterize;
+}
+//#endregion
+//#region src/2d/nodes/particles-2d.d.ts
+/**
+* GPU-instanced particle emitter with predefined looks: set `preset` to
+* `'fire' | 'smoke' | 'sparks' | 'fireworks' | 'explosion' | 'flash' |
+* 'lightning' | 'rain' | 'snow' | 'magic'` and every prop snaps to that
+* look's baseline — any prop you write in the scene overrides it. `rate: 0`
+* + `burst` makes a one-shot that emits `finished` (queueFree it there).
+* Simulation is deterministic under the engine seed.
+*/
+declare class Particles2D extends Node2D {
+  static override readonly typeName: string;
+  static override readonly signals: readonly string[];
+  static override readonly props: PropSchema;
+  preset: string;
+  emitting: boolean;
+  rate: number;
+  burst: number;
+  lifetime: number[];
+  speed: number[];
+  directionDeg: number;
+  spreadDeg: number;
+  gravity: number[];
+  drag: number;
+  sizeStart: number;
+  sizeEnd: number;
+  colorStart: string;
+  colorEnd: string;
+  /** Per-particle base colours sampled by the particle's stable seed (multi-
+  * colour confetti). Empty → the colorStart→colorEnd ramp is used unchanged. */
+  paletteColors: string[];
+  alphaStart: number;
+  alphaEnd: number;
+  /** Per-particle alpha twinkle frequency in Hz (0 = off) — a seed-phased sine
+  * over the particle's age, so each sparkle glitters on its own rhythm. */
+  shimmer: number;
+  blend: string;
+  maxParticles: number;
+  /** Loader hook: unknown presets and bad blends fail at LOAD. */
+  static validateJson(node: Node): void;
+  private sim;
+  private bursted;
+  private finishedEmitted;
+  /** @internal Lazily applies the preset + builds the deterministic sim. */
+  _ensureSim(): ParticleSim;
+  override update(dt: number): void;
+  /** Restart a one-shot (re-burst + allow finished to fire again). */
+  replay(): void;
+  private mesh;
+  /** Parsed `paletteColors`, reused; rebuilt only when the hex list changes. */
+  private paletteCache;
+  private paletteCacheKey;
+  /** Parse `paletteColors` into a reused `Color[]`, rebuilt only on change;
+  * null when empty so the caller uses the colorStart→colorEnd ramp. */
+  private refreshPalette;
+  override _syncObject2D(assets: AssetStore2D | null): void;
+}
+//#endregion
+//#region src/2d/nodes/ui-layer.d.ts
+declare const ANCHORS: readonly ["top-left", "top", "top-right", "left", "center", "right", "bottom-left", "bottom", "bottom-right"];
+type UIAnchor = (typeof ANCHORS)[number];
+/**
+* Screen-space container (Godot CanvasLayer): 2D descendants render in a
+* separate pass that ignores the world camera — HUDs, scores, menus.
+*
+* `anchor` pins the layer's origin to a screen corner/edge/center, so HUD
+* coordinates stay tiny offsets that survive any canvas size: a Label at
+* [-16, 16] under a 'top-right' layer hugs the top-right corner everywhere.
+*/
+declare class UILayer extends Node {
+  static override readonly typeName: string;
+  static readonly props: PropSchema;
+  anchor: string;
+  private group;
+  /** @internal The three group all descendants mount under (lazily created). */
+  _ensureGroup(): Group;
+  /** Loader hook: a misspelled anchor fails at LOAD, listing the valid set. */
+  static validateJson(node: Node): void;
+  /** @internal Anchor origin in y-down ui px for a given ui size. */
+  _anchorOrigin(width: number, height: number): {
+    x: number;
+    y: number;
+  };
+}
+//#endregion
+//#region src/2d/register.d.ts
+/**
+* Register the 2D node taxonomy (and the core nodes). Call once in your game
+* entry before loading a 2D scene. Explicit — never an import side effect.
+*/
+declare function registerNodes2D(): void;
+//#endregion
+//#region src/2d/picking.d.ts
+/**
+* Pure view-transform helpers shared by Renderer2D's picking API and editor
+* overlays. World space is y-down pixels (the engine's 2D convention); screen
+* space is CSS pixels on the canvas.
+*/
+interface View2D {
+  /** World-space view center. */
+  cx: number;
+  cy: number;
+  zoom: number;
+  /** Canvas CSS size. */
+  w: number;
+  h: number;
+}
+//#endregion
+//#region src/2d/renderer.d.ts
+interface Renderer2DOptions {
+  canvas: HTMLCanvasElement;
+  engine: Engine;
+  /** Bring your own store (custom loader) — defaults to a TextureLoader-backed one. */
+  assets?: AssetStore2D;
+  /**
+  * Backbuffer scale. DEFAULTS TO 1 — Phaser parity: the browser upscales on
+  * hiDPI screens, which reads as soft antialiased edges. Pass
+  * `window.devicePixelRatio` for crisp retina rendering instead.
+  */
+  pixelRatio?: number;
+  /** MSAA on the canvas. Defaults to TRUE (Phaser parity). */
+  antialias?: boolean;
+}
+/**
+* 2D presentation layer: world pass through the active Camera2D
+* (center/zoom/limits), then a screen-space UI pass for UILayer subtrees.
+* 1 unit = 1 px, (0,0) top-left, +y down.
+*/
+declare class Renderer2D {
+  /**
+  * When set, the world pass frames THIS view instead of the scene's active
+  * Camera2D — tooling (the scene editor) pans/zooms freely without touching
+  * scene data. `null` restores normal camera behavior.
+  */
+  viewOverride: {
+    cx: number;
+    cy: number;
+    zoom: number;
+  } | null;
+  private readonly webgl;
+  private readonly worldScene;
+  private readonly uiScene;
+  private readonly worldCam;
+  private readonly uiCam;
+  private readonly engine;
+  private readonly assets;
+  private readonly loadedAssetScenes;
+  private readonly disconnect;
+  private readonly canvas;
+  constructor(opts: Renderer2DOptions);
+  private readonly debugLines;
+  private syncDebugLines;
+  private render;
+  private lastViewport;
+  private lastView;
+  /** The world view used by the LAST render (center/zoom/canvas size). */
+  view(): View2D;
+  /**
+  * GPU counters for the LAST rendered frame (world + UI passes combined),
+  * straight from three's per-frame-maintained `renderer.info`.
+  */
+  stats(): RendererStats;
+  worldFromScreen(sx: number, sy: number): {
+    x: number;
+    y: number;
+  };
+  screenFromWorld(wx: number, wy: number): {
+    x: number;
+    y: number;
+  };
+  /**
+  * The topmost world-pass node under a canvas pixel (UI pass excluded).
+  * Hits resolve through `userData.incantoNode` and prefer higher renderOrder.
+  */
+  pick(sx: number, sy: number): Node | null;
+  /**
+  * Canvas-pixel AABB of a node's rendered world-pass objects, or null when it
+  * has no renderable extent (plain Nodes, empty containers).
+  */
+  boundsOf(node: Node): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+  } | null;
+  dispose(): void;
+}
+//#endregion
+//#region src/2d/sync.d.ts
+interface Sync2DResult {
+  activeCamera: Camera2D | null;
+}
+interface UiSize {
+  width: number;
+  height: number;
+}
+/**
+* Mirror an Incanto node tree onto two three scenes:
+* - `world`: camera-space drawables
+* - `ui`: everything under a `UILayer` (screen space, ignores the camera);
+*   each layer mounts through its own group, positioned by its `anchor`
+*   against `uiSize` (origin when no size is known — headless).
+*
+* Same dirty-push contract as the 3D sync; pure scene-graph math, headless-testable.
+*/
+declare function syncTree2D(root: Node, world: Scene, ui: Scene, assets: AssetStore2D | null, uiSize?: UiSize): Sync2DResult;
+//#endregion
+export { AnimatedSprite2D, type AnimationDef, Area2D, type AssetStatus, AssetStore2D, Camera2D, CharacterBody2D, CharacterController2D, ColorRect2D, type CreateGame2DOptions, type Game2D, Label, Node2D, Particles2D, Physics2D, type Physics2DOptions, PhysicsBody2D, Renderer2D, type Renderer2DOptions, type ResolvedSpriteTexture, RigidBody2D, type SheetInfo, Sprite2D, type SpriteFromLibraryResult, StaticBody2D, type Sync2DResult, type TextureLoadCallbacks, type UIAnchor, UILayer, createGame2D, enablePhysics2D, registerNodes2D, spriteFromLibraryMeta, syncTree2D };

package/dist/2d.js

@@ -0,0 +1,44 @@
+import { t as IncantoError } from "./errors-BpWbnbb_.js";
+import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-CZHROKcT.js";
+import { a as ColorRect2D, c as AnimatedSprite2D, d as CharacterBody2D, f as PhysicsBody2D, h as Node2D, i as Label, l as Sprite2D, m as StaticBody2D, n as UILayer, o as CharacterController2D, p as RigidBody2D, r as Particles2D, s as Camera2D, t as registerNodes2D, u as Area2D } from "./register-DPEV9_9t.js";
+import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-KuMWPTf6.js";
+//#region src/2d/library-sprite.ts
+/**
+* Turn a library sprite-animation JSON into a scene-ready spritesheet asset
+* declaration + AnimatedSprite2D props. `autoplay` defaults to the first
+* LOOPING animation (idle-like), falling back to the first one.
+*/
+function spriteFromLibraryMeta(meta, opts) {
+	const m = meta;
+	if (typeof m?.frame?.width !== "number" || typeof m.frame.height !== "number" || !m.animations || Object.keys(m.animations).length === 0) throw new IncantoError("BAD_FORMAT", `Library sprite metadata needs {frame: {width, height}, animations: {<name>: {start, end, frameRate, repeat}}} — got ${JSON.stringify(meta).slice(0, 120)}.`);
+	const animations = {};
+	let firstName = null;
+	let firstLooping = null;
+	for (const [name, anim] of Object.entries(m.animations)) {
+		if (typeof anim.start !== "number" || typeof anim.end !== "number" || typeof anim.frameRate !== "number") throw new IncantoError("BAD_FORMAT", `Library animation '${name}' needs numeric start/end/frameRate, got ${JSON.stringify(anim)}.`);
+		const loop = anim.repeat === -1;
+		animations[name] = {
+			frames: [anim.start, anim.end],
+			fps: anim.frameRate,
+			loop
+		};
+		firstName ??= name;
+		if (loop && firstLooping === null) firstLooping = name;
+	}
+	const autoplay = opts.autoplay ?? firstLooping ?? firstName;
+	return {
+		asset: {
+			type: "spritesheet",
+			url: opts.url,
+			frameWidth: m.frame.width,
+			frameHeight: m.frame.height
+		},
+		props: {
+			sheet: `$${opts.assetKey}`,
+			autoplay,
+			animations
+		}
+	};
+}
+//#endregion
+export { AnimatedSprite2D, Area2D, AssetStore2D, Camera2D, CharacterBody2D, CharacterController2D, ColorRect2D, Label, Node2D, Particles2D, Physics2D, PhysicsBody2D, Renderer2D, RigidBody2D, Sprite2D, StaticBody2D, UILayer, createGame2D, enablePhysics2D, registerNodes2D, spriteFromLibraryMeta, syncTree2D };