@idosgames/module-sdk 0.2.1 → 0.3.1

package/dist/index.cjs

@@ -1 +1 @@
-'use strict';var m=/^[a-z0-9][a-z0-9-]*:[a-z0-9][a-z0-9-]*@[1-9]\d*$/;function x(e){return typeof e=="string"&&m.test(e)}function M(e){let t=e.indexOf(":");return t<0?"":e.slice(0,t)}var l=/^(string|number|boolean)(\[\])?(\?)?$/;function u(e){return typeof e=="object"&&e!==null&&!Array.isArray(e)}function c(e,t){return e==="number"?typeof t=="number"&&Number.isFinite(t):typeof t===e}function f(e,t,r){if(!u(t))return `${r||"payload"} must be an object`;for(let[n,o]of Object.entries(e)){let i=r?`${r}.${n}`:n,a=t[n];if(typeof o!="string"){let p=f(o,a,i);if(p)return p;continue}let d=l.exec(o);if(!d)return `${i}: invalid descriptor "${o}"`;let[,s="",g,S]=d;if(a===void 0){if(S)continue;return `${i} is missing`}if(g){if(!Array.isArray(a))return `${i} must be ${s}[]`;if(!a.every(p=>c(s,p)))return `${i} must contain only ${s} values`;continue}if(!c(s,a))return `${i} must be a ${s}`}return null}function y(e,t){for(let[r,n]of Object.entries(e)){let o=t?`${t}.${r}`:r;if(typeof n=="string"){if(!l.test(n))throw new Error(`shape(): field "${o}" has invalid type "${n}" \u2014 use "string" | "number" | "boolean", optionally with "[]" and/or a trailing "?"`)}else if(u(n))y(n,o);else throw new Error(`shape(): field "${o}" must be a type string or an object`)}}function h(e){return y(e,""),{descriptor:e,check:t=>f(e,t,"")}}function v(e,t){if(!x(e))throw new Error(`defineTopic(): "${e}" is not a valid topic name \u2014 expected "<module-id>:<event>@<major>", e.g. "idle-rpg:character-upgraded@1"`);return {name:e,shape:t}}var E={modeChanged:v("host:mode-changed@1",h({from:"string?",to:"string"}))};var T=["currency-bar","wallet","status","account"];function $(e){return typeof e=="string"&&T.includes(e)}function D(e){return e}exports.SHARED_UI_ROLES=T;exports.TOPIC_NAME_RE=m;exports.defineModule=D;exports.defineTopic=v;exports.hostTopics=E;exports.isSharedUiRole=$;exports.isTopicName=x;exports.shape=h;exports.topicNamespace=M;
+'use strict';var S=/^[a-z0-9][a-z0-9-]*:[a-z0-9][a-z0-9-]*@[1-9]\d*$/;function x(e){return typeof e=="string"&&S.test(e)}function M(e){let t=e.indexOf(":");return t<0?"":e.slice(0,t)}var l=/^(string|number|boolean)(\[\])?(\?)?$/;function u(e){return typeof e=="object"&&e!==null&&!Array.isArray(e)}function c(e,t){return e==="number"?typeof t=="number"&&Number.isFinite(t):typeof t===e}function f(e,t,r){if(!u(t))return `${r||"payload"} must be an object`;for(let[n,o]of Object.entries(e)){let i=r?`${r}.${n}`:n,a=t[n];if(typeof o!="string"){let p=f(o,a,i);if(p)return p;continue}let d=l.exec(o);if(!d)return `${i}: invalid descriptor "${o}"`;let[,s="",g,m]=d;if(a===void 0){if(m)continue;return `${i} is missing`}if(g){if(!Array.isArray(a))return `${i} must be ${s}[]`;if(!a.every(p=>c(s,p)))return `${i} must contain only ${s} values`;continue}if(!c(s,a))return `${i} must be a ${s}`}return null}function y(e,t){for(let[r,n]of Object.entries(e)){let o=t?`${t}.${r}`:r;if(typeof n=="string"){if(!l.test(n))throw new Error(`shape(): field "${o}" has invalid type "${n}" \u2014 use "string" | "number" | "boolean", optionally with "[]" and/or a trailing "?"`)}else if(u(n))y(n,o);else throw new Error(`shape(): field "${o}" must be a type string or an object`)}}function h(e){return y(e,""),{descriptor:e,check:t=>f(e,t,"")}}function v(e,t){if(!x(e))throw new Error(`defineTopic(): "${e}" is not a valid topic name \u2014 expected "<module-id>:<event>@<major>", e.g. "idle-rpg:character-upgraded@1"`);return {name:e,shape:t}}var E={modeChanged:v("host:mode-changed@1",h({from:"string?",to:"string"}))};var T=["currency-bar","wallet","status","account"];function D(e){return typeof e=="string"&&T.includes(e)}function $(e){return e}exports.SHARED_UI_ROLES=T;exports.TOPIC_NAME_RE=S;exports.defineModule=$;exports.defineTopic=v;exports.hostTopics=E;exports.isSharedUiRole=D;exports.isTopicName=x;exports.shape=h;exports.topicNamespace=M;

