@vgai/engine 0.2.0 → 0.3.0

package/dist/manifest/load.js

@@ -0,0 +1,255 @@
+// T3.1 slice 1 — the game manifest loader/validator (docs/GAME-MANIFEST-DESIGN.md §5).
+//
+// 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: the tier-table doc
+// test in slice 2 pins docs/CAPABILITY-TIERS.md's rows against this).
+// ---------------------------------------------------------------------------
+/**
+ * Ceiling (maximum legal declared `Tier`) per adapter type and delivery
+ * context. `default` worlds are always first-party in both contexts (D6/§2 —
+ * a first-party world is fully vgai-native everywhere). `ingest` worlds 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` world 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 worlds (see `resolveCapabilities`), since there is no
+ * default to derive.
+ */
+export const CAPABILITY_CEILINGS = {
+    default: { 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;
+}
+function isIngestAdapter(adapter) {
+    return typeof adapter === 'object' && 'ingest' in adapter;
+}
+// ---------------------------------------------------------------------------
+// Cross-field checks (§3 — beyond what Zod alone enforces)
+// ---------------------------------------------------------------------------
+//
+// D-V6 (docs/WAVE5-MULTIWORLD-INGEST-DESIGN.md): world-id uniqueness used to
+// be a cross-field check HERE (`checkUniqueWorldIds`, removed) — it moved
+// INTO `GameManifestSchema`'s `worlds` `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 `checkUniqueWorldIds` 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 checkAdapterSceneEntryRules(world) {
+    const { adapter } = world;
+    if (adapter === 'default' && !world.scene && !world.entry) {
+        throw new Error(`Game manifest: world "${world.id}" uses the 'default' adapter but declares neither ` +
+            '`scene` nor `entry` — a default-adapter world requires one of the two (§3).');
+    }
+    if (isIngestAdapter(adapter) && world.scene !== undefined) {
+        throw new Error(`Game manifest: world "${world.id}" uses an { ingest } adapter but declares \`scene\` — ` +
+            'ingest adapters forbid `scene` (adapt-never-migrate: ingested games keep their own ' +
+            "formats; overlay persistence is T3.2's) (§3).");
+    }
+}
+// Historical note (Track N, N1): this file used to reject EVERY `kind:
+// 'react'` + `{ ingest }` world outright here (`checkReactAdapterRestriction`,
+// citing "no react ingest program is un-parked"). Track N un-parks exactly
+// that program (docs/REACT-INGEST-LANDING-DESIGN.md) — react+ingest is now a
+// structurally legal combination, resolved to the `'ingest-react'` identity
+// by `resolveAdapter` below like any other ingest world. There is nothing
+// left to reject at THIS layer: `checkAdapterSceneEntryRules` above already
+// forbids `scene` on any `{ ingest }`-adapter world (kind-agnostic), and 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(world) {
+    const { adapter, kind } = world;
+    if (adapter === 'default') {
+        const identity = kind === 'threejs' ? 'default-three' : kind === 'pixijs' ? 'default-pixi' : 'default-react';
+        return { type: 'default', identity };
+    }
+    if (isModuleAdapter(adapter)) {
+        return { type: 'module', identity: 'module', module: adapter.module };
+    }
+    // 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 = kind === 'threejs' ? 'ingest-three' : kind === 'pixijs' ? 'ingest-pixi' : 'ingest-react';
+    const ingest = adapter.ingest;
+    return {
+        type: 'ingest',
+        identity,
+        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 (adapter === 'default')
+        return CAPABILITY_CEILINGS.default[context];
+    if (isModuleAdapter(adapter))
+        return CAPABILITY_CEILINGS.module[context];
+    return CAPABILITY_CEILINGS.ingest[adapter.ingest.strategy][context];
+}
+function resolveCapabilities(world) {
+    const contexts = ['local', 'hosted'];
+    const result = {};
+    for (const context of contexts) {
+        const declared = world.capabilities?.[context];
+        if (declared !== undefined) {
+            const ceiling = ceilingFor(world.adapter, context);
+            if (TIER_RANK[declared] > TIER_RANK[ceiling]) {
+                throw new Error(`Game manifest: world "${world.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 (world.adapter === 'default') {
+            result[context] = 'first-party';
+        }
+        else if (isModuleAdapter(world.adapter)) {
+            throw new Error(`Game manifest: world "${world.id}": { module } adapter requires an explicit ` +
+                `capabilities.${context} declaration — a custom adapter's reach is not derivable (§4).`);
+        }
+        else {
+            result[context] = CAPABILITY_CEILINGS.ingest[world.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 world entry into its `ResolvedWorldEntry`
+ * (adapter identity, capabilities, and a pass-through of every other field).
+ * Every `WorldEntry` field participates here or in a check above:
+ * `id`/`kind` drive adapter resolution + uniqueness; `adapter` (incl. its
+ * `module`/`ingest.*` sub-fields) drives identity + capability-ceiling
+ * resolution; `scene`/`entry` drive the scene/entry cross-field rule and are
+ * carried through; `zOrder` drives the final sort; `pausable`/`loop` are
+ * carried through as-is (their consumers are the runtime/CLI, T3.2/T3.3);
+ * `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 world's description into `IngestGame.description`.
+ */
+function resolveWorld(world) {
+    checkAdapterSceneEntryRules(world);
+    return {
+        id: world.id,
+        kind: world.kind,
+        description: world.description,
+        adapter: resolveAdapter(world),
+        scene: world.scene,
+        entry: world.entry,
+        zOrder: world.zOrder,
+        pausable: world.pausable,
+        loop: world.loop,
+        capabilities: resolveCapabilities(world),
+    };
+}
+// ---------------------------------------------------------------------------
+// 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 world/field) on
+ * any Zod validation failure or cross-field rule violation.
+ */
+export function loadGameManifest(raw) {
+    const parsed = GameManifestSchema.safeParse(raw);
+    if (!parsed.success) {
+        // D-V6: the `worlds` `superRefine`'s duplicate-id issue is the one
+        // schema-level violation this loader still surfaces as a clean, single
+        // `Error` (matching `checkUniqueWorldIds`'s pre-D-V6 message shape) —
+        // 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 dupIssue = parsed.error.issues.find((issue) => issue.message.startsWith('Game manifest: duplicate world id'));
+        if (dupIssue)
+            throw new Error(dupIssue.message);
+        throw parsed.error;
+    }
+    const manifest = parsed.data;
+    checkEngineVersionPin(manifest.engine.version);
+    const resolvedWithIndex = manifest.worlds.map((world, index) => ({
+        world: resolveWorld(world),
+        index,
+    }));
+    resolvedWithIndex.sort((a, b) => a.world.zOrder - b.world.zOrder || a.index - b.index);
+    const worlds = resolvedWithIndex.map(({ world }) => world);
+    const server = manifest.server
+        ? { room: manifest.server.room, module: manifest.server.module ?? DEFAULT_SERVER_MODULE }
+        : undefined;
+    return {
+        manifestVersion: manifest.manifestVersion,
+        name: manifest.name,
+        version: manifest.version,
+        engine: { version: manifest.engine.version },
+        worlds,
+        server,
+        resolution: manifest.resolution,
+    };
+}

package/dist/manifest/schema.d.ts

@@ -0,0 +1,173 @@
+import { z } from 'zod';
+export declare const IngestStrategySchema: z.ZodEnum<{
+    shared: "shared";
+    deduped: "deduped";
+    "iframe-reachable": "iframe-reachable";
+    "opaque-embed": "opaque-embed";
+}>;
+export type IngestStrategy = z.infer<typeof IngestStrategySchema>;
+export declare const TierSchema: z.ZodEnum<{
+    shared: "shared";
+    deduped: "deduped";
+    "iframe-reachable": "iframe-reachable";
+    "opaque-embed": "opaque-embed";
+    "first-party": "first-party";
+    unsupported: "unsupported";
+}>;
+export type Tier = z.infer<typeof TierSchema>;
+export declare const WorldAdapterSchema: z.ZodUnion<readonly [z.ZodLiteral<"default">, z.ZodObject<{
+    module: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    ingest: z.ZodObject<{
+        strategy: z.ZodEnum<{
+            shared: "shared";
+            deduped: "deduped";
+            "iframe-reachable": "iframe-reachable";
+            "opaque-embed": "opaque-embed";
+        }>;
+        entryHtml: z.ZodOptional<z.ZodString>;
+        assets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        domStubs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        captureTimeoutMs: z.ZodOptional<z.ZodNumber>;
+        bundleUrl: z.ZodOptional<z.ZodString>;
+        baseHref: z.ZodOptional<z.ZodString>;
+        assetBaseUrl: z.ZodOptional<z.ZodString>;
+        extraDeps: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        pixiModuleUrl: z.ZodOptional<z.ZodString>;
+        bodyHtml: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>]>;
+export type WorldAdapter = z.infer<typeof WorldAdapterSchema>;
+export declare const WorldEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodEnum<{
+        threejs: "threejs";
+        pixijs: "pixijs";
+        react: "react";
+    }>;
+    description: z.ZodOptional<z.ZodString>;
+    adapter: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<"default">, z.ZodObject<{
+        module: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        ingest: z.ZodObject<{
+            strategy: z.ZodEnum<{
+                shared: "shared";
+                deduped: "deduped";
+                "iframe-reachable": "iframe-reachable";
+                "opaque-embed": "opaque-embed";
+            }>;
+            entryHtml: z.ZodOptional<z.ZodString>;
+            assets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            domStubs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            captureTimeoutMs: z.ZodOptional<z.ZodNumber>;
+            bundleUrl: z.ZodOptional<z.ZodString>;
+            baseHref: z.ZodOptional<z.ZodString>;
+            assetBaseUrl: z.ZodOptional<z.ZodString>;
+            extraDeps: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            pixiModuleUrl: z.ZodOptional<z.ZodString>;
+            bodyHtml: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>]>>;
+    scene: z.ZodOptional<z.ZodString>;
+    entry: z.ZodOptional<z.ZodString>;
+    zOrder: z.ZodDefault<z.ZodNumber>;
+    pausable: z.ZodDefault<z.ZodBoolean>;
+    loop: z.ZodDefault<z.ZodEnum<{
+        gated: "gated";
+        "self-driven": "self-driven";
+    }>>;
+    capabilities: z.ZodOptional<z.ZodObject<{
+        local: z.ZodOptional<z.ZodEnum<{
+            shared: "shared";
+            deduped: "deduped";
+            "iframe-reachable": "iframe-reachable";
+            "opaque-embed": "opaque-embed";
+            "first-party": "first-party";
+            unsupported: "unsupported";
+        }>>;
+        hosted: z.ZodOptional<z.ZodEnum<{
+            shared: "shared";
+            deduped: "deduped";
+            "iframe-reachable": "iframe-reachable";
+            "opaque-embed": "opaque-embed";
+            "first-party": "first-party";
+            unsupported: "unsupported";
+        }>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type WorldEntry = z.infer<typeof WorldEntrySchema>;
+export declare const GameManifestSchema: z.ZodObject<{
+    manifestVersion: z.ZodLiteral<1>;
+    name: z.ZodString;
+    version: z.ZodString;
+    engine: z.ZodObject<{
+        version: z.ZodString;
+    }, z.core.$strip>;
+    worlds: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodEnum<{
+            threejs: "threejs";
+            pixijs: "pixijs";
+            react: "react";
+        }>;
+        description: z.ZodOptional<z.ZodString>;
+        adapter: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<"default">, z.ZodObject<{
+            module: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            ingest: z.ZodObject<{
+                strategy: z.ZodEnum<{
+                    shared: "shared";
+                    deduped: "deduped";
+                    "iframe-reachable": "iframe-reachable";
+                    "opaque-embed": "opaque-embed";
+                }>;
+                entryHtml: z.ZodOptional<z.ZodString>;
+                assets: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+                domStubs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                captureTimeoutMs: z.ZodOptional<z.ZodNumber>;
+                bundleUrl: z.ZodOptional<z.ZodString>;
+                baseHref: z.ZodOptional<z.ZodString>;
+                assetBaseUrl: z.ZodOptional<z.ZodString>;
+                extraDeps: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                pixiModuleUrl: z.ZodOptional<z.ZodString>;
+                bodyHtml: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>;
+        }, z.core.$strip>]>>;
+        scene: z.ZodOptional<z.ZodString>;
+        entry: z.ZodOptional<z.ZodString>;
+        zOrder: z.ZodDefault<z.ZodNumber>;
+        pausable: z.ZodDefault<z.ZodBoolean>;
+        loop: z.ZodDefault<z.ZodEnum<{
+            gated: "gated";
+            "self-driven": "self-driven";
+        }>>;
+        capabilities: z.ZodOptional<z.ZodObject<{
+            local: z.ZodOptional<z.ZodEnum<{
+                shared: "shared";
+                deduped: "deduped";
+                "iframe-reachable": "iframe-reachable";
+                "opaque-embed": "opaque-embed";
+                "first-party": "first-party";
+                unsupported: "unsupported";
+            }>>;
+            hosted: z.ZodOptional<z.ZodEnum<{
+                shared: "shared";
+                deduped: "deduped";
+                "iframe-reachable": "iframe-reachable";
+                "opaque-embed": "opaque-embed";
+                "first-party": "first-party";
+                unsupported: "unsupported";
+            }>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    server: z.ZodOptional<z.ZodObject<{
+        room: z.ZodString;
+        module: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    resolution: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type GameManifest = z.infer<typeof GameManifestSchema>;
+//# sourceMappingURL=schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/manifest/schema.ts"],"names":[],"mappings":"AAyBA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,eAAO,MAAM,oBAAoB;;;;;EAK/B,CAAC;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAMlE,eAAO,MAAM,UAAU;;;;;;;EAOrB,CAAC;AACH,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAS9C,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;mBA8K5B,CAAC;AACJ,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAM9D,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA6D3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAM1D,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA+D2D,CAAC;AAE3F,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}