@idosgames/module-sdk 0.1.0 → 0.1.2

package/dist/index.d.cts

@@ -18,6 +18,66 @@ interface ModuleMeta {
     genre?: string;
     engine: ModuleEngine;
 }
+/** A module's author, for catalog attribution. */
+interface ModuleAuthor {
+    name: string;
+    url?: string;
+}
+/** Preview media for a module, as hosted URLs — modules never bundle binaries. */
+interface ModuleMedia {
+    /** Cover / preview image URL. */
+    image?: string;
+    /** Short preview or demo video URL. */
+    video?: string;
+}
+/**
+ * Catalog metadata for a module, authored as `module.meta.json` next to the module's package.json.
+ *
+ * This is NOT part of the runtime contract (`Module` / `ModuleMeta`) — the host never reads it. It
+ * feeds three consumers: the Module & Skills Registry, the platform's module picker, and the AI
+ * Coder's available-modules catalog. The last one is the point: the agent matches a publisher's
+ * prompt against `provides` and reuses a ready module instead of rebuilding the same feature.
+ *
+ * A third-party author ships one by dropping this JSON into their module folder — no code, no build
+ * step. Only `id`, `summary` and `provides` are required; `name`/`type`/`engine` come from the
+ * runtime `ModuleMeta` in `module.ts` and need not be repeated here.
+ */
+interface ModuleManifest {
+    /** Must equal the module's folder / registry id (e.g. "board-game"). */
+    id: string;
+    /**
+     * The module's catalog type: `"template"` is a complete, ready-to-run game/app you start FROM
+     * (e.g. voxelcraft — a full Minecraft-like sandbox); `"feature"` is a capability you ADD to a
+     * project (a HUD, a shop, an event system, …). This is the catalog-facing type and is distinct
+     * from the runtime `ModuleMeta.type` (`game | app | ai-app`) in `module.ts`. Defaults to
+     * `"feature"`.
+     */
+    type?: "template" | "feature";
+    /** Overrides the catalog display name; defaults to `ModuleMeta.name` from `module.ts`. */
+    name?: string;
+    /** One-line pitch shown on the catalog card. */
+    summary: string;
+    /** Longer description (Markdown allowed). */
+    description?: string;
+    /**
+     * What functionality this module already implements, as plain feature phrases. The AI Coder
+     * matches a user's request against these to decide whether to reuse the module rather than write
+     * new code — so phrase them the way a publisher describes a feature ("turn-based dice movement",
+     * "buy / upgrade tiles", "offline idle income"), not as file or API names.
+     */
+    provides: string[];
+    /** Free-form tags for search and filtering. */
+    tags?: string[];
+    /** Preview media (hosted URLs — modules do not bundle binaries). */
+    media?: ModuleMedia;
+    /** Live, playable demo of just this module. */
+    demoUrl?: string;
+    /** Documentation link. */
+    docsUrl?: string;
+    author?: ModuleAuthor;
+    /** Semver of the module content; defaults to the module's package.json `version`. */
+    version?: string;
+}
 /**
  * The manifest a module exports. The host calls `setup` exactly once, passing shared services;
  * the module registers its scene/panels/routes and returns nothing.
@@ -32,6 +92,12 @@ interface Module {
 interface ModuleContext {
     /** The one shared, already-authenticated SDK client. Modules never create their own. */
     client: IDosGamesClient;
+    /**
+     * The Title the host resolved at startup. Always use this — never re-read the title from the
+     * URL inside a module: the host may have resolved it from the baked project config instead,
+     * and a module that disagrees with its host talks to a different title's data.
+     */
+    titleId: string;
     /** Cross-module bus — e.g. an idle module emits "gold:granted", a board module reacts. */
     events: SharedEventBus;
     /** Requests host-managed DOM surfaces (canvas hosts, HUD slots) when a module needs one directly. */
