incanto 0.28.0 → 0.29.0

package/README.md

@@ -53,6 +53,50 @@ engine.start();
 - `schemas/scene.schema.json` — generated JSON Schema for scene files (the agent contract)
 - `templates/agent8-server.js` — the multiplayer server kernel for the agent8 platform
 
+## Debug mode
+
+Off by default, with **no URL toggle** — a deployed build can never be switched on by a player.
+Gate it to your own dev server (every template already ships the line):
+
+```ts
+createGame3D({ ..., debug: import.meta.env.VITE_INCANTO_DEBUG === '1' });
+```
+
+```bash
+VITE_INCANTO_DEBUG=1 bun run dev   # overlay ON; plain `bun run dev` and prod builds = off
+```
+
+A **☰ debug** menu appears top-left: **Explorer** (live scene tree; the selected node's bounds
+light up orange in-game), **Inspector** (its props, editable while running), **Logs**
+(`engine.log` tail with filters), **Stats** (fps · frame ms · nodes · tris · draw calls), and
+**Colliders** (physics shapes as wireframe; one click cycles off → all → **selected**, and
+`selected` draws only the collider of whatever the Explorer has picked — the way to find one shape
+in a world full of them). In code: `physics.debugDraw = true` + `physics.debugScope = node`, or
+`(await import('incanto/debug')).attachDebugOverlay(engine)` to boot the overlay by hand.
+
+## The agent8 asset library
+
+`bunx incanto-editor --token <v8 access token>` (or `INCANTO_V8_TOKEN`) adds a
+**📚** button to every field that takes a resource — model, texture, sprite
+sheet, sound. Shelves, search, real previews (a GLB is rendered by the engine
+itself), and one pick writes the URL, or the scene `assets{}` entry plus its
+`$ref` for fields that take one. Without a token the panel asks for one and
+keeps it in the browser; the editor server proxies the catalog because it is
+per-account and not CORS-open to localhost.
+
+## Play ⇄ edit, in one window
+
+The menu's last item, **✎ edit this scene**, turns the running game into the scene editor in the
+page you are already in — same window, no reload, and the edit camera starts where the player's
+eye was. The editor's **▶ play** offers the way back as a choice: **preview here** (simulate in
+the viewport, scripts stripped) or **run as the game** (this page becomes the real game again,
+with your edits). **✕ exit** returns without playing.
+
+It follows `debug`, so an overlay build already has it. `editor: false` opts out;
+`editor: { save }` gives the editor a save button that writes your file; `game.openEditor()` is
+the same switch as a function. The editor loads lazily (`incanto/editor`) the first time it is
+asked for — a game that never opens it never downloads it.
+
 Docs, agent skills, examples, and architecture: **https://github.com/rareboe/Incanto**
 
 © 2026 Verse8. All rights reserved. Proprietary — see [LICENSE](./LICENSE). Bundled third-party OSS notices: [THIRD-PARTY-NOTICES.md](./THIRD-PARTY-NOTICES.md).

package/bin/incanto-editor.mjs

@@ -13,6 +13,14 @@
  *   POST /api/scenes          → { path } creates a minimal scene (project mode)
  *   GET  /api/scene[?file=]   → scene JSON  (single mode ignores ?file=)
  *   PUT  /api/scene[?file=]   → validates the scene shape, writes the file
+ *   GET  /api/library?tags=…  → proxies the agent8 asset catalog (see below)
+ *
+ * The library proxy exists because the catalog cannot be reached from a page:
+ * it wants a Verse8 access token and its CORS allow-list has no localhost in
+ * it. This server has neither problem. The token comes from --token, from
+ * INCANTO_V8_TOKEN / V8_ACCESS_TOKEN, or from the page's own
+ * `x-incanto-v8-token` header (what the browser stores when you paste one) —
+ * it is forwarded upstream and never written to disk.
  *
  * Security: on loopback binds, the Host header must be loopback (defeats DNS
  * rebinding); writes additionally require Origin (when present) to match the
