@volter/project 0.5.211 → 0.5.213

package/src/manifest/load.ts

@@ -1,28 +1,10 @@
-// The game manifest loader/validator.
-//
-// Pure data-in/data-out: `loadGameManifest(raw)` parses `raw` against
-// `GameManifestSchema`, runs the cross-field checks §3 promises beyond what
-// Zod alone can express, resolves every optional/derivable field, and
-// returns a `ResolvedGameManifest` with nothing left implicit. This is the
-// schema's runtime reader (T4.1 policy) — every described field in
-// `schema.ts` either drives a check here or is carried into the resolved
-// output explicitly (see the per-field comments below and
-// `packages/engine/test/schema-consumption-map.ts`'s `manifest.*` entries).
-//
-// No `fs` import here on purpose — `load-file.ts` is the thin Node-only
+// Parse and resolve project manifests without filesystem access. load-file.ts supplies the
+// Node path wrapper; this reader validates cross-field constraints and resolves root defaults.
 
-// wrapper that reads a path and calls this function, so browser bundles that
-// only need `loadGameManifest` never pull in `node:fs`.
-
-import {
-  configurationIssues,
-  configurationKind,
-  type DeclaredConfiguration,
-} from './configuration-kinds';
 import {
   type AdapterRoot,
-  type GameManifest,
-  GameManifestSchema,
+  type ProjectManifest,
+  ProjectManifestSchema,
   type LearnMetadata,
   type RootAdapter,
 } from './schema';
