@volter/editor-sdk 0.5.57

package/src/session/editor-compatibility.ts

@@ -0,0 +1,248 @@
+import { GAME_MANIFEST_VERSION } from '@volter/editor-project/manifest/schema';
+
+export interface EditorServerCompatibility {
+  apiVersion: 1;
+  engineVersion: string | null;
+  manifestVersion: number;
+  startedAt: string;
+  source:
+    | { state: 'current' }
+    | { state: 'restart-required'; changedPath: string; changedAt: string };
+}
+
+export type StartupRecovery =
+  | {
+      kind: 'retry-editor';
+      title: 'Editor server unavailable';
+      guidance: string;
+      command: 'volter-editor edit .';
+    }
+  | {
+      kind: 'restart-editor';
+      title: 'Restart this editor';
+      guidance: string;
+      command: 'volter-editor edit .' | 'volter-editor close && volter-editor edit .';
+    }
+  | {
+      kind: 'use-compatible-editor';
+      title: 'Use a compatible editor';
+      guidance: string;
+    };
+
+export class ProjectCompatibilityError extends Error {
+  readonly recovery: StartupRecovery;
+
+  constructor(message: string, recovery: StartupRecovery) {
+    super(message);
+    this.name = 'ProjectCompatibilityError';
+    this.recovery = recovery;
+  }
+}
+
+export function editorServerUnavailableError(detail?: string): ProjectCompatibilityError {
+  return new ProjectCompatibilityError(
+    `Could not reach the local editor server${detail ? `: ${detail}` : '.'}`,
+    {
+      kind: 'retry-editor',
+      title: 'Editor server unavailable',
+      guidance: 'Make sure the local editor is running, then retry this operation.',
+      command: 'volter-editor edit .',
+    },
+  );
+}
+
+export function isStartupRecovery(value: unknown): value is StartupRecovery {
+  if (!value || typeof value !== 'object') return false;
+  const candidate = value as Record<string, unknown>;
+  if (typeof candidate['title'] !== 'string' || typeof candidate['guidance'] !== 'string') {
+    return false;
+  }
+  switch (candidate['kind']) {
+    case 'retry-editor':
+      return candidate['command'] === 'volter-editor edit .';
+    case 'restart-editor':
+      return (
+        candidate['command'] === 'volter-editor edit .' ||
+        candidate['command'] === 'volter-editor close && volter-editor edit .'
+      );
+    case 'use-compatible-editor':
+      return candidate['command'] === undefined;
+    default:
+      return false;
+  }
+}
+
+interface ProjectIdentity {
+  manifestVersion?: unknown;
+  engine?: { version?: unknown } | undefined;
+  /**
+   * The manifest's `roots`, RAW or resolved — read only by
+   * `usesNoPinnedEngineApi` below, structurally, so either shape works. Left
+   * `unknown` on purpose: this module is the pre-Zod identity check, and
+   * inventing a typed root here would duplicate the loader it runs before.
+   */
+  roots?: unknown;
+}
+
+/**
+ * Does this project mount through the engine's PINNED API at all? (S-7.)
+ *
+ * The engine-version pin below is an identity pin on the API a project's own
+ * source compiles against. An INGEST root has no such source: the game is
+ * foreign, unmodified, and reaches the host through the adapter seam, so
+ * there is nothing in it that a `@volter/editor-project` version could break — and
+ * nothing `vgai upgrade` could rewrite if the pin did complain. Found
+ * source-mounting SimCity: the project scaffolded at an older pin, and the
+ * editor refused to open it with "run vgai upgrade", an instruction that
+ * could not be carried out because the project has no engine surface to
+ * upgrade.
+ *
+ * The discriminator is the manifest itself — a root whose adapter carries an
+ * `ingest` block (raw) / resolves to `type: 'ingest'` — never a new opt-out
+ * flag, which would be a second thing to keep true. EVERY root must be an
+ * ingest for the exemption to apply: one first-party root and the project
+ * does compile against the pinned API, so the pin means exactly what it says.
+ *
+ * Note what this does NOT exempt: the manifest FORMAT version. The editor
+ * reads `vgai.project.json` for every project, ingest or not, so a v1
+ * manifest is still an upgrade this editor genuinely requires.
+ */
+export function usesNoPinnedEngineApi(project: ProjectIdentity): boolean {
+  const roots = project.roots;
+  if (!Array.isArray(roots) || roots.length === 0) return false;
+  return roots.every((root) => {
+    if (!root || typeof root !== 'object') return false;
+    const adapter = (root as { adapter?: unknown }).adapter;
+    if (!adapter || typeof adapter !== 'object') return false;
+    const shape = adapter as { ingest?: unknown; type?: unknown };
+    return shape.type === 'ingest' || (shape.ingest !== undefined && shape.ingest !== null);
+  });
+}
+
+const EXACT_SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+
+function compareSemver(a: string, b: string): -1 | 0 | 1 | null {
+  const aMatch = EXACT_SEMVER.exec(a);
+  const bMatch = EXACT_SEMVER.exec(b);
+  if (!aMatch || !bMatch) return null;
+  for (let index = 1; index <= 3; index++) {
+    const aPart = Number(aMatch[index]);
+    const bPart = Number(bMatch[index]);
+    if (aPart < bPart) return -1;
+    if (aPart > bPart) return 1;
+  }
+  return 0;
+}
+
+export function missingCompatibilityError(): ProjectCompatibilityError {
+  return new ProjectCompatibilityError(
+    'The editor page is newer than its local server. The running server does not expose the compatibility handshake this page expects.',
+    {
+      kind: 'restart-editor',
+      title: 'Restart this editor',
+      guidance: 'From the project folder, restart the local editor and then reopen this page.',
+      command: 'volter-editor close && volter-editor edit .',
+    },
+  );
+}
+
+/** Verify that the browser bundle and its long-running local server still agree. */
+export function assertEditorCompatibility(identity: EditorServerCompatibility): void {
+  if (identity.source.state === 'restart-required') {
+    throw new ProjectCompatibilityError(
+      `The local editor server is stale. ${identity.source.changedPath} changed after this server started at ${identity.startedAt}.`,
+      {
+        kind: 'restart-editor',
+        title: 'Restart this editor',
+        guidance:
+          'The browser has newer source than the running Node process. Run the editor command again from the project folder; it will replace the stale server on the same port.',
+        command: 'volter-editor edit .',
+      },
+    );
+  }
+
+  if (identity.manifestVersion !== GAME_MANIFEST_VERSION) {
+    throw new ProjectCompatibilityError(
+      `The editor page supports project format v${GAME_MANIFEST_VERSION}, but its local server supports v${identity.manifestVersion}.`,
+      {
+        kind: 'restart-editor',
+        title: 'Restart this editor',
+        guidance: 'The browser and server are from different editor builds. Restart them together.',
+        command: 'volter-editor close && volter-editor edit .',
+      },
+    );
+  }
+}
+
+/**
+ * The manifest FORMAT half of the check below. Split out so the pin half
+ * stays readable next to its S-7 exemption; no behavior of its own beyond
+ * what it always did.
+ */
+function assertManifestVersionCompatibility(project: ProjectIdentity): void {
+  if (
+    typeof project.manifestVersion === 'number' &&
+    project.manifestVersion !== GAME_MANIFEST_VERSION
+  ) {
+    if (project.manifestVersion < GAME_MANIFEST_VERSION) {
+      throw new ProjectCompatibilityError(
+        `This project uses manifest format v${project.manifestVersion}; this editor requires v${GAME_MANIFEST_VERSION}.`,
+        {
+          kind: 'use-compatible-editor',
+          title: 'Use a compatible editor',
+          guidance:
+            'Open this project with the editor version that created it. This product does not provide an automatic project-format upgrade.',
+        },
+      );
+    }
+    throw new ProjectCompatibilityError(
+      `This project uses manifest format v${project.manifestVersion}, which is newer than this editor's v${GAME_MANIFEST_VERSION} format.`,
+      {
+        kind: 'use-compatible-editor',
+        title: 'Use a compatible editor',
+        guidance: 'Open this project with the newer Volter Editor checkout or installation that created it.',
+      },
+    );
+  }
+}
+
+/** Verify the lightweight identity fields before full Zod manifest parsing. */
+export function assertProjectCompatibility(
+  project: ProjectIdentity,
+  editor: EditorServerCompatibility,
+): void {
+  assertManifestVersionCompatibility(project);
+
+  const projectEngine = project.engine?.version;
+  const editorEngine = editor.engineVersion;
+  if (typeof projectEngine !== 'string' || !editorEngine || projectEngine === editorEngine) return;
+  // S-7: a project that mounts nothing through the pinned API is not gated by
+  // it. See `usesNoPinnedEngineApi` for why, and for why it is the manifest —
+  // not a flag — that decides.
+  if (usesNoPinnedEngineApi(project)) return;
+
+  const comparison = compareSemver(projectEngine, editorEngine);
+  if (comparison === -1) {
+    throw new ProjectCompatibilityError(
+      `This project is pinned to @volter/editor-project ${projectEngine}, but this editor is running ${editorEngine}.`,
+      {
+        kind: 'use-compatible-editor',
+        title: 'Use a compatible editor',
+        guidance:
+          'Open the project with the editor version matching its pinned project API. This product does not automatically rewrite project source.',
+      },
+    );
+  }
+
+  throw new ProjectCompatibilityError(
+    `This project is pinned to @volter/editor-project ${projectEngine}, but this editor is running ${editorEngine}.`,
+    {
+      kind: 'use-compatible-editor',
+      title: 'Use a compatible editor',
+      guidance:
+        comparison === 1
+          ? 'This project targets a newer engine. Open it from the matching newer Volter Editor checkout or installation.'
+          : 'The engine identities differ. Open the project with the exact Volter Editor version it is pinned to.',
+    },
+  );
+}

