@vgai/engine 0.5.42 → 0.5.45

package/dist/manifest/configuration-kinds.js

@@ -0,0 +1,148 @@
+/**
+ * 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 { z } from 'zod';
+const CONFIGURATION_ROLES = ['run', 'build'];
+/** Register a contribution's kind after checking its shape by name. */
+export function registerContributedConfigurationKind(value, source) {
+    const record = (value ?? {});
+    const problems = [];
+    if (typeof record.kind !== 'string' || record.kind.length === 0)
+        problems.push('`kind` must be a non-empty string');
+    if (!CONFIGURATION_ROLES.includes(record.role))
+        problems.push("`role` must be 'run' or 'build'");
+    if (typeof record.describe !== 'string')
+        problems.push('`describe` must be a string');
+    const schema = record.schema;
+    if (!schema || typeof schema.safeParse !== 'function')
+        problems.push('`schema` must be a Zod schema');
+    const build = record.build;
+    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);
+}
+const registry = new Map();
+/** Register a kind. A second registration replaces the first (a module
+ *  re-evaluated on save); never throws. */
+export function registerConfigurationKind(registration) {
+    const entry = registration;
+    registry.set(registration.kind, entry);
+    return () => {
+        if (registry.get(registration.kind) === entry)
+            registry.delete(registration.kind);
+    };
+}
+export function registeredConfigurationKinds() {
+    return [...registry.keys()];
+}
+export function configurationKind(kind) {
+    return registry.get(kind);
+}
+/** The id of the implicit configuration: mount every root in the host. */
+export const PLAY_CONFIGURATION_ID = 'play';
+registerConfigurationKind({
+    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(),
+});
+registerConfigurationKind({
+    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(),
+});
+registerConfigurationKind({
+    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(),
+});
+/** Validate `configurations[]` against the registry: every kind registered, every
+ *  declaration its kind's shape, ids unique, compound members declared. */
+export function configurationIssues(configurations) {
+    const issues = [];
+    const ids = new Set();
+    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.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/dist/manifest/index.d.ts

@@ -1,6 +1,7 @@
+export * from './configuration-kinds';
 export { isManifestFilename, MANIFEST_FILENAME, REMOVED_MANIFEST_FILENAME, removedManifestFilenameMessage, } from './filename';
 export type { ResolvedAdapter, ResolvedAdapterRoot, ResolvedGameManifest } from './load';
-export { DEFAULT_SERVER_MODULE, loadGameManifest } from './load';
+export { loadGameManifest } from './load';
 export type { AdapterRoot, GameManifest, RootAdapter } from './schema';
 export { AdapterRootSchema, GameManifestSchema, RootAdapterSchema } from './schema';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/manifest/index.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,yBAAyB,EACzB,8BAA8B,GAC/B,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AACzF,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AACjE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvE,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/manifest/index.ts"],"names":[],"mappings":"AAGA,cAAc,uBAAuB,CAAC;AACtC,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,yBAAyB,EACzB,8BAA8B,GAC/B,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,eAAe,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AACzF,OAAO,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAC1C,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACvE,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC"}

package/dist/manifest/index.js

@@ -1,9 +1,10 @@
 // Game manifest (vgai.project.json) — schema + loader (T3.1 slice
 // 1)..
+export * from './configuration-kinds';
 export { isManifestFilename, MANIFEST_FILENAME, REMOVED_MANIFEST_FILENAME, removedManifestFilenameMessage, } from './filename';
-export { DEFAULT_SERVER_MODULE, loadGameManifest } from './load';
+export { loadGameManifest } from './load';
 export { AdapterRootSchema, GameManifestSchema, RootAdapterSchema } from './schema';
-// `loadGameManifestFile` (Node-only, reads `path` via `node:fs`) is
+// File loading and kind-module discovery read `node:fs` and are
 // deliberately NOT re-exported here — this barrel must stay import-safe for
 // browser bundles. Import it directly from `@engine/manifest/load-file` in
-// Node-only contexts (CLI, tests).
+// Node-only contexts; kind discovery lives in `@engine/manifest/kind-modules`.

package/dist/manifest/kind-modules.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Where a project's CONFIGURATION-KIND CONTRIBUTIONS live and how a host
+ * takes them in (ARCHITECTURE-CORE §The project model). A module named
+ * `src/contributions/<name>.kind.ts` (or `.tsx`) exports `kind`, a plain
+ * `ConfigurationKindContribution`; the HOST that loads the manifest — the
+ * editor server through Vite's SSR loader, a project's own validate script
+ * through tsx — imports each and registers it in its own registry through
+ * {@link registerContributedConfigurationKind}. Node-only: it walks the
+ * project folder.
+ */
+/** Whether one file name is a kind contribution by the convention. */
+export declare function isConfigurationKindModule(fileName: string): boolean;
+/** Absolute paths of the project's kind contributions, sorted. */
+export declare function contributedKindModulePaths(projectDir: string): string[];
+/** Register the `kind` export of an already-imported module; the source
+ *  path names the module in a refusal. */
+export declare function registerKindModule(module: unknown, source: string): () => void;
+//# sourceMappingURL=kind-modules.d.ts.map

package/dist/manifest/kind-modules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kind-modules.d.ts","sourceRoot":"","sources":["../../src/manifest/kind-modules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAQH,sEAAsE;AACtE,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEnE;AAED,kEAAkE;AAClE,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAwBvE;AAED;0CAC0C;AAC1C,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,IAAI,CAM9E"}

package/dist/manifest/kind-modules.js

@@ -0,0 +1,58 @@
+/**
+ * Where a project's CONFIGURATION-KIND CONTRIBUTIONS live and how a host
+ * takes them in (ARCHITECTURE-CORE §The project model). A module named
+ * `src/contributions/<name>.kind.ts` (or `.tsx`) exports `kind`, a plain
+ * `ConfigurationKindContribution`; the HOST that loads the manifest — the
+ * editor server through Vite's SSR loader, a project's own validate script
+ * through tsx — imports each and registers it in its own registry through
+ * {@link registerContributedConfigurationKind}. Node-only: it walks the
+ * project folder.
+ */
+import { readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { registerContributedConfigurationKind } from './configuration-kinds';
+const KIND_SUFFIXES = ['.kind.ts', '.kind.tsx'];
+/** Whether one file name is a kind contribution by the convention. */
+export function isConfigurationKindModule(fileName) {
+    return KIND_SUFFIXES.some((suffix) => fileName.endsWith(suffix));
+}
+/** Absolute paths of the project's kind contributions, sorted. */
+export function contributedKindModulePaths(projectDir) {
+    const found = [];
+    const walk = (directory) => {
+        let names;
+        try {
+            names = readdirSync(directory);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            if (name.startsWith('.') || name === 'node_modules')
+                continue;
+            const absolute = join(directory, name);
+            let isDirectory = false;
+            try {
+                isDirectory = statSync(absolute).isDirectory();
+            }
+            catch {
+                continue;
+            }
+            if (isDirectory)
+                walk(absolute);
+            else if (isConfigurationKindModule(name))
+                found.push(absolute);
+        }
+    };
+    walk(join(projectDir, 'src', 'contributions'));
+    return found.sort();
+}
+/** Register the `kind` export of an already-imported module; the source
+ *  path names the module in a refusal. */
+export function registerKindModule(module, source) {
+    const exported = module?.kind;
+    if (exported === undefined) {
+        throw new Error(`${source}: a kind contribution must export \`kind\``);
+    }
+    return registerContributedConfigurationKind(exported, source);
+}

package/dist/manifest/load-file.d.ts

@@ -1,7 +1,7 @@
-import { type ResolvedGameManifest } from './load';
+import { type LoadGameManifestOptions, type ResolvedGameManifest } from './load';
 export { hasManifest, manifestWritePath, resolveManifestPath } from './locate';
 /** Read + JSON.parse `path`, then resolve it via `loadGameManifest`. Node-only. */
-export declare function loadGameManifestFile(path: string): ResolvedGameManifest;
+export declare function loadGameManifestFile(path: string, options?: LoadGameManifestOptions): ResolvedGameManifest;
 /** {@link loadGameManifestFile} against `dir`'s `vgai.project.json`. */
-export declare function loadGameManifestDir(dir: string): ResolvedGameManifest;
+export declare function loadGameManifestDir(dir: string, options?: LoadGameManifestOptions): ResolvedGameManifest;
 //# sourceMappingURL=load-file.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"load-file.d.ts","sourceRoot":"","sources":["../../src/manifest/load-file.ts"],"names":[],"mappings":"AASA,OAAO,EAAoB,KAAK,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAMrE,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAE/E,mFAAmF;AACnF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,oBAAoB,CAGvE;AAED,wEAAwE;AACxE,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,CAErE"}
+{"version":3,"file":"load-file.d.ts","sourceRoot":"","sources":["../../src/manifest/load-file.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,KAAK,uBAAuB,EAAoB,KAAK,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAMnG,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAE/E,mFAAmF;AACnF,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,uBAA4B,GACpC,oBAAoB,CAGtB;AAED,wEAAwE;AACxE,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,uBAA4B,GACpC,oBAAoB,CAEtB"}

package/dist/manifest/load-file.js

@@ -13,11 +13,11 @@ import { resolveManifestPath } from './locate';
 // module.
 export { hasManifest, manifestWritePath, resolveManifestPath } from './locate';
 /** Read + JSON.parse `path`, then resolve it via `loadGameManifest`. Node-only. */
-export function loadGameManifestFile(path) {
+export function loadGameManifestFile(path, options = {}) {
     const raw = JSON.parse(readFileSync(path, 'utf-8'));
-    return loadGameManifest(raw);
+    return loadGameManifest(raw, options);
 }
 /** {@link loadGameManifestFile} against `dir`'s `vgai.project.json`. */
-export function loadGameManifestDir(dir) {
-    return loadGameManifestFile(resolveManifestPath(dir));
+export function loadGameManifestDir(dir, options = {}) {
+    return loadGameManifestFile(resolveManifestPath(dir), options);
 }

package/dist/manifest/load.d.ts

@@ -1,4 +1,5 @@
-import { type LearnMetadata } from './schema';
+import { type DeclaredConfiguration } from './configuration-kinds';
+import { type GameManifest, type LearnMetadata } from './schema';
 /** D6's resolved adapter identities. */
 export type ResolvedAdapter = {
     readonly type: 'builtin';
@@ -62,14 +63,15 @@ export interface ResolvedGameManifest {
     };
     /** Sorted by zOrder; ties broken by original array order (§3). */
     readonly roots: readonly ResolvedAdapterRoot[];
-    readonly server: {
-        readonly room: string;
-        readonly module: string;
-        /** The declared endpoint, or `undefined` = the scaffold default (see
-         *  the schema's own description; the editor resolves it against the
-         *  page host, which the loader has no business knowing). */
-        readonly endpoint: string | undefined;
-    } | undefined;
+    /** 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[];
+    /** Deploy-baked relay credentials, when the served manifest carries them. */
+    readonly relay: GameManifest['relay'];
     readonly resolution: {
         readonly width: number;
         readonly height: number;
@@ -117,13 +119,16 @@ export interface ResolvedGameManifest {
      *  gallery/wizard/Learn-catalog registries. */
     readonly learn: LearnMetadata | undefined;
 }
-/** 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;
+export interface LoadGameManifestOptions {
+    /** `require` (default): a declaration of an unregistered kind refuses.
+     *  `defer`: it is reported in `deferredConfigurationKinds` instead. */
+    readonly configurationKinds?: 'require' | 'defer';
+}
+export declare function loadGameManifest(raw: unknown, options?: LoadGameManifestOptions): ResolvedGameManifest;
 //# sourceMappingURL=load.d.ts.map

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

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

package/dist/manifest/load.js

@@ -12,9 +12,8 @@
 // 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 { configurationIssues, configurationKind, } from './configuration-kinds';
 import { GameManifestSchema, } from './schema';
-/** 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
@@ -119,16 +118,7 @@ function resolveRoot(root) {
         loop: root.loop,
     };
 }
-// ---------------------------------------------------------------------------
-// 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) {
+export function loadGameManifest(raw, options = {}) {
     // 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.
@@ -156,13 +146,31 @@ export function loadGameManifest(raw) {
     }));
     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,
-            endpoint: manifest.server.endpoint,
+    const configurations = (manifest.configurations ?? []);
+    // 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 = [];
+    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]);
+        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);
         }
-        : undefined;
+    }
     return {
         manifestVersion: manifest.manifestVersion,
         name: manifest.name,
@@ -170,7 +178,9 @@ export function loadGameManifest(raw) {
         version: manifest.version,
         engine: { version: manifest.engine.version },
         roots,
-        server,
+        configurations,
+        deferredConfigurationKinds,
+        relay: manifest.relay,
         resolution: manifest.resolution,
         rendering: manifest.rendering,
         authoring: manifest.authoring,

package/dist/manifest/runtime-environment.d.ts

@@ -0,0 +1,11 @@
+/** `engines.node` from the project's `package.json`, or `null` when the
+ *  project declares none (or has no package.json). */
+export declare function declaredNodeRange(projectDir: string): string | null;
+/**
+ * Why a process of this project cannot start on the running Node, spelled
+ * for the person who will fix it — or `null` when it can. A range that is
+ * not valid semver is itself the issue: a declaration nobody can satisfy is
+ * named, never skipped.
+ */
+export declare function nodeRuntimeIssue(projectDir: string, running?: string): string | null;
+//# sourceMappingURL=runtime-environment.d.ts.map

package/dist/manifest/runtime-environment.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-environment.d.ts","sourceRoot":"","sources":["../../src/manifest/runtime-environment.ts"],"names":[],"mappings":"AAeA;sDACsD;AACtD,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQnE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,MAA8B,GACtC,MAAM,GAAG,IAAI,CAWf"}

package/dist/manifest/runtime-environment.js

@@ -0,0 +1,44 @@
+/**
+ * THE RUNTIME HALF OF A PROJECT'S ENVIRONMENT (ARCHITECTURE-CORE §The
+ * project model, "environment"): the Node version a project's processes need
+ * is declared ONCE, where the ecosystem already declares it —
+ * `package.json` `engines.node` — and read here by whatever starts a
+ * `process` configuration (the editor server's configurations route, the
+ * CLI's autoboot). The manifest carries no `environment` key: a second
+ * declaration of the same fact is the drift a single home prevents.
+ *
+ * Node-only (reads the project folder), like `locate.ts`.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import semver from 'semver';
+/** `engines.node` from the project's `package.json`, or `null` when the
+ *  project declares none (or has no package.json). */
+export function declaredNodeRange(projectDir) {
+    try {
+        const raw = JSON.parse(readFileSync(join(projectDir, 'package.json'), 'utf-8'));
+        const engines = raw?.engines;
+        return typeof engines?.node === 'string' && engines.node.trim() ? engines.node.trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Why a process of this project cannot start on the running Node, spelled
+ * for the person who will fix it — or `null` when it can. A range that is
+ * not valid semver is itself the issue: a declaration nobody can satisfy is
+ * named, never skipped.
+ */
+export function nodeRuntimeIssue(projectDir, running = process.versions.node) {
+    const range = declaredNodeRange(projectDir);
+    if (range === null)
+        return null;
+    if (semver.validRange(range) === null) {
+        return `package.json declares engines.node "${range}", which is not a semver range`;
+    }
+    if (semver.satisfies(running, range, { includePrerelease: true }))
+        return null;
+    return (`package.json declares engines.node "${range}" and this host runs Node ${running} — ` +
+        `run the editor and \`vgai\` on a Node that satisfies it, or change engines.node`);
+}

package/dist/manifest/schema.d.ts

@@ -168,15 +168,16 @@ export declare const GameManifestSchema: z.ZodObject<{
             }, z.core.$strict>>>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
-    server: z.ZodOptional<z.ZodObject<{
-        room: z.ZodString;
-        endpoint: z.ZodOptional<z.ZodString>;
-        module: z.ZodOptional<z.ZodString>;
-        relay: z.ZodOptional<z.ZodObject<{
-            signalingUrl: z.ZodOptional<z.ZodString>;
-            accessToken: z.ZodString;
-            expiresAt: z.ZodNumber;
-        }, z.core.$strict>>;
+    configurations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodString;
+    }, z.core.$loose>>>;
+    relay: z.ZodOptional<z.ZodObject<{
+        signalingUrl: z.ZodOptional<z.ZodString>;
+        grant: z.ZodOptional<z.ZodString>;
+        sessionUrl: z.ZodOptional<z.ZodString>;
+        accessToken: z.ZodOptional<z.ZodString>;
+        expiresAt: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;
     resolution: z.ZodOptional<z.ZodObject<{
         width: z.ZodNumber;

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

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/manifest/schema.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAG,CAAU,CAAC;AAsFhD,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;qBA0H3B,CAAC;AACJ,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAM5D,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAqFnB,CAAC;AACZ,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAkB5D,eAAO,MAAM,eAAe;;;;;EAMzB,CAAC;AACJ,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,eAAO,MAAM,qBAAqB;;;;EAEa,CAAC;AAChD,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;kBAqC7B,CAAC;AACJ,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAMhE,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBA8TyD,CAAC;AAEzF,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/manifest/schema.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAG,CAAU,CAAC;AAsFhD,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;qBA0H3B,CAAC;AACJ,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAM5D,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAqFnB,CAAC;AACZ,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAkB5D,eAAO,MAAM,eAAe;;;;;EAMzB,CAAC;AACJ,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAExD,eAAO,MAAM,qBAAqB;;;;EAEa,CAAC;AAChD,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;kBAqC7B,CAAC;AACJ,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAchE,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBA4TyD,CAAC;AAEzF,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/manifest/schema.js

@@ -328,6 +328,13 @@ export const LearnMetadataSchema = z
 // ---------------------------------------------------------------------------
 // Game manifest (vgai.project.json)
 // ---------------------------------------------------------------------------
+/** The envelope of one run configuration; the kind's schema takes the rest. */
+const ConfigurationEnvelopeSchema = z
+    .object({
+    id: z.string().min(1).describe('Configuration id, unique in the manifest'),
+    kind: z.string().min(1).describe('A registered run kind'),
+})
+    .passthrough();
 export const GameManifestSchema = z
     .object({
     $schema: z
@@ -354,7 +361,6 @@ export const GameManifestSchema = z
         .describe('Engine version pin'),
     roots: z
         .array(AdapterRootSchema)
-        .min(1)
         .superRefine((roots, ctx) => {
         // D-V6 (debt): root ids are described as unique above but that was
         // describe-only at the SCHEMA level — only load.ts's loader-level
@@ -410,7 +416,7 @@ export const GameManifestSchema = z
             });
         }
     })
-        .describe("The Game's explicit, non-empty adapter-root composition. There is no implicit root. " +
+        .describe("The project's explicit adapter-root composition — ZERO OR MORE roots, and no implicit root: a project with no roots mounts nothing (a library of models, a folder of documents) and the editor derives its chrome from what IS declared. " +
         'Root ids are unique, and a project declares at most ONE world root per medium — ' +
         'one `three`, one `dom`, one canvas-surface root (first-party canvas, canvas ingest ' +
         'and canvas module are the same medium).'),
@@ -443,40 +449,39 @@ export const GameManifestSchema = z
         .strict()
         .optional()
         .describe('Editor-only authoring metadata; never runtime ownership'),
-    server: z
+    configurations: z
+        .array(ConfigurationEnvelopeSchema)
+        .optional()
+        .describe("The project's run configurations — its ENTRYPOINTS beyond the host mount (`play`): each an " +
+        'id and a registered kind (`process`, `compound`, and whatever a capability registers) with ' +
+        "that kind's own fields. The editor's transport, `vgai run <id>` and a harness start the same declaration."),
+    relay: z
         .object({
-        room: z.string().describe('Colyseus room name'),
-        endpoint: z
+        signalingUrl: z
             .string()
             .optional()
-            .describe('WebSocket endpoint the editor reports for this room, e.g. "wss://rooms.example.com". ' +
-            'Omit to declare the scaffold default, `ws://<the page host>:2567` — the port ' +
-            "`server/colyseus-setup.ts` listens on. Stated here because the endpoint is the game's " +
-            'own deployment fact, not something the editor may guess'),
-        module: z
+            .describe('Managed relay signaling URL to prefer over the client default; omitted when the deploy did not pin one'),
+        grant: z
             .string()
             .optional()
-            .describe('Module path for the Colyseus room bootstrap; defaults to the scaffolded server bootstrap'),
-        relay: z
-            .object({
-            signalingUrl: z
-                .string()
-                .optional()
-                .describe('Managed relay signaling URL to prefer over the client default; omitted when the deploy did not pin one'),
-            accessToken: z
-                .string()
-                .describe('Room-scoped managed-relay access token minted at `vgai deploy` and read by the standalone client (main.ts)'),
-            expiresAt: z
-                .number()
-                .describe('Token expiry as epoch milliseconds; the client falls back to a tokenless join once elapsed'),
-        })
-            .strict()
+            .describe('Room-scoped managed-relay GRANT minted at `vgai deploy`; players exchange it for a fresh token at `sessionUrl`'),
+        sessionUrl: z
+            .string()
+            .optional()
+            .describe('Public session endpoint where a deployed client exchanges the grant for a short-lived relay token'),
+        accessToken: z
+            .string()
+            .optional()
+            .describe('A baked relay token (older deploys); used directly while unexpired'),
+        expiresAt: z
+            .number()
             .optional()
-            .describe('Deploy-baked managed-relay credentials. NEVER hand-authored in source — written only into the staged manifest by `vgai deploy` and fetched at runtime by the standalone client'),
+            .describe('Token expiry as epoch milliseconds; the client falls back to a tokenless join once elapsed'),
     })
         .strict()
         .optional()
-        .describe('Multiplayer server config (Colyseus), if this game registers a room'),
+        .describe('Deploy-baked managed-relay credentials — a DEPLOYMENT fact. NEVER hand-authored in source: written only into ' +
+        'the staged manifest by `vgai deploy` and read by the deployed client at connect time.'),
     resolution: z
         .object({
         width: z.number().describe('Canvas width in pixels'),