@vgai/engine 0.5.4 → 0.5.6

package/dist/manifest/load-file.js

@@ -0,0 +1,23 @@
+// T3.1 slice 1 — Node-only path wrapper around `loadGameManifest` (§5).
+//
+// Kept in its own module (rather than folded into `load.ts`) so that
+// `loadGameManifest` itself stays free of `node:fs` — anything that only
+// needs the pure parse/resolve function (e.g. a future browser/hosted-editor
+// caller) can import `./load` without pulling a Node-only module into its
+// bundle.
+import { readFileSync } from 'node:fs';
+import { loadGameManifest } from './load';
+import { resolveManifestPath } from './locate';
+// The dual-name filesystem lookup lives in `./locate` (Zod-free on purpose);
+// re-exported here so the common "load a project's manifest" import is one
+// module.
+export { hasManifest, manifestWritePath, resolveManifestPath } from './locate';
+/** Read + JSON.parse `path`, then resolve it via `loadGameManifest`. Node-only. */
+export function loadGameManifestFile(path) {
+    const raw = JSON.parse(readFileSync(path, 'utf-8'));
+    return loadGameManifest(raw);
+}
+/** {@link loadGameManifestFile} against `dir`'s `vgai.project.json`. */
+export function loadGameManifestDir(dir) {
+    return loadGameManifestFile(resolveManifestPath(dir));
+}

package/dist/manifest/load.d.ts