@@ -42,6 +108,47 @@ interface ModuleContext {
     registerPanel(panel: UiPanel): void;
     /** Register a nav / mode entry so the player can switch to this module. */
     registerRoute(entry: RouteEntry): void;
+    /**
+     * Publish a debug surface for the AI Coder's agent — what the module IS and what it can be told
+     * to DO. Optional: a module without it simply stays opaque to the agent.
+     *
+     * Why it exists: the agent inspects a running app by reading the DOM, and a rendered game has no
+     * DOM to read — a Three/Phaser module is a single `<canvas>`. Without this the agent is blind to
+     * everything that matters (where the player is, what the world looks like) and cannot act at all.
+     * Synthetic key/mouse events are not a substitute: an engine that gates input on Pointer Lock
+     * ignores them, and Pointer Lock is unavailable in the preview sandbox.
+     *
+     * @see ModuleAgentApi
+     */
+    exposeToAgent(api: ModuleAgentApi): void;
+}
+/**
+ * A module's debug surface for the agent: read its state, drive it with named actions.
+ *
+ * Keep both sides SMALL and STABLE. This is a debugging contract, not a public API for gameplay:
+ * the agent reads `state()` to answer "what is happening" and calls an action to reproduce a bug
+ * ("walk forward and check you did not fall through the floor"). Actions must go through the
+ * module's normal input path (intents/commands) — never a second movement implementation, which
+ * would drift from the real one and make the agent's checks meaningless.
+ */
+interface ModuleAgentApi {
+    /**
+     * A snapshot of what matters right now: player position/health, current screen or turn, score,
+     * inventory size, fps. Must be cheap (it is called per request), JSON-serializable and free of
+     * secrets — it is sent verbatim into an LLM prompt.
+     */
+    state(): unknown;
+    /**
+     * Named actions the agent may perform, e.g. `move({ dir: "forward", ms: 500 })`, `jump()`,
+     * `endTurn()`. Return whatever is useful (usually nothing — the agent reads `state()` after).
+     * Anything destructive to the player's saved data does NOT belong here.
+     */
+    actions?: Record<string, (args?: Record<string, unknown>) => unknown | Promise<unknown>>;
+    /**
+     * One line per action explaining what it does and which args it takes. The agent sees these
+     * verbatim and has no other way to learn the calling convention.
+     */
+    describeActions?: Record<string, string>;
 }
 /** Where on screen a surface lives. The host's layout decides actual placement. */
 type SurfaceKind = "fullbleed-canvas" | "sidebar-panel" | "overlay" | "hud-slot";
@@ -115,4 +222,4 @@ interface SharedEventBus<Events extends Record<string, unknown> = Record<string,
 /** Identity helper that pins a module literal to the `Module` type for editor help and errors. */
 declare function defineModule(module: Module): Module;
 
-export { type EngineScene, type Module, type ModuleContext, type ModuleEngine, type ModuleMeta, type ModuleType, type PanelSlot, type RouteEntry, type SceneMountContext, type SharedEventBus, type SurfaceAllocator, type SurfaceHandle, type SurfaceKind, type UiPanel, defineModule };
+export { type EngineScene, type Module, type ModuleAgentApi, type ModuleAuthor, type ModuleContext, type ModuleEngine, type ModuleManifest, type ModuleMedia, type ModuleMeta, type ModuleType, type PanelSlot, type RouteEntry, type SceneMountContext, type SharedEventBus, type SurfaceAllocator, type SurfaceHandle, type SurfaceKind, type UiPanel, defineModule };

package/dist/index.d.ts

@@ -18,6 +18,66 @@ interface ModuleMeta {
     genre?: string;
     engine: ModuleEngine;
 }
+/** A module's author, for catalog attribution. */
+interface ModuleAuthor {
+    name: string;
+    url?: string;
+}
+/** Preview media for a module, as hosted URLs — modules never bundle binaries. */
+interface ModuleMedia {
+    /** Cover / preview image URL. */
+    image?: string;
+    /** Short preview or demo video URL. */
+    video?: string;
+}
+/**
+ * Catalog metadata for a module, authored as `module.meta.json` next to the module's package.json.
+ *
+ * This is NOT part of the runtime contract (`Module` / `ModuleMeta`) — the host never reads it. It
+ * feeds three consumers: the Module & Skills Registry, the platform's module picker, and the AI
+ * Coder's available-modules catalog. The last one is the point: the agent matches a publisher's
+ * prompt against `provides` and reuses a ready module instead of rebuilding the same feature.
+ *
+ * A third-party author ships one by dropping this JSON into their module folder — no code, no build
+ * step. Only `id`, `summary` and `provides` are required; `name`/`type`/`engine` come from the
+ * runtime `ModuleMeta` in `module.ts` and need not be repeated here.
+ */
+interface ModuleManifest {
+    /** Must equal the module's folder / registry id (e.g. "board-game"). */
+    id: string;
+    /**
+     * The module's catalog type: `"template"` is a complete, ready-to-run game/app you start FROM
+     * (e.g. voxelcraft — a full Minecraft-like sandbox); `"feature"` is a capability you ADD to a
+     * project (a HUD, a shop, an event system, …). This is the catalog-facing type and is distinct
+     * from the runtime `ModuleMeta.type` (`game | app | ai-app`) in `module.ts`. Defaults to
+     * `"feature"`.
+     */
+    type?: "template" | "feature";
+    /** Overrides the catalog display name; defaults to `ModuleMeta.name` from `module.ts`. */
+    name?: string;
+    /** One-line pitch shown on the catalog card. */
+    summary: string;
+    /** Longer description (Markdown allowed). */
+    description?: string;
+    /**
+     * What functionality this module already implements, as plain feature phrases. The AI Coder
+     * matches a user's request against these to decide whether to reuse the module rather than write
+     * new code — so phrase them the way a publisher describes a feature ("turn-based dice movement",
+     * "buy / upgrade tiles", "offline idle income"), not as file or API names.
+     */
+    provides: string[];
+    /** Free-form tags for search and filtering. */
+    tags?: string[];
+    /** Preview media (hosted URLs — modules do not bundle binaries). */
+    media?: ModuleMedia;
+    /** Live, playable demo of just this module. */
+    demoUrl?: string;
+    /** Documentation link. */
+    docsUrl?: string;
+    author?: ModuleAuthor;
+    /** Semver of the module content; defaults to the module's package.json `version`. */
+    version?: string;
+}
 /**
  * The manifest a module exports. The host calls `setup` exactly once, passing shared services;
  * the module registers its scene/panels/routes and returns nothing.
@@ -32,6 +92,12 @@ interface Module {
 interface ModuleContext {
     /** The one shared, already-authenticated SDK client. Modules never create their own. */
     client: IDosGamesClient;
