@downdraft/engine 0.1.1 → 0.1.2-alpha.5

package/dist/core/src/plugin/manifest.js

@@ -0,0 +1,424 @@
+// ============================================================================
+// Plugin manifest — the plugin.json contract for user-authored plugins.
+//
+// A plugin is a runtime-loadable extension authored by an end user / modder
+// (distinct from the compile-time `Module` system). Each plugin ships a
+// `plugin.json` manifest that declares its identity, format, capability tier,
+// requested permissions, target thread, and dependency graph.
+//
+// Validation rules enforce the tier/format/thread/permission matrix described
+// in the plan. Validation is hand-rolled (no zod) to match the existing
+// `validateManifest` style in `../assets/manifest.ts`.
+// ============================================================================
+// ── Permission sets per tier (single source of truth; permissions.ts mirrors) ──
+const SCRIPT_ALLOWED = new Set([
+    "events",
+    "state",
+    "tick",
+    "storage",
+    "log",
+]);
+const NATIVE_ALLOWED = new Set([
+    "ecs",
+    "sab",
+    "gpu",
+    "events",
+    "state",
+    "tick",
+    "storage",
+    "network",
+    "log",
+    "physics",
+    "assets",
+]);
+// ── Helpers ──
+const KEBAB_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+// Minimal semver range check: accepts "^1.2.3", "~1.2.3", "1.2.3", ">=1.0.0",
+// "*", "x". Not a full semver implementation — good enough to reject garbage.
+const SEMVER_RANGE_RE = /^(\^|~|>=?|=)?\s*(\d+|x|X)(?:\.(\d+|x|X))?(?:\.(\d+|x|X))?(?:[-+].+)?$/;
+const SEMVER_PLAIN_RE = /^\d+\.\d+\.\d+(?:[-+].+)?$/;
+function isSemverRange(s) {
+    return s === "*" || SEMVER_RANGE_RE.test(s);
+}
+function isSemverPlain(s) {
+    return SEMVER_PLAIN_RE.test(s);
+}
+/** Validate a plugin manifest. Returns a list of errors (empty if valid). */
+export function validatePluginManifest(raw) {
+    const errors = [];
+    if (!raw || typeof raw !== "object") {
+        return { valid: false, errors: ["manifest must be a JSON object"] };
+    }
+    const m = raw;
+    // Required string fields
+    if (typeof m.id !== "string" || !m.id) {
+        errors.push("id: required string (kebab-case)");
+    }
+    else if (!KEBAB_RE.test(m.id)) {
+        errors.push(`id: "${m.id}" must be kebab-case (lowercase, hyphen-separated)`);
+    }
+    if (typeof m.name !== "string" || !m.name)
+        errors.push("name: required string");
+    if (typeof m.version !== "string" || !isSemverPlain(m.version)) {
+        errors.push(`version: required semver (e.g. "1.0.0"), got "${m.version}"`);
+    }
+    if (typeof m.engineVersion !== "string" || !isSemverRange(m.engineVersion)) {
+        errors.push(`engineVersion: required semver range (e.g. "^0.1.0"), got "${m.engineVersion}"`);
+    }
+    if (typeof m.game !== "string" || !m.game) {
+        errors.push("game: required string (target game appId)");
+    }
+    // format
+    const format = m.format;
+    const VALID_FORMATS = ["worker-js", "wasm", "quickjs", "asset"];
+    if (typeof format !== "string" || !VALID_FORMATS.includes(format)) {
+        errors.push(`format: required one of ${VALID_FORMATS.join("|")}, got "${format}"`);
+    }
+    // tier
+    const tier = m.tier;
+    const VALID_TIERS = ["data", "script", "native"];
+    if (typeof tier !== "string" || !VALID_TIERS.includes(tier)) {
+        errors.push(`tier: required one of ${VALID_TIERS.join("|")}, got "${tier}"`);
+    }
+    // thread
+    const thread = m.thread;
+    const VALID_THREADS = ["sim", "renderer", "own-worker"];
+    if (typeof thread !== "string" || !VALID_THREADS.includes(thread)) {
+        errors.push(`thread: required one of ${VALID_THREADS.join("|")}, got "${thread}"`);
+    }
+    // permissions
+    const perms = m.permissions;
+    let permList = [];
+    if (perms !== undefined) {
+        if (!Array.isArray(perms) || !perms.every((p) => typeof p === "string")) {
+            errors.push("permissions: must be an array of strings");
+        }
+        else {
+            permList = perms;
+        }
+    }
+    // entry
+    if (m.entry !== undefined && typeof m.entry !== "string") {
+        errors.push("entry: must be a string path");
+    }
+    // provides / requires / dependencies
+    ["provides", "requires", "dependencies"].forEach((field) => {
+        const v = m[field];
+        if (v !== undefined && (!Array.isArray(v) || !v.every((x) => typeof x === "string"))) {
+            errors.push(`${field}: must be an array of strings`);
+        }
+    });
+    // assets
+    if (m.assets !== undefined) {
+        if (typeof m.assets !== "object") {
+            errors.push("assets: must be an object");
+        }
+        else {
+            const a = m.assets;
+            if (typeof a.files !== "object" || a.files === null) {
+                errors.push("assets.files: required object (asset id → path)");
+            }
+            else {
+                for (const [k, v] of Object.entries(a.files)) {
+                    if (typeof v !== "string")
+                        errors.push(`assets.files["${k}"]: must be a string path`);
+                }
+            }
+            ["textures", "audio", "meshes", "data"].forEach((sub) => {
+                if (a[sub] !== undefined && (!Array.isArray(a[sub]) || !a[sub].every((x) => typeof x === "string"))) {
+                    errors.push(`assets.${sub}: must be an array of strings`);
+                }
+            });
+        }
+    }
+    // ── Mod (pack) fields: logic + extensions ──
+    if (m.logic !== undefined) {
+        validateModLogic(m.logic, errors);
+    }
+    if (m.extensions !== undefined) {
+        validateModExtensions(m.extensions, errors);
+    }
+    // ── Cross-field rules (only run if basic shape is OK) ──
+    if (errors.length === 0) {
+        const t = tier;
+        const f = format;
+        let th = thread;
+        const logic = m.logic;
+        const hasLogic = !!logic;
+        // When logic is present, the entry lives on logic.entry and permissions
+        // on logic.permissions; the top-level entry/permissions may be omitted.
+        const effectiveEntry = m.entry ?? logic?.entry;
+        const effectivePerms = logic?.permissions ?? permList;
+        // wasm always own-worker (check both top-level and logic thread)
+        if (f === "wasm" && th !== "own-worker") {
+            errors.push(`format "wasm" must use thread "own-worker" (got "${th}") — host will force it`);
+        }
+        if (hasLogic && logic.format === "wasm" && logic.thread !== "own-worker") {
+            errors.push(`logic.format "wasm" must use thread "own-worker" (got "${logic.thread}") — host will force it`);
+        }
+        // data tier ⇒ format asset, no perms, no entry, no logic
+        if (t === "data") {
+            if (f !== "asset") {
+                errors.push(`tier "data" requires format "asset" (got "${f}")`);
+            }
+            if (effectivePerms.length > 0) {
+                errors.push(`tier "data" must not request permissions (got [${effectivePerms.join(", ")}])`);
+            }
+            if (effectiveEntry !== undefined) {
+                errors.push(`tier "data" must not declare an entry (got "${effectiveEntry}")`);
+            }
+            if (hasLogic) {
+                errors.push(`tier "data" must not declare a "logic" extension`);
+            }
+        }
+        // asset format ⇒ data tier
+        if (f === "asset" && t !== "data") {
+            errors.push(`format "asset" requires tier "data" (got "${t}")`);
+        }
+        // script tier permissions subset
+        if (t === "script") {
+            const bad = effectivePerms.filter((p) => !SCRIPT_ALLOWED.has(p));
+            if (bad.length > 0) {
+                errors.push(`tier "script" allows only [${[...SCRIPT_ALLOWED].join(", ")}] — disallowed: [${bad.join(", ")}]`);
+            }
+        }
+        // native tier: any permission allowed but must be explicit (no implicit grant).
+        // (Nothing to enforce here beyond "must be a known permission", already checked.)
+        if (t === "native") {
+            const bad = effectivePerms.filter((p) => !NATIVE_ALLOWED.has(p));
+            if (bad.length > 0) {
+                errors.push(`tier "native" disallows unknown permissions: [${bad.join(", ")}]`);
+            }
+        }
+        // code-bearing formats require an entry (top-level OR logic.entry)
+        if ((f === "worker-js" || f === "wasm" || f === "quickjs") && effectiveEntry === undefined) {
+            errors.push(`format "${f}" requires an "entry" path`);
+        }
+        // asset format: entry forbidden, assets OR extensions required
+        if (f === "asset") {
+            if (effectiveEntry !== undefined)
+                errors.push(`format "asset" must not declare an entry`);
+            if (!m.assets && !m.extensions)
+                errors.push(`format "asset" requires an "assets" section or "extensions"`);
+        }
+    }
+    if (errors.length > 0)
+        return { valid: false, errors };
+    // ── Normalize ──
+    const normalized = { ...raw };
+    if (normalized.format === "wasm")
+        normalized.thread = "own-worker";
+    // Populate logic + extensions from legacy fields if not already set, so the
+    // host's extension dispatch works for both mod.json and legacy plugin.json.
+    normalizeLogicAndExtensions(normalized);
+    return { valid: true, errors: [], normalized };
+}
+// ── Mod logic validation ──
+function validateModLogic(l, errors) {
+    const VALID_LOGIC_FORMATS = ["worker-js", "wasm", "quickjs"];
+    if (typeof l.format !== "string" || !VALID_LOGIC_FORMATS.includes(l.format)) {
+        errors.push(`logic.format: required one of ${VALID_LOGIC_FORMATS.join("|")}, got "${l.format}"`);
+    }
+    const VALID_THREADS = ["sim", "renderer", "own-worker"];
+    if (typeof l.thread !== "string" || !VALID_THREADS.includes(l.thread)) {
+        errors.push(`logic.thread: required one of ${VALID_THREADS.join("|")}, got "${l.thread}"`);
+    }
+    if (typeof l.entry !== "string" || !l.entry) {
+        errors.push(`logic.entry: required string path, got "${l.entry}"`);
+    }
+    if (l.permissions !== undefined) {
+        if (!Array.isArray(l.permissions) || !l.permissions.every((p) => typeof p === "string")) {
+            errors.push("logic.permissions: must be an array of strings");
+        }
+    }
+}
+// ── Mod extensions validation ──
+function validateModExtensions(e, errors) {
+    if (typeof e !== "object" || e === null) {
+        errors.push("extensions: must be an object");
+        return;
+    }
+    if (e.assets !== undefined) {
+        if (!Array.isArray(e.assets)) {
+            errors.push("extensions.assets: must be an array");
+        }
+        else {
+            e.assets.forEach((a, i) => validateAssetExtension(a, i, errors));
+        }
+    }
+    if (e.maps !== undefined) {
+        if (!Array.isArray(e.maps)) {
+            errors.push("extensions.maps: must be an array");
+        }
+        else {
+            e.maps.forEach((mp, i) => {
+                if (!mp || typeof mp !== "object")
+                    return errors.push(`extensions.maps[${i}]: must be an object`);
+                if (typeof mp.id !== "string")
+                    errors.push(`extensions.maps[${i}].id: required string`);
+                if (typeof mp.path !== "string")
+                    errors.push(`extensions.maps[${i}].path: required string`);
+            });
+        }
+    }
+    if (e.physics !== undefined) {
+        if (!Array.isArray(e.physics)) {
+            errors.push("extensions.physics: must be an array");
+        }
+        else {
+            e.physics.forEach((p, i) => {
+                if (!p || typeof p !== "object")
+                    return errors.push(`extensions.physics[${i}]: must be an object`);
+                if (typeof p.id !== "string")
+                    errors.push(`extensions.physics[${i}].id: required string`);
+                if (typeof p.path !== "string")
+                    errors.push(`extensions.physics[${i}].path: required string`);
+            });
+        }
+    }
+    if (e.shaders !== undefined) {
+        if (typeof e.shaders !== "object" || e.shaders === null) {
+            errors.push("extensions.shaders: must be an object");
+        }
+        else {
+            const s = e.shaders;
+            if (s.postfx !== undefined) {
+                if (!Array.isArray(s.postfx)) {
+                    errors.push("extensions.shaders.postfx: must be an array");
+                }
+                else {
+                    s.postfx.forEach((fx, i) => validatePostfxExtension(fx, i, errors));
+                }
+            }
+            if (s.materials !== undefined) {
+                if (!Array.isArray(s.materials)) {
+                    errors.push("extensions.shaders.materials: must be an array");
+                }
+                else {
+                    s.materials.forEach((mat, i) => {
+                        if (!mat || typeof mat !== "object")
+                            return errors.push(`extensions.shaders.materials[${i}]: must be an object`);
+                        if (typeof mat.id !== "string")
+                            errors.push(`extensions.shaders.materials[${i}].id: required string`);
+                        if (typeof mat.wgsl !== "string")
+                            errors.push(`extensions.shaders.materials[${i}].wgsl: required string path`);
+                        if (mat.uniforms !== undefined && typeof mat.uniforms !== "number")
+                            errors.push(`extensions.shaders.materials[${i}].uniforms: must be a number`);
+                    });
+                }
+            }
+        }
+    }
+}
+function validateAssetExtension(a, i, errors) {
+    if (!a || typeof a !== "object") {
+        errors.push(`extensions.assets[${i}]: must be an object`);
+        return;
+    }
+    const ext = a;
+    const VALID_KINDS = ["mesh", "texture", "pbr-material", "texture-pipeline"];
+    if (typeof ext.kind !== "string" || !VALID_KINDS.includes(ext.kind)) {
+        errors.push(`extensions.assets[${i}].kind: required one of ${VALID_KINDS.join("|")}, got "${ext.kind}"`);
+    }
+    if (typeof ext.id !== "string" || !ext.id) {
+        errors.push(`extensions.assets[${i}].id: required string`);
+    }
+    // `path` is optional for mesh assets: a pathless mesh means "procedural
+    // primitive prop" (shape/physics meta only, no file). All other kinds
+    // still require a file path.
+    if (ext.kind !== "mesh" && (typeof ext.path !== "string" || !ext.path)) {
+        errors.push(`extensions.assets[${i}].path: required string`);
+    }
+}
+function validatePostfxExtension(fx, i, errors) {
+    if (!fx || typeof fx !== "object") {
+        errors.push(`extensions.shaders.postfx[${i}]: must be an object`);
+        return;
+    }
+    const ext = fx;
+    if (typeof ext.id !== "string" || !ext.id)
+        errors.push(`extensions.shaders.postfx[${i}].id: required string`);
+    if (typeof ext.name !== "string")
+        errors.push(`extensions.shaders.postfx[${i}].name: required string`);
+    if (typeof ext.wgsl !== "string")
+        errors.push(`extensions.shaders.postfx[${i}].wgsl: required string path`);
+    const VALID_LAYOUTS = ["cc", "cd", "cvvh", "cvd", "dnfn"];
+    if (typeof ext.layout !== "string" || !VALID_LAYOUTS.includes(ext.layout)) {
+        errors.push(`extensions.shaders.postfx[${i}].layout: required one of ${VALID_LAYOUTS.join("|")}, got "${ext.layout}"`);
+    }
+    const VALID_ORDERS = ["hdr", "color-grading", "camera", "stylized"];
+    if (typeof ext.order !== "string" || !VALID_ORDERS.includes(ext.order)) {
+        errors.push(`extensions.shaders.postfx[${i}].order: required one of ${VALID_ORDERS.join("|")}, got "${ext.order}"`);
+    }
+    if (ext.uniforms !== undefined && typeof ext.uniforms !== "number") {
+        errors.push(`extensions.shaders.postfx[${i}].uniforms: must be a number`);
+    }
+}
+// ── Normalizer: populate logic + extensions from legacy plugin.json fields ──
+//
+// A legacy plugin.json uses `format`/`tier`/`thread`/`entry`/`permissions`/
+// `assets`. A mod.json uses `logic`/`extensions`. This populates whichever is
+// missing so the host's extension dispatch works uniformly for both shapes.
+// The legacy fields are preserved (existing loaders still read them).
+function normalizeLogicAndExtensions(m) {
+    // When logic is present, ensure the top-level format/thread/entry/permissions
+    // mirror it (so legacy loaders that read m.format / m.entry keep working).
+    if (m.logic) {
+        if (!m.format)
+            m.format = m.logic.format;
+        if (!m.thread)
+            m.thread = m.logic.thread;
+        if (!m.entry)
+            m.entry = m.logic.entry;
+        if (!m.permissions && m.logic.permissions)
+            m.permissions = m.logic.permissions;
+        if (m.logic.format === "wasm")
+            m.thread = "own-worker";
+    }
+    // Populate `logic` from legacy fields when not already present and the
+    // manifest is a code-bearing format.
+    if (!m.logic && m.format && m.format !== "asset" && m.entry) {
+        m.logic = {
+            format: m.format,
+            thread: m.thread,
+            entry: m.entry,
+            permissions: m.permissions,
+            ...(m.quickjs ? { quickjs: m.quickjs } : {}),
+        };
+    }
+    // Populate `extensions.assets` from the legacy `assets` section when not
+    // already present (data-tier asset plugins).
+    if (!m.extensions && m.assets) {
+        const assets = [];
+        (m.assets.meshes ?? []).forEach((meshPath) => {
+            assets.push({ kind: "mesh", id: meshPath, path: meshPath });
+        });
+        (m.assets.textures ?? []).forEach((texPath) => {
+            assets.push({ kind: "texture", id: texPath, path: texPath });
+        });
+        (m.assets.data ?? []).forEach((dataPath) => {
+            // Legacy data files are registered as textures of kind "texture" only if
+            // they're image files; otherwise they're opaque data. Keep them as
+            // texture-kind entries with the data path so the asset loader can
+            // dispatch by extension.
+            assets.push({ kind: "texture", id: dataPath, path: dataPath });
+        });
+        if (assets.length > 0)
+            m.extensions = { assets };
+    }
+}
+/** Flatten a manifest's extensions into a dispatch list (bucket + extension).
+ *  Returns extensions in a stable order: assets, maps, physics, shader-postfx,
+ *  shader-material. Used by the host to drive ExtensionLoaders. */
+export function flattenExtensions(m) {
+    const out = [];
+    const ext = m.extensions;
+    if (!ext)
+        return out;
+    (ext.assets ?? []).forEach((a) => { out.push({ bucket: "assets", extension: a }); ; });
+    (ext.maps ?? []).forEach((mp) => { out.push({ bucket: "maps", extension: mp }); ; });
+    (ext.physics ?? []).forEach((p) => { out.push({ bucket: "physics", extension: p }); ; });
+    (ext.shaders?.postfx ?? []).forEach((fx) => { out.push({ bucket: "shader-postfx", extension: fx }); ; });
+    (ext.shaders?.materials ?? []).forEach((mat) => { out.push({ bucket: "shader-material", extension: mat }); ; });
+    return out;
+}