@@ -31,37 +13,28 @@ import {
 // Resolved shapes
 // ---------------------------------------------------------------------------
 
-/** D6's resolved adapter identities. */
+/** Resolved adapter identities. */
 export type ResolvedAdapter =
   | {
       readonly type: 'builtin';
-      readonly identity: 'three' | 'canvas' | 'dom';
-      readonly surface: 'three' | 'canvas' | 'dom';
+      readonly identity: 'stage' | 'canvas' | 'dom';
+      readonly surface: 'stage' | 'canvas' | 'dom';
     }
   | {
       readonly type: 'module';
       readonly identity: 'module';
       readonly module: string;
-      readonly surface: 'three' | 'canvas' | 'dom';
+      readonly surface: 'stage' | 'canvas' | 'dom';
     }
   | {
       readonly type: 'ingest';
-      // 'ingest-react' (Track N, N1) is assigned here purely structurally
-      // (surface === 'dom'), same as 'ingest-three'/'ingest-pixi'.
-      readonly identity: 'ingest-three' | 'ingest-pixi' | 'ingest-react';
-      readonly surface: 'three' | 'canvas' | 'dom';
+      // Named for the root's declared surface alone.
+      readonly identity: `ingest-${'stage' | 'canvas' | 'dom'}`;
+      readonly surface: 'stage' | 'canvas' | 'dom';
       /**
-       * Project-relative ES module declaring `window.volterGame` beside a
-       * pristine copy. OPTIONAL rather than required-and-possibly-undefined
-       * (the shape its siblings above use) because most ingested games have
-       * nothing to say about it, and requiring the key would only make every
-       * construction site say `undefined`.
-       */
-      readonly contractShim?: string | undefined;
-      /**
-       * Project-relative ES module that writes this game'''s own DATA file back
-       * (see the field'''s schema description). Same OPTIONAL shape and same
-       * reason as {@link contractShim}: a game whose truth is entirely source
+       * Project-relative ES module that writes this project's own DATA file back
+       * (see the field's schema description). OPTIONAL rather than
+       * required-and-possibly-undefined: a project whose truth is entirely source
        * declares nothing here.
        */
       readonly dataWriter?: string | undefined;
@@ -77,9 +50,9 @@ export interface ResolvedAdapterRoot {
   readonly adapter: ResolvedAdapter;
   readonly entry: string | undefined;
   /**
-   * The component this root's WORLD is, in the game's own source (see the
+   * The component this root's WORLD is, in the project's own source (see the
    * field's schema description). Present ⇒ Edit mounts THAT component alone as
-   * its design-time document and Play mounts the game through `entry`;
+   * its design-time document and Play mounts the project through `entry`;
    * absent ⇒ `entry` is what both modes mount.
    */
   readonly world?: { readonly entry: string; readonly export: string | undefined } | undefined;
@@ -88,24 +61,15 @@ export interface ResolvedAdapterRoot {
   readonly loop: 'gated' | 'self-driven';
 }
 
-export interface ResolvedGameManifest {
-  readonly manifestVersion: 2;
+export interface ResolvedProjectManifest {
+  readonly manifestVersion: number;
   readonly name: string;
   readonly appId: string | undefined;
   readonly version: string;
   readonly engine: { readonly version: string };
-  /** Sorted by zOrder; ties broken by original array order (§3). */
+  /** Sorted by zOrder; ties broken by original array order. */
   readonly roots: readonly ResolvedAdapterRoot[];
-  /** The declared run configurations, validated by kind (`run-kinds.ts`). */
-  readonly configurations: readonly DeclaredConfiguration[];
-  /** Ids whose kind no registry here knows — only ever non-empty when the
-   *  caller loaded with `configurationKinds: 'defer'` (a bundled host that
-   *  cannot evaluate a project's kind contributions); the editor session
-   *  is the validator for those. */
-  readonly deferredConfigurationKinds: readonly string[];
   readonly resolution: { readonly width: number; readonly height: number } | undefined;
-  /** Construction-time renderer properties no world can declare for itself — see the schema. */
-  readonly rendering: { readonly antialias: boolean } | undefined;
   readonly authoring:
     | {
         readonly hierarchy?:
@@ -122,32 +86,7 @@ export interface ResolvedGameManifest {
           | undefined;
       }
     | undefined;
-  /** D18 — read by the debug-bridge installer to gate `?volter-debug=1` in production builds. */
-  readonly debug: { readonly allowInProduction: boolean } | undefined;
-  /** D15 — read by `mount-manifest.ts`'s boot-time seeding reader (gates
-   *  whether `ctx.random` is seeded from `defaultSeed`/`?volter-seed=`), the
-   *  gameplay-rng-ban burn-down scan, and the dev-mode Math.random phase
-   *  trap.. */
-  readonly determinism:
-    | { readonly seededRandom: boolean; readonly defaultSeed?: number | undefined }
-    | undefined;
-  /** W3d (F11 perf gates) — read by `volter perf --assert-budget`
-   *  (packages/volter-cli/src/perf.ts, assertBudget): each set metric is
-   *  compared against the seeded headless perf run's measured value and any
-   *  exceedance fails the gate with a per-metric table + nonzero exit. */
-  readonly budget:
-    | {
-        readonly frameCpuMsP95?: number | undefined;
-        readonly physicsMsP95?: number | undefined;
-        readonly maxEntities?: number | undefined;
-        readonly maxDrawCalls?: number | undefined;
-        readonly maxTriangles?: number | undefined;
-      }
-    | undefined;
-  /** Learner-facing metadata on shipped example projects; read by the editor
-   *  server's registry surface (`GET /__editor/examples`,
-   *  packages/editor-core/server/editor-server.ts) to generate the
-   *  gallery/wizard/Learn-catalog registries. */
+  /** Learner-facing metadata carried from the project manifest. */
   readonly learn: LearnMetadata | undefined;
 }
 
@@ -164,37 +103,31 @@ function isModuleAdapter(
 }
 
 // ---------------------------------------------------------------------------
-// Cross-field checks (§3 — beyond what Zod alone enforces)
+// Cross-field checks beyond individual schema fields
 // ---------------------------------------------------------------------------
 //
-// Root-id uniqueness used to be a cross-field check HERE
-// (`checkUniqueRootIds`, removed) — it moved INTO `GameManifestSchema`'s
-// `roots` `superRefine` (schema.ts) instead, so the generated JSON Schema and
-// any other schema consumer see the same constraint the loader always
-// enforced. `parseManifest` below catches that one recognizable schema-level
-// issue and rethrows it as a clean, single `Error` — the exact message shape
-// `checkUniqueRootIds` used to throw directly — rather than a raw multi-issue
-// `ZodError` dump, so existing callers/tests that pattern-match the message
-// text are unaffected by the enforcement moving one layer down.
+// ProjectManifestSchema's `roots` superRefine checks composition rules, including root-id
+// uniqueness. The maintained JSON schema validates field shapes; runtime loading applies these
+// additional rules. loadProjectManifest surfaces composition issues as a single Error.
 
 function checkAdapterEntryRules(root: AdapterRoot): void {
   const { adapter } = root;
   if (typeof adapter === 'string' && !root.entry) {
     throw new Error(
-      `Game manifest: root "${root.id}" uses the '${adapter}' adapter but declares no ` +
+      `Project manifest: root "${root.id}" uses the '${adapter}' adapter but declares no ` +
         '`entry` — a built-in adapter root is authored as an entry module.',
     );
   }
   if (typeof adapter === 'object' && 'ingest' in adapter && !root.entry) {
     throw new Error(
-      `Game manifest: root "${root.id}" is an { ingest } root but declares no \`entry\` — the ` +
-        "game's own entry module is what the host imports.",
+      `Project manifest: root "${root.id}" is an { ingest } root but declares no \`entry\` — the ` +
+        "project's own entry module is what the host imports.",
     );
   }
 }
 
 // ---------------------------------------------------------------------------
-// Resolution (§5)
+// Resolution
 // ---------------------------------------------------------------------------
 
 function resolveAdapter(root: AdapterRoot): ResolvedAdapter {
@@ -213,20 +146,13 @@ function resolveAdapter(root: AdapterRoot): ResolvedAdapter {
     };
   }
 
-  // isIngestAdapter (Track N, N1: 'ingest-react' joins 'ingest-three'/
-  // 'ingest-pixi').
-  const identity =
-    adapter.surface === 'three'
-      ? 'ingest-three'
-      : adapter.surface === 'canvas'
-        ? 'ingest-pixi'
-        : 'ingest-react';
+  // isIngestAdapter: the identity names the root's declared surface.
+  const identity = `ingest-${adapter.surface}` as const;
   const ingest = adapter.ingest;
   return {
     type: 'ingest',
     identity,
     surface: adapter.surface,
-    contractShim: ingest.contractShim,
     dataWriter: ingest.dataWriter,
     assets: ingest.assets,
     domStubs: ingest.domStubs,
@@ -237,28 +163,17 @@ function resolveAdapter(root: AdapterRoot): ResolvedAdapter {
 function checkEngineVersionPin(version: string): void {
   if (!SEMVER_RE.test(version)) {
     throw new Error(
-      `Game manifest: engine.version "${version}" is not a valid exact semver string (e.g. ` +
+      `Project manifest: engine.version "${version}" is not a valid exact semver string (e.g. ` +
         '"0.1.0") — §1.5 requires an exact identity pin, not a range.',
     );
   }
 }
 
 /**
- * Resolve one already-Zod-validated root entry into its `ResolvedAdapterRoot`
- * (adapter identity, and a pass-through of every other field).
- * Every `AdapterRoot` field participates here or in a check above:
- * `id` drives uniqueness; `adapter` (incl. its surface and
- * `module`/`ingest.*` sub-fields) drives adapter identity
- * resolution; `entry` drives the entry cross-field rule and is
- * carried through; `world` is carried through for the ONE reader that mounts a
- * design-time document (the editor's design session) and is deliberately not
- * cross-checked against `entry` — the two name different modules on purpose;
- * `zOrder` drives the final sort; `pausable`/`loop` are
- * carried through as-is (their consumers are the runtime/CLI, T3.2/T3.3);
- * `description` (T3.3
- * slice 3) is carried through as-is — its consumer today is
- * `resolveIngestDescriptor` (packages/editor-game/src/ingest/resolve-three.ts), which
- * threads an ingest-three root's description into `IngestGame.description`.
+ * Resolve a validated root’s adapter identity and entry rules, carrying its
+ * remaining fields into the resolved root. `world` names the design-time module
+ * and is independent of the runtime `entry`. The manifest loader checks unique
+ * ids and sorts the resolved roots by z-order.
  */
 function resolveRoot(root: AdapterRoot): ResolvedAdapterRoot {
   checkAdapterEntryRules(root);
@@ -283,43 +198,25 @@ function resolveRoot(root: AdapterRoot): ResolvedAdapterRoot {
 // ---------------------------------------------------------------------------
 
 /**
- * Parse + validate + resolve a raw manifest value into a `ResolvedGameManifest`.
+ * Parse + validate + resolve a raw manifest value into a `ResolvedProjectManifest`.
  * Pure data-in/data-out (no `fs`) — see `load-file.ts` for the Node path-based
  * wrapper. Throws a descriptive `Error` (naming the offending root/field) on
  * any Zod validation failure or cross-field rule violation.
  */
-export interface LoadGameManifestOptions {
-  /** `require` (default): a declaration of an unregistered kind refuses.
-   *  `defer`: it is reported in `deferredConfigurationKinds` instead. */
-  readonly configurationKinds?: 'require' | 'defer';
-}
-
-export function loadGameManifest(
-  raw: unknown,
-  options: LoadGameManifestOptions = {},
-): ResolvedGameManifest {
-  // Removed-format guard FIRST, on the raw value: a root declaring a removed
-  // content field would otherwise fail Zod's `roots` discriminated union with
-  // a confusing shape error instead of the named migration message.
-  const parsed = GameManifestSchema.safeParse(raw);
+export function loadProjectManifest(raw: unknown): ResolvedProjectManifest {
+  const parsed = ProjectManifestSchema.safeParse(raw);
   if (!parsed.success) {
-    // D-V6: the `roots` `superRefine`'s composition issues — a duplicate root
-    // id, or more than one world root of the same medium — are the
-    // schema-level violations this loader surfaces as a clean, single `Error`
-    // (matching `checkUniqueRootIds`'s pre-D-V6 message shape) rather than a
-    // raw multi-issue dump, because each one already reads as a finished
-    // sentence naming the offending ids. Every other schema violation keeps
-    // propagating as the raw `ZodError` it always has (unchanged behavior,
-    // e.g. an unrecognized key or a bad `manifestVersion`).
+    // Composition issues already name the offending root ids. Surface that
+    // message as a single Error; preserve other failures as ZodError details.
     const compositionIssue = parsed.error.issues.find(
       (issue) =>
-        issue.message.startsWith('Game manifest: duplicate root id') ||
-        issue.message.startsWith('Game manifest: a project has at most one'),
+        issue.message.startsWith('Project manifest: duplicate root id') ||
+        issue.message.startsWith('Project manifest: a project has at most one'),
     );
     if (compositionIssue) throw new Error(compositionIssue.message);
     throw parsed.error;
   }
-  const manifest: GameManifest = parsed.data;
+  const manifest: ProjectManifest = parsed.data;
 
   checkEngineVersionPin(manifest.engine.version);
 
@@ -329,37 +226,11 @@ export function loadGameManifest(
   }));
 
   resolvedWithIndex.sort(
-    (a, b) => a.root.zOrder - b.root.zOrder || a.index - b.index, // ties -> array order (§3)
+    (a, b) => a.root.zOrder - b.root.zOrder || a.index - b.index, // ties -> array order
   );
 
   const roots = resolvedWithIndex.map(({ root }) => root);
 
-  const configurations = (manifest.configurations ?? []) as DeclaredConfiguration[];
-  // Kinds are OPEN (ARCHITECTURE-CORE §The project model): each declaration
-  // is checked against its registered kind's own schema HERE, where the
-  // host's registry is, not in the Zod schema. A host that cannot evaluate a
-  // project's kind contributions defers unknown kinds by name instead of
-  // refusing them.
-  const deferredConfigurationKinds: string[] = [];
-  const kindIssues = configurationIssues(configurations).filter((issue) => {
-    if (options.configurationKinds !== 'defer') return true;
-    const unknown = /^configurations "([^"]+)": unknown kind/.exec(issue);
-    if (!unknown) return true;
-    deferredConfigurationKinds.push(unknown[1] as string);
-    return false;
-  });
-  if (kindIssues.length > 0) {
-    throw new Error(`Game manifest: ${kindIssues.join('\n  ')}`);
-  }
-  for (const configuration of configurations) {
-    if (
-      !configurationKind(configuration.kind) &&
-      !deferredConfigurationKinds.includes(configuration.id)
-    ) {
-      deferredConfigurationKinds.push(configuration.id);
-    }
-  }
-
   return {
     manifestVersion: manifest.manifestVersion,
     name: manifest.name,
@@ -367,14 +238,8 @@ export function loadGameManifest(
     version: manifest.version,
     engine: { version: manifest.engine.version },
     roots,
-    configurations,
-    deferredConfigurationKinds,
     resolution: manifest.resolution,
-    rendering: manifest.rendering,
     authoring: manifest.authoring,
-    debug: manifest.debug,
-    determinism: manifest.determinism,
-    budget: manifest.budget,
     learn: manifest.learn,
   };
 }

package/src/manifest/locate.ts

@@ -1,51 +1,27 @@
-// Finding the project manifest ON DISK. There is ONE filename — see
-// `./filename.ts` for why the old one was removed rather than kept readable.
+// Finding the project manifest ON DISK. There is ONE filename (`./filename.ts`).
 //
 // Deliberately dependency-light — `node:fs` + `node:path` + `./filename` and
-// NOTHING else (no Zod, no `./load`). Several callers are explicitly
-// schema-free by design (`packages/editor-core/server/project-root-surface.ts`,
-// `packages/editor/vite-plugin-ui-oid.ts`) and must be able to locate a
-// manifest without dragging the validator in.
+// NOTHING else (no Zod, no `./load`). Its callers (the editor's server, the
+// live session and a product's CLI) locate a manifest without dragging the
+// validator in.
 
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import {
-  MANIFEST_FILENAME,
-  REMOVED_MANIFEST_FILENAME,
-  removedManifestFilenameMessage,
-} from './filename';
+import { MANIFEST_FILENAME } from './filename';
 
 /**
- * Throw the rename instruction if `dir` carries only the REMOVED manifest
- * filename. The `assertNoRemoved*` shape: a removed thing must reject loudly
- * naming the exact fix, never be silently ignored (which would present as
- * "this folder is not a project" — a diagnosis pointing nowhere).
- *
- * Returns normally when `dir` holds the current manifest, or neither file.
- */
-export function assertNoRemovedManifestFilename(dir: string): void {
-  if (existsSync(join(dir, MANIFEST_FILENAME))) return;
-  if (!existsSync(join(dir, REMOVED_MANIFEST_FILENAME))) return;
-  throw new Error(removedManifestFilenameMessage(join(dir, REMOVED_MANIFEST_FILENAME)));
-}
-
-/**
- * The manifest path inside `dir`. Always `volter.project.json` — so a "not
- * found" message names the filename a project must be using — except that a
- * directory carrying only the removed `volter.game.json` THROWS the rename
- * instruction instead of reporting a phantom path.
+ * The manifest path inside `dir`: always `volter.project.json`, so a "not
+ * found" message names the filename a project must be using.
  *
  * This is the drop-in replacement for a hand-written `join(dir, …)` everywhere
  * a manifest is READ. Writers want {@link manifestWritePath}.
  */
 export function resolveManifestPath(dir: string): string {
-  assertNoRemovedManifestFilename(dir);
   return join(dir, MANIFEST_FILENAME);
 }
 
-/** True when `dir` holds a manifest. A lone `volter.game.json` throws. */
+/** True when `dir` holds a manifest. */
 export function hasManifest(dir: string): boolean {
-  assertNoRemovedManifestFilename(dir);
   return existsSync(join(dir, MANIFEST_FILENAME));
 }