package/dist/index.d.cts

@@ -132,6 +132,70 @@ interface SharedUiContext {
 }
 declare function isSharedUiRole(value: unknown): value is SharedUiRole;
 
+/** Bytes of one file. Strings are UTF-8 encoded (JSON saves are the common case). */
+type ContentFileData = Blob | ArrayBuffer | Uint8Array | string;
+/** Something local the player can publish (a saved world, a level they built). */
+interface LocalContentItem {
+    id: string;
+    name: string;
+    /** Epoch ms of the last change — lists are shown newest first. */
+    updatedAt?: number;
+    /** One line under the name ("recipe world · 256×256"). */
+    subtitle?: string;
+}
+/** What `capture` hands to the Workshop to publish. Roles and MIME types must fit the title's content type config. */
+interface CapturedContent {
+    files: Array<{
+        role: string;
+        contentType: string;
+        data: ContentFileData;
+    }>;
+    thumbnail?: {
+        contentType: "image/png" | "image/jpeg" | "image/webp";
+        data: ContentFileData;
+    };
+    suggestedTitle?: string;
+    suggestedDescription?: string;
+    tags?: string[];
+    metadata?: Record<string, string>;
+}
+/** What the Workshop hands to `open` after the player got access. */
+interface DownloadedContent {
+    contentID: string;
+    title?: string | null;
+    /** Revision of the publication — lets a game tell an update from a first download. */
+    revision?: number | null;
+    files: Array<{
+        role: string;
+        contentType: string;
+        data: ArrayBuffer;
+    }>;
+}
+interface ContentTypeHandler {
+    /** Must equal a key of `Workshop.ContentTypes` in the title config (e.g. "voxelcraft.world"). */
+    type: string;
+    /** Shown in the Workshop's type filter and publish wizard. */
+    label: string;
+    icon?: string;
+    /** Mode (route id) to switch to after `open` — the game that plays this content. */
+    modeId?: string;
+    /** Local items the player can publish. Omit when the type cannot be published from the game. */
+    listLocal?(): Promise<LocalContentItem[]>;
+    /** Serialize one local item for publishing. */
+    capture?(localId: string): Promise<CapturedContent>;
+    /** Load downloaded content into the game (import a world, start a level). */
+    open?(content: DownloadedContent): Promise<void>;
+}
+/** `ctx.content` — the host's registry of content types, shared by every module of the session. */
+interface ContentRegistry {
+    /** Register (or replace) the handler of a type. Returns an unregister function. */
+    registerType(handler: ContentTypeHandler): () => void;
+    getType(type: string): ContentTypeHandler | undefined;
+    listTypes(): ContentTypeHandler[];
+    /** Called when a type is registered or removed (a UI re-renders its type list). */
+    subscribe(listener: () => void): () => void;
+}
+
 /** What a module is, for catalog/UI purposes. Not every module is a game. */
 type ModuleType = "game" | "app" | "ai-app";
 /**
@@ -213,6 +277,20 @@ interface ModuleManifest {
      * AI Coder's hygiene notes compare this with the `defineTopic("…")` literals in `src/`.
      */
     events?: ModuleEventsManifest;