package/src/session/editor-control-lifecycle.ts

@@ -0,0 +1,68 @@
+/**
+ * The identity envelope shared by every editor control transport.
+ *
+ * A page has more than one useful identity: the server process it loaded
+ * from, the tab it occupies, the page load inside that tab, and the current
+ * transport connection. Treating any one of those as all four is how a
+ * duplicated tab could heartbeat as B while its copied control socket still
+ * received commands as A. Every upstream control fact now names the complete
+ * generation that made it true.
+ */
+
+export const EDITOR_CONTROL_LIFECYCLE_VERSION = 1 as const;
+
+export interface EditorControlLifecycle {
+  readonly version: typeof EDITOR_CONTROL_LIFECYCLE_VERSION;
+  /** The editor server process (`processSessionId()`). */
+  readonly serverGeneration: string;
+  /** One accepted event-stream connection. Reconnects always mint a new one. */
+  readonly connectionGeneration: string;
+  /** The inline bootstrap's per-page id. */
+  readonly clientId: string;
+  /** The sessionStorage identity that survives reloads. */
+  readonly tabId: string;
+  /** The heartbeat worker's page-load epoch. */
+  readonly pageGeneration: string;
+}
+
+export function parseEditorControlLifecycle(value: unknown): EditorControlLifecycle | null {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return null;
+  const record = value as Record<string, unknown>;
+  if (
+    record['version'] !== EDITOR_CONTROL_LIFECYCLE_VERSION ||
+    typeof record['serverGeneration'] !== 'string' ||
+    typeof record['connectionGeneration'] !== 'string' ||
+    typeof record['clientId'] !== 'string' ||
+    typeof record['tabId'] !== 'string' ||
+    typeof record['pageGeneration'] !== 'string'
+  ) {
+    return null;
+  }
+  return {
+    version: EDITOR_CONTROL_LIFECYCLE_VERSION,
+    serverGeneration: record['serverGeneration'],
+    connectionGeneration: record['connectionGeneration'],
+    clientId: record['clientId'],
+    tabId: record['tabId'],
+    pageGeneration: record['pageGeneration'],
+  };
+}
+
+export type EditorControlLifecycleField = Exclude<keyof EditorControlLifecycle, 'version'>;
+
+/** Which parent generation disagrees, or null when the envelope is current. */
+export function editorControlLifecycleMismatch(
+  expected: EditorControlLifecycle,
+  reported: EditorControlLifecycle,
+): EditorControlLifecycleField | null {
+  for (const field of [
+    'serverGeneration',
+    'connectionGeneration',
+    'clientId',
+    'tabId',
+    'pageGeneration',
+  ] as const) {
+    if (expected[field] !== reported[field]) return field;
+  }
+  return null;
+}

