incanto 0.1.0

package/dist/loader-Mo0KghCv.d.ts

@@ -0,0 +1,41 @@
+import { i as SceneJson } from "./schema-CcoWb32N.js";
+import { v as Engine, w as Scene } from "./behavior-BAQq7HGM.js";
+
+//#region src/core/scene/loader.d.ts
+interface LoadSceneOptions {
+  /** Resolve a sub-scene path referenced by `{instance: '<path>'}`. */
+  resolveScene?: (path: string) => SceneJson;
+  /**
+  * Tool/preview mode (the editor's ▶ play strips behaviors — and their
+  * `static signals` with them): declare each connection's signal on its
+  * from-node instead of hard-failing with UNKNOWN_SIGNAL. Games should
+  * NOT set this — the strict default catches typos.
+  */
+  declareConnectionSignals?: boolean;
+  /**
+  * Validation/tool mode (incanto-check, structure-only validation without
+  * the game's TypeScript): scripts naming UNREGISTERED behaviors get a no-op
+  * stub — props unvalidated, handlers accepted. Registered behaviors still
+  * validate for real. Games should NOT set this.
+  */
+  stubMissingBehaviors?: boolean;
+  /**
+  * Attach the engine BEFORE onEnterTree/onReady fire, so behaviors can use
+  * `this.engine` / `this.rng` / `this.log` in onReady. `createGame` does
+  * this for you; pair it with `engine.setScene(scene)` afterwards.
+  */
+  engine?: Engine;
+}
+/**
+* Build a live Scene from scene JSON.
+*
+* Takes `unknown` on purpose: the loader hard-validates everything at runtime,
+* so consumers can pass an imported JSON module without TypeScript casts.
+*
+* Order: validate header → instantiate nodes top-down → attach to a SceneTree
+* (enterTree/ready fire) → wire connections LAST. Every failure is a hard
+* IncantoError naming valid alternatives — agents self-correct on hard errors.
+*/
+declare function loadScene(json: unknown, opts?: LoadSceneOptions): Scene;
+//#endregion
+export { loadScene as n, LoadSceneOptions as t };

package/dist/net.d.ts