package/dist/core/src/plugin/material-registry.js

@@ -0,0 +1,44 @@
+// ============================================================================
+// MaterialRegistry — mod-defined material shaders for spawned props.
+//
+// Mods register custom WGSL material shaders via the ShaderRegistry extension
+// loader. The MaterialRegistry tracks registered materials and provides
+// lookup by id. The renderer integrates with this registry to apply custom
+// materials to spawned props.
+//
+// This is a lightweight, testable registry. The actual GPU pipeline creation
+// + bindless material integration happens in the renderer when a prop is
+// spawned with a custom material id (the renderer looks up the material in
+// this registry and compiles the WGSL on demand).
+// ============================================================================
+/** Registry for mod-defined material shaders. */
+export class MaterialRegistry {
+    materials = new Map();
+    /** Register a material shader. Throws if the id is already registered. */
+    register(material) {
+        if (this.materials.has(material.id)) {
+            throw new Error(`Material "${material.id}" is already registered`);
+        }
+        this.materials.set(material.id, material);
+    }
+    /** Unregister a material by id. */
+    unregister(id) {
+        this.materials.delete(id);
+    }
+    /** Get a registered material by id. Returns undefined if not found. */
+    get(id) {
+        return this.materials.get(id);
+    }
+    /** Check if a material is registered. */
+    has(id) {
+        return this.materials.has(id);
+    }
+    /** Get all registered material ids. */
+    ids() {
+        return [...this.materials.keys()];
+    }
+    /** Clear all registered materials. */
+    clear() {
+        this.materials.clear();
+    }
+}

