@volter/editor-core 0.5.57

package/server/routes/route-helpers.ts

@@ -0,0 +1,29 @@
+/**
+ * The helpers shared across `register<Family>Routes` modules — extracted with
+ * the routes that already used them when they moved out of `editor-server.ts`.
+ * Route bodies themselves are byte-preserved by the split; nothing here
+ * changes what any route answers.
+ */
+
+import type { Request, Response } from 'express';
+
+/**
+ * An `AbortSignal` that fires when the CLIENT gives up, so a long git or
+ * network operation stops with the request that asked for it rather than
+ * running to completion for nobody.
+ */
+export function requestOperationSignal(req: Request): AbortSignal {
+  const controller = new AbortController();
+  req.once('aborted', () => controller.abort());
+  return controller.signal;
+}
+
+/**
+ * The share-host verbs' error answer. 409 for the one recoverable case (the
+ * owner has to open their editor tab before a host identity can be bound),
+ * 400 for everything else.
+ */
+export function shareControlError(res: Response, error: unknown): void {
+  const message = error instanceof Error ? error.message : String(error);
+  res.status(message.includes('Open the local editor tab') ? 409 : 400).json({ error: message });
+}

package/server/routes/served-modules.ts

@@ -0,0 +1,138 @@
+/**
+ * `/__editor/served-modules` — the ONE door by which the Code-OSS frame finds
+ * the editor.
+ *
+ * WHO ASKS. The fork's workbench contribution (docs/CODE-OSS.md). It boots into
+ * a VS Code page, hands over its parts, and then needs the vgai editor's own
+ * entry point to import — the PRODUCT's entry, which mounts the kit's bridge and
+ * so swaps the SDK layout host that renders our panels into those parts. The
+ * contribution reads `modules[].url` for the id `vscode-bridge`, imports exactly
+ * that, and reads `mountVgai` off it.
+ * `vgaiSessionOrigin.ts` also uses this route as its "is there a session here"
+ * probe, so it answers 200 even when it has nothing to serve.
+ *
+ * WHAT IT SERVES: the PRODUCT's one source entry — `@vgai/game-editor`'s or
+ * `@vgai/model-editor`'s `src/index.ts`, which composes the product and
+ * re-exports `mountVgai` (`packages/editor/src/frame/product.ts`). Which
+ * product that is comes from the project's own dependencies, resolved by the
+ * CLI and handed over (`session-product.ts`); the kit's own mount,
+ * `frame/bridge.tsx`'s `mountEditor`, is not served to anybody and names no
+ * product.
+ *
+ * WHERE THE URL COMES FROM is the host's, not this route's, because the two
+ * hosts serve the editor differently and only they know how:
+ *
+ *  - `dev.ts` runs Vite over the checkout, so the product entry is an ordinary
+ *    module in the graph and the URL is its path, stamped with its own mtime.
+ *  - `packaged.ts` serves the PRODUCT's production build, so the URL is the
+ *    built entry's hashed chunk.
+ *
+ * A host with no bundler behind it supplies no answer at all, and a session
+ * whose project declares no product supplies `null`; this route says either by
+ * name, with the id the contribution was looking for — a frame that cannot find
+ * the editor must read as a refusal, never as an empty list.
+ *
+ * THE QUERY KEY MAY NEVER BE `v` — see {@link ServedModuleAnswer.url}.
+ */
+
+import { PRODUCT_INSTALL_LINES } from '@volter/editor-sdk/session/product-locator';
+import type { Request, Response } from 'express';
+import type { EditorServerRouter } from '../editor-server';
+import type { RouteContext } from './context';
+
+/**
+ * The one id this door serves, and the one the fork's contribution looks for
+ * (`vgaiBlender.contribution.ts`). It is a wire constant shared by two
+ * repositories: changing it here without changing it there is a frame that
+ * mounts nothing.
+ */
+export const FRAME_BRIDGE_MODULE_ID = 'vscode-bridge';
+
+export interface ServedModuleAnswer {
+  readonly id: string;
+  /**
+   * The import URL, carrying the file's own mtime in dev and the build's hash
+   * when packaged. A changed bridge is a changed URL and therefore a fresh
+   * transform; an unchanged one reuses Vite's cache.
+   *
+   * THE QUERY KEY IS `mtime` AND MAY NEVER BE `v`, and that spelling is the
+   * whole of walk 3's session-restart break (measured 2026-09-20). Vite's
+   * transform middleware decides its cache header with
+   * `DEP_VERSION_RE = /[?&](v=[\w.-]+)\b/` — any `?v=` at all — and answers a
+   * match with `Cache-Control: max-age=31536000, immutable`, the header meant
+   * for content-addressed dep chunks. So `?v=<mtime>` made the browser keep
+   * this module's TRANSFORMED BODY for a year without revalidating, and that
+   * body has Vite's rewritten imports baked into it:
+   * `…/node_modules/.vite-editor/v2-<key>/deps/react.js?v=<browserHash>`.
+   * Close the session, start another, and every ordinary editor module (served
+   * `no-cache`) revalidates onto the new generation while the cached bridge
+   * replays the old one — two React instances in one page, which the editor
+   * reports as `Invalid hook call` / `Cannot read properties of null (reading
+   * 'useState')` at `AppRoot`. That is why the documented recovery needed BOTH
+   * a fresh browser profile (the poison is the HTTP cache) and
+   * `rm -rf node_modules/.vite-editor` (so the stale generation stops
+   * resolving). With `mtime` the response is `no-cache`, the browser
+   * revalidates against the ETag, and an unchanged bridge still costs one 304.
+   */
+  readonly url: string;
+}
+
+export interface ServedModuleRefusal {
+  readonly id: string | null;
+  readonly message: string;
+}
+
+export function registerServedModuleRoutes(router: EditorServerRouter, ctx: RouteContext): void {
+  router.get('/__editor/served-modules', (_req: Request, res: Response) => {
+    res.set('Cache-Control', 'no-store');
+    const answer = ctx.options.frameBridgeUrl;
+    if (answer === undefined) {
+      res.json({
+        modules: [],
+        refusals: [
+          {
+            id: FRAME_BRIDGE_MODULE_ID,
+            message:
+              'This session serves no module graph, so it cannot serve the editor to the Code-OSS ' +
+              'frame (no bundler behind it). `volter-editor edit` sessions — the dev checkout and the ' +
+              "project's own installed @vgai/editor — both can.",
+          },
+        ],
+      });
+      return;
+    }
+    let url: string | null;
+    try {
+      url = answer();
+    } catch (error) {
+      res.json({
+        modules: [],
+        refusals: [
+          {
+            id: FRAME_BRIDGE_MODULE_ID,
+            message: error instanceof Error ? error.message : String(error),
+          },
+        ],
+      });
+      return;
+    }
+    if (url === null) {
+      res.json({
+        modules: [],
+        refusals: [
+          {
+            id: FRAME_BRIDGE_MODULE_ID,
+            message:
+              'This session is serving no vgai product, so there is no editor for the Code-OSS ' +
+              'frame to import. A product is the running program — the editor IS ' +
+              '@vgai/game-editor or @vgai/model-editor — and which one runs is what the project ' +
+              'installed. Install one and run `volter-editor edit` again:\n' +
+              `${PRODUCT_INSTALL_LINES.join('\n')}`,
+          },
+        ],
+      });
+      return;
+    }
+    res.json({ modules: [{ id: FRAME_BRIDGE_MODULE_ID, url }], refusals: [] });
+  });
+}