@@ -0,0 +1,427 @@
+import { c as JsonValue, i as SceneJson, s as JsonObject } from "./schema-CcoWb32N.js";
+import { T as Node, et as Signal, l as PropSchema, v as Engine } from "./behavior-BAQq7HGM.js";
+
+//#region src/net/types.d.ts
+type Unsubscribe = () => void;
+/**
+* Incanto's pluggable multiplayer transport contract. The engine speaks ONLY
+* this interface — any backend works by implementing it:
+*
+* - `LoopbackTransport` (built in): in-memory — offline dev, tests, split-screen
+* - `createAgent8Server()` (built in): adapter for `@agent8/gameserver`
+* - your own: Socket.IO, Colyseus, Supabase Realtime, a custom WebSocket server…
+*
+* The room protocol a transport's backend must answer via `remoteFunction`:
+* `joinRoom(roomId?) → roomId` · `leaveRoom(roomId)` · `setMyState(roomId, patch)`
+* (SHALLOW merge) · `patchRoomState(roomId, patch)` · `addEntity(roomId, coll,
+* entity) → id` · `updateEntity(roomId, coll, id, patch)` · `removeEntity(roomId,
+* coll, id)` · `sendEvent(roomId, type, payload)`.
+* (The shape happens to align with @agent8/gameserver's GameServer class, so that
+* adapter is thin — but nothing in the engine depends on that backend.)
+*/
+interface NetworkTransport {
+  readonly account: string;
+  readonly connected: boolean;
+  connect(): Promise<boolean>;
+  disconnect(): Promise<void>;
+  /** Calls a function defined in the game's server.js (see templates/agent8-server.js). */
+  remoteFunction(fn: string, args?: unknown[], opts?: {
+    needResponse?: boolean;
+    throttle?: number;
+    throttleKey?: string;
+  }): Promise<unknown>;
+  subscribeRoomState(roomId: string, cb: (state: JsonObject) => void): Unsubscribe;
+  subscribeRoomMyState(roomId: string, cb: (state: JsonObject) => void): Unsubscribe;
+  subscribeRoomAllUserStates(roomId: string, cb: (states: Record<string, JsonObject>) => void): Unsubscribe;
+  subscribeRoomCollection(roomId: string, collectionId: string, cb: (entities: Record<string, JsonObject>) => void): Unsubscribe;
+  onRoomMessage(roomId: string, type: string, cb: (message: JsonValue) => void): Unsubscribe;
+  onRoomUserJoin(roomId: string, cb: (account: string) => void): Unsubscribe;
+  onRoomUserLeave(roomId: string, cb: (account: string) => void): Unsubscribe;
+  /**
+  * GLOBAL (cross-room, persistent) channels — OPTIONAL. A backend that has no
+  * global tier (e.g. the fixed `LoopbackHub`) simply omits them; NetworkManager
+  * degrades gracefully (its global signals never fire). `LocalGameServer` and the
+  * agent8 adapter implement them. Each fires the current value once on subscribe.
+  */
+  subscribeGlobalState?(cb: (state: JsonObject) => void): Unsubscribe;
+  /** The caller's own global user state. */
+  subscribeGlobalMyState?(cb: (state: JsonObject) => void): Unsubscribe;
+  subscribeGlobalUserState?(account: string, cb: (state: JsonObject) => void): Unsubscribe;
+  subscribeGlobalCollection?(collectionId: string, cb: (entities: Record<string, JsonObject>) => void): Unsubscribe;
+  /** An account's currency ledger (`$asset`). */
+  subscribeAsset?(account: string, cb: (assets: Record<string, number>) => void): Unsubscribe;
+  onGlobalMessage?(type: string, cb: (message: JsonValue) => void): Unsubscribe;
+}
+//#endregion
+//#region src/net/agent8.d.ts
+/**
+* The real transport: wraps `@agent8/gameserver`'s framework-free GameServer
+* class via a DEEP dynamic import (the package index re-exports React hooks
+* and zustand stores we must never pull in). The SDK is an optional peer dep —
+* games without multiplayer never load (or need) it.
+*
+* Adapter responsibilities beyond pass-through:
+* 1. allUserStates shape conversion: v2 delivers a fully delta-merged ARRAY of
+*    `{...state, account, __updated}` (left users already removed from it). We
+*    convert that to incanto's account-keyed Record, stripping the v2-internal
+*    `account`/`__updated`/`__leaved` markers, and emit it as a full snapshot.
+* 2. collection shape conversion: v2 delivers `{items: [{__id, …}], changes}`;
+*    we convert the merged `items` array to incanto's `__id`-keyed Record.
+* 3. Reconnect: the SDK clears pending subscriptions on disconnect and never
+*    restores them — we re-issue every active subscription after reconnect.
+*/
+declare function createAgent8Server(config?: {
+  verse?: string;
+  account?: string;
+  auth?: string;
+}): Promise<NetworkTransport>;
+//#endregion
+//#region src/net/loopback.d.ts
+interface Room {
+  users: Map<string, JsonObject>;
+  state: JsonObject;
+  collections: Map<string, Map<string, JsonObject>>;
+}
+/**
+* In-memory multiplayer hub implementing the SAME kernel contract as
+* `templates/agent8-server.js` — local split-screen demos, offline development,
+* and headless tests run real multi-client flows without any infrastructure.
+*/
+declare class LoopbackHub {
+  private readonly rooms;
+  private accountSeq;
+  private roomSeq;
+  private entitySeq;
+  /** Per-room listener registries, keyed by roomId. */
+  private readonly listeners;
+  createClient(account?: string): LoopbackTransport;
+  /** @internal */
+  _room(roomId: string): Room;
+  /** @internal The server.js kernel, in memory. */
+  _call(account: string, fn: string, args: unknown[]): unknown;
+  /** @internal */
+  _subscribe<K extends keyof LoopbackHub["listeners"]>(kind: K, roomId: string, entry: LoopbackHub["listeners"][K] extends Map<string, Set<infer E>> ? E : never): Unsubscribe;
+  /** @internal */
+  _snapshotUsers(roomId: string): Record<string, JsonObject>;
+  /** @internal */
+  _snapshotCollection(roomId: string, collectionId: string): Record<string, JsonObject>;
+  /** @internal */
+  _snapshotRoomState(roomId: string): JsonObject;
+  private fire;
+  private fireAllUsers;
+  private fireCollection;
+}
+/** A client on a LoopbackHub. Subscriptions fire immediately with a snapshot. */
+declare class LoopbackTransport implements NetworkTransport {
+  private readonly hub;
+  readonly account: string;
+  connected: boolean;
+  constructor(hub: LoopbackHub, account: string);
+  connect(): Promise<boolean>;
+  disconnect(): Promise<void>;
+  remoteFunction(fn: string, args?: unknown[]): Promise<unknown>;
+  subscribeRoomState(roomId: string, cb: (state: JsonObject) => void): Unsubscribe;
+  subscribeRoomMyState(roomId: string, cb: (state: JsonObject) => void): Unsubscribe;
+  subscribeRoomAllUserStates(roomId: string, cb: (states: Record<string, JsonObject>) => void): Unsubscribe;
+  subscribeRoomCollection(roomId: string, collectionId: string, cb: (entities: Record<string, JsonObject>) => void): Unsubscribe;
+  onRoomMessage(roomId: string, type: string, cb: (message: JsonValue) => void): Unsubscribe;
+  onRoomUserJoin(roomId: string, cb: (account: string) => void): Unsubscribe;
+  onRoomUserLeave(roomId: string, cb: (account: string) => void): Unsubscribe;
+}
+//#endregion
+//#region src/net/local-game-server.d.ts
+/** A user's `server/src/server.ts` `Server` class (or any class with room methods). */
+type ServerClass = new () => object;
+interface LocalGameServerOptions {
+  /**
+  * The game's `Server` class from `server/src/server.ts` (the v2 structured
+  * project). Omit it to fall back to the built-in kernel only — identical to a
+  * raw `LoopbackHub`.
+  */
+  server?: ServerClass;
+}
+/**
+* Run a multiplayer game's REAL agent8-sdk-v2 `Server` class **locally**, in
+* memory, with NO cloud and NO auth — the preview/dev path.
+*
+* `LoopbackHub` answers only the fixed built-in room protocol (joinRoom,
+* setMyState, collections, events). Real games add server-AUTHORITATIVE rules
+* (`awardPoint`, `castSpell`, `$roomTick` match clocks) in `server/src/server.ts`
+* against the v2 contexts `$sender`/`$global`/`$room`/`$lock`. LocalGameServer
+* runs that exact class body so the whole game — client + server logic — is
+* playable in dev before it ever touches the Agent8 platform. Swap
+* `local.createClient(account)` for `await createAgent8Server()` to go live;
+* nothing else changes.
+*
+* How it stays faithful to the isolated-vm platform:
+* - A FRESH `Server` instance runs per request, so `this.*` never persists.
+* - The v2 globals are injected on `globalThis` for the duration of each call
+*   (the SAME `server/src/server.ts` body that reads bare `$room`/`$sender`
+*   runs unmodified).
+* - Calls are SERIALIZED through one queue, so a global binding can't leak across
+*   another request's `await`s (the platform isolates per request; we serialize).
+* - `$roomTick(deltaMS, roomId)` runs only while a room has users — drive it from
+*   the engine: `engine.updated.connect((dt) => local.tick(dt * 1000))`.
+*
+* NOT a substitute for the cloud: no isolated-vm sandboxing, no persistence, no
+* rate limits — a faithful FUNCTIONAL emulator for local play and tests.
+*/
+declare class LocalGameServer {
+  private readonly hub;
+  private readonly serverClass?;
+  /** Each client's current room — binds `$sender.roomId` on later calls. */
+  private readonly clientRooms;
+  /** All remoteFunction/tick calls run one-at-a-time so injected globals never overlap. */
+  private queue;
+  /** Per-key mutex backing `$lock`. */
+  private readonly locks;
+  /** Persistent (process-lifetime) store backing the `$global` + `$asset` contexts. */
+  private readonly g_state;
+  private readonly g_userStates;
+  private readonly g_collections;
+  private readonly g_assets;
+  private g_seq;
+  /** Client-side global/asset subscription registries (fanned out on mutation). */
+  private readonly subState;
+  private readonly subUser;
+  private readonly subColl;
+  private readonly subAsset;
+  private readonly subMsg;
+  constructor(serverClass?: ServerClass);
+  /** A client on this server. Distinct `account` per player (default auto-assigned). */
+  createClient(account?: string): LocalGameServerTransport;
+  private collectionSnapshot;
+  private assetSnapshot;
+  /** @internal */
+  subscribeGlobalState(cb: (s: JsonObject) => void): Unsubscribe;
+  /** @internal */
+  subscribeGlobalUserState(account: string, cb: (s: JsonObject) => void): Unsubscribe;
+  /** @internal */
+  subscribeGlobalCollection(id: string, cb: (r: Record<string, JsonObject>) => void): Unsubscribe;
+  /** @internal */
+  subscribeAsset(account: string, cb: (a: Record<string, number>) => void): Unsubscribe;
+  /** @internal Messages are events — no immediate snapshot. */
+  onGlobalMessage(account: string, type: string, cb: (m: JsonValue) => void): Unsubscribe;
+  private fireState;
+  private fireUser;
+  private fireColl;
+  private fireAsset;
+  private fireMsg;
+  /**
+  * Advance server-driven periodic logic. Calls the `Server`'s `$roomTick(deltaMS,
+  * roomId)` once per room that currently has users. No-op without a `$roomTick`.
+  */
+  tick(deltaMS: number): Promise<void>;
+  /** @internal Dispatch a remoteFunction (serialized). */
+  call(account: string, fn: string, args: unknown[]): Promise<unknown>;
+  private enqueue;
+  private dispatch;
+  private runTick;
+  /** Install the v2 globals for one dispatch; returns a restorer. */
+  private bindGlobals;
+  /**
+  * The `$global` context — room membership, persistent GLOBAL state/user-state/
+  * collections, room management, and global messaging. Backed by an in-memory
+  * store that survives between requests (unlike rooms, which the hub clears when
+  * empty) — matching the platform's persistent-global / ephemeral-room split.
+  */
+  private globalContext;
+  /**
+  * The `$asset` context — a per-account currency ledger. `burn`/`transfer` throw
+  * on an insufficient balance (the documented pattern always checks `has` first),
+  * surfacing economy bugs in preview just as the platform would.
+  */
+  private assetContext;
+  /** The `$room` context, bound to one room — maps onto the hub's kernel primitives. */
+  private roomContext;
+  private withLock;
+}
+/** Firebase-style query options for `$global`/`$room` collections (preview subset). */
+interface CollectionOptions {
+  filters?: {
+    field: string;
+    operator: string;
+    value: JsonValue;
+  }[];
+  orderBy?: {
+    field: string;
+    direction?: "asc" | "desc";
+  }[];
+  limit?: number;
+  startAfter?: JsonValue;
+  endBefore?: JsonValue;
+}
+/** Construct a local preview server. With no `server`, it equals a raw LoopbackHub. */
+declare function createLocalGameServer(opts?: LocalGameServerOptions): LocalGameServer;
+/**
+* A client of a {@link LocalGameServer}. Subscriptions read the shared in-memory
+* store directly (same fan-out as Loopback); `remoteFunction` routes through the
+* server's serialized dispatch so the game's `Server` class actually runs.
+*/
+declare class LocalGameServerTransport implements NetworkTransport {
+  private readonly server;
+  private readonly loop;
+  readonly account: string;
+  connected: boolean;
+  constructor(server: LocalGameServer, loop: LoopbackTransport);
+  connect(): Promise<boolean>;
+  disconnect(): Promise<void>;
+  remoteFunction(fn: string, args?: unknown[]): Promise<unknown>;
+  subscribeRoomState(roomId: string, cb: (state: JsonObject) => void): Unsubscribe;
+  subscribeRoomMyState(roomId: string, cb: (state: JsonObject) => void): Unsubscribe;
+  subscribeRoomAllUserStates(roomId: string, cb: (states: Record<string, JsonObject>) => void): Unsubscribe;
+  subscribeRoomCollection(roomId: string, collectionId: string, cb: (entities: Record<string, JsonObject>) => void): Unsubscribe;
+  onRoomMessage(roomId: string, type: string, cb: (message: JsonValue) => void): Unsubscribe;
+  onRoomUserJoin(roomId: string, cb: (account: string) => void): Unsubscribe;
+  onRoomUserLeave(roomId: string, cb: (account: string) => void): Unsubscribe;
+  subscribeGlobalState(cb: (state: JsonObject) => void): Unsubscribe;
+  subscribeGlobalMyState(cb: (state: JsonObject) => void): Unsubscribe;
+  subscribeGlobalUserState(account: string, cb: (state: JsonObject) => void): Unsubscribe;
+  subscribeGlobalCollection(collectionId: string, cb: (entities: Record<string, JsonObject>) => void): Unsubscribe;
+  subscribeAsset(account: string, cb: (assets: Record<string, number>) => void): Unsubscribe;
+  onGlobalMessage(type: string, cb: (message: JsonValue) => void): Unsubscribe;
+}
+//#endregion
+//#region src/net/network-manager.d.ts
+interface NetworkManagerOptions {
+  /**
+  * The transport to speak through — `LoopbackTransport` (offline/dev/tests),
+  * `await createAgent8Server()` (agent8 platform), or any custom
+  * NetworkTransport implementation. Default: the agent8 adapter.
+  */
+  transport?: NetworkTransport;
+  /** Room id; default: scene `multiplayer.room` ('auto' = server-assigned). */
+  room?: string;
+  /** Config for the default agent8 adapter (ignored when `transport` is injected). */
+  config?: {
+    verse?: string;
+    account?: string;
+    auth?: string;
+  };
+  /** Replication send window in ms (default 50; node `network.throttleMs` can lower it). */
+  throttleMs?: number;
+}
+/**
+* Per-engine multiplayer hub: joins a room, exposes the room channels as core
+* Signals, replicates `network: {mode:'owner'}` node props on a throttle
+* window, and resolves registered scenes for NetworkSpawner.
+*/
+declare class NetworkManager {
+  readonly account: string;
+  readonly roomId: string;
+  readonly roomState: Signal<[JsonObject]>;
+  readonly allUserStates: Signal<[Record<string, JsonObject>]>;
+  readonly userJoined: Signal<[string]>;
+  readonly userLeft: Signal<[string]>;
+  /**
+  * GLOBAL (cross-room, persistent) channels — populated only when the transport
+  * supports them (`LocalGameServer`, the agent8 adapter). On a transport without a
+  * global tier they stay empty / never fire.
+  */
+  readonly globalState: Signal<[JsonObject]>;
+  readonly globalMyState: Signal<[JsonObject]>;
+  /** The local account's `$asset` ledger. */
+  readonly asset: Signal<[Record<string, number>]>;
+  /** Latest snapshots for polling consumers (NetworkSpawner). */
+  latestUserStates: Record<string, JsonObject>;
+  latestRoomState: JsonObject;
+  latestGlobalState: JsonObject;
+  latestGlobalMyState: JsonObject;
+  latestAsset: Record<string, number>;
+  private readonly server;
+  private readonly engine;
+  private readonly throttleMs;
+  private readonly subs;
+  private readonly messageSignals;
+  private readonly collectionSignals;
+  private readonly latestCollections;
+  private readonly globalMessageSignals;
+  private readonly globalCollectionSignals;
+  private readonly latestGlobalCollections;
+  private readonly scenes;
+  private readonly lastSent;
+  private sendAccumulator;
+  private detachReplication;
+  private lastOwner;
+  private boundScene;
+  static get(engine: Engine): NetworkManager | null;
+  static create(engine: Engine, opts?: NetworkManagerOptions): Promise<NetworkManager>;
+  private constructor();
+  /** Signal for a typed room message (`sendEvent` on any client). */
+  message(type: string): Signal<[JsonValue]>;
+  /** Signal + snapshot for a room collection (spawned entities). */
+  collection(id: string): Signal<[Record<string, JsonObject>]>;
+  latestCollection(id: string): Record<string, JsonObject>;
+  /** Signal for a typed GLOBAL message (`$global.broadcastToAll`/`sendMessageToUser`). */
+  globalMessage(type: string): Signal<[JsonValue]>;
+  /** Signal + snapshot for a GLOBAL collection (persistent, cross-room). */
+  globalCollection(id: string): Signal<[Record<string, JsonObject>]>;
+  latestGlobalCollection(id: string): Record<string, JsonObject>;
+  setMyState(patch: JsonObject): Promise<unknown>;
+  patchRoomState(patch: JsonObject): Promise<unknown>;
+  addEntity(collectionId: string, entity: JsonObject): Promise<unknown>;
+  updateEntity(collectionId: string, id: string, patch: JsonObject): Promise<unknown>;
+  removeEntity(collectionId: string, id: string): Promise<unknown>;
+  sendEvent(type: string, payload: JsonValue): Promise<unknown>;
+  /**
+  * Invoke a CUSTOM server-authoritative function — a method you added to your
+  * `server/src/server.ts` `Server` class (run live on the Agent8 platform, or
+  * locally via `createLocalGameServer`). The room id is prepended automatically,
+  * matching the `(roomId, …)` shape every server method takes:
+  *
+  *   `manager.call('claimCoin', coinId)` → server `claimCoin(roomId, coinId)`
+  *
+  * Returns the function's result (use it for server-validated outcomes — a
+  * rejected claim, a rolled value). This is THE entry point for game rules the
+  * client must not be trusted to compute.
+  */
+  call(fn: string, ...args: JsonValue[]): Promise<unknown>;
+  /** Register a scene for NetworkSpawner (`"scene": "<key>"`). */
+  registerScene(key: string, json: SceneJson): void;
+  resolveScene(key: string): SceneJson;
+  dispose(): Promise<void>;
+  private replicate;
+}
+/**
+* @internal Applies a replicated flat sync patch (`{'position': …,
+* 'Sprite.animation': …}`) onto a spawned subtree (NetworkSpawner).
+*/
+declare function applySyncPatch(root: Node, patch: JsonObject, setProp: (target: Node, prop: string, value: JsonValue) => void): void;
+//#endregion
+//#region src/net/nodes/network-spawner.d.ts
+/**
+* Materializes a registered scene per remote player or collection entity:
+*
+* - `source: 'users'` — one instance per OTHER account in the room
+*   (self is skipped; the local player is your own owned node)
+* - `source: 'collection:<id>'` — one instance per entity (bullets, pickups…)
+*
+* Replicated flat `{sync: {...}}` patches apply onto each instance's root;
+* `position` lerps toward its target when `interpolate` is on. Emits
+* `spawned(node, key)` / `despawned(node, key)`.
+*/
+declare class NetworkSpawner extends Node {
+  static override readonly typeName: string;
+  static override readonly signals: readonly string[];
+  static readonly props: PropSchema;
+  source: string;
+  /** Key registered via `manager.registerScene(key, json)`. */
+  scene: string;
+  interpolate: boolean;
+  private readonly spawned;
+  private readonly positionTargets;
+  private readonly failedKeys;
+  override update(dt: number): void;
+  private currentEntries;
+  private setProp;
+  private stepInterpolation;
+}
+//#endregion
+//#region src/net/register.d.ts
+/**
+* Register the networking node types (and the core nodes). Call once in your
+* game entry before loading a multiplayer scene. Explicit — never a side effect.
+*/
+declare function registerNodesNet(): void;
+//#endregion
+export { type CollectionOptions, LocalGameServer, type LocalGameServerOptions, LocalGameServerTransport, LoopbackHub, LoopbackTransport, NetworkManager, type NetworkManagerOptions, NetworkSpawner, type NetworkTransport, type ServerClass, type Unsubscribe, applySyncPatch, createAgent8Server, createLocalGameServer, registerNodesNet };