package/dist/core/src/plugin/mcp-tools.js

@@ -0,0 +1,147 @@
+// ============================================================================
+// MCP automation tools for the plugin system.
+//
+// Games call `createPluginMcpTools(pluginHost)` in their MCP setup to register
+// tools that let the in-game MCP harness (and `draft test` e2e specs) inspect
+// and control plugins:
+//   - plugin_list: list all discovered plugins with status.
+//   - plugin_get_info: get detailed info for a single plugin.
+//   - plugin_reload: reload a plugin by id.
+//   - plugin_unload: unload a plugin by id.
+//   - plugin_get_state: get a plugin's KV state.
+//
+// These integrate with the existing createMcpHarness from @downdraft/engine/app/renderer.
+// ============================================================================
+function jsonResult(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+}
+function errorResult(msg) {
+    return { content: [{ type: "text", text: JSON.stringify({ error: msg }) }] };
+}
+/**
+ * Create MCP tool registrations for plugin management.
+ * Games pass these to `createMcpHarness({ tools: [...] })`.
+ */
+export function createPluginMcpTools(pluginHost) {
+    return [
+        {
+            def: {
+                name: "plugin_list",
+                description: "List all discovered plugins with their current status, format, tier, and thread. " +
+                    "Useful for verifying plugins loaded correctly in e2e tests.",
+                inputSchema: { type: "object", properties: {} },
+            },
+            handler: async () => {
+                const snap = pluginHost.snapshot();
+                return jsonResult({
+                    count: snap.length,
+                    plugins: snap.map((p) => ({
+                        id: p.id,
+                        name: p.name,
+                        version: p.version,
+                        format: p.format,
+                        tier: p.tier,
+                        thread: p.thread,
+                        status: p.status,
+                        error: p.error,
+                        permissions: p.permissions,
+                    })),
+                });
+            },
+        },
+        {
+            def: {
+                name: "plugin_get_info",
+                description: "Get detailed info for a single plugin by id, including denied permissions and source.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        id: { type: "string", description: "Plugin id" },
+                    },
+                    required: ["id"],
+                },
+            },
+            handler: async (params) => {
+                const id = params.id;
+                const snap = pluginHost.snapshot();
+                const info = snap.find((p) => p.id === id);
+                if (!info)
+                    return errorResult(`Plugin "${id}" not found`);
+                return jsonResult(info);
+            },
+        },
+        {
+            def: {
+                name: "plugin_reload",
+                description: "Reload a plugin by id. The plugin is unloaded and re-loaded from its source. " +
+                    "Useful for testing plugin lifecycle in e2e specs.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        id: { type: "string", description: "Plugin id" },
+                    },
+                    required: ["id"],
+                },
+            },
+            handler: async (params) => {
+                const id = params.id;
+                try {
+                    await pluginHost.reload(id);
+                    const snap = pluginHost.snapshot();
+                    const info = snap.find((p) => p.id === id);
+                    return jsonResult({ success: true, status: info?.status, error: info?.error });
+                }
+                catch (e) {
+                    return errorResult(`Failed to reload plugin "${id}": ${e.message}`);
+                }
+            },
+        },
+        {
+            def: {
+                name: "plugin_unload",
+                description: "Unload a plugin by id. The plugin is disposed and removed from the active set.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        id: { type: "string", description: "Plugin id" },
+                    },
+                    required: ["id"],
+                },
+            },
+            handler: async (params) => {
+                const id = params.id;
+                try {
+                    pluginHost.unload(id);
+                    return jsonResult({ success: true });
+                }
+                catch (e) {
+                    return errorResult(`Failed to unload plugin "${id}": ${e.message}`);
+                }
+            },
+        },
+        {
+            def: {
+                name: "plugin_get_state",
+                description: "Get a plugin's KV state keys. Returns the list of state keys for the plugin.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        id: { type: "string", description: "Plugin id" },
+                    },
+                    required: ["id"],
+                },
+            },
+            handler: async (params) => {
+                const id = params.id;
+                const snap = pluginHost.snapshot();
+                const info = snap.find((p) => p.id === id);
+                if (!info)
+                    return errorResult(`Plugin "${id}" not found`);
+                // The PluginHost doesn't expose the per-plugin state store directly,
+                // but the snapshot includes the manifest. For full state access, the
+                // game would need to expose the context backing. This is a stub.
+                return jsonResult({ id, stateKeys: [], note: "State access requires game-side wiring" });
+            },
+        },
+    ];
+}