+    /**
+     * The Title the host resolved at startup. Always use this — never re-read the title from the
+     * URL inside a module: the host may have resolved it from the baked project config instead,
+     * and a module that disagrees with its host talks to a different title's data.
+     */
+    titleId: string;
     /** Cross-module bus — e.g. an idle module emits "gold:granted", a board module reacts. */
     events: SharedEventBus;
     /** Requests host-managed DOM surfaces (canvas hosts, HUD slots) when a module needs one directly. */
@@ -42,6 +108,47 @@ interface ModuleContext {
     registerPanel(panel: UiPanel): void;
     /** Register a nav / mode entry so the player can switch to this module. */
     registerRoute(entry: RouteEntry): void;
+    /**
+     * Publish a debug surface for the AI Coder's agent — what the module IS and what it can be told
+     * to DO. Optional: a module without it simply stays opaque to the agent.
+     *
+     * Why it exists: the agent inspects a running app by reading the DOM, and a rendered game has no
+     * DOM to read — a Three/Phaser module is a single `<canvas>`. Without this the agent is blind to
+     * everything that matters (where the player is, what the world looks like) and cannot act at all.
+     * Synthetic key/mouse events are not a substitute: an engine that gates input on Pointer Lock
+     * ignores them, and Pointer Lock is unavailable in the preview sandbox.
+     *
+     * @see ModuleAgentApi
+     */
+    exposeToAgent(api: ModuleAgentApi): void;
+}
+/**
+ * A module's debug surface for the agent: read its state, drive it with named actions.
+ *
+ * Keep both sides SMALL and STABLE. This is a debugging contract, not a public API for gameplay:
+ * the agent reads `state()` to answer "what is happening" and calls an action to reproduce a bug
+ * ("walk forward and check you did not fall through the floor"). Actions must go through the
+ * module's normal input path (intents/commands) — never a second movement implementation, which
+ * would drift from the real one and make the agent's checks meaningless.
+ */
+interface ModuleAgentApi {
+    /**
+     * A snapshot of what matters right now: player position/health, current screen or turn, score,
+     * inventory size, fps. Must be cheap (it is called per request), JSON-serializable and free of
+     * secrets — it is sent verbatim into an LLM prompt.
+     */
+    state(): unknown;
+    /**
+     * Named actions the agent may perform, e.g. `move({ dir: "forward", ms: 500 })`, `jump()`,
+     * `endTurn()`. Return whatever is useful (usually nothing — the agent reads `state()` after).
+     * Anything destructive to the player's saved data does NOT belong here.
+     */
+    actions?: Record<string, (args?: Record<string, unknown>) => unknown | Promise<unknown>>;
+    /**
+     * One line per action explaining what it does and which args it takes. The agent sees these
+     * verbatim and has no other way to learn the calling convention.
+     */
+    describeActions?: Record<string, string>;
 }
 /** Where on screen a surface lives. The host's layout decides actual placement. */
 type SurfaceKind = "fullbleed-canvas" | "sidebar-panel" | "overlay" | "hud-slot";
@@ -115,4 +222,4 @@ interface SharedEventBus<Events extends Record<string, unknown> = Record<string,
 /** Identity helper that pins a module literal to the `Module` type for editor help and errors. */
 declare function defineModule(module: Module): Module;
 
-export { type EngineScene, type Module, type ModuleContext, type ModuleEngine, type ModuleMeta, type ModuleType, type PanelSlot, type RouteEntry, type SceneMountContext, type SharedEventBus, type SurfaceAllocator, type SurfaceHandle, type SurfaceKind, type UiPanel, defineModule };
+export { type EngineScene, type Module, type ModuleAgentApi, type ModuleAuthor, type ModuleContext, type ModuleEngine, type ModuleManifest, type ModuleMedia, type ModuleMeta, type ModuleType, type PanelSlot, type RouteEntry, type SceneMountContext, type SharedEventBus, type SurfaceAllocator, type SurfaceHandle, type SurfaceKind, type UiPanel, defineModule };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idosgames/module-sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "The composable-module contract for the iDosGames host shell: Module / ModuleContext types plus tiny authoring helpers. Framework-neutral at runtime — a module can be a game (Three/Phaser), a plain app, or an AI app.",
   "type": "module",
   "license": "MIT",