@@ -60,6 +68,7 @@ function parseArgs(argv) {
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--output') args.output = argv[++i];
+    else if (a === '--token') args.token = argv[++i];
     else if (a === '--port') args.port = Number(argv[++i]);
     else if (a === '--host') args.host = argv[++i];
     else if (a === '--help' || a === '-h') args.help = true;
@@ -79,7 +88,11 @@ if (args.help || args.error || Number.isNaN(args.port) || (args.output && !args.
 Without a file: PROJECT mode — discovers every *.scene.json under the current
 directory (a picker opens; a single scene auto-opens; new scenes can be created).
 With a file: SINGLE mode — that file only; saving writes to --output (default:
-the input file). --output requires an input file. Use --host 0.0.0.0 inside containers.`);
+the input file). --output requires an input file. Use --host 0.0.0.0 inside containers.
+
+--token <v8 access token> (or INCANTO_V8_TOKEN) unlocks the agent8 asset library
+inside the editor. Without it the 📚 button asks for a token and remembers it in
+the browser instead.`);
   process.exit(args.help && !args.error ? 0 : 1);
 }
 
@@ -91,6 +104,102 @@ const VERSION = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf-8')
 
 const SKIP_DIRS = new Set(['node_modules', 'dist', 'build', 'out', 'coverage']);
 
+// --- agent8 asset library -------------------------------------------------
+const LIBRARY_URL =
+  process.env.INCANTO_LIBRARY_URL ?? 'https://agent8-backend.verse8.io/api/resources';
+const ENV_TOKEN = args.token ?? process.env.INCANTO_V8_TOKEN ?? process.env.V8_ACCESS_TOKEN ?? '';
+const LIBRARY_TIMEOUT_MS = 15_000;
+
+/** Upstream row → the shape the editor consumes (ids are strings here). */
+function libraryItem(row) {
+  return {
+    id: String(row?.id ?? row?.url ?? ''),
+    url: String(row?.url ?? ''),
+    description: typeof row?.description === 'string' ? row.description : '',
+    metadata: row?.metadata && typeof row.metadata === 'object' ? row.metadata : {},
+  };
+}
+
+async function proxyLibrary(req, res, url) {
+  // the page's token wins over the server's: a user who pasted one is telling
+  // us which account to search as
+  const token = (req.headers['x-incanto-v8-token'] || '').toString().trim() || ENV_TOKEN;
+  if (!token) {
+    return send(
+      res,
+      401,
+      JSON.stringify({
+        error:
+          'no Verse8 access token. Start the editor with --token <t> (or INCANTO_V8_TOKEN), or paste one into the library panel.',
+        needsToken: true,
+      }),
+    );
+  }
+  const params = new URLSearchParams({
+    tags: url.searchParams.get('tags') ?? '',
+    page: url.searchParams.get('page') ?? '1',
+    limit: url.searchParams.get('limit') ?? '24',
+  });
+  const keyword = url.searchParams.get('keyword');
+  if (keyword) params.set('keyword', keyword);
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), LIBRARY_TIMEOUT_MS);
+  try {
+    const upstream = await fetch(`${LIBRARY_URL}?${params}`, {
+      headers: { authorization: `Bearer ${token}`, accept: 'application/json' },
+      signal: controller.signal,
+    });
+    const text = await upstream.text();
+    if (upstream.status === 401 || upstream.status === 403) {
+      return send(
+        res,
+        401,
+        JSON.stringify({
+          error: 'the asset library rejected that token (expired or wrong account)',
+          needsToken: true,
+        }),
+      );
+    }
+    if (!upstream.ok) {
+      return send(res, 502, JSON.stringify({ error: `asset library: HTTP ${upstream.status}` }));
+    }
+    let body;
+    try {
+      body = JSON.parse(text);
+    } catch {
+      return send(res, 502, JSON.stringify({ error: 'asset library returned non-JSON' }));
+    }
+    if (body?.success === false) {
+      return send(res, 502, JSON.stringify({ error: String(body.error ?? 'asset library error') }));
+    }
+    const rows = Array.isArray(body?.data) ? body.data : [];
+    return send(
+      res,
+      200,
+      JSON.stringify({
+        items: rows.map(libraryItem).filter((i) => i.url),
+        page: Number(body?.pagination?.page ?? params.get('page') ?? 1),
+        hasNext: body?.pagination?.hasNext === true,
+        total: typeof body?.pagination?.total === 'number' ? body.pagination.total : undefined,
+      }),
+    );
+  } catch (error) {
+    const aborted = error?.name === 'AbortError';
+    return send(
+      res,
+      502,
+      JSON.stringify({
+        error: aborted
+          ? `asset library timed out after ${LIBRARY_TIMEOUT_MS / 1000}s`
+          : `asset library unreachable: ${String(error?.message ?? error)}`,
+      }),
+    );
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 function discoverScenes() {
   const found = [];
   const walk = (dir, depth) => {
@@ -217,6 +326,14 @@ const server = createServer((req, res) => {
     );
   }
 
+  if (url.pathname === '/api/library') {
+    if (req.method !== 'GET') {
+      return send(res, 405, JSON.stringify({ error: 'method not allowed' }));
+    }
+    proxyLibrary(req, res, url);
+    return;
+  }
+
   if (url.pathname === '/api/scenes') {
     if (MODE !== 'project') {
       return send(res, 400, JSON.stringify({ error: 'scene listing is project-mode only' }));

package/dist/2d.d.ts

@@ -1,6 +1,7 @@
-import { s as JsonObject } from "./schema-CcoWb32N.js";
-import { $ as Node, C as RendererStats, S as GameStats, b as Scheduler, l as PropSchema, n as BehaviorCtor, v as Engine, w as Scene$1 } from "./behavior-CPibUfnH.js";
-import { t as LoadSceneOptions } from "./loader-DILt9PGC.js";
+import { i as SceneJson, s as JsonObject } from "./schema-CcoWb32N.js";
+import { $ as Node, C as RendererStats, S as GameStats, b as Scheduler, l as PropSchema, n as BehaviorCtor, v as Engine, w as Scene$1 } from "./behavior-BAc0erXF.js";
+import { t as EditorSwitchOptions } from "./editor-switch-B0wB_DSr.js";
+import { t as LoadSceneOptions } from "./loader-B242FF6N.js";
 import { t as ParticleSim } from "./particle-sim-CwJ5rI_P.js";
 import { Group, Mesh, Object3D, Scene, Texture } from "three";
 import * as RapierNs from "@dimforge/rapier2d-compat";
@@ -160,6 +161,8 @@ declare class Physics2D {
   private readonly engine;
   /** Render collider outlines in the GAME view (renderers pick this up). */
   debugDraw: boolean;
+  /** Narrow those outlines to one node's subtree (see DebugLineSource). */
+  debugScope: object | null;
   readonly dimension = "2d";
   private readonly unregisterDebug;
   private readonly warnedNoCollider;
@@ -179,6 +182,13 @@ declare class Physics2D {
   moveAndSlide(node: CharacterBody2D): void;
   /** Rapier debug segments, scaled back to pixels. Null while debugDraw is off. */
   debugLines(): Float32Array | null;
+  /**
+  * Only the selected node's colliders (meters — the caller scales to pixels).
+  * Rapier draws the whole world or nothing, so a chosen few are outlined from
+  * the same shape data the solver holds. 2D colliders are rect/circle/capsule,
+  * which is the whole switch.
+  */
+  private scopedLines;
   /** Create newly-arrived joints; tear down departed ones. */
   private syncJoints;
   /**
@@ -249,6 +259,17 @@ interface CreateGame2DOptions {
   * to development, e.g. `debug: import.meta.env.VITE_INCANTO_DEBUG === '1'`.
   */
   debug?: boolean;
+  /**
+  * LIVE EDITING: the ☰ debug menu gains "edit this scene", which turns this
+  * page into the scene editor — same window, no reload — and the editor's play
+  * button turns it back into the game.
+  *
+  * DEFAULTS TO `debug`, costs nothing until clicked (the editor is a lazy
+  * chunk), and is never reachable without it — the ☰ menu is its only
+  * entrance. `false` opts out; `{ open }` loads the editor yourself (apps that
+  * alias incanto to source); `{ save }` makes its save button write your file.
+  */
+  editor?: boolean | EditorSwitchOptions;
   /** @internal Test seam — replaces `document` for the debug overlay. */
   _debugDoc?: {
     createElement(tag: string): HTMLElement;
@@ -272,10 +293,22 @@ interface GameRenderer {
 interface Game2D {
   engine: Engine;
   scene: Scene$1;
+  /**
+  * The AUTHORED scene this game booted from — the JSON, not the live tree.
+  * A running tree has moved; the editor gets what was written down.
+  */
+  sourceJson: SceneJson;
   renderer: GameRenderer;
   physics: Physics2D | null;
   /** Engine + renderer perf counters in one read (fps/nodes/triangles/…). */
   stats(): GameStats;
+  /**
+  * Turn this page into the scene editor — what the ☰ debug menu's "edit this
+  * scene" calls. The game is disposed on the way out and rebooted when the
+  * editor hands it back, so THIS handle is dead afterwards. `null` when the
+  * game was booted with `editor: false`.
+  */
+  openEditor: (() => Promise<void>) | null;
   /** Tear the whole game down (renderer, loop, scene, listeners). */
   dispose(): void;
 }
@@ -724,8 +757,8 @@ declare class Renderer2D {
   /** 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`.
+  * GPU counters for the LAST rendered frame — world + UI passes combined (see
+  * the `info.reset()` in the render pass), plus GPU memory.
   */
   stats(): RendererStats;
   worldFromScreen(sx: number, sy: number): {

package/dist/2d.js

@@ -1,7 +1,7 @@
 import { t as IncantoError } from "./errors-BpWbnbb_.js";
-import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-71TJjW1T.js";
-import { _ as RigidBody2D, a as parseCells, c as ColorRect2D, d as AnimatedSprite2D, f as Sprite2D, g as PhysicsBody2D, h as CharacterBody2D, i as mergeSolidRects, l as CharacterController2D, m as Area2D, n as UILayer, o as Particles2D, p as Joint2D, r as TileMap2D, s as Label, t as registerNodes2D, u as Camera2D, v as StaticBody2D, y as Node2D } from "./register-CvpSUU3O.js";
-import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-DiVFFlH3.js";
+import { a as AssetStore2D, i as syncTree2D, r as Renderer2D, t as createGame2D } from "./create-game-CbuLWorm.js";
+import { _ as RigidBody2D, a as parseCells, c as ColorRect2D, d as AnimatedSprite2D, f as Sprite2D, g as PhysicsBody2D, h as CharacterBody2D, i as mergeSolidRects, l as CharacterController2D, m as Area2D, n as UILayer, o as Particles2D, p as Joint2D, r as TileMap2D, s as Label, t as registerNodes2D, u as Camera2D, v as StaticBody2D, y as Node2D } from "./register-DWcWq4QG.js";
+import { n as enablePhysics2D, t as Physics2D } from "./physics-2d-CCVTrKOd.js";
 //#region src/2d/library-sprite.ts
 /**
 * Turn a library sprite-animation JSON into a scene-ready spritesheet asset