@combos-fun/engine 0.0.24 → 0.0.27

package/agent-skill.md

@@ -17,11 +17,11 @@ Read this every time before working on a Combos Fun project. The entry skill loa
 
 ### Values
 
-`Game`, `Scene`, `GameObject`, `Component`, `System`, `Transform`, `resource`, `resourceLoader`, `decorators`, `IDEProp`, `componentObserver`, `LOAD_EVENT`, `RESOURCE_TYPE`, `OBSERVER_TYPE`, `LOAD_SCENE_MODE`, `RESOURCE_TYPE_STRATEGY`, `version`, `COMBOS_GAME_PLUGIN_INIT_SUCCESS`, `postParentPluginInitSuccess`.
+`Game`, `Scene`, `GameObject`, `Component`, `System`, `Transform`, `resource`, `resourceLoader`, `decorators`, `IDEProp`, `componentObserver`, `LOAD_EVENT`, `RESOURCE_TYPE`, `OBSERVER_TYPE`, `LOAD_SCENE_MODE`, `RESOURCE_TYPE_STRATEGY`, `version`, `COMBOS_GAME_PLUGIN_INIT_SUCCESS`, `COMBOS_GAME_READY`, `COMBOS_GAME_SET_PLAYING`, `COMBOS_GAME_STATE_CHANGED`, `postParentPluginInitSuccess`, `postParentGameReady`, `postParentGameState`, `parseSetPlayingMessage`, `DEFAULT_ALLOWED_MESSAGE_HOST_SUFFIXES`, `isAllowedMessageOrigin`, `mergeAllowedMessageOrigins`.
 
 ### Types
 
-`GameParams`, `PluginStruct`, `TransformParams`, `ComponentChanged`, `UpdateParams`, `ComponentParams`, `ObserverInfo`, `PureObserverInfo`, `ResourceBase`, `SystemConstructor`, `CombosGamePluginInitSuccessMessage`.
+`GameParams`, `PluginStruct`, `TransformParams`, `ComponentChanged`, `UpdateParams`, `ComponentParams`, `ObserverInfo`, `PureObserverInfo`, `ResourceBase`, `SystemConstructor`, `CombosGamePluginInitSuccessMessage`, `CombosGameReadyMessage`, `CombosGameStateChangedMessage`, `CombosGameSetPlayingMessage`.
 
 ### `GameParams`
 
@@ -33,7 +33,8 @@ Read this every time before working on a Combos Fun project. The entry skill loa
 | `autoStart`                    | `boolean`                | `true`  |                                          |
 | `needScene`                    | `boolean`                | `true`  | Auto-creates `Scene('scene')`            |
 | `onSystemsBootstrapComplete`   | `(game, error?) => void` | —       | After all systems init                   |
-| `pluginInitNotifyTargetOrigin` | `string`                 | `'*'`   | postMessage target                       |
+| `pluginInitNotifyTargetOrigin` | `string`                 | `'*'`   | Outbound postMessage target (init / ready / state) |
+| `allowedMessageOrigins`        | `string[]`               | defaults | Inbound origins allowed to send `set-playing` (merged with defaults; `['*']` = any) |
 
 
 When the game runs inside an iframe (`window.parent !== window`), each `Game.addSystem` call posts to the parent after that system's `init` completes:
@@ -50,10 +51,31 @@ When the game runs inside an iframe (`window.parent !== window`), each `Game.add
 
 Official `@combos-fun/plugin-*` packages get `packageName` / `packageVersion` automatically via `scripts/build-package.mjs` (no hand-written static fields). Host pages can gate tooling on specific systems or versions using this payload. Types: `CombosGamePluginInitSuccessMessage`, helper `postParentPluginInitSuccess` in `bootstrapMessages.ts`.
 
+### Host lifecycle protocol (preload → hold → play)
+
+Core `Game` speaks a `postMessage` protocol with the embedding page so a host APP can preload, hold, then start the game on user intent. All outbound messages go to `pluginInitNotifyTargetOrigin`; the inbound command is origin-checked against `allowedMessageOrigins`.
+
+**Outbound (iframe → parent):**
+
+| Type | When | Payload |
+| ---- | ---- | ------- |
+| `combos-game:ready` | Bootstrap finished (systems `init`/`awake`, optional scene load & start). Sent once even with `autoStart:false`. | `{ engineVersion, error? }` |
+| `combos-game:state-changed` | After `start` / `pause` / `resume` | `{ playing, started }` |
+
+**Inbound (parent → iframe):**
+
+| Type | Effect | Payload |
+| ---- | ------ | ------- |
+| `combos-game:set-playing` | `true` → cold `start()` on first play, else `resume()`; `false` → `pause()` | `{ playing: boolean }` |
+
+Recommended flow: create the game with `autoStart:false`, wait for `combos-game:ready`, keep the game held at frame 0 (host shows a cover/loading overlay), then post `{ type: 'combos-game:set-playing', playing: true }` when the user taps play. `game.setPlaying(playing)` is the programmatic equivalent. Helpers: `postParentGameReady`, `postParentGameState`, `parseSetPlayingMessage`.
+
+> Note: play/pause is owned by the engine core here, **not** by `plugin-development-tool` (which now only handles pick mode + mute).
+
 
 ### `Game` methods
 
-`addSystem(system)`, `removeSystem(system | class | string)` (calls `system.destroy()` internally), `getSystem(class | string)`, `loadScene({ scene, mode?, params? })` (`LOAD_SCENE_MODE.SINGLE | MULTI_CANVAS`), `start()`, `pause()`, `resume()`, `destroy()`.
+`addSystem(system)`, `removeSystem(system | class | string)` (calls `system.destroy()` internally), `getSystem(class | string)`, `loadScene({ scene, mode?, params? })` (`LOAD_SCENE_MODE.SINGLE | MULTI_CANVAS`), `start()`, `pause()`, `resume()`, `setPlaying(playing)` (host bridge: cold-start-or-resume / pause), `destroy()`.
 
 ### `resource` singleton
 

package/dist/engine.cjs.js

@@ -964,7 +964,7 @@ class Scene extends GameObject {
 }
 
 /** Generated at build from package.json */
-const version = "0.0.23";
+const version = "0.0.27";
 
 /**
  * Sent to `window.parent` after each `System.init` completes during `Game.addSystem`
@@ -972,13 +972,36 @@ const version = "0.0.23";
  */
 const COMBOS_GAME_PLUGIN_INIT_SUCCESS = "combos-game:plugin-init-success";
 /**
- * Notifies the embedding page that a system (plugin) finished async/sync `init`.
+ * iframe → parent: game bootstrap finished (all systems `init`/`awake`, optional
+ * scene load and `start`). Sent once, even when `autoStart` is `false`, so the host
+ * knows assets + scene graph are ready and it may pause / hold before play.
  */
-function postParentPluginInitSuccess(input, targetOrigin = "*") {
+const COMBOS_GAME_READY = "combos-game:ready";
+/**
+ * parent → iframe: start / pause the game loop. Payload: `{ playing: boolean }`.
+ * `true` cold-starts (`Game.start`) on first play, otherwise resumes; `false` pauses.
+ */
+const COMBOS_GAME_SET_PLAYING = "combos-game:set-playing";
+/**
+ * iframe → parent: current run state after a `start` / `pause` / `resume`.
+ */
+const COMBOS_GAME_STATE_CHANGED = "combos-game:state-changed";
+function postToParent(payload, targetOrigin) {
     if (typeof window === "undefined")
         return;
     if (!window.parent || window.parent === window)
         return;
+    try {
+        window.parent.postMessage(payload, targetOrigin);
+    }
+    catch {
+        /* ignore cross-origin or detached frame */
+    }
+}
+/**
+ * Notifies the embedding page that a system (plugin) finished async/sync `init`.
+ */
+function postParentPluginInitSuccess(input, targetOrigin = "*") {
     const payload = {
         type: COMBOS_GAME_PLUGIN_INIT_SUCCESS,
         systemName: input.systemName,
@@ -986,12 +1009,109 @@ function postParentPluginInitSuccess(input, targetOrigin = "*") {
         ...(input.packageName ? { packageName: input.packageName } : {}),
         ...(input.packageVersion ? { packageVersion: input.packageVersion } : {}),
     };
+    postToParent(payload, targetOrigin);
+}
+/** Notifies the embedding page that game bootstrap finished. */
+function postParentGameReady(error, targetOrigin = "*") {
+    const payload = {
+        type: COMBOS_GAME_READY,
+        engineVersion: version,
+        ...(error === undefined
+            ? {}
+            : { error: error instanceof Error ? error.message : String(error) }),
+    };
+    postToParent(payload, targetOrigin);
+}
+/** Notifies the embedding page of the current play/pause state. */
+function postParentGameState(state, targetOrigin = "*") {
+    const payload = {
+        type: COMBOS_GAME_STATE_CHANGED,
+        playing: state.playing,
+        started: state.started,
+    };
+    postToParent(payload, targetOrigin);
+}
+/**
+ * Reads a `combos-game:set-playing` command from an inbound `postMessage` payload.
+ * Returns the requested `playing` value, or `null` when the message is unrelated / malformed.
+ */
+function parseSetPlayingMessage(data) {
+    if (!data || typeof data !== "object")
+        return null;
+    const d = data;
+    if (d.type !== COMBOS_GAME_SET_PLAYING)
+        return null;
+    if (typeof d.playing !== "boolean")
+        return null;
+    return d.playing;
+}
+
+/** Default inbound postMessage host suffixes (host + all subdomains). */
+const DEFAULT_ALLOWED_MESSAGE_HOST_SUFFIXES = [
+    "knoffice.tech",
+    "converge.ai",
+];
+/**
+ * Returns whether `origin` is allowed by `allowed`.
+ *
+ * Each entry in `allowed` is either:
+ * - a **host suffix** (e.g. `knoffice.tech`) — matches that host and `*.knoffice.tech`;
+ * - a **full origin** (e.g. `https://creator.knoffice.tech`) — exact match;
+ * - `'*'` — accept any origin (escape hatch).
+ */
+function isAllowedMessageOrigin(origin, allowed) {
+    if (allowed.includes("*")) {
+        return true;
+    }
+    if (allowed.length === 0) {
+        return false;
+    }
+    let parsed;
     try {
-        window.parent.postMessage(payload, targetOrigin);
+        parsed = new URL(origin);
     }
     catch {
-        /* ignore cross-origin or detached frame */
+        return false;
+    }
+    const originLower = origin.toLowerCase();
+    const hostLower = parsed.hostname.toLowerCase();
+    for (const entry of allowed) {
+        const trimmed = entry.trim();
+        if (!trimmed) {
+            continue;
+        }
+        if (trimmed.includes("://")) {
+            if (originLower === trimmed.toLowerCase()) {
+                return true;
+            }
+            continue;
+        }
+        const suffix = trimmed.toLowerCase().replace(/^\./, "");
+        if (hostLower === suffix || hostLower.endsWith(`.${suffix}`)) {
+            return true;
+        }
+    }
+    return false;
+}
+/** Defaults plus any extra entries (deduped). `['*']` alone accepts any origin. */
+function mergeAllowedMessageOrigins(extra) {
+    if (!extra?.length) {
+        return [...DEFAULT_ALLOWED_MESSAGE_HOST_SUFFIXES];
+    }
+    if (extra.includes("*")) {
+        return ["*"];
+    }
+    const seen = new Set();
+    const result = [];
+    for (const entry of [...DEFAULT_ALLOWED_MESSAGE_HOST_SUFFIXES, ...extra]) {
+        const trimmed = entry.trim();
+        if (!trimmed || seen.has(trimmed)) {
+            continue;
+        }
+        seen.add(trimmed);
+        result.push(trimmed);
     }
+    return result;
 }
 
 function systemClassName(ctor) {
@@ -1097,7 +1217,7 @@ const gameObjectPause = (gameObjects) => {
     }
 };
 class Game extends EventEmitter__default.default {
-    constructor({ systems, frameRate = 60, autoStart = true, needScene = true, onSystemsBootstrapComplete, pluginInitNotifyTargetOrigin = "*", } = {}) {
+    constructor({ systems, frameRate = 60, autoStart = true, needScene = true, onSystemsBootstrapComplete, pluginInitNotifyTargetOrigin = "*", allowedMessageOrigins, } = {}) {
         super();
         /**
          * State of game
@@ -1109,20 +1229,61 @@ class Game extends EventEmitter__default.default {
         /** Systems alled to this game */
         this.systems = [];
         /**
-         * Passed to `postMessage` when reporting `COMBOS_GAME_PLUGIN_INIT_SUCCESS` to `window.parent`.
+         * Passed to `postMessage` when reporting lifecycle events to `window.parent`
+         * (`plugin-init-success`, `ready`, `state-changed`).
          */
         this.pluginInitNotifyTargetOrigin = "*";
+        /** Inbound `postMessage` origins allowed to send host commands. */
+        this.allowedMessageOrigins = mergeAllowedMessageOrigins();
+        /** Bound inbound `message` handler; retained so it can be removed on `destroy`. */
+        this.onHostMessage = (e) => {
+            if (!isAllowedMessageOrigin(e.origin, this.allowedMessageOrigins))
+                return;
+            const playing = parseSetPlayingMessage(e.data);
+            if (playing === null)
+                return;
+            this.setPlaying(playing);
+        };
         this.pluginInitNotifyTargetOrigin = pluginInitNotifyTargetOrigin;
+        this.allowedMessageOrigins = mergeAllowedMessageOrigins(allowedMessageOrigins);
         this.ticker = new Ticker({ autoStart: false, frameRate });
         this.initTicker();
+        if (typeof window !== "undefined") {
+            window.addEventListener("message", this.onHostMessage);
+        }
         if (systems && systems.length) {
             const systemsToAdd = [...systems];
             void this.bootstrapSystemsAndMaybeStart(systemsToAdd, needScene, autoStart, onSystemsBootstrapComplete);
         }
         else {
             onSystemsBootstrapComplete?.(this);
+            this.notifyReady();
         }
     }
+    /**
+     * Host command bridge: `true` cold-starts on first play (`start`), otherwise
+     * `resume`s; `false` pauses. Mirrors what a parent frame drives via
+     * `postMessage({ type: 'combos-game:set-playing', playing })`.
+     */
+    setPlaying(playing) {
+        if (playing) {
+            if (this.started) {
+                this.resume();
+            }
+            else {
+                this.start();
+            }
+        }
+        else {
+            this.pause();
+        }
+    }
+    notifyReady(error) {
+        postParentGameReady(error, this.pluginInitNotifyTargetOrigin);
+    }
+    notifyStateChanged() {
+        postParentGameState({ playing: this.playing, started: this.started }, this.pluginInitNotifyTargetOrigin);
+    }
     /** When `systems` is passed in the constructor, run async `init` for each before `loadScene` / `start`. */
     async bootstrapSystemsAndMaybeStart(systemsToAdd, needScene, autoStart, onComplete) {
         let error;
@@ -1143,6 +1304,7 @@ class Game extends EventEmitter__default.default {
         }
         finally {
             onComplete?.(this, error);
+            this.notifyReady(error);
         }
     }
     /**
@@ -1245,6 +1407,7 @@ class Game extends EventEmitter__default.default {
         this.playing = false;
         this.ticker.pause();
         this.triggerPause();
+        this.notifyStateChanged();
     }
     /** Start game */
     start() {
@@ -1253,6 +1416,7 @@ class Game extends EventEmitter__default.default {
         this.playing = true;
         this.started = true;
         this.ticker.start();
+        this.notifyStateChanged();
     }
     /** Resume game */
     resume() {
@@ -1261,6 +1425,7 @@ class Game extends EventEmitter__default.default {
         this.playing = true;
         this.ticker.start();
         this.triggerResume();
+        this.notifyStateChanged();
     }
     /**
      * add main render method to ticker
@@ -1327,6 +1492,9 @@ class Game extends EventEmitter__default.default {
     }
     /** Destroy game instance */
     destroy() {
+        if (typeof window !== "undefined") {
+            window.removeEventListener("message", this.onHostMessage);
+        }
         this.removeAllListeners();
         this.pause();
         this.scene.destroy();
@@ -1728,7 +1896,11 @@ const decorators = {
 console.log(`@combos-fun/engine version: ${version}`);
 
 exports.COMBOS_GAME_PLUGIN_INIT_SUCCESS = COMBOS_GAME_PLUGIN_INIT_SUCCESS;
+exports.COMBOS_GAME_READY = COMBOS_GAME_READY;
+exports.COMBOS_GAME_SET_PLAYING = COMBOS_GAME_SET_PLAYING;
+exports.COMBOS_GAME_STATE_CHANGED = COMBOS_GAME_STATE_CHANGED;
 exports.Component = Component;
+exports.DEFAULT_ALLOWED_MESSAGE_HOST_SUFFIXES = DEFAULT_ALLOWED_MESSAGE_HOST_SUFFIXES;
 exports.Game = Game;
 exports.GameObject = GameObject;
 exports.IDEProp = IDEProp;
@@ -1738,6 +1910,11 @@ exports.System = System;
 exports.Transform = Transform;
 exports.componentObserver = componentObserver;
 exports.decorators = decorators;
+exports.isAllowedMessageOrigin = isAllowedMessageOrigin;
+exports.mergeAllowedMessageOrigins = mergeAllowedMessageOrigins;
+exports.parseSetPlayingMessage = parseSetPlayingMessage;
+exports.postParentGameReady = postParentGameReady;
+exports.postParentGameState = postParentGameState;
 exports.postParentPluginInitSuccess = postParentPluginInitSuccess;
 exports.resource = resource;
 exports.resourceLoader = resourceLoader;