package/server/routes/session-tabs.ts

@@ -0,0 +1,196 @@
+/**
+ * `/__editor/heartbeat`, the heartbeat worker script, `/__editor/tab/**` and
+ * `/__editor/tab-yielded` — the TAB BIJECTION's HTTP surface.
+ *
+ * Per edited game, one and only one tab: extras yield, a lost tab self-heals,
+ * shutdown closes it. These routes are deliberately trivial, because presence
+ * has to keep working no matter what is wrong with the rest of the page — the
+ * worker POSTs a beat whenever its own socket cannot carry one, and a yielded
+ * tab lands on a static page rather than a running editor.
+ *
+ * The decisions all live in `tab-lifecycle.ts` and the control plane; this
+ * module is the doorway.
+ */
+
+import type { Request, Response } from 'express';
+import { renderEditorBrandPage } from '../editor-brand-html';
+import type { EditorServerRouter } from '../editor-server';
+import { allowCrossOriginFrameEmbedding } from '../server-utils';
+import { readTabBootstrapSource, TAB_BOOTSTRAP_PATH } from '../tab-bootstrap';
+import {
+  parseBeat,
+  parseTabClose,
+  TAB_CLOSE_PATH,
+  TAB_HEARTBEAT_WORKER_PATH,
+  TAB_HEARTBEAT_WORKER_SOURCE,
+} from '../tab-heartbeat';
+import type { RouteContext } from './context';
+import type { ControlPlane } from './control-plane';
+
+export function registerSessionTabRoutes(
+  router: EditorServerRouter,
+  ctx: RouteContext,
+  plane: ControlPlane,
+): void {
+  const { hostTabLifecycle, participantTabLifecycles, tabBijectionOptions, trustedShareIdentity } =
+    ctx;
+  const { handleTabRoute } = plane;
+
+  // ---- The tab bootstrap (tab-bootstrap.ts) ----
+  //
+  // What makes a PAGE a TAB, for a page vgai does not author: the Code-OSS
+  // frame loads this exact script — index.html's own inline bootstrap, read
+  // out of index.html, never copied — and from there it mints an identity,
+  // beats, and departs like any other tab. See tab-bootstrap.ts's header.
+  router.get(TAB_BOOTSTRAP_PATH, (_req: Request, res: Response) => {
+    let source: string;
+    try {
+      source = readTabBootstrapSource();
+    } catch (error) {
+      // A frame that cannot get this script is a tab that never beats, so the
+      // failure is stated in the body the page will have in its console —
+      // never an empty 200 that looks like it worked.
+      res.status(500).type('text/plain').send(String(error));
+      return;
+    }
+    res.setHeader('Content-Type', 'text/javascript; charset=utf-8');
+    // Never cached, for the heartbeat worker's reason and one more: Electron's
+    // HTTP cache is what made a desktop page straddle two module generations
+    // (docs/CODE-OSS.md §Desktop traps), and the bootstrap is the one script
+    // whose staleness the session cannot detect.
+    res.setHeader('Cache-Control', 'no-store');
+    allowCrossOriginFrameEmbedding(res);
+    res.send(source);
+  });
+
+  // ---- The tab heartbeat (tab-heartbeat.ts) ----
+  //
+  // The worker script, and the POST the worker falls back to whenever its own
+  // socket cannot carry a beat. Both are deliberately trivial: presence must
+  // survive whatever is wrong with the rest of the page.
+  router.get(TAB_HEARTBEAT_WORKER_PATH, (_req: Request, res: Response) => {
+    res.setHeader('Content-Type', 'text/javascript; charset=utf-8');
+    // Never cached: a stale worker is a tab that beats a protocol the server
+    // has moved on from, and the file is under 4 KB.
+    res.setHeader('Cache-Control', 'no-store');
+    allowCrossOriginFrameEmbedding(res);
+    res.send(TAB_HEARTBEAT_WORKER_SOURCE);
+  });
+
+  router.post('/__editor/heartbeat', (req: Request, res: Response) => {
+    const beat = parseBeat(req.body);
+    if (beat === null) {
+      res.status(400).json({ error: 'heartbeat requires { tabId, epoch, seq, visibility }' });
+      return;
+    }
+    res.json({ reply: hostTabLifecycle.onBeat(beat) });
+  });
+
+  // THE PAGE'S GOODBYE. `pagehide` → `navigator.sendBeacon`, which is the one
+  // transport the browser promises to deliver for a document that is already
+  // gone — so this route must do nothing but record and answer. It is what
+  // lets the table say `closed`/`reloading` where it could previously only
+  // watch the beats stop and call it `crashed`. No response body: a beacon's
+  // sender is gone and cannot read one.
+  router.post(TAB_CLOSE_PATH, (req: Request, res: Response) => {
+    const beacon = parseTabClose(req.body);
+    if (beacon === null) {
+      res.status(400).json({ error: 'tab close requires { tabId, epoch }' });
+      return;
+    }
+    hostTabLifecycle.onTabClose(beacon);
+    for (const lifecycle of participantTabLifecycles.values()) lifecycle?.onTabClose(beacon);
+    res.status(204).end();
+  });
+
+  // ---- Tab bijection (one browser tab per edited game — tab-lifecycle.ts) ----
+  //
+  // POST /__editor/tab/ensure — `vgai edit`/`create`'s idempotent
+  // convergence: focus/retarget the blessed tab, wait for an arriving one,
+  // or open exactly one. `{ open: false }` (the caller's --no-open) never
+  // opens. When bijection is off for this session, answer honestly from the
+  // raw SSE count so the CLI can decide for itself.
+  router.post('/__editor/tab/ensure', (req: Request, res: Response) => {
+    const open = (req.body as { open?: unknown } | undefined)?.['open'] !== false;
+    if (!tabBijectionOptions) {
+      // Bijection is off for this session, but the TABLE still knows whether
+      // a tab is here — answer from it, not from a socket count.
+      res.json({
+        status: hostTabLifecycle.blessedTabId() !== null ? 'focused' : 'disabled',
+      });
+      return;
+    }
+    res.json({ status: hostTabLifecycle.ensure(open) });
+  });
+
+  // POST /__editor/tab/route — the page saying which surface it is showing
+  // ('project' = the editor on this session's project; 'no-project' = the
+  // launcher or the startup-failure surface). A launcher tab holds the same
+  // SSE connection as an editor tab, so the bijection SEES it (before this it
+  // held none at all, and the lifecycle happily opened a second tab beside a
+  // perfectly good one); the route is what keeps `ensure` honest about
+  // whether that tab is on the project yet.
+  router.post('/__editor/tab/route', (req: Request, res: Response) => {
+    const outcome = handleTabRoute(
+      (req.body ?? {}) as Record<string, unknown>,
+      trustedShareIdentity(req),
+    );
+    if (outcome.status === 200) res.json({ ok: true });
+    else res.status(outcome.status).json({ error: outcome.error });
+  });
+
+  // POST /__editor/tab/claim — the yield page's "Use here instead": the
+  // current blessed tab is told to yield; the claimant reloads `/` and its
+  // fresh connection takes the blessing.
+  router.post('/__editor/tab/claim', (req: Request, res: Response) => {
+    const claimedParticipantId = (req.body as { participantId?: unknown } | undefined)
+      ?.participantId;
+    const trusted = trustedShareIdentity(req);
+    if (
+      trusted &&
+      typeof claimedParticipantId === 'string' &&
+      trusted.participantId !== claimedParticipantId
+    ) {
+      res.status(403).json({ error: 'A shared tab can only claim its own participant.' });
+      return;
+    }
+    const participantId = trusted?.participantId ?? claimedParticipantId;
+    const lifecycle =
+      typeof participantId === 'string'
+        ? participantTabLifecycles.get(participantId)
+        : trusted
+          ? undefined
+          : hostTabLifecycle;
+    lifecycle?.claim();
+    res.json({ ok: true });
+  });
+
+  // POST /__editor/tab/expect-restart — a successor server is about to take
+  // this port (source-change restart): keep the tab, it will reconnect.
+  router.post('/__editor/tab/expect-restart', (_req: Request, res: Response) => {
+    for (const lifecycle of new Set([hostTabLifecycle, ...participantTabLifecycles.values()])) {
+      lifecycle?.expectRestart();
+    }
+    res.json({ ok: true });
+  });
+
+  // GET /__editor/tab-yielded — the static page a yielded tab lands on when
+  // `window.close()` is refused (user-opened tabs). Minimal on purpose: the
+  // editor must never RUN in two tabs for one session.
+  router.get('/__editor/tab-yielded', (_req: Request, res: Response) => {
+    res.type('html').send(
+      renderEditorBrandPage({
+        subject: 'Editor open in another tab',
+        description: 'This Volter Editor session is active in another browser tab.',
+        contentHtml:
+          "<h1>Editor open in another tab</h1><p>This game's editor is active elsewhere.</p>" +
+          '<button id="claim">Use here instead</button>',
+        scriptHtml:
+          'document.getElementById("claim").addEventListener("click",async()=>{' +
+          'const participantId=new URLSearchParams(location.search).get("participantId");' +
+          'try{await fetch("/__editor/tab/claim",{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify({participantId})})}catch{}' +
+          'location.replace("/")});',
+      }),
+    );
+  });
+}

