incanto 0.28.0 → 0.30.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

@@ -9,17 +9,25 @@
  *
  * API (the page can only address *.scene.json files under the launch directory):
  *   GET  /api/meta            → { version, mode, root, input?, output? }
- *   GET  /api/scenes          → [{ rel, abs }]            (project mode)
+ *   GET  /api/scenes          → [{ rel, abs, size, modified, scene?|notScene? }]
  *   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
  * request host. Bodies are capped at 8MB. Addressable paths are root-bounded
  * and must end in .scene.json.
  */
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { createServer } from 'node:http';
 import { basename, dirname, extname, join, normalize, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -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) => {
@@ -104,9 +213,20 @@ function discoverScenes() {
     for (const e of entries) {
       if (e.isDirectory()) {
         if (!SKIP_DIRS.has(e.name) && !e.name.startsWith('.')) walk(join(dir, e.name), depth + 1);
-      } else if (e.name.endsWith('.scene.json')) {
+      } else if (e.name.endsWith('.json')) {
         const abs = join(dir, e.name);
-        found.push({ rel: relative(ROOT, abs), abs });
+        // size + mtime are what the browser prints beside each row; a folder
+        // whose files are all "just now" is the one you were working in
+        let size = 0;
+        let modified = 0;
+        try {
+          const stat = statSync(abs);
+          size = stat.size;
+          modified = stat.mtimeMs;
+        } catch {
+          // listed without facts beats not listed at all
+        }
+        found.push({ rel: relative(ROOT, abs), abs, size, modified, ...inspectJson(abs, size) });
       }
     }
   };
@@ -114,9 +234,65 @@ function discoverScenes() {
   return found.sort((a, b) => a.rel.localeCompare(b.rel));
 }
 
-/** Root-bounded, *.scene.json-only — the page can never address anything else. */
+/**
+ * Is this JSON a scene? The file says so itself — `type: "scene"`, the same key
+ * the loader demands — so a row can be marked instead of guessed from its name.
+ */
+function sceneFacts(json) {
+  if (json === null || typeof json !== 'object' || Array.isArray(json)) {
+    return { ok: false, why: 'the file is JSON, but not a JSON object' };
+  }
+  if (json.type !== 'scene') {
+    return {
+      ok: false,
+      why:
+        json.type === undefined
+          ? '"type" must be "scene", and this file has no "type"'
+          : `"type" must be "scene", not ${JSON.stringify(json.type)}`,
+    };
+  }
+  if (json.format !== 1)
+    return { ok: false, why: `"format" must be 1, not ${JSON.stringify(json.format)}` };
+  if (typeof json.root !== 'object' || json.root === null) {
+    return { ok: false, why: '"root" must be a node object' };
+  }
+  const count = (n) =>
+    Array.isArray(n?.children) ? n.children.reduce((t, c) => t + count(c), 1) : 1;
+  return {
+    ok: true,
+    name: typeof json.name === 'string' ? json.name : '',
+    // only when the file SAYS so — `dimension` is optional and has no default
+    ...(json.dimension === '2d' || json.dimension === '3d' ? { dimension: json.dimension } : {}),
+    nodes: count(json.root),
+  };
+}
+
+function inspectJson(abs, size) {
+  if (size > 16_000_000) return { notScene: 'too large to check without opening it' };
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(abs, 'utf-8'));
+  } catch (error) {
+    return { notScene: `not valid JSON: ${String(error.message ?? error)}` };
+  }
+  const facts = sceneFacts(parsed);
+  return facts.ok
+    ? {
+        scene: {
+          name: facts.name,
+          ...(facts.dimension ? { dimension: facts.dimension } : {}),
+          nodes: facts.nodes,
+        },
+      }
+    : { notScene: facts.why };
+}
+
+/**
+ * Root-bounded, .json-only — the browser offers every JSON and the LOAD decides,
+ * but this must never become a way to read .env or somebody's key file.
+ */
 function resolveSceneFile(rel) {
-  if (typeof rel !== 'string' || !rel.endsWith('.scene.json')) return null;
+  if (typeof rel !== 'string' || !rel.endsWith('.json')) return null;
   const abs = normalize(resolve(ROOT, rel));
   if (abs !== ROOT && !abs.startsWith(ROOT + sep)) return null;
   return abs;
@@ -167,18 +343,6 @@ function originAllowed(req) {
   }
 }
 
