@fzgame/kit 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Fanzeal
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,183 @@
-# Temporary Holding Version
+# @fzgame/kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The client kit a FZ GameHub game loads: it resolves which game instance is being played, creates or
+resumes a play session, keeps a local snapshot of the session, and posts lifecycle events back to the
+server. The editor and the sandbox talk to a game through the same message protocol.
+
+## Install
+
+```sh
+npm install @fzgame/kit
+```
+
+The kit is ESM-first and also ships a CommonJS build. In the GameHub hosts a game loads the bundle as
+a dev-time URL or as `game/vendor/kit.js` from a published zip, so a game does not bundle the kit
+itself; the CLI's `fzgame build` vendors it. Items below assume a bundler when you import it directly.
+
+## Quick start
+
+```js
+import { createKit } from '@fzgame/kit'
+
+// Reads apiUrl, gameInstanceId, and playerToken from the query string.
+const kit = createKit()
+
+await kit.load() // the published game instance
+await kit.connect() // a play session
+await kit.emit('ready')
+
+await kit.emit('start')
+kit.setState({ clicks: 1 })
+await kit.emit('score', { score: 1 })
+await kit.emit('finish', { score: 1, result: { clicks: 1 } })
+
+kit.snapshot // { status, score, result, state }
+kit.config() // validated form values for this instance
+```
+
+Pass the values explicitly instead of reading the query string:
+
+```js
+const kit = createKit({ apiUrl, gameInstanceId, playerToken })
+```
+
+`createKit()` reads anything you leave out from the query string (`apiUrl`, `gameInstanceId`,
+`playerToken`). A value that is still missing throws at construction.
+
+## Lifecycle
+
+```
+CREATED → READY → PLAYING ⇄ PAUSED → FINISHED
+                     ↘ ABORTED
+```
+
+`emit(type, payload?)` sends the event and adopts the session the server returns, so `kit.snapshot`
+tracks the server rather than your local guess. The events the server acts on are `ready`, `start`,
+`pause`, `finish`, `abort`, `score`, and `snapshot` (also exported as `LIFECYCLE_EVENTS`). Any other
+string is stored as the session's last event and leaves the status alone.
+
+| Event | Effect |
+| --- | --- |
+| `ready` | Status `READY`. |
+| `start` | Status `PLAYING`. |
+| `pause` | Status `PAUSED`. |
+| `finish` | Status `FINISHED`; `payload.score` and `payload.result` are stored. |
+| `abort` | Status `ABORTED`. |
+| `score` | Stores `payload.score`. |
+| `snapshot` | Stores `payload.state` as the session snapshot. |
+
+`emit()` and `setState()` require a session and throw if you call them before `connect()`.
+
+## Snapshot
+
+`kit.snapshot` is `{ status, score, result, state }`, refreshed after every call that returns a
+session. `setState(state)` also stores the value in the session's metadata, so a resumed session
+restores where the player stopped.
+
+## Config
+
+`kit.config()` merges, in increasing priority: defaults from the game instance's config schema, the
+instance overrides an operator set, and the config passed to `createKit` (or read from the query
+string). `readFormSchema(schema)` exposes the schema itself when you render the settings form.
+
+## Preview
+
+`?preview=true` (also `1` / `yes`) skips every server call. `load`, `connect`, `emit`, and `setState`
+stay in memory so the game is free to play, and credentials become optional. The sandbox and editor
+put unsaved settings in `?gameSetting={"goal":10}`; it wins over the older `?config=`, so Play reloads
+with your draft before you submit.
+
+```
+/game/index.html?preview=true&gameSetting=%7B%22goal%22%3A20%7D&kit=/@fzgame/kit.js
+```
+
+## Editor protocol
+
+A game running inside the editor can send its draft config out and receive the editor's init message.
+Both directions post to `window.parent`; the editor and sandbox listen on the `fzgame-editor` and
+`fzgame-host` sources exported as `EDITOR_SOURCE` and `HOST_SOURCE`.
+
+```js
+import { postEditorSave, onHostInit } from '@fzgame/kit'
+
+const stop = onHostInit(({ config, configSchema, gameInstanceId }) => { /* apply */ })
+postEditorSave({ goal: 20 })
+```
+
+`onHostInit` returns an unsubscribe function. Messages are posted with a `'*'` target origin, because
+a game running in a cross-origin frame cannot read the parent's origin.
+
+## Errors
+
+| Error | When |
+| --- | --- |
+| `Error` | A required option is missing, or `emit` / `setState` runs before `connect()`. |
+| `KitApiError` | A request answered with a non-OK status. Carries `status`, `statusText`, `method`, `url`, the parsed `body`, and `code` when the body has one. |
+| `KitTimeoutError` | A request outlived `timeoutMs`. Carries `timeoutMs`, `method`, and `url`. |
+
+```js
+import { KitApiError } from '@fzgame/kit'
+
+try {
+  await kit.connect()
+} catch (error) {
+  if (error instanceof KitApiError && error.status === 404) {
+    // the instance is gone
+  }
+}
+```
+
+## Timeouts
+
+Every request is aborted after `timeoutMs`, 30 seconds by default, so a game's loading screen never
+hangs on a dead socket. Set `timeoutMs: 0` to wait without a deadline.
+
+```js
+const kit = createKit({ timeoutMs: 5_000 })
+```
+
+The kit uses `AbortController` rather than `AbortSignal.timeout`, so it runs in older browsers.
+
+## Debug channel
+
+When the game runs in a frame, the kit posts its progress to the parent as
+`{ source: 'fzgame-kit', type: 'debug', event, payload, at }`. The sandbox shows these in its log
+panel. Credential-looking keys (`token`, `secret`, `password`, `authorization`, `apiKey`) and
+reference cycles are replaced before posting.
+
+## API
+
+| Export | Purpose |
+| --- | --- |
+| `createKit(options?)` | Build a kit from options plus the query string. |
+| `FzGameKit` | The class, if you would rather construct it directly. |
+| `DEFAULT_TIMEOUT_MS` | 30000. |
+| `KIT_SOURCE`, `EDITOR_SOURCE`, `HOST_SOURCE` | Message `source` values. |
+| `postEditorSave`, `onHostInit` | Outgoing save and incoming init for the editor. |
+| `readQueryConfig`, `readFormSchema`, `isPreviewFlag` | Query and schema helpers. |
+| `LIFECYCLE_EVENTS`, `PLAY_SESSION_STATUSES`, `emptySnapshot` | Lifecycle constants. |
+| `KitApiError`, `KitTimeoutError` | Typed failures. |
+| `KitOptions`, `EmitType`, `Snapshot`, `LifecycleEvent`, `GameInstancePayload`, `PlaySessionPayload` | Types. |
+
+## What it does not do
+
+- It renders nothing. No DOM, no canvas, no styles: your game draws and the kit keeps score.
+- It stores nothing locally. No `localStorage`, no cookies. State reaches the server through
+  `setState` and `emit`, so a player who reloads outside a resumed session starts over.
+- It does not retry. A request that fails or times out rejects; nothing is queued, so a `finish`
+  event during a network blip is lost unless the game sends it again.
+- It does not validate the config it returns. `kit.config()` merges default values, instance
+  overrides, and your own in that order and hands the result over as-is.
+
+## Development
+
+```sh
+pnpm build        # tsup, ESM + CJS + declarations
+pnpm check-types
+pnpm test:run
+pnpm smoke        # pack the tarball and consume it from a CJS and an ESM consumer
+```
+
+## License
+
+ISC

