@vgai/engine 0.5.42 → 0.5.45

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, `vgai run`) or `build` (Export, `vgai build`). */
+  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
+ * `src/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/index.ts

@@ -1,6 +1,7 @@
 // Game manifest (vgai.project.json) — schema + loader (T3.1 slice
 // 1)..
 
+export * from './configuration-kinds';
 export {
   isManifestFilename,
   MANIFEST_FILENAME,
@@ -8,11 +9,11 @@ export {
   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';
 
-// `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/src/manifest/kind-modules.ts

@@ -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'] as const;
+
+/** Whether one file name is a kind contribution by the convention. */
+export function isConfigurationKindModule(fileName: string): boolean {
+  return KIND_SUFFIXES.some((suffix) => fileName.endsWith(suffix));
+}
+
+/** Absolute paths of the project's kind contributions, sorted. */
+export function contributedKindModulePaths(projectDir: string): string[] {
+  const found: string[] = [];
+  const walk = (directory: string): void => {
+    let names: string[];
+    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: unknown, source: string): () => void {
+  const exported = (module as { kind?: unknown } | null)?.kind;
+  if (exported === undefined) {
+    throw new Error(`${source}: a kind contribution must export \`kind\``);
+  }
+  return registerContributedConfigurationKind(exported, source);
+}

package/src/manifest/load-file.ts

@@ -7,7 +7,7 @@
 // bundle.
 
 import { readFileSync } from 'node:fs';
-import { loadGameManifest, type ResolvedGameManifest } from './load';
+import { type LoadGameManifestOptions, loadGameManifest, type ResolvedGameManifest } from './load';
 import { resolveManifestPath } from './locate';
 
 // The dual-name filesystem lookup lives in `./locate` (Zod-free on purpose);
@@ -16,12 +16,18 @@ import { resolveManifestPath } from './locate';
 export { hasManifest, manifestWritePath, resolveManifestPath } from './locate';
 
 /** Read + JSON.parse `path`, then resolve it via `loadGameManifest`. Node-only. */
-export function loadGameManifestFile(path: string): ResolvedGameManifest {
+export function loadGameManifestFile(
+  path: string,
+  options: LoadGameManifestOptions = {},
+): ResolvedGameManifest {
   const raw: unknown = 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: string): ResolvedGameManifest {
-  return loadGameManifestFile(resolveManifestPath(dir));
+export function loadGameManifestDir(
+  dir: string,
+  options: LoadGameManifestOptions = {},
+): ResolvedGameManifest {
+  return loadGameManifestFile(resolveManifestPath(dir), options);
 }

package/src/manifest/load.ts

@@ -10,9 +10,15 @@
 // `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 {
+  configurationIssues,
+  configurationKind,
+  type DeclaredConfiguration,
+} from './configuration-kinds';
 import {
   type AdapterRoot,
   type GameManifest,
@@ -90,16 +96,15 @@ export interface ResolvedGameManifest {
   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;
-        /** 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 } | undefined;
   /** Construction-time renderer properties no world can declare for itself — see the schema. */
   readonly rendering: { readonly antialias: boolean } | undefined;
@@ -148,9 +153,6 @@ export interface ResolvedGameManifest {
   readonly learn: LearnMetadata | undefined;
 }
 
-/** 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-.]+)?$/;
 
 // ---------------------------------------------------------------------------
@@ -288,7 +290,16 @@ function resolveRoot(root: AdapterRoot): ResolvedAdapterRoot {
  * wrapper. Throws a descriptive `Error` (naming the offending root/field) on
  * any Zod validation failure or cross-field rule violation.
  */
-export 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 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.
@@ -325,13 +336,31 @@ export function loadGameManifest(raw: unknown): ResolvedGameManifest {
 
   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,
-      }
-    : undefined;
+  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,
@@ -340,7 +369,9 @@ export function loadGameManifest(raw: unknown): ResolvedGameManifest {
     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/src/manifest/runtime-environment.ts

@@ -0,0 +1,48 @@
+/**
+ * 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: string): string | null {
+  try {
+    const raw: unknown = JSON.parse(readFileSync(join(projectDir, 'package.json'), 'utf-8'));
+    const engines = (raw as { engines?: { node?: unknown } } | null)?.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: string,
+  running: string = process.versions.node,
+): string | null {
+  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/src/manifest/schema.ts

@@ -398,6 +398,14 @@ export type LearnMetadata = z.infer<typeof LearnMetadataSchema>;
 // 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
@@ -426,7 +434,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
@@ -482,7 +489,7 @@ export const GameManifestSchema = z
         }
       })
       .describe(
-        "The Game's explicit, non-empty adapter-root composition. There is no implicit root. " +
+        "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).',
@@ -518,52 +525,51 @@ 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',
+            'Managed relay signaling URL to prefer over the client default; omitted when the deploy did not pin one',
           ),
-        module: z
+        grant: z
           .string()
           .optional()
           .describe(
-            'Module path for the Colyseus room bootstrap; defaults to the scaffolded server bootstrap',
+            'Room-scoped managed-relay GRANT minted at `vgai deploy`; players exchange it for a fresh token at `sessionUrl`',
           ),
-        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()
+        sessionUrl: z
+          .string()
           .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',
+            '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(
+            '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'),

package/src/react/use-data.ts

@@ -57,7 +57,7 @@ export function useData<T>(handle: DataHandle<T>): T {
  * runtime state belongs in your game's own store, never written back into
  * data files. Outside a running editor there is no `/__editor` server, so
  * this rejects with a teaching error (a shipped game could never reach the
- * route anyway — builds strip `src/tools/` entirely, §4).
+ * route anyway — builds strip `src/contributions/` and `src/tools/` entirely, §4).
  *
  * The body is PARSED VALUES, never serialized text: the dev server's fold
  * (`packages/editor/server/data-file-serialize.ts`) owns key order and the