+    /**
+     * Data collections this module needs (the title's `DataCollections` section): collection id →
+     * declaration, in the engine's JSON shape (`Kind`, `Fields`, `SortKeys`, `Access`, …). When the AI
+     * Coder composes a project it merges them into the title config, so a module brings its own data
+     * structures along instead of the agent re-inventing them. Ids MUST be prefixed with the module id
+     * (`"guild-system:guilds"`) — two modules never collide. Roles the rules reference go to
+     * `dataRoles`. Declare only what no ready platform module covers.
+     */
+    collections?: Record<string, unknown>;
+    /** Title user roles the module's collection rules reference (role id → `{ DisplayName }`). */
+    dataRoles?: Record<string, {
+        DisplayName?: string;
+        Description?: string;
+    }>;
 }
 /**
  * The manifest a module exports. The host calls `setup` exactly once, passing shared services;
@@ -257,6 +335,16 @@ interface ModuleContext {
     registerPanel(panel: UiPanel): void;
     /** Register a nav / mode entry so the player can switch to this module. */
     registerRoute(entry: RouteEntry): void;
+    /**
+     * Content types other modules can publish and open (see `ContentTypeHandler`). A game registers
+     * its type here; the Workshop module reads the registry — neither imports the other.
+     */
+    content: ContentRegistry;
+    /**
+     * Switch the host to another mode (a route id registered by any module) — e.g. the Workshop opens a
+     * world and hands the screen to the game. Unknown ids are ignored.
+     */
+    navigate(modeId: string): 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.
@@ -371,4 +459,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 InferShape, type Module, type ModuleAgentApi, type ModuleAuthor, type ModuleContext, type ModuleEngine, type ModuleEventEmit, type ModuleEventListen, type ModuleEvents, type ModuleEventsManifest, type ModuleManifest, type ModuleMedia, type ModuleMeta, type ModuleSharedUi, type ModuleType, type PanelSlot, type RouteEntry, SHARED_UI_ROLES, type SceneMountContext, type Shape, type ShapeDescriptor, type ShapeLeaf, type ShapeLeafSpec, type SharedEventBus, type SharedUiContext, type SharedUiRole, type SurfaceAllocator, type SurfaceHandle, type SurfaceKind, TOPIC_NAME_RE, type Topic, type TopicName, type TopicPayload, type UiPanel, defineModule, defineTopic, hostTopics, isSharedUiRole, isTopicName, shape, topicNamespace };
+export { type CapturedContent, type ContentFileData, type ContentRegistry, type ContentTypeHandler, type DownloadedContent, type EngineScene, type InferShape, type LocalContentItem, type Module, type ModuleAgentApi, type ModuleAuthor, type ModuleContext, type ModuleEngine, type ModuleEventEmit, type ModuleEventListen, type ModuleEvents, type ModuleEventsManifest, type ModuleManifest, type ModuleMedia, type ModuleMeta, type ModuleSharedUi, type ModuleType, type PanelSlot, type RouteEntry, SHARED_UI_ROLES, type SceneMountContext, type Shape, type ShapeDescriptor, type ShapeLeaf, type ShapeLeafSpec, type SharedEventBus, type SharedUiContext, type SharedUiRole, type SurfaceAllocator, type SurfaceHandle, type SurfaceKind, TOPIC_NAME_RE, type Topic, type TopicName, type TopicPayload, type UiPanel, defineModule, defineTopic, hostTopics, isSharedUiRole, isTopicName, shape, topicNamespace };

package/dist/index.d.ts

@@ -132,6 +132,70 @@ interface SharedUiContext {
 }
 declare function isSharedUiRole(value: unknown): value is SharedUiRole;
 