package/dist/index.cjs

@@ -0,0 +1,435 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  DEFAULT_TIMEOUT_MS: () => DEFAULT_TIMEOUT_MS,
+  EDITOR_SOURCE: () => EDITOR_SOURCE,
+  FzGameKit: () => FzGameKit,
+  HOST_SOURCE: () => HOST_SOURCE,
+  KIT_SOURCE: () => KIT_SOURCE,
+  KitApiError: () => KitApiError,
+  KitTimeoutError: () => KitTimeoutError,
+  LIFECYCLE_EVENTS: () => LIFECYCLE_EVENTS,
+  PLAY_SESSION_STATUSES: () => PLAY_SESSION_STATUSES,
+  createKit: () => createKit,
+  emptySnapshot: () => emptySnapshot,
+  isPreviewFlag: () => isPreviewFlag,
+  onHostInit: () => onHostInit,
+  postEditorSave: () => postEditorSave,
+  readFormSchema: () => readFormSchema,
+  readQueryConfig: () => readQueryConfig
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/lifecycle.ts
+var PLAY_SESSION_STATUSES = [
+  "CREATED",
+  "READY",
+  "PLAYING",
+  "PAUSED",
+  "FINISHED",
+  "ABORTED",
+  "EXPIRED"
+];
+var LIFECYCLE_EVENTS = [
+  "ready",
+  "start",
+  "pause",
+  "finish",
+  "abort",
+  "score",
+  "snapshot"
+];
+function emptySnapshot() {
+  return { status: "CREATED", score: null, result: null, state: null };
+}
+
+// src/kit.ts
+var DEFAULT_TIMEOUT_MS = 3e4;
+var KIT_SOURCE = "fzgame-kit";
+var SECRET_KEY = /(token|secret|password|authorization|api[-_]?key)/i;
+function redact(value, seen = /* @__PURE__ */ new WeakSet(), depth = 0) {
+  if (depth > 8 || value === null || typeof value !== "object") return value;
+  if (seen.has(value)) return "[circular]";
+  seen.add(value);
+  const out = Array.isArray(value) ? value.map((item) => redact(item, seen, depth + 1)) : Object.fromEntries(
+    Object.entries(value).map(([key, item]) => [
+      key,
+      SECRET_KEY.test(key) ? "[redacted]" : redact(item, seen, depth + 1)
+    ])
+  );
+  seen.delete(value);
+  return out;
+}
+var KitApiError = class extends Error {
+  constructor(response, body, method, url) {
+    super(`${method} ${url} failed with ${response.status} ${response.statusText}`);
+    __publicField(this, "status");
+    __publicField(this, "statusText");
+    __publicField(this, "method");
+    __publicField(this, "url");
+    /** Parsed response body, or the raw text when it is not JSON. */
+    __publicField(this, "body");
+    /** `body.code` when the server sends one. */
+    __publicField(this, "code");
+    this.name = "KitApiError";
+    this.status = response.status;
+    this.statusText = response.statusText;
+    this.method = method;
+    this.url = url;
+    this.body = body;
+    const code = body && typeof body === "object" ? body.code : void 0;
+    if (typeof code === "string") this.code = code;
+  }
+};
+var KitTimeoutError = class extends Error {
+  constructor(timeoutMs, method, url) {
+    super(`${method} ${url} did not answer within ${timeoutMs}ms`);
+    __publicField(this, "timeoutMs");
+    __publicField(this, "method");
+    __publicField(this, "url");
+    this.name = "KitTimeoutError";
+    this.timeoutMs = timeoutMs;
+    this.method = method;
+    this.url = url;
+  }
+};
+var FzGameKit = class {
+  constructor(options) {
+    __publicField(this, "options");
+    __publicField(this, "instance", null);
+    __publicField(this, "session", null);
+    __publicField(this, "snapshot", emptySnapshot());
+    __publicField(this, "injectedConfig");
+    __publicField(this, "connecting", null);
+    const preview = Boolean(options.preview);
+    this.options = {
+      apiUrl: (options.apiUrl || "").replace(/\/$/, ""),
+      gameInstanceId: options.gameInstanceId || (preview ? "preview" : ""),
+      playerToken: options.playerToken || (preview ? "preview" : ""),
+      timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      config: options.config,
+      preview
+    };
+    if (!preview && (!this.options.apiUrl || !this.options.gameInstanceId || !this.options.playerToken)) {
+      throw new Error("FzGameKit requires apiUrl, gameInstanceId, and playerToken");
+    }
+    this.injectedConfig = options.config ?? readQueryConfig() ?? {};
+  }
+  get preview() {
+    return this.options.preview;
+  }
+  async load() {
+    try {
+      if (this.options.preview) {
+        this.instance = {
+          id: this.options.gameInstanceId,
+          name: "preview",
+          overrides: this.injectedConfig
+        };
+        this.debug("load", { instance: this.instance, preview: true });
+        return this.instance;
+      }
+      this.instance = await this.request(
+        `/pub/game-instances/${this.options.gameInstanceId}`
+      );
+      this.debug("load", { instance: this.instance });
+      return this.instance;
+    } catch (error) {
+      this.debug("load", { error: errorMessage(error) });
+      throw error;
+    }
+  }
+  async connect() {
+    this.connecting ?? (this.connecting = this.startSession().finally(() => {
+      this.connecting = null;
+    }));
+    return this.connecting;
+  }
+  async startSession() {
+    try {
+      if (this.options.preview) {
+        this.session = previewSession();
+        this.hydrate();
+        this.debug("connect", { session: this.session, preview: true });
+        return this.session;
+      }
+      this.session = await this.request(
+        "/games/runtime/sessions",
+        {
+          method: "POST",
+          body: JSON.stringify({
+            gameInstanceId: this.options.gameInstanceId,
+            playerToken: this.options.playerToken
+          })
+        }
+      );
+      this.hydrate();
+      this.debug("connect", { session: this.session });
+      return this.session;
+    } catch (error) {
+      this.debug("connect", { error: errorMessage(error) });
+      throw error;
+    }
+  }
+  async emit(type, payload) {
+    try {
+      if (this.options.preview) {
+        this.session = this.session ?? previewSession();
+        applyLocalEmit(this.session, type, payload);
+        this.hydrate();
+        this.debug("emit", { type, payload: payload ?? null, session: this.session, preview: true });
+        return this.session;
+      }
+      const token = this.requireToken();
+      this.session = await this.request(
+        `/games/runtime/sessions/${token}/emit`,
+        {
+          method: "POST",
+          body: JSON.stringify({ type, payload })
+        }
+      );
+      this.hydrate();
+      this.debug("emit", { type, payload: payload ?? null, session: this.session });
+      return this.session;
+    } catch (error) {
+      this.debug("emit", { type, payload: payload ?? null, error: errorMessage(error) });
+      throw error;
+    }
+  }
+  async setState(state) {
+    try {
+      this.snapshot = { ...this.snapshot, state };
+      if (this.options.preview) {
+        this.session = this.session ?? previewSession();
+        this.session.metadata = { snapshot: state };
+        this.hydrate();
+        this.debug("snapshot", { state, session: this.session, preview: true });
+        return this.snapshot;
+      }
+      const token = this.requireToken();
+      this.session = await this.request(
+        `/games/runtime/sessions/${token}/snapshot`,
+        {
+          method: "PUT",
+          body: JSON.stringify({ state })
+        }
+      );
+      this.hydrate();
+      this.debug("snapshot", { state, session: this.session });
+      return this.snapshot;
+    } catch (error) {
+      this.debug("snapshot", { state, error: errorMessage(error) });
+      throw error;
+    }
+  }
+  config() {
+    const schema = readFormSchema(this.instance?.game?.configSchema);
+    const defaults = readDefaults(schema);
+    return { ...defaults, ...this.instance?.overrides ?? {}, ...this.injectedConfig };
+  }
+  hydrate() {
+    if (!this.session) return;
+    const meta = this.session.metadata;
+    this.snapshot = {
+      status: this.session.status,
+      score: this.session.score ?? null,
+      result: this.session.result ?? null,
+      state: meta && typeof meta === "object" ? meta.snapshot ?? this.snapshot.state : this.snapshot.state
+    };
+  }
+  requireToken() {
+    if (!this.session?.token) {
+      throw new Error("Call connect() before emit or setState");
+    }
+    return this.session.token;
+  }
+  debug(event, payload) {
+    const w = typeof globalThis !== "undefined" ? globalThis.window : void 0;
+    if (!w?.parent?.postMessage) return;
+    const message = {
+      source: KIT_SOURCE,
+      type: "debug",
+      event,
+      payload: redact(payload),
+      at: Date.now()
+    };
+    try {
+      w.parent.postMessage(message, "*");
+    } catch {
+    }
+  }
+  async request(path, init = {}) {
+    const url = `${this.options.apiUrl}${path}`;
+    const method = init.method ?? "GET";
+    const headers = new Headers(init.headers);
+    if (init.body && !headers.has("content-type")) {
+      headers.set("content-type", "application/json");
+    }
+    const res = await this.fetchWithTimeout(url, { ...init, headers }, method);
+    if (!res.ok) {
+      throw new KitApiError(res, await readBody(res), method, url);
+    }
+    return await res.json();
+  }
+  async fetchWithTimeout(url, init, method) {
+    const { timeoutMs } = this.options;
+    if (!timeoutMs || timeoutMs <= 0) return fetch(url, init);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+      return await fetch(url, { ...init, signal: controller.signal });
+    } catch (error) {
+      if (controller.signal.aborted) throw new KitTimeoutError(timeoutMs, method, url);
+      throw error;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+};
+async function readBody(res) {
+  const text = await res.text();
+  if (!text) return void 0;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+function createKit(options = {}) {
+  const params = typeof location !== "undefined" ? new URLSearchParams(location.search) : new URLSearchParams();
+  const preview = options.preview ?? isPreviewFlag(params.get("preview"));
+  const apiUrl = options.apiUrl || params.get("apiUrl") || "";
+  const gameInstanceId = options.gameInstanceId || params.get("gameInstanceId") || "";
+  const playerToken = options.playerToken || params.get("playerToken") || "";
+  const config = options.config ?? readQueryConfig();
+  return new FzGameKit({
+    apiUrl,
+    gameInstanceId,
+    playerToken,
+    config,
+    preview,
+    timeoutMs: options.timeoutMs
+  });
+}
+function readQueryConfig() {
+  if (typeof location === "undefined") return void 0;
+  const params = new URLSearchParams(location.search);
+  return parseConfigParam(params.get("gameSetting")) ?? parseConfigParam(params.get("config"));
+}
+function isPreviewFlag(raw) {
+  if (!raw) return false;
+  const value = raw.trim().toLowerCase();
+  return value === "true" || value === "1" || value === "yes";
+}
+function parseConfigParam(raw) {
+  if (!raw) return void 0;
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+  } catch {
+  }
+  return void 0;
+}
+function previewSession() {
+  return {
+    id: "preview",
+    token: "preview",
+    status: "CREATED",
+    score: null,
+    result: null,
+    metadata: { snapshot: {} }
+  };
+}
+function applyLocalEmit(session, type, payload) {
+  if (type === "ready") session.status = "READY";
+  if (type === "start") session.status = "PLAYING";
+  if (type === "pause") session.status = "PAUSED";
+  if (type === "finish") {
+    session.status = "FINISHED";
+    if (typeof payload?.score === "number") session.score = payload.score;
+    if (payload && "result" in payload) session.result = payload.result;
+  }
+  if (type === "abort") session.status = "ABORTED";
+  if (type === "score" && typeof payload?.score === "number") session.score = payload.score;
+  if (type === "snapshot") {
+    session.metadata = { snapshot: payload?.state ?? payload ?? {} };
+  }
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function readFormSchema(schema) {
+  if (!schema) return {};
+  const form = schema.formSchema;
+  if (form && typeof form === "object" && !Array.isArray(form)) {
+    return form;
+  }
+  return schema;
+}
+function readDefaults(schema) {
+  const properties = schema.properties;
+  if (!properties || typeof properties !== "object") return {};
+  const out = {};
+  for (const [key, value] of Object.entries(properties)) {
+    if (value && "default" in value) out[key] = value.default;
+  }
+  return out;
+}
+var EDITOR_SOURCE = "fzgame-editor";
+var HOST_SOURCE = "fzgame-host";
+function postEditorSave(config, target = window.parent) {
+  const message = { source: EDITOR_SOURCE, type: "save", config };
+  target.postMessage(message, "*");
+}
+function onHostInit(handler) {
+  const listener = (event) => {
+    const data = event.data;
+    if (!data || data.source !== HOST_SOURCE || data.type !== "init") return;
+    handler(data);
+  };
+  window.addEventListener("message", listener);
+  return () => window.removeEventListener("message", listener);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_TIMEOUT_MS,
+  EDITOR_SOURCE,
+  FzGameKit,
+  HOST_SOURCE,
+  KIT_SOURCE,
+  KitApiError,
+  KitTimeoutError,
+  LIFECYCLE_EVENTS,
+  PLAY_SESSION_STATUSES,
+  createKit,
+  emptySnapshot,
+  isPreviewFlag,
+  onHostInit,
+  postEditorSave,
+  readFormSchema,
+  readQueryConfig
+});
+//# sourceMappingURL=index.cjs.map