package/server/routes/settings.ts

@@ -0,0 +1,121 @@
+/**
+ * THE TWO SHARED SETTINGS LAYERS on disk (ARCHITECTURE-CORE §Editor chrome,
+ * "Settings have four layers with named homes"):
+ *
+ *   GET/POST /__editor/settings/user      ~/.vgai/settings.json
+ *   GET/POST /__editor/settings/project   <project>/.vgai/settings.json
+ *
+ * A read validates the file against `EditorSettingsSchema` and, when it does
+ * not parse, answers `{ settings: {}, issues }` naming the file's problems so
+ * the editor still opens and the person sees exactly what to fix. A write is
+ * refused (400, same issues) rather than persisting a document the next read
+ * would reject. Whole-document replace, like `/__editor/editor-state`: the
+ * client store is the one writer and merges its own patches.
+ *
+ * The user file's home is `VGAI_USER_SETTINGS_PATH` when set (the same
+ * override idiom as `VGAI_ACCOUNT_PATH`), else `~/.vgai/settings.json`.
+ */
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import type { Request, Response } from 'express';
+import { type EditorSettings, parseEditorSettings } from '@volter/editor-project/settings/schema';
+import type { EditorServerRouter } from '../editor-server';
+import type { RouteContext } from './context';
+
+export const USER_SETTINGS_PATH = process.env['VGAI_USER_SETTINGS_PATH']
+  ? resolve(process.env['VGAI_USER_SETTINGS_PATH'])
+  : join(homedir(), '.vgai', 'settings.json');
+
+export function projectSettingsPath(projectRoot: string): string {
+  return join(projectRoot, '.vgai', 'settings.json');
+}
+
+export interface SettingsFileRead {
+  readonly settings: EditorSettings;
+  /** Validation problems with the file on disk, empty when it parsed (or is absent). */
+  readonly issues: readonly string[];
+  readonly path: string;
+}
+
+export async function readSettingsFile(path: string): Promise<SettingsFileRead> {
+  let raw: string;
+  try {
+    raw = await readFile(path, 'utf-8');
+  } catch {
+    return { settings: {}, issues: [], path };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (cause) {
+    return { settings: {}, issues: [`not JSON: ${(cause as Error).message}`], path };
+  }
+  const result = parseEditorSettings(parsed);
+  return result.settings
+    ? { settings: result.settings, issues: [], path }
+    : { settings: {}, issues: result.issues, path };
+}
+
+const pendingWrites = new Map<string, Promise<void>>();
+
+export async function writeSettingsFile(path: string, settings: EditorSettings): Promise<void> {
+  const text = `${JSON.stringify(settings, null, 2)}\n`;
+  // Applying a style sets several axes in one turn. Concurrent truncating
+  // writes used to interleave, leaving a JSON document with another's tail.
+  // Order this server's writes and publish atomically for other sessions.
+  const write = (pendingWrites.get(path) ?? Promise.resolve())
+    .catch(() => {})
+    .then(async () => {
+      await mkdir(dirname(path), { recursive: true });
+      const temporary = `${path}.${randomUUID()}.tmp`;
+      try {
+        await writeFile(temporary, text, { encoding: 'utf-8', mode: 0o600 });
+        await rename(temporary, path);
+      } finally {
+        await rm(temporary, { force: true });
+      }
+    });
+  pendingWrites.set(path, write);
+  try {
+    await write;
+  } finally {
+    if (pendingWrites.get(path) === write) pendingWrites.delete(path);
+  }
+}
+
+export function registerSettingsRoutes(router: EditorServerRouter, ctx: RouteContext): void {
+  const register = (layer: 'user' | 'project', pathFor: () => string | null) => {
+    router.get(`/__editor/settings/${layer}`, async (_req: Request, res: Response) => {
+      const path = pathFor();
+      if (!path) {
+        res.json({ settings: {}, issues: [], path: null });
+        return;
+      }
+      res.json(await readSettingsFile(path));
+    });
+    router.post(`/__editor/settings/${layer}`, async (req: Request, res: Response) => {
+      const path = pathFor();
+      if (!path) {
+        res.status(400).json({ error: 'No project open.' });
+        return;
+      }
+      const result = parseEditorSettings(req.body);
+      if (!result.settings) {
+        res.status(400).json({ error: `Invalid ${layer} settings.`, issues: result.issues });
+        return;
+      }
+      try {
+        await writeSettingsFile(path, result.settings);
+        res.json({ ok: true, path });
+      } catch (cause) {
+        res.status(500).json({ error: `Could not write ${path}: ${(cause as Error).message}` });
+      }
+    });
+  };
+  register('user', () => USER_SETTINGS_PATH);
+  register('project', () =>
+    ctx.projectRoot === ctx.engineRoot ? null : projectSettingsPath(ctx.projectRoot),
+  );
+}