@vgai/engine 0.3.0 → 0.4.0-canary.20260715.0

package/dist/manifest/load.js

@@ -1,255 +0,0 @@
-// 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

@@ -1,173 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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"}