+/** Bytes of one file. Strings are UTF-8 encoded (JSON saves are the common case). */
+type ContentFileData = Blob | ArrayBuffer | Uint8Array | string;
+/** Something local the player can publish (a saved world, a level they built). */
+interface LocalContentItem {
+    id: string;
+    name: string;
+    /** Epoch ms of the last change — lists are shown newest first. */
+    updatedAt?: number;
+    /** One line under the name ("recipe world · 256×256"). */
+    subtitle?: string;
+}
+/** What `capture` hands to the Workshop to publish. Roles and MIME types must fit the title's content type config. */
+interface CapturedContent {
+    files: Array<{
+        role: string;
+        contentType: string;
+        data: ContentFileData;
+    }>;
+    thumbnail?: {
+        contentType: "image/png" | "image/jpeg" | "image/webp";
+        data: ContentFileData;
+    };
+    suggestedTitle?: string;
+    suggestedDescription?: string;
+    tags?: string[];
+    metadata?: Record<string, string>;
+}
+/** What the Workshop hands to `open` after the player got access. */
+interface DownloadedContent {
+    contentID: string;
+    title?: string | null;
+    /** Revision of the publication — lets a game tell an update from a first download. */
+    revision?: number | null;
+    files: Array<{
+        role: string;
+        contentType: string;
+        data: ArrayBuffer;
+    }>;
+}
+interface ContentTypeHandler {
+    /** Must equal a key of `Workshop.ContentTypes` in the title config (e.g. "voxelcraft.world"). */
+    type: string;
+    /** Shown in the Workshop's type filter and publish wizard. */
+    label: string;
+    icon?: string;
+    /** Mode (route id) to switch to after `open` — the game that plays this content. */
+    modeId?: string;
+    /** Local items the player can publish. Omit when the type cannot be published from the game. */
+    listLocal?(): Promise<LocalContentItem[]>;
+    /** Serialize one local item for publishing. */
+    capture?(localId: string): Promise<CapturedContent>;
+    /** Load downloaded content into the game (import a world, start a level). */
+    open?(content: DownloadedContent): Promise<void>;
+}
+/** `ctx.content` — the host's registry of content types, shared by every module of the session. */
+interface ContentRegistry {
+    /** Register (or replace) the handler of a type. Returns an unregister function. */
+    registerType(handler: ContentTypeHandler): () => void;
+    getType(type: string): ContentTypeHandler | undefined;
+    listTypes(): ContentTypeHandler[];
+    /** Called when a type is registered or removed (a UI re-renders its type list). */
+    subscribe(listener: () => void): () => void;
+}
+
 /** What a module is, for catalog/UI purposes. Not every module is a game. */
 type ModuleType = "game" | "app" | "ai-app";
 /**
@@ -213,6 +277,20 @@ interface ModuleManifest {
      * AI Coder's hygiene notes compare this with the `defineTopic("…")` literals in `src/`.
      */
     events?: ModuleEventsManifest;
+    /**
+     * Data collections this module needs (the title's `DataCollections` section): collection id →
+     * declaration, in the engine's JSON shape (`Kind`, `Fields`, `SortKeys`, `Access`, …). When the AI
+     * Coder composes a project it merges them into the title config, so a module brings its own data
+     * structures along instead of the agent re-inventing them. Ids MUST be prefixed with the module id
+     * (`"guild-system:guilds"`) — two modules never collide. Roles the rules reference go to
+     * `dataRoles`. Declare only what no ready platform module covers.
+     */
+    collections?: Record<string, unknown>;
+    /** Title user roles the module's collection rules reference (role id → `{ DisplayName }`). */
+    dataRoles?: Record<string, {
+        DisplayName?: string;
+        Description?: string;
+    }>;
 }
 /**
  * The manifest a module exports. The host calls `setup` exactly once, passing shared services;
@@ -257,6 +335,16 @@ interface ModuleContext {
     registerPanel(panel: UiPanel): void;
     /** Register a nav / mode entry so the player can switch to this module. */
     registerRoute(entry: RouteEntry): void;