-function isSceneShaped(json) {
-  return (
-    json !== null &&
-    typeof json === 'object' &&
-    json.format === 1 &&
-    json.type === 'scene' &&
-    typeof json.name === 'string' &&
-    json.root !== null &&
-    typeof json.root === 'object'
-  );
-}
-
 function readBody(req, res, onJson) {
   const chunks = [];
   let received = 0;
@@ -217,6 +381,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' }));
@@ -229,18 +401,23 @@ const server = createServer((req, res) => {
         return send(res, 403, JSON.stringify({ error: 'cross-origin write rejected' }));
       }
       readBody(req, res, (body) => {
-        const abs = resolveSceneFile(body?.path);
+        // a path with no extension means the usual thing, so `levels/arena` works
+        const wanted =
+          typeof body?.path === 'string' && body.path && !body.path.endsWith('.json')
+            ? `${body.path}.scene.json`
+            : body?.path;
+        const abs = resolveSceneFile(wanted);
         if (!abs) {
           return send(
             res,
             400,
-            JSON.stringify({ error: 'path must be a *.scene.json inside the project' }),
+            JSON.stringify({ error: 'path must be a .json file inside the project' }),
           );
         }
         if (existsSync(abs)) {
-          return send(res, 409, JSON.stringify({ error: `already exists: ${body.path}` }));
+          return send(res, 409, JSON.stringify({ error: `already exists: ${wanted}` }));
         }
-        const name = basename(abs).replace(/\.scene\.json$/, '') || 'Scene';
+        const name = basename(abs).replace(/\.scene\.json$|\.json$/, '') || 'Scene';
         const scene = {
           format: 1,
           type: 'scene',
@@ -271,26 +448,39 @@ const server = createServer((req, res) => {
       );
     }
     if (req.method === 'GET') {
+      let text;
+      let parsed;
       try {
-        const text = readFileSync(target.input, 'utf-8');
-        JSON.parse(text); // must at least be JSON before the page gets it
-        return send(res, 200, text);
+        text = readFileSync(target.input, 'utf-8');
+        parsed = JSON.parse(text); // must at least be JSON before the page gets it
       } catch (error) {
         return send(res, 422, JSON.stringify({ error: String(error.message ?? error) }));
       }
+      // A JSON that is not a scene is refused WITH THE REASON and its contents
+      // never leave: "offer everything, explain the no" must not also mean
+      // "this server will read you any JSON in the project".
+      const facts = sceneFacts(parsed);
+      if (!facts.ok) {
+        return send(
+          res,
+          422,
+          JSON.stringify({ error: `not an incanto scene — ${facts.why}.`, notScene: true }),
+        );
+      }
+      return send(res, 200, text);
     }
     if (req.method === 'PUT') {
       if (!originAllowed(req)) {
         return send(res, 403, JSON.stringify({ error: 'cross-origin write rejected' }));
       }
       readBody(req, res, (json, raw) => {
-        if (!isSceneShaped(json)) {
+        const shape = sceneFacts(json);
+        if (!shape.ok) {
           return send(
             res,
             422,
             JSON.stringify({
-              error:
-                'not an incanto scene — required: format: 1, type: "scene", name: string, root: object. The file was NOT written.',
+              error: `not an incanto scene — ${shape.why}. The file was NOT written.`,
             }),
           );
         }

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";
@@ -145,6 +146,12 @@ type Rapier = typeof RapierNs;
 interface Physics2DOptions {
   /** px/s², y-down. Default: scene `physics.gravity`, else [0, 980]. */
   gravity?: [number, number];
+  /**
+  * Build the colliders and keep them on the tree, but never advance the world
+  * (default: `true`, i.e. simulate). See {@link Physics3DOptions.simulate} —
+  * the scene editor uses it to draw the REAL colliders without running them.
+  */
+  simulate?: boolean;
 }
 /**
 * Enable 2D physics for an engine. Dynamically imports Rapier (compat build,
@@ -157,9 +164,11 @@ declare function enablePhysics2D(engine: Engine, opts?: Physics2DOptions): Promi
 */
 declare class Physics2D {
   private readonly R;
-  private readonly engine;
+  readonly engine: 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;
@@ -174,11 +183,20 @@ declare class Physics2D {
   private lastScene;
   constructor(R: Rapier, engine: Engine, opts?: Physics2DOptions);
   /** @internal Driven by engine.fixedUpdated. */
+  /** Whether the solver runs at all. False = collider outlines only. */
+  private readonly simulate;
   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;
+  /**
+  * 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;
   /**
@@ -200,6 +218,13 @@ declare class Physics2D {
   private readonly jointSet;
   private readonly joints;
   private readonly bodySet;
+  /**
+  * Move every body to its node's current transform — outline mode only.
+  *
+  * Computed exactly as `ensureEntry` computes a body's first pose, so an
+  * outline drawn in the editor is the outline the running game draws.
+  */
+  private poseFromTree;
   private syncBodies;
   private ensureEntry;
 }
@@ -249,6 +274,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 +308,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 +772,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-5z_QVtLx.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-3kOQCtgd.js";
 //#region src/2d/library-sprite.ts
 /**
 * Turn a library sprite-animation JSON into a scene-ready spritesheet asset