@@ -0,0 +1,161 @@
+import { type IngestStrategy, type LearnMetadata, type Tier } from './schema';
+/** D6's resolved adapter identities. */
+export type ResolvedAdapter = {
+    readonly type: 'builtin';
+    readonly identity: 'three' | 'canvas' | 'dom';
+    readonly surface: 'three' | 'canvas' | 'dom';
+} | {
+    readonly type: 'module';
+    readonly identity: 'module';
+    readonly module: string;
+    readonly surface: 'three' | 'canvas' | 'dom';
+} | {
+    readonly type: 'ingest';
+    readonly identity: 'ingest-three' | 'ingest-pixi' | 'ingest-react';
+    readonly surface: 'three' | 'canvas' | 'dom';
+    readonly strategy: IngestStrategy;
+    readonly entryHtml: string | undefined;
+    readonly assets: Record<string, string> | undefined;
+    readonly domStubs: string[] | undefined;
+    readonly captureTimeoutMs: number | undefined;
+    /** Iframe-reachable-multi mount fields. */
+    readonly bundleUrl: string | undefined;
+    readonly baseHref: string | undefined;
+    readonly assetBaseUrl: string | undefined;
+    readonly extraDeps: string[] | undefined;
+    readonly pixiModuleUrl: string | undefined;
+    readonly bodyHtml: string | undefined;
+};
+export interface ResolvedAdapterRoot {
+    readonly id: string;
+    readonly surface: ResolvedAdapter['surface'];
+    readonly description: string | undefined;
+    readonly adapter: ResolvedAdapter;
+    readonly entry: string | undefined;
+    readonly zOrder: number;
+    readonly pausable: boolean;
+    /** `dev: true` — this root is a DEV LAYER, not shipped game content. See
+     *  `manifest/schema.ts`'s `dev` field for the four readers. */
+    readonly dev: boolean;
+    readonly loop: 'gated' | 'self-driven';
+    /** Every optional resolved: both contexts always present (§4/§5). */
+    readonly capabilities: {
+        readonly local: Tier;
+        readonly hosted: Tier;
+    };
+}
+export interface ResolvedGameManifest {
+    readonly manifestVersion: 2;
+    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). */
+    readonly roots: readonly ResolvedAdapterRoot[];
+    readonly server: {
+        readonly room: string;
+        readonly module: string;
+    } | undefined;
+    readonly resolution: {
+        readonly width: number;
+        readonly height: number;
+    } | undefined;
+    readonly authoring: {
+        readonly hierarchy?: {
+            readonly rootLabels?: Readonly<Record<string, string>> | undefined;
+            readonly groups?: readonly {
+                readonly id: string;
+                readonly label: string;
+                readonly roots: readonly string[];
+            }[] | undefined;
+        } | undefined;
+    } | undefined;
+    /** D18 — read by the debug-bridge installer to gate `?vgai-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`/`?vgai-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 `vgai perf --assert-budget`
+     *  (packages/vgai-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/server/editor-server.ts) to generate the
+     *  gallery/wizard/Learn-catalog registries. */
+    readonly learn: LearnMetadata | undefined;
+}
+/**
+ * Ceiling (maximum legal declared `Tier`) per adapter type and delivery
+ * context. `default` roots are always first-party in both contexts (D6/§2 —
+ * a first-party root is fully vgai-native everywhere). `ingest` roots are
+ * ceilinged by their own capture `strategy`: locally the local CLI's Vite
+ * pipeline gives bundler dedupe, so every strategy reaches its own natural
+ * rung; hosted has no bundler (esbuild-wasm + externals only), and a
+ * `deduped` root is DEFINED by being source built through our pipeline — no
+ * prebuilt bundle exists to fall back to an iframe rung, and nothing
+ * implements a hosted build for it, so hosted is `unsupported` (honesty over
+ * optimism; if the hosted esbuild-wasm path ever proves capable, raising
+ * this ceiling is a non-breaking widening). `shared`/`iframe-reachable`/
+ * `opaque-embed` don't depend on a bundler either way, so they carry through
+ * unchanged. `module` adapters have no derivable ceiling ("a custom
+ * adapter's reach is not derivable", §4) — modeled here as `first-party`
+ * (the top rank), i.e. no ceiling actually constrains a module adapter's
+ * declared tier; the loader instead requires the tier to be declared
+ * explicitly for module roots (see `resolveCapabilities`), since there is no
+ * default to derive.
+ */
+export declare const CAPABILITY_CEILINGS: {
+    readonly builtin: {
+        readonly local: "first-party";
+        readonly hosted: "first-party";
+    };
+    readonly ingest: {
+        readonly shared: {
+            readonly local: "shared";
+            readonly hosted: "shared";
+        };
+        readonly deduped: {
+            readonly local: "deduped";
+            readonly hosted: "unsupported";
+        };
+        readonly 'iframe-reachable': {
+            readonly local: "iframe-reachable";
+            readonly hosted: "iframe-reachable";
+        };
+        readonly 'opaque-embed': {
+            readonly local: "opaque-embed";
+            readonly hosted: "opaque-embed";
+        };
+    };
+    readonly module: {
+        readonly local: "first-party";
+        readonly hosted: "first-party";
+    };
+};
+/** Default relative path for `server.module` when omitted (§3) — the scaffolded Colyseus bootstrap. */
+export declare const DEFAULT_SERVER_MODULE = "server/colyseus-setup.ts";
+/**
+ * Parse + validate + resolve a raw manifest value into a `ResolvedGameManifest`.
+ * 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 declare function loadGameManifest(raw: unknown): ResolvedGameManifest;
+//# sourceMappingURL=load.d.ts.map

package/dist/manifest/load.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../src/manifest/load.ts"],"names":[],"mappings":"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"}

package/dist/manifest/load.js

@@ -0,0 +1,269 @@
+// 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
+// wrapper that reads a path and calls this function, so browser bundles that
+// only need `loadGameManifest` never pull in `node:fs`.
+import { GameManifestSchema, } from './schema';
+// ---------------------------------------------------------------------------
+// §4 — the per-context ceiling table (named + exported so the tier-table test
+// can pin its rows against this).
+// ---------------------------------------------------------------------------
+/**
+ * Ceiling (maximum legal declared `Tier`) per adapter type and delivery
+ * context. `default` roots are always first-party in both contexts (D6/§2 —
+ * a first-party root is fully vgai-native everywhere). `ingest` roots are
+ * ceilinged by their own capture `strategy`: locally the local CLI's Vite
+ * pipeline gives bundler dedupe, so every strategy reaches its own natural
+ * rung; hosted has no bundler (esbuild-wasm + externals only), and a
+ * `deduped` root is DEFINED by being source built through our pipeline — no
+ * prebuilt bundle exists to fall back to an iframe rung, and nothing
+ * implements a hosted build for it, so hosted is `unsupported` (honesty over
+ * optimism; if the hosted esbuild-wasm path ever proves capable, raising
+ * this ceiling is a non-breaking widening). `shared`/`iframe-reachable`/
+ * `opaque-embed` don't depend on a bundler either way, so they carry through
+ * unchanged. `module` adapters have no derivable ceiling ("a custom
+ * adapter's reach is not derivable", §4) — modeled here as `first-party`
+ * (the top rank), i.e. no ceiling actually constrains a module adapter's
+ * declared tier; the loader instead requires the tier to be declared
+ * explicitly for module roots (see `resolveCapabilities`), since there is no
+ * default to derive.
+ */
+export const CAPABILITY_CEILINGS = {
+    builtin: { local: 'first-party', hosted: 'first-party' },
+    ingest: {
+        shared: { local: 'shared', hosted: 'shared' },
+        deduped: { local: 'deduped', hosted: 'unsupported' },
+        'iframe-reachable': { local: 'iframe-reachable', hosted: 'iframe-reachable' },
+        'opaque-embed': { local: 'opaque-embed', hosted: 'opaque-embed' },
+    },
+    module: { local: 'first-party', hosted: 'first-party' },
+};
+/** Total order over `Tier` (§4: `first-party > shared ≈ deduped > iframe-reachable > opaque-embed > unsupported`). */
+const TIER_RANK = {
+    'first-party': 5,
+    shared: 4,
+    deduped: 4,
+    'iframe-reachable': 3,
+    'opaque-embed': 2,
+    unsupported: 1,
+};
+/** Default relative path for `server.module` when omitted (§3) — the scaffolded Colyseus bootstrap. */
+export const DEFAULT_SERVER_MODULE = 'server/colyseus-setup.ts';
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-.]+)?(?:\+[0-9A-Za-z-.]+)?$/;
+// ---------------------------------------------------------------------------
+// Adapter shape guards
+// ---------------------------------------------------------------------------
+function isModuleAdapter(adapter) {
+    return typeof adapter === 'object' && 'module' in adapter;
+}
+// ---------------------------------------------------------------------------
+// Cross-field checks (§3 — beyond what Zod alone enforces)
+// ---------------------------------------------------------------------------
+//
+// 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.
+function checkAdapterEntryRules(root) {
+    const { adapter } = root;
+    if (typeof adapter === 'string' && !root.entry) {
+        throw new Error(`Game manifest: root "${root.id}" uses the '${adapter}' adapter but declares no ` +
+            '`entry` — a built-in adapter root is authored as an entry module.');
+    }
+}
+// Historical note (Track N, N1): this file used to reject EVERY `kind:
+// 'react'` + `{ ingest }` root outright here (`checkReactAdapterRestriction`,
+// citing "no react ingest program is un-parked"). Track N un-parks exactly
+// that program — react+ingest is now a structurally legal combination,
+// resolved to the `'ingest-react'` identity by `resolveAdapter` below like
+// any other ingest root. There is nothing left to reject at THIS layer: the
+// v1 "deduped strategy only" restriction is an editor-resolver concern (D-N3),
+// not a manifest-shape concern — see the `ResolvedAdapter` type's comment
+// above.
+// ---------------------------------------------------------------------------
+// Resolution (§5)
+// ---------------------------------------------------------------------------
+function resolveAdapter(root) {
+    const { adapter } = root;
+    if (typeof adapter === 'string') {
+        return { type: 'builtin', identity: adapter, surface: adapter };
+    }
+    if (isModuleAdapter(adapter)) {
+        return {
+            type: 'module',
+            identity: 'module',
+            module: adapter.module,
+            surface: adapter.surface,
+        };
+    }
+    // isIngestAdapter (Track N, N1: 'ingest-react' joins 'ingest-three'/
+    // 'ingest-pixi' — see the `ResolvedAdapter` type's comment above for why
+    // this stays strategy-agnostic here).
+    const identity = adapter.surface === 'three'
+        ? 'ingest-three'
+        : adapter.surface === 'canvas'
+            ? 'ingest-pixi'
+            : 'ingest-react';
+    const ingest = adapter.ingest;
+    return {
+        type: 'ingest',
+        identity,
+        surface: adapter.surface,
+        strategy: ingest.strategy,
+        entryHtml: ingest.entryHtml,
+        assets: ingest.assets,
+        domStubs: ingest.domStubs,
+        captureTimeoutMs: ingest.captureTimeoutMs,
+        bundleUrl: ingest.bundleUrl,
+        baseHref: ingest.baseHref,
+        assetBaseUrl: ingest.assetBaseUrl,
+        extraDeps: ingest.extraDeps,
+        pixiModuleUrl: ingest.pixiModuleUrl,
+        bodyHtml: ingest.bodyHtml,
+    };
+}
+function ceilingFor(adapter, context) {
+    if (typeof adapter === 'string')
+        return CAPABILITY_CEILINGS.builtin[context];
+    if (isModuleAdapter(adapter))
+        return CAPABILITY_CEILINGS.module[context];
+    return CAPABILITY_CEILINGS.ingest[adapter.ingest.strategy][context];
+}
+function resolveCapabilities(root) {
+    const contexts = ['local', 'hosted'];
+    const result = {};
+    for (const context of contexts) {
+        const declared = root.capabilities?.[context];
+        if (declared !== undefined) {
+            const ceiling = ceilingFor(root.adapter, context);
+            if (TIER_RANK[declared] > TIER_RANK[ceiling]) {
+                throw new Error(`Game manifest: root "${root.id}": declared capabilities.${context} tier "${declared}" ` +
+                    `exceeds the "${ceiling}" ceiling for this adapter in the ${context} context (§4). ` +
+                    'Under-claiming (including `unsupported`) is legal; over-claiming is not.');
+            }
+            result[context] = declared;
+            continue;
+        }
+        // Omitted -> derive.
+        if (typeof root.adapter === 'string') {
+            result[context] = 'first-party';
+        }
+        else if (isModuleAdapter(root.adapter)) {
+            throw new Error(`Game manifest: root "${root.id}": { module } adapter requires an explicit ` +
+                `capabilities.${context} declaration — a custom adapter's reach is not derivable (§4).`);
+        }
+        else {
+            result[context] = CAPABILITY_CEILINGS.ingest[root.adapter.ingest.strategy][context];
+        }
+    }
+    return result;
+}
+function checkEngineVersionPin(version) {
+    if (!SEMVER_RE.test(version)) {
+        throw new Error(`Game 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, capabilities, 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 identity + capability-ceiling
+ * resolution; `entry` drives the entry cross-field rule and is
+ * carried through; `zOrder` drives the final sort; `pausable`/`loop` are
+ * carried through as-is (their consumers are the runtime/CLI, T3.2/T3.3);
+ * `dev` is carried through for the four dev-layer readers (`mountManifestRoots`'s
+ * ship gate, the host's topmost stacking pass, the play compositor's capture
+ * exclusion, and the editor's chrome-not-content seam);
+ * `capabilities.{local,hosted}` drive tier resolution; `description` (T3.3
+ * slice 3) is carried through as-is — its consumer today is
+ * `resolveIngestDescriptor` (packages/editor/src/adapter-resolver.ts), which
+ * threads an ingest-three root's description into `IngestGame.description`.
+ */
+function resolveRoot(root) {
+    checkAdapterEntryRules(root);
+    const adapter = resolveAdapter(root);
+    return {
+        id: root.id,
+        surface: adapter.surface,
+        description: root.description,
+        adapter,
+        entry: root.entry,
+        zOrder: root.zOrder,
+        pausable: root.pausable,
+        dev: root.dev,
+        loop: root.loop,
+        capabilities: resolveCapabilities(root),
+    };
+}
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+/**
+ * Parse + validate + resolve a raw manifest value into a `ResolvedGameManifest`.
+ * 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 function loadGameManifest(raw) {
+    // Removed-format guard FIRST, on the raw value: a legacy `.vscn.json` root
+    // would otherwise fail Zod's `roots` discriminated union with a confusing
+    // shape error instead of a migration message (WO-8).
+    const parsed = GameManifestSchema.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. the iframe-reachable field-exclusivity / manifestVersion checks).
+        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'));
+        if (compositionIssue)
+            throw new Error(compositionIssue.message);
+        throw parsed.error;
+    }
+    const manifest = parsed.data;
+    checkEngineVersionPin(manifest.engine.version);
+    const resolvedWithIndex = manifest.roots.map((root, index) => ({
+        root: resolveRoot(root),
+        index,
+    }));
+    resolvedWithIndex.sort((a, b) => a.root.zOrder - b.root.zOrder || a.index - b.index);
+    const roots = resolvedWithIndex.map(({ root }) => root);
+    const server = manifest.server
+        ? { room: manifest.server.room, module: manifest.server.module ?? DEFAULT_SERVER_MODULE }
+        : undefined;
+    return {
+        manifestVersion: manifest.manifestVersion,
+        name: manifest.name,
+        appId: manifest.appId,
+        version: manifest.version,
+        engine: { version: manifest.engine.version },
+        roots,
+        server,
+        resolution: manifest.resolution,
+        authoring: manifest.authoring,
+        debug: manifest.debug,
+        determinism: manifest.determinism,
+        budget: manifest.budget,
+        learn: manifest.learn,
+    };
+}

package/dist/manifest/locate.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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 declare function assertNoRemovedManifestFilename(dir: string): void;
+/**
+ * The manifest path inside `dir`. Always `vgai.project.json` — so a "not
+ * found" message names the filename a project must be using — except that a
+ * directory carrying only the removed `vgai.game.json` THROWS the rename
+ * instruction instead of reporting a phantom path.
+ *
+ * This is the drop-in replacement for a hand-written `join(dir, …)` everywhere
+ * a manifest is READ. Writers want {@link manifestWritePath}.
+ */
+export declare function resolveManifestPath(dir: string): string;
+/** True when `dir` holds a manifest. A lone `vgai.game.json` throws. */
+export declare function hasManifest(dir: string): boolean;
+/** Where a manifest gets WRITTEN in `dir`. There is one answer. */
+export declare function manifestWritePath(dir: string): string;
+//# sourceMappingURL=locate.d.ts.map

package/dist/manifest/locate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locate.d.ts","sourceRoot":"","sources":["../../src/manifest/locate.ts"],"names":[],"mappings":"AAiBA;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAIjE;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGvD;AAED,wEAAwE;AACxE,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAGhD;AAED,mEAAmE;AACnE,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAErD"}

package/dist/manifest/locate.js

@@ -0,0 +1,48 @@
+// Finding the project manifest ON DISK. There is ONE filename — see
+// `./filename.ts` for why the old one was removed rather than kept readable.
+//
+// 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/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.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { MANIFEST_FILENAME, REMOVED_MANIFEST_FILENAME, removedManifestFilenameMessage, } 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) {
+    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 `vgai.project.json` — so a "not
+ * found" message names the filename a project must be using — except that a
+ * directory carrying only the removed `vgai.game.json` THROWS the rename
+ * instruction instead of reporting a phantom path.
+ *
+ * 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) {
+    assertNoRemovedManifestFilename(dir);
+    return join(dir, MANIFEST_FILENAME);
+}
+/** True when `dir` holds a manifest. A lone `vgai.game.json` throws. */
+export function hasManifest(dir) {
+    assertNoRemovedManifestFilename(dir);
+    return existsSync(join(dir, MANIFEST_FILENAME));
+}
+/** Where a manifest gets WRITTEN in `dir`. There is one answer. */
+export function manifestWritePath(dir) {
+    return join(dir, MANIFEST_FILENAME);
+}