+    /**
+     * Content types other modules can publish and open (see `ContentTypeHandler`). A game registers
+     * its type here; the Workshop module reads the registry — neither imports the other.
+     */
+    content: ContentRegistry;
+    /**
+     * Switch the host to another mode (a route id registered by any module) — e.g. the Workshop opens a
+     * world and hands the screen to the game. Unknown ids are ignored.
+     */
+    navigate(modeId: string): 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.
@@ -371,4 +459,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 InferShape, type Module, type ModuleAgentApi, type ModuleAuthor, type ModuleContext, type ModuleEngine, type ModuleEventEmit, type ModuleEventListen, type ModuleEvents, type ModuleEventsManifest, type ModuleManifest, type ModuleMedia, type ModuleMeta, type ModuleSharedUi, type ModuleType, type PanelSlot, type RouteEntry, SHARED_UI_ROLES, type SceneMountContext, type Shape, type ShapeDescriptor, type ShapeLeaf, type ShapeLeafSpec, type SharedEventBus, type SharedUiContext, type SharedUiRole, type SurfaceAllocator, type SurfaceHandle, type SurfaceKind, TOPIC_NAME_RE, type Topic, type TopicName, type TopicPayload, type UiPanel, defineModule, defineTopic, hostTopics, isSharedUiRole, isTopicName, shape, topicNamespace };
+export { type CapturedContent, type ContentFileData, type ContentRegistry, type ContentTypeHandler, type DownloadedContent, type EngineScene, type InferShape, type LocalContentItem, type Module, type ModuleAgentApi, type ModuleAuthor, type ModuleContext, type ModuleEngine, type ModuleEventEmit, type ModuleEventListen, type ModuleEvents, type ModuleEventsManifest, type ModuleManifest, type ModuleMedia, type ModuleMeta, type ModuleSharedUi, type ModuleType, type PanelSlot, type RouteEntry, SHARED_UI_ROLES, type SceneMountContext, type Shape, type ShapeDescriptor, type ShapeLeaf, type ShapeLeafSpec, type SharedEventBus, type SharedUiContext, type SharedUiRole, type SurfaceAllocator, type SurfaceHandle, type SurfaceKind, TOPIC_NAME_RE, type Topic, type TopicName, type TopicPayload, type UiPanel, defineModule, defineTopic, hostTopics, isSharedUiRole, isTopicName, shape, topicNamespace };

package/dist/index.js

