@volter/project 0.0.0-stage → 0.5.203

package/src/inspection.ts

@@ -0,0 +1,281 @@
+/**
+ * Read-only first-contact inspection for a folder the user may want to open
+ * or adapt. Detection is deliberately evidence-based and never writes files.
+ */
+
+export type ProjectWorkspaceState =
+  | 'volter-project'
+  | 'adaptable-project'
+  | 'empty-folder'
+  | 'unknown-project';
+
+export type SuggestedAdapterSurface = 'three' | 'canvas' | 'dom';
+
+export interface ProjectInspection {
+  workspaceState: ProjectWorkspaceState;
+  detectedTechnologies: string[];
+  suggestedSurface: SuggestedAdapterSurface | null;
+  entryCandidates: string[];
+  /** Evidence that makes automatic one-file metadata adaptation unsafe. */
+  adaptationBlockers: string[];
+  hasManifest: boolean;
+  writesPerformed: false;
+  summary: string;
+  nextAction: string;
+}
+
+export interface ProjectInspectionReader {
+  exists(path: string): Promise<boolean>;
+  read(path: string): Promise<string>;
+  list(path: string): Promise<ProjectInspectionEntry[]>;
+}
+
+export interface ProjectInspectionEntry {
+  name: string;
+  path: string;
+  type: 'file' | 'dir';
+}
+
+export interface IngestManifestOptions {
+  name: string;
+  engineVersion: string;
+  surface?: SuggestedAdapterSurface | undefined;
+  entry?: string | undefined;
+}
+
+const IGNORED_DIRECTORIES = new Set([
+  '.git',
+  '.volter',
+  'build',
+  'coverage',
+  'dist',
+  'node_modules',
+  'out',
+]);
+const SOURCE_EXTENSIONS = new Set(['.js', '.jsx', '.mjs', '.ts', '.tsx']);
+const MAX_VISITED_FILES = 500;
+const MAX_DIRECTORY_DEPTH = 4;
+
+function extension(path: string): string {
+  const dot = path.lastIndexOf('.');
+  return dot < 0 ? '' : path.slice(dot).toLowerCase();
+}
+
+function dependencyNames(value: unknown): Set<string> {
+  if (!value || typeof value !== 'object') return new Set();
+  const record = value as Record<string, unknown>;
+  const names = new Set<string>();
+  for (const field of ['dependencies', 'devDependencies', 'peerDependencies']) {
+    const dependencies = record[field];
+    if (!dependencies || typeof dependencies !== 'object') continue;
+    for (const name of Object.keys(dependencies as Record<string, unknown>)) names.add(name);
+  }
+  return names;
+}
+
+async function readPackageDependencies(reader: ProjectInspectionReader): Promise<Set<string>> {
+  if (!(await reader.exists('package.json'))) return new Set();
+  try {
+    return dependencyNames(JSON.parse(await reader.read('package.json')));
+  } catch {
+    return new Set();
+  }
+}
+
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: bounded breadth-first file evidence collection keeps traversal limits and filtering in one place.
+async function collectSourceFiles(reader: ProjectInspectionReader): Promise<string[]> {
+  const files: string[] = [];
+  const queue: Array<{ path: string; depth: number }> = [{ path: '', depth: 0 }];
+  while (queue.length > 0 && files.length < MAX_VISITED_FILES) {
+    const current = queue.shift();
+    if (!current) break;
+    let entries: ProjectInspectionEntry[];
+    try {
+      entries = await reader.list(current.path);
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (entry.type === 'dir') {
+        if (current.depth < MAX_DIRECTORY_DEPTH && !IGNORED_DIRECTORIES.has(entry.name)) {
+          queue.push({ path: entry.path, depth: current.depth + 1 });
+        }
+      } else if (SOURCE_EXTENSIONS.has(extension(entry.path)) || entry.path === 'index.html') {
+        files.push(entry.path);
+        if (files.length >= MAX_VISITED_FILES) break;
+      }
+    }
+  }
+  return files;
+}
+
+function candidateEntries(files: string[]): string[] {
+  const preferredNames = [
+    'src/volter-entry.tsx',
+    'src/volter-entry.ts',
+    'src/volter-host.tsx',
+    'src/volter-host.ts',
+    'src/adapter.tsx',
+    'src/adapter.ts',
+    'src/main.tsx',
+    'src/main.ts',
+    'src/index.tsx',
+    'src/index.ts',
+    'src/main.jsx',
+    'src/main.js',
+    'src/index.jsx',
+    'src/index.js',
+    'index.html',
+  ];
+  const available = new Set(files);
+  const preferred = preferredNames.filter((name) => available.has(name));
+  return [...preferred, ...files.filter((name) => !preferred.includes(name))].slice(0, 8);
+}
+
+/** Inspect a folder without mutating it or assuming that it is already VOLTER-shaped. */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one ordered evidence-to-recommendation decision table.
+export async function inspectProject(reader: ProjectInspectionReader): Promise<ProjectInspection> {
+  if (await reader.exists('volter.project.json')) {
+    return {
+      workspaceState: 'volter-project',
+      detectedTechnologies: ['Volter Editor'],
+      suggestedSurface: null,
+      entryCandidates: [],
+      adaptationBlockers: [],
+      hasManifest: true,
+      writesPerformed: false,
+      summary: 'This folder is already a Volter Editor project.',
+      nextAction: 'Open it in the editor.',
+    };
+  }
+
+  // An inaccessible root is not an empty folder. Propagate the read failure
+  // so callers can report it honestly instead of offering to scaffold over
+  // a location they could not inspect.
+  const rootEntries = await reader.list('');
+  if (rootEntries.length === 0) {
+    return {
+      workspaceState: 'empty-folder',
+      detectedTechnologies: [],
+      suggestedSurface: null,
+      entryCandidates: [],
+      adaptationBlockers: [],
+      hasManifest: false,
+      writesPerformed: false,
+      summary: 'This folder is empty.',
+      nextAction: 'Create a new Volter Editor project here.',
+    };
+  }
+
+  const dependencies = await readPackageDependencies(reader);
+  const files = await collectSourceFiles(reader);
+  const technologies: string[] = [];
+  if (dependencies.has('@react-three/fiber')) technologies.push('React Three Fiber');
+  if (dependencies.has('three')) technologies.push('three.js');
+  if (dependencies.has('pixi.js') || [...dependencies].some((name) => name.startsWith('@pixi/'))) {
+    technologies.push('PixiJS');
+  }
+  if (dependencies.has('react')) technologies.push('React');
+  if (dependencies.has('vite')) technologies.push('Vite');
+
+  const suggestedSurface: SuggestedAdapterSurface | null = technologies.some(
+    (name) => name === 'three.js' || name === 'React Three Fiber',
+  )
+    ? 'three'
+    : technologies.includes('PixiJS')
+      ? 'canvas'
+      : technologies.includes('React')
+        ? 'dom'
+        : null;
+  const entries = candidateEntries(files);
+  const adaptationBlockers: string[] = [];
+  if (suggestedSurface && entries.length === 0) {
+    adaptationBlockers.push('No JavaScript or TypeScript entry candidate was found.');
+  }
+  if (suggestedSurface === 'dom' && entries[0]) {
+    let entrySource = '';
+    try {
+      entrySource = await reader.read(entries[0]);
+    } catch {
+      adaptationBlockers.push(`The suggested React entry ${entries[0]} could not be read.`);
+    }
+    if (/\b(?:ReactDOM\s*\.\s*render|createRoot|hydrateRoot)\s*\(/.test(entrySource)) {
+      adaptationBlockers.push(
+        `The React app mounts itself in ${entries[0]}; Volter Editor ingest requires a host-shim module that default-exports the mounted component and preserves the app's providers.`,
+      );
+    } else if (!/\bexport\s+default\b/.test(entrySource)) {
+      adaptationBlockers.push(
+        `The React entry ${entries[0]} does not default-export a component; create a host-shim module that does before adding Volter Editor metadata.`,
+      );
+    }
+  }
+  const adaptable = suggestedSurface !== null && adaptationBlockers.length === 0;
+
+  return {
+    workspaceState: adaptable ? 'adaptable-project' : 'unknown-project',
+    detectedTechnologies: technologies,
+    suggestedSurface,
+    entryCandidates: entries,
+    adaptationBlockers,
+    hasManifest: false,
+    writesPerformed: false,
+    summary: adaptable
+      ? `This looks like an existing ${technologies.join(' + ') || 'web'} project.`
+      : suggestedSurface
+        ? `This ${technologies.join(' + ') || 'web'} project needs an adapter step before Volter Editor metadata can be added safely.`
+        : 'This folder is not empty, but its game framework could not be identified.',
+    nextAction: adaptable
+      ? 'Review the detected entry and adapter, then add Volter Editor metadata without rewriting the game source.'
+      : (adaptationBlockers[0] ??
+        'Choose the entry point and adapter explicitly before adding Volter Editor metadata.'),
+  };
+}
+
+/**
+ * Build the one-file, source-preserving metadata bridge for a detected app.
+ * The caller is responsible for obtaining explicit consent before writing it.
+ */
+export function createIngestManifest(
+  inspection: ProjectInspection,
+  options: IngestManifestOptions,
+): Record<string, unknown> {
+  const surface = options.surface ?? inspection.suggestedSurface;
+  const entry = options.entry ?? inspection.entryCandidates[0];
+  const portableEntry = entry?.replace(/\\/g, '/');
+  const entryEscapesProject =
+    portableEntry !== undefined &&
+    (portableEntry.startsWith('/') ||
+      portableEntry.startsWith('//') ||
+      /^[A-Za-z]:\//.test(portableEntry) ||
+      portableEntry.split('/').includes('..'));
+  const explicitUnknownOverride =
+    inspection.workspaceState === 'unknown-project' &&
+    options.surface !== undefined &&
+    options.entry !== undefined;
+  if (
+    (inspection.workspaceState !== 'adaptable-project' && !explicitUnknownOverride) ||
+    !surface ||
+    !entry ||
+    entryEscapesProject
+  ) {
+    throw new Error(
+      entryEscapesProject
+        ? 'Adapter entry must be a project-relative path that stays inside the selected folder.'
+        : (inspection.adaptationBlockers[0] ??
+            'Choose a supported adapter surface and source entry before adapting this folder.'),
+    );
+  }
+  return {
+    manifestVersion: 2,
+    name: options.name,
+    version: '0.1.0',
+    engine: { version: options.engineVersion },
+    roots: [
+      {
+        id: 'game',
+        adapter: { surface, ingest: {} },
+        entry,
+      },
+    ],
+  };
+}

package/src/manifest/configuration-kinds.ts

@@ -0,0 +1,241 @@
+/**
+ * THE RUN-CONFIGURATION KIND REGISTRY — the open set of kinds a manifest's
+ * `configurations[]` may declare (ARCHITECTURE-CORE §The project model). A run
+ * configuration is one of the project's ENTRYPOINTS: something the editor,
+ * the CLI or a harness can start by id. The engine registers two kinds
+ * here; a capability registers more through the same door; the manifest
+ * validates each declaration against its kind's own schema at load, and an
+ * unregistered kind refuses loudly naming the registered ones.
+ *
+ * The implicit configuration every project with roots has is `play` — mount
+ * every root in the host — which is never declared and may be named by a
+ * `compound`.
+ */
+
+import { type ZodType, z } from 'zod';
+
+/** The envelope every declaration carries; the rest is the kind's. */
+export interface ConfigurationEnvelope {
+  readonly id: string;
+  readonly kind: string;
+}
+
+export type ConfigurationRole = 'run' | 'build';
+
+export interface ConfigurationKindRegistration<
+  T extends ConfigurationEnvelope = ConfigurationEnvelope,
+> {
+  readonly kind: T['kind'];
+  /** Where a configuration of this kind surfaces and which verb starts it:
+   *  `run` (the transport) or `build` (Build Profiles, Export). */
+  readonly role: ConfigurationRole;
+  /** The declaration's full shape, envelope included; `.strict()`. */
+  readonly schema: ZodType<T>;
+  /** One line for schema output and refusals. */
+  readonly describe: string;
+  /** A build-role kind backed by a project TOOL (the operation catalog):
+   *  the host runs `tool` with `input(configuration)` and reports its
+   *  outcome as the build's. This is how a capability's bake becomes a
+   *  build without the engine knowing what a bake is. */
+  readonly build?: { readonly tool: string; readonly input: (configuration: T) => unknown };
+}
+
+/**
+ * What a CONTRIBUTION exports to register a kind — a plain object, so a
+ * project module (evaluated with the project's own copy of the engine)
+ * hands it to the HOST, which registers it in the host's registry. A module
+ * `editor/contributions/<name>.kind.ts` exports it as `kind`.
+ */
+export type ConfigurationKindContribution = ConfigurationKindRegistration;
+
+const CONFIGURATION_ROLES: readonly ConfigurationRole[] = ['run', 'build'];
+
+/** Register a contribution's kind after checking its shape by name. */
+export function registerContributedConfigurationKind(value: unknown, source: string): () => void {
+  const record = (value ?? {}) as Partial<ConfigurationKindContribution>;
+  const problems: string[] = [];
+  if (typeof record.kind !== 'string' || record.kind.length === 0)
+    problems.push('`kind` must be a non-empty string');
+  if (!CONFIGURATION_ROLES.includes(record.role as ConfigurationRole))
+    problems.push("`role` must be 'run' or 'build'");
+  if (typeof record.describe !== 'string') problems.push('`describe` must be a string');
+  const schema = record.schema as { safeParse?: unknown } | undefined;
+  if (!schema || typeof schema.safeParse !== 'function')
+    problems.push('`schema` must be a Zod schema');
+  const build = record.build as { tool?: unknown; input?: unknown } | undefined;
+  if (
+    build !== undefined &&
+    (typeof build.tool !== 'string' || typeof build.input !== 'function')
+  ) {
+    problems.push('`build` must be `{ tool: string; input(configuration) }`');
+  }
+  if (problems.length > 0) {
+    throw new Error(`${source}: not a configuration kind — ${problems.join('; ')}`);
+  }
+  return registerConfigurationKind(record as ConfigurationKindContribution);
+}
+
+const registry = new Map<string, ConfigurationKindRegistration>();
+
+/** Register a kind. A second registration replaces the first (a module
+ *  re-evaluated on save); never throws. */
+export function registerConfigurationKind<T extends ConfigurationEnvelope>(
+  registration: ConfigurationKindRegistration<T>,
+): () => void {
+  const entry = registration as unknown as ConfigurationKindRegistration;
+  registry.set(registration.kind, entry);
+  return () => {
+    if (registry.get(registration.kind) === entry) registry.delete(registration.kind);
+  };
+}
+
+export function registeredConfigurationKinds(): readonly string[] {
+  return [...registry.keys()];
+}
+
+export function configurationKind(kind: string): ConfigurationKindRegistration | undefined {
+  return registry.get(kind);
+}
+
+/** The id of the implicit configuration: mount every root in the host. */
+export const PLAY_CONFIGURATION_ID = 'play';
+
+/** A process the project runs beside the host: an entry module started
+ *  with the project's own toolchain, listening on a port when it has one. */
+export interface ProcessConfiguration extends ConfigurationEnvelope {
+  readonly kind: 'process';
+  /** Project-relative entry module (`server/main.ts`). */
+  readonly entry: string;
+  /** The command that starts it, run in a shell at `cwd`; `npx tsx <entry>`
+   *  when omitted. Declare it when the entry needs its own flags. */
+  readonly command?: string;
+  /** The port it listens on, when readiness means a port. */
+  readonly port?: number;
+  /** Project-relative working directory; the project root when omitted. */
+  readonly cwd?: string;
+  readonly env?: Readonly<Record<string, string>>;
+  /** How a runner knows it is up: the port accepting connections (the
+   *  default when `port` is set), or an HTTP path answering 2xx on it. */
+  readonly ready?: { readonly http?: string };
+}
+
+/** Several configurations started together, `play` included by name. */
+export interface CompoundConfiguration extends ConfigurationEnvelope {
+  readonly kind: 'compound';
+  readonly run: readonly string[];
+  /** How many instances of the host mount to run against the rest (the
+   *  editor's Instances picker is this parameter). */
+  readonly instances?: number;
+}
+
+/** A packaged build of the project's own web bundle: the project's build
+ *  script, then `dist/` packaged as the web artifact. The first build-role
+ *  kind; a capability registers more (a bake, a static site). */
+export interface BundleConfiguration extends ConfigurationEnvelope {
+  readonly kind: 'bundle';
+  /** The package.json script that builds (`build`). */
+  readonly script?: string;
+  /** Extra arguments after `--` (`['--base', './']` for an itch-style relative bundle). */
+  readonly args?: readonly string[];
+}
+
+export type DeclaredConfiguration = ConfigurationEnvelope & Readonly<Record<string, unknown>>;
+
+registerConfigurationKind<ProcessConfiguration>({
+  kind: 'process',
+  role: 'run',
+  describe: 'A process beside the host: an entry module, a port, readiness',
+  schema: z
+    .object({
+      id: z.string().min(1).describe('Configuration id'),
+      kind: z.literal('process'),
+      entry: z.string().min(1).describe('Project-relative entry module'),
+      command: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Shell command that starts it; `npx tsx <entry>` when omitted'),
+      port: z.number().int().min(1).max(65535).optional().describe('Port it listens on'),
+      cwd: z.string().min(1).optional().describe('Project-relative working directory'),
+      env: z.record(z.string(), z.string()).optional().describe('Environment for the process'),
+      ready: z
+        .object({ http: z.string().min(1).optional().describe('HTTP path answering 2xx when up') })
+        .strict()
+        .optional()
+        .describe('Readiness beyond the port accepting connections'),
+    })
+    .strict() as unknown as ZodType<ProcessConfiguration>,
+});
+
+registerConfigurationKind<CompoundConfiguration>({
+  kind: 'compound',
+  role: 'run',
+  describe: 'Several configurations started together; `play` names the host mount',
+  schema: z
+    .object({
+      id: z.string().min(1).describe('Configuration id'),
+      kind: z.literal('compound'),
+      run: z.array(z.string().min(1)).min(1).describe('Configuration ids, `play` included'),
+      instances: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe('Instances of the host mount to run against the rest'),
+    })
+    .strict() as unknown as ZodType<CompoundConfiguration>,
+});
+
+registerConfigurationKind<BundleConfiguration>({
+  kind: 'bundle',
+  role: 'build',
+  describe: "The project's web bundle: its build script, then dist/ packaged as the artifact",
+  schema: z
+    .object({
+      id: z.string().min(1).describe('Configuration id'),
+      kind: z.literal('bundle'),
+      script: z.string().min(1).optional().describe('package.json script that builds (`build`)'),
+      args: z.array(z.string()).optional().describe('Arguments passed after `--`'),
+    })
+    .strict() as unknown as ZodType<BundleConfiguration>,
+});
+
+/** Validate `configurations[]` against the registry: every kind registered, every
+ *  declaration its kind's shape, ids unique, compound members declared. */
+export function configurationIssues(configurations: readonly ConfigurationEnvelope[]): string[] {
+  const issues: string[] = [];
+  const ids = new Set<string>();
+  for (const declaration of configurations) {
+    if (ids.has(declaration.id)) issues.push(`configurations: duplicate id "${declaration.id}"`);
+    ids.add(declaration.id);
+    const registration = registry.get(declaration.kind);
+    if (!registration) {
+      issues.push(
+        `configurations "${declaration.id}": unknown kind "${declaration.kind}" — registered: ${registeredConfigurationKinds()
+          .map((k) => `"${k}"`)
+          .join(', ')}`,
+      );
+      continue;
+    }
+    const parsed = registration.schema.safeParse(declaration);
+    if (!parsed.success) {
+      for (const issue of parsed.error.issues) {
+        issues.push(
+          `configurations "${declaration.id}" (${declaration.kind}): ${issue.path.join('.') || '(declaration)'}: ${issue.message}`,
+        );
+      }
+    }
+  }
+  for (const declaration of configurations) {
+    if (declaration.kind !== 'compound') continue;
+    const members = (declaration as { run?: readonly string[] }).run ?? [];
+    for (const member of members) {
+      if (member !== PLAY_CONFIGURATION_ID && !ids.has(member)) {
+        issues.push(
+          `configurations "${declaration.id}": member "${member}" is not a declared configuration (or "${PLAY_CONFIGURATION_ID}")`,
+        );
+      }
+    }
+  }
+  return issues;
+}

package/src/manifest/editor-port.ts

@@ -0,0 +1,69 @@
+/**
+ * The editor's built-in port fallback, and the paired HMR-socket derivation.
+ *
+ * ONE owner for the number, because it is spelled in a launcher (the editor's `edit` command),
+ * three servers (dev / prod / packaged), and a client default — a duplicated
+ * literal across those drifts silently.
+ *
+ * **Why not Vite's 5173.** It used to be exactly that, and 5173 is the default
+ * of every Vite app on the machine. On a box running any other Vite dev server
+ * the engine-repo editor and that app fight over one port, and — worse —
+ * `http://…:5173` can resolve to a FOREIGN application. Measured 2026-08-07:
+ * an unrelated process on 5173 was what the editor's tab self-heal opened.
+ *
+ * **The band.** 20000-20199 is Volter's own reserved band: fixed, hand-picked
+ * ports that must never be minted for a worktree session. Machine-local
+ * allocations start at 20200, so one can never land on this default by chance.
+ * 20173 keeps Vite's memorable `173` tail while sitting in a range nothing
+ * else claims.
+ */
+export const DEFAULT_EDITOR_PORT = 20_173;
+
+/**
+ * The Vite HMR websocket port paired with an editor port.
+ *
+ * Editor ports in 20000-29999 map into the parallel 30000-39999 band, so two
+ * worktree sessions cannot collide merely because their editor ports differ
+ * by 100. Anything outside that band keeps the simple +100 offset.
+ *
+ * `DEFAULT_EDITOR_PORT` derives 30173 through the first arm — no special case,
+ * which is the point: the old expression carried a hardcoded `5173 -> 24678`
+ * exception precisely because the default sat outside the band it designed.
+ */
+export function editorHmrPort(editorPort: number): number {
+  return editorPort >= 20_000 && editorPort < 30_100 ? editorPort + 10_000 : editorPort + 100;
+}
+
+/**
+ * Wrap a bare IPv6 literal in brackets so it is legal inside a URL authority.
+ * `127.0.0.1`, a hostname, and an already-bracketed literal pass through.
+ */
+function urlAuthorityHost(host: string): string {
+  if (host.startsWith('[')) return host;
+  return host.includes(':') ? `[${host}]` : host;
+}
+
+/**
+ * The ONE composer for an editor origin — every URL volter PRINTS, OPENS,
+ * SELF-HEALS with, records in `.volter/session.json`, or dials.
+ *
+ * **It never says `localhost`.** A bare-`localhost` URL is a different address
+ * from the one the server is listening on: on a dual-stack box `localhost`
+ * resolves `::1` first while the editor binds `127.0.0.1`, so the URL reaches
+ * whatever else happens to hold that port on IPv6. Measured 2026-08-07 — the
+ * tab bijection's self-heal opened an UNRELATED application in the owner's
+ * browser because it composed its reopen URL from `localhost` instead of the
+ * host the server had actually bound.
+ *
+ * `bindHost` is the host the server bound (`resolveBindHost`); callers that
+ * only know a port — the CLI and SDK clients dialing a local session — omit it
+ * and get the IPv4 loopback literal. A wildcard bind (`0.0.0.0` / `::`, which
+ * is what WSL gets) is not an address a browser can visit, so it degrades to
+ * that same literal: reachable from the same box, and reachable from Windows
+ * through WSL2's loopback forwarding.
+ */
+export function editorOrigin(port: number, bindHost?: string): string {
+  const host = (bindHost ?? '').trim();
+  const unusable = host === '' || host === '0.0.0.0' || host === '::' || host === '[::]';
+  return `http://${unusable ? '127.0.0.1' : urlAuthorityHost(host)}:${port}`;
+}

package/src/manifest/filename.ts

@@ -0,0 +1,45 @@
+// The project manifest's FILENAME. There is exactly ONE.
+//
+// The manifest is `volter.project.json`, and NOTHING reads a second spelling
+// (the legacy-removal doctrine, `docs/ARCHITECTURE-CORE.md` §Vocabulary). Two
+// accepted names is the defect, not the convenience: both get written, and
+// copies of the "try both" probe spread into modules that agree with the real
+// resolver only by coincidence.
+//
+// The removed name REJECTS LOUDLY, naming the exact one-line fix — never
+// silently ignored, never redirected. A directory
+// carrying only `volter.game.json` is an error with a `git mv` in the message,
+// not a project that quietly fails to open.
+//
+// This module is the ONE place either literal is spelled out, and it is
+// dependency-free (no `node:fs`) so browser bundles can import it. The
+// filesystem side lives in `./locate` (`resolveManifestPath`, `hasManifest`,
+// `assertNoRemovedManifestFilename`).
+
+/** The manifest filename. Every reader reads it; every writer writes it. */
+export const MANIFEST_FILENAME = 'volter.project.json';
+
+/** The removed filename. Read by nothing — its only job is the error message. */
+export const REMOVED_MANIFEST_FILENAME = 'volter.game.json';
+
+/** True for the manifest filename (basename comparison). */
+export function isManifestFilename(name: string): boolean {
+  return name === MANIFEST_FILENAME;
+}
+
+/**
+ * The verbatim rejection an on-disk `volter.game.json` earns — the one-line fix
+ * spelled out, per the removed-format contract. Shared by the Node
+ * (`./locate`) and browser (storage-backend) halves so a project author sees
+ * the same sentence wherever the stale name is found.
+ */
+export function removedManifestFilenameMessage(where: string): string {
+  return (
+    `${where}: found \`${REMOVED_MANIFEST_FILENAME}\` and no \`${MANIFEST_FILENAME}\`. ` +
+    `\`${REMOVED_MANIFEST_FILENAME}\` was REMOVED (the legacy-removal doctrine, ` +
+    'docs/ARCHITECTURE-CORE.md §Vocabulary) — nothing reads it any more, and it is ' +
+    'deliberately NOT read as a fallback, because a second accepted name is the defect.\n' +
+    `Fix: rename it — \`git mv ${REMOVED_MANIFEST_FILENAME} ${MANIFEST_FILENAME}\`. ` +
+    'The contents are unchanged; only the filename moved.'
+  );
+}