package/src/session/editor-control-protocol.ts

@@ -0,0 +1,5 @@
+/**
+ * Downstream receipt emitted after the original command caller's response finishes.
+ * The browser waits for it before scheduling deferred selection presentation.
+ */
+export const COMMAND_RESULT_RECEIPT_EVENT = 'command-result-received';

package/src/session/entrypoint-selection-readers.ts

@@ -0,0 +1,66 @@
+/**
+ * Pure TS-AST readers over an entrypoint's SELECTION TABLE — shared by the
+ * write side (`entrypoint-selection-source.ts`) and the read side
+ * (`finders/scenes-from-entrypoint-selection.ts`). These two must agree on
+ * what a selection table IS, or play remounts a key the finder never
+ * discovered; one spelling here is what makes that agreement structural.
+ * (The finder-import boundary bans importing from `finders/` — this sibling
+ * sits outside that directory precisely so both sides can share it.)
+ */
+
+import ts from 'typescript';
+
+/** The object literal a module-level `const <name> = { … }` binds. */
+export function selectionTable(
+  sf: ts.SourceFile,
+  name: string,
+): ts.ObjectLiteralExpression | undefined {
+  for (const statement of sf.statements) {
+    if (!ts.isVariableStatement(statement)) continue;
+    for (const declaration of statement.declarationList.declarations) {
+      if (!ts.isIdentifier(declaration.name) || declaration.name.text !== name) continue;
+      const initializer = declaration.initializer;
+      if (initializer && ts.isObjectLiteralExpression(initializer)) return initializer;
+    }
+  }
+  return undefined;
+}
+
+/** A property's key when it is a plain identifier or string literal. */
+export function propertyKey(property: ts.ObjectLiteralElementLike): string | undefined {
+  const name = property.name;
+  if (!name) return undefined;
+  if (ts.isIdentifier(name) || ts.isStringLiteral(name)) return name.text;
+  return undefined;
+}
+
+/**
+ * The identifier the entrypoint INDEXES the selection table with — the
+ * `activeScene` in `scenes[activeScene]`.
+ *
+ * `undefined` when the module never indexes the table; `null` when it does
+ * but not readably (several identifiers, or a non-identifier index). Both
+ * are honest "cannot be read" answers the callers turn into their own notes.
+ */
+export function indexingIdentifier(
+  sf: ts.SourceFile,
+  selection: string,
+): string | undefined | null {
+  const names = new Set<string>();
+  let unreadable = false;
+  const visit = (node: ts.Node): void => {
+    if (
+      ts.isElementAccessExpression(node) &&
+      ts.isIdentifier(node.expression) &&
+      node.expression.text === selection
+    ) {
+      if (ts.isIdentifier(node.argumentExpression)) names.add(node.argumentExpression.text);
+      else unreadable = true;
+    }
+    ts.forEachChild(node, visit);
+  };
+  ts.forEachChild(sf, visit);
+  if (names.size === 0 && !unreadable) return undefined;
+  if (names.size !== 1 || unreadable) return null;
+  return [...names][0];
+}

package/src/session/entrypoint-selection-source.ts

@@ -0,0 +1,120 @@
+/**
+ * Serve-time rewrite of an entrypoint's swap-slot key.
+ *
+ * The scenes finder (`adapter/finders/scenes-from-entrypoint-selection.ts`)
+ * READS the same facts this module WRITES: a module-level `const <selection>
+ * = { … }` table, indexed by one identifier whose own module-level `const`
+ * is a string literal (`const activeScene = 'main'`). This is not an
+ * extraction of that finder — the finder stays the adapter-selected discovery
+ * algorithm, import-banned everywhere except the adapter loader. The rewrite
+ * is a host-owned mount parameter: play remounts the same entrypoint with a
+ * different declared key, without a new adapter slot and without mutating
+ * the file on disk.
+ *
+ * `typescript` is the same parser the finder already uses. This module is
+ * host-side only — a game's `vgai.adapter.ts` must not import it.
+ */
+
+import ts from 'typescript';
+import { indexingIdentifier, propertyKey, selectionTable } from './entrypoint-selection-readers';
+
+export type EntrypointSelectionRewrite =
+  | { readonly ok: true; readonly source: string; readonly changed: boolean }
+  | { readonly ok: false; readonly reason: string };
+
+function parse(path: string, source: string): ts.SourceFile {
+  return ts.createSourceFile(path, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+}
+
+function tableKeys(table: ts.ObjectLiteralExpression): string[] {
+  const keys: string[] = [];
+  for (const property of table.properties) {
+    const key = propertyKey(property);
+    if (key !== undefined) keys.push(key);
+  }
+  return keys;
+}
+
+function moduleLevelStringLiteral(sf: ts.SourceFile, name: string): ts.StringLiteral | undefined {
+  for (const statement of sf.statements) {
+    if (!ts.isVariableStatement(statement)) continue;
+    if ((statement.declarationList.flags & ts.NodeFlags.Const) === 0) continue;
+    for (const declaration of statement.declarationList.declarations) {
+      if (!ts.isIdentifier(declaration.name) || declaration.name.text !== name) continue;
+      const initializer = declaration.initializer;
+      if (initializer && ts.isStringLiteral(initializer)) return initializer;
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Rewrite the entrypoint so its swap slot mounts `key` instead of the
+ * source-declared occupant.
+ *
+ * Fails (never guesses) when the source is not the template's shape: no
+ * table, a key the table does not declare, or an index that is not a
+ * module-level `const` string. A no-op rewrite (`key` already at the slot)
+ * is still `ok` — remounting the same key is a real restart.
+ */
+export function rewriteEntrypointSelectionKey(
+  source: string,
+  path: string,
+  selection: string,
+  key: string,
+): EntrypointSelectionRewrite {
+  const sf = parse(path, source);
+  const table = selectionTable(sf, selection);
+  if (!table) {
+    return {
+      ok: false,
+      reason:
+        `${path} declares no module-level \`const ${selection} = { … }\` selection table, ` +
+        'so the host cannot remount it at another key.',
+    };
+  }
+  const keys = tableKeys(table);
+  if (!keys.includes(key)) {
+    return {
+      ok: false,
+      reason:
+        `"${key}" is not a key of ${path}'s \`${selection}\` table ` +
+        `(known: ${keys.length > 0 ? keys.join(', ') : 'none'}).`,
+    };
+  }
+  const identifier = indexingIdentifier(sf, selection);
+  if (identifier === undefined) {
+    return {
+      ok: false,
+      reason: `${path} never indexes \`${selection}\`, so there is no slot key to rewrite.`,
+    };
+  }
+  if (identifier === null) {
+    return {
+      ok: false,
+      reason:
+        `${path} indexes \`${selection}\` with something other than one single identifier, ` +
+        'so the host cannot rewrite the key it mounts.',
+    };
+  }
+  const literal = moduleLevelStringLiteral(sf, identifier);
+  if (!literal) {
+    return {
+      ok: false,
+      reason:
+        `${path} indexes \`${selection}\` with \`${identifier}\`, which is not a ` +
+        'module-level `const` bound to a string literal — the running game cannot be ' +
+        'sent to another key by rewriting the slot.',
+    };
+  }
+  if (literal.text === key) return { ok: true, source, changed: false };
+  const start = literal.getStart(sf);
+  const end = literal.getEnd();
+  const quote = source[start] ?? "'";
+  return {
+    ok: true,
+    source: `${source.slice(0, start)}${quote}${key}${quote}${source.slice(end)}`,
+    changed: true,
+  };
+}

package/src/session/game-css-scope.ts

@@ -0,0 +1,30 @@
+/**
+ * The ONE spelling of the game-CSS scope marker, and the act of putting it on
+ * an element.
+ *
+ * A game's page-level stylesheet is served rewritten into
+ * `@scope ([data-vgai-game-styles]) { … }` (`server/scoped-game-css.ts`), so
+ * the attribute below is the entire contract between the two halves: the
+ * server emits the selector, and every host container that owns a game's DOM
+ * wears the attribute. Both sides import it from here rather than spelling it,
+ * because a drift between them is silent — the sheet loads, matches nothing,
+ * and the HUD is unstyled exactly as it was before the feature existed.
+ *
+ * Deliberately dependency-free: the server imports this module, and a server
+ * import must not drag the editor's browser modules into a Node process.
+ */
+
+/** Attribute a host container wears to become a game-CSS scope root. */
+export const GAME_CSS_SCOPE_ATTRIBUTE = 'data-vgai-game-styles';
+
+/** The `@scope (…)` selector the served stylesheet is rooted at. */
+export const GAME_CSS_SCOPE_SELECTOR = `[${GAME_CSS_SCOPE_ATTRIBUTE}]`;
+
+/**
+ * Make `element` a game-CSS scope root. Idempotent, and deliberately the only
+ * writer of the attribute — a container that stops being a scope root is torn
+ * down with its mount, never un-marked.
+ */
+export function markGameCssScope(element: HTMLElement): void {
+  element.setAttribute(GAME_CSS_SCOPE_ATTRIBUTE, '');
+}

package/src/session/product-create.ts

@@ -0,0 +1,24 @@
+/** Project creation is executable product code, shared by its CLI and the host. */
+export interface ProductCreateRequest {
+  name: string;
+  targetDir: string;
+  template?: string;
+}
+export interface ProductCreateResult {
+  targetDir: string;
+  manifest: unknown;
+}
+export interface ProductCreateDeclaration {
+  readonly product: string;
+  readonly templates: readonly { readonly id: string; readonly name: string; readonly description?: string }[];
+  create(request: ProductCreateRequest): Promise<ProductCreateResult>;
+}
+export function assertProductCreateDeclaration(value: unknown, source: string): ProductCreateDeclaration {
+  const declaration = value as Partial<ProductCreateDeclaration> | null;
+  if (!declaration || typeof declaration.product !== 'string' ||
+      typeof declaration.create !== 'function' || !Array.isArray(declaration.templates) ||
+      declaration.templates.some(t => typeof t?.id !== 'string' || typeof t?.name !== 'string')) {
+    throw new Error(`${source}: expected a product, templates and create(request) function`);
+  }
+  return declaration as ProductCreateDeclaration;
+}