@@ -1 +1 @@
-var m=/^[a-z0-9][a-z0-9-]*:[a-z0-9][a-z0-9-]*@[1-9]\d*$/;function x(e){return typeof e=="string"&&m.test(e)}function M(e){let t=e.indexOf(":");return t<0?"":e.slice(0,t)}var l=/^(string|number|boolean)(\[\])?(\?)?$/;function u(e){return typeof e=="object"&&e!==null&&!Array.isArray(e)}function c(e,t){return e==="number"?typeof t=="number"&&Number.isFinite(t):typeof t===e}function f(e,t,r){if(!u(t))return `${r||"payload"} must be an object`;for(let[n,o]of Object.entries(e)){let i=r?`${r}.${n}`:n,a=t[n];if(typeof o!="string"){let p=f(o,a,i);if(p)return p;continue}let d=l.exec(o);if(!d)return `${i}: invalid descriptor "${o}"`;let[,s="",g,S]=d;if(a===void 0){if(S)continue;return `${i} is missing`}if(g){if(!Array.isArray(a))return `${i} must be ${s}[]`;if(!a.every(p=>c(s,p)))return `${i} must contain only ${s} values`;continue}if(!c(s,a))return `${i} must be a ${s}`}return null}function y(e,t){for(let[r,n]of Object.entries(e)){let o=t?`${t}.${r}`:r;if(typeof n=="string"){if(!l.test(n))throw new Error(`shape(): field "${o}" has invalid type "${n}" \u2014 use "string" | "number" | "boolean", optionally with "[]" and/or a trailing "?"`)}else if(u(n))y(n,o);else throw new Error(`shape(): field "${o}" must be a type string or an object`)}}function h(e){return y(e,""),{descriptor:e,check:t=>f(e,t,"")}}function v(e,t){if(!x(e))throw new Error(`defineTopic(): "${e}" is not a valid topic name \u2014 expected "<module-id>:<event>@<major>", e.g. "idle-rpg:character-upgraded@1"`);return {name:e,shape:t}}var E={modeChanged:v("host:mode-changed@1",h({from:"string?",to:"string"}))};var T=["currency-bar","wallet","status","account"];function $(e){return typeof e=="string"&&T.includes(e)}function D(e){return e}export{T as SHARED_UI_ROLES,m as TOPIC_NAME_RE,D as defineModule,v as defineTopic,E as hostTopics,$ as isSharedUiRole,x as isTopicName,h as shape,M as topicNamespace};
+var S=/^[a-z0-9][a-z0-9-]*:[a-z0-9][a-z0-9-]*@[1-9]\d*$/;function x(e){return typeof e=="string"&&S.test(e)}function M(e){let t=e.indexOf(":");return t<0?"":e.slice(0,t)}var l=/^(string|number|boolean)(\[\])?(\?)?$/;function u(e){return typeof e=="object"&&e!==null&&!Array.isArray(e)}function c(e,t){return e==="number"?typeof t=="number"&&Number.isFinite(t):typeof t===e}function f(e,t,r){if(!u(t))return `${r||"payload"} must be an object`;for(let[n,o]of Object.entries(e)){let i=r?`${r}.${n}`:n,a=t[n];if(typeof o!="string"){let p=f(o,a,i);if(p)return p;continue}let d=l.exec(o);if(!d)return `${i}: invalid descriptor "${o}"`;let[,s="",g,m]=d;if(a===void 0){if(m)continue;return `${i} is missing`}if(g){if(!Array.isArray(a))return `${i} must be ${s}[]`;if(!a.every(p=>c(s,p)))return `${i} must contain only ${s} values`;continue}if(!c(s,a))return `${i} must be a ${s}`}return null}function y(e,t){for(let[r,n]of Object.entries(e)){let o=t?`${t}.${r}`:r;if(typeof n=="string"){if(!l.test(n))throw new Error(`shape(): field "${o}" has invalid type "${n}" \u2014 use "string" | "number" | "boolean", optionally with "[]" and/or a trailing "?"`)}else if(u(n))y(n,o);else throw new Error(`shape(): field "${o}" must be a type string or an object`)}}function h(e){return y(e,""),{descriptor:e,check:t=>f(e,t,"")}}function v(e,t){if(!x(e))throw new Error(`defineTopic(): "${e}" is not a valid topic name \u2014 expected "<module-id>:<event>@<major>", e.g. "idle-rpg:character-upgraded@1"`);return {name:e,shape:t}}var E={modeChanged:v("host:mode-changed@1",h({from:"string?",to:"string"}))};var T=["currency-bar","wallet","status","account"];function D(e){return typeof e=="string"&&T.includes(e)}function $(e){return e}export{T as SHARED_UI_ROLES,S as TOPIC_NAME_RE,$ as defineModule,v as defineTopic,E as hostTopics,D as isSharedUiRole,x as isTopicName,h as shape,M as topicNamespace};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idosgames/module-sdk",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "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",
@@ -46,7 +46,7 @@
   },
   "//": "@idosgames/core is a real range, not '*': a published contract must name the version of core whose IDosGamesClient/SdkEvents shapes it references. Bump in step with core (see RELEASING.md). react is an OPTIONAL peer — the contract references React's ComponentType type only (a UI panel is a React component), which is erased at build, so a runtime-only module needs no React.",
   "dependencies": {
-    "@idosgames/core": "^0.13.0"
+    "@idosgames/core": "^0.14.0"
   },
   "peerDependencies": {
     "react": "^18.3.1 || ^19.0.0"