@ikirmikir/game-sdk 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maruf (Ikirmikir)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,27 @@
-# Temporary Holding Version
+# @ikirmikir/game-sdk
 
-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.
+Optional SDK for browser games on [Ikirmikir](https://ikirmikir.com): real loading progress, gameplay start and stop, pause and resume, the player's sound switch, player context (language, device, touch) and sharing. Any engine that runs in a browser. Outside Ikirmikir it runs in local mode, so one build works everywhere, and no call ever throws.
+
+```bash
+npm install @ikirmikir/game-sdk
+```
+
+```js
+import { Ikirmikir } from "@ikirmikir/game-sdk";
+
+const ik = await Ikirmikir.init({ gameId: "your-game" });
+ik.game.loadingProgress(50);
+ik.game.loadingDone();
+ik.on("pause", () => game.pause());
+ik.on("mute", muted => { audio.muted = muted; });
+```
+
+Without a bundler, use `dist/ikirmikir.js` (gives `window.Ikirmikir`), from this package or the CDN:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@ikirmikir/game-sdk@1.0.0/dist/ikirmikir.js"></script>
+```
+
+Quick start, API reference and a test tool: https://ikirmikir.com/developers/
+
+MIT license.

package/dist/ikirmikir.js

@@ -0,0 +1,2 @@
+/*! @ikirmikir/game-sdk 1.0.0 | MIT | https://ikirmikir.com/developers/ */
+"use strict";(()=>{var I=["loading","gameplay","pause","mute","context","share"],h=e=>typeof e=="object"&&e!==null&&!Array.isArray(e),P=(e,t)=>typeof e=="string"&&e.length>0&&e.length<=t,C=(e,t,i)=>Number.isInteger(e)&&e>=t&&e<=i,c=e=>typeof e=="boolean";function x(e){if(!h(e)||e.ik!==1)return null;switch(e.type){case"welcome":{let t=e.context;return!Array.isArray(e.features)||!c(e.muted)||!h(t)||!P(t.language,35)||t.device!=="mobile"&&t.device!=="desktop"||!c(t.touch)?null:{ik:1,type:"welcome",features:I.filter(u=>e.features.includes(u)),context:{language:t.language,device:t.device,touch:t.touch},muted:e.muted}}case"pause":return{ik:1,type:"pause"};case"resume":return{ik:1,type:"resume"};case"mute":return c(e.muted)?{ik:1,type:"mute",muted:e.muted}:null;case"shared":return C(e.id,0,1e9)&&c(e.shared)?{ik:1,type:"shared",id:e.id,shared:e.shared}:null;default:return null}}function b(e){return e==="https://ikirmikir.com"||e==="http://localhost:3000"||e==="http://127.0.0.1:3000"||/^https:\/\/([0-9a-f]{8}\.)?ikirmikir\.pages\.dev$/.test(e)}var M="1.0.0",R=1500,w;function T(e){return w??(w=F(e))}async function F({gameId:e}){let t={pause:new Set,resume:new Set,mute:new Set},i=(r,...a)=>t[r].forEach(o=>{try{o(...a)}catch(n){console.error(n)}}),u="local",f=A(),p=!1,g=[],s,m=new Map,S=1,k=-1,l=!1,y=!1,d=r=>{if(s)try{parent.postMessage({ik:1,...r},s)}catch{}};if(typeof window<"u"&&window.parent!==window){let r=new Promise(a=>{addEventListener("message",o=>{if(o.source!==window.parent||!b(o.origin)||s&&o.origin!==s)return;let n=x(o.data);if(n){if(n.type==="welcome")return s?void 0:(s=o.origin,u="ikirmikir",f=n.context,p=n.muted,g=n.features,a(!0));s&&(n.type==="pause"||n.type==="resume"?i(n.type):n.type==="mute"?n.muted!==p&&(p=n.muted,i("mute",p)):n.type==="shared"&&(m.get(n.id)?.(n.shared),m.delete(n.id)))}}),setTimeout(()=>a(!1),R)});try{parent.postMessage({ik:1,type:"hello",gameId:String(e).slice(0,64),sdk:M},"*")}catch{}await r}return u==="local"&&(g=["gameplay","loading","pause","context",...E()?["share"]:[]],typeof document<"u"&&document.addEventListener("visibilitychange",()=>i(document.hidden?"pause":"resume"))),{get env(){return u},get context(){return{...f}},get muted(){return p},has:r=>g.includes(r),game:{loadingProgress(r){let a=Math.max(0,Math.min(100,Math.round(Number(r)||0)));y||a===k||(k=a,d({type:"loading",progress:a}))},loadingDone(){y||(y=!0,d({type:"ready"}))},gameplayStart(){l||(l=!0,d({type:"gameplay",playing:l}))},gameplayStop(){l&&(l=!1,d({type:"gameplay",playing:l}))}},on(r,a){let o=t[r];return!o||typeof a!="function"?()=>{}:(o.add(a),()=>{o.delete(a)})},async share(){if(u==="local"){if(!E())return{shared:!1};try{return await navigator.share({url:location.href}),{shared:!0}}catch{return{shared:!1}}}let r=S++;return new Promise(a=>{m.set(r,o=>a({shared:o})),setTimeout(()=>{m.delete(r)&&a({shared:!1})},6e4),d({type:"share",id:r})})}}}function A(){let e=typeof navigator<"u"?navigator:void 0,t=!!e&&e.maxTouchPoints>0,i=typeof matchMedia<"u"&&matchMedia("(pointer: coarse)").matches;return{language:(e?.language||"en").split("-")[0],device:i?"mobile":"desktop",touch:t}}var E=()=>typeof navigator<"u"&&typeof navigator.share=="function",O={init:T,VERSION:M};globalThis.Ikirmikir=O;})();

package/dist/index.d.ts

@@ -0,0 +1,45 @@
+import { type Context, type Feature } from "./protocol";
+export type { Context, Feature } from "./protocol";
+export declare const VERSION = "1.0.0";
+type Events = {
+    pause: () => void;
+    resume: () => void;
+    mute: (muted: boolean) => void;
+};
+export interface Sdk {
+    /** "ikirmikir" inside the Ikirmikir player, "local" anywhere else. */
+    readonly env: "ikirmikir" | "local";
+    /** Language, device and input of the player. */
+    readonly context: Context;
+    /** True when Ikirmikir's sound switch is off: keep the game silent. */
+    readonly muted: boolean;
+    /** Whether a feature works here. */
+    has(feature: Feature): boolean;
+    game: {
+        /** Loading progress, 0 to 100. Ikirmikir shows it as its loading bar. */
+        loadingProgress(percent: number): void;
+        /** The game is ready to play. Ikirmikir hides its loader. */
+        loadingDone(): void;
+        /** Someone is actually playing (after menus). */
+        gameplayStart(): void;
+        /** Play stopped: menu, game over, between rounds. */
+        gameplayStop(): void;
+    };
+    /** Listen for "pause", "resume" or "mute". Returns a function that stops listening. */
+    on<E extends keyof Events>(event: E, listener: Events[E]): () => void;
+    /** Ask Ikirmikir to share the game's link. Resolves { shared: false } when nothing was shared. */
+    share(): Promise<{
+        shared: boolean;
+    }>;
+}
+export interface InitOptions {
+    /** The game's id on Ikirmikir, for example "runbro". */
+    gameId: string;
+}
+/** Start the SDK. Call once, early in loading. Never rejects; calling again returns the same instance. */
+declare function init(options: InitOptions): Promise<Sdk>;
+export declare const Ikirmikir: {
+    init: typeof init;
+    VERSION: string;
+};
+export default Ikirmikir;

package/dist/index.js

@@ -0,0 +1,182 @@
+/*! @ikirmikir/game-sdk 1.0.0 | MIT | https://ikirmikir.com/developers/ */
+
+// src/protocol.ts
+var PROTOCOL = 1;
+var FEATURES = ["loading", "gameplay", "pause", "mute", "context", "share"];
+var obj = (d) => typeof d === "object" && d !== null && !Array.isArray(d);
+var str = (v, max) => typeof v === "string" && v.length > 0 && v.length <= max;
+var int = (v, min, max) => Number.isInteger(v) && v >= min && v <= max;
+var bool = (v) => typeof v === "boolean";
+function readPageMessage(d) {
+  if (!obj(d) || d.ik !== PROTOCOL) return null;
+  switch (d.type) {
+    case "welcome": {
+      const c = d.context;
+      if (!Array.isArray(d.features) || !bool(d.muted) || !obj(c)) return null;
+      if (!str(c.language, 35) || c.device !== "mobile" && c.device !== "desktop" || !bool(c.touch)) return null;
+      const features = FEATURES.filter((f) => d.features.includes(f));
+      return { ik: 1, type: "welcome", features, context: { language: c.language, device: c.device, touch: c.touch }, muted: d.muted };
+    }
+    case "pause":
+      return { ik: 1, type: "pause" };
+    case "resume":
+      return { ik: 1, type: "resume" };
+    case "mute":
+      return bool(d.muted) ? { ik: 1, type: "mute", muted: d.muted } : null;
+    case "shared":
+      return int(d.id, 0, 1e9) && bool(d.shared) ? { ik: 1, type: "shared", id: d.id, shared: d.shared } : null;
+    default:
+      return null;
+  }
+}
+function isIkirmikirOrigin(origin) {
+  return origin === "https://ikirmikir.com" || origin === "http://localhost:3000" || origin === "http://127.0.0.1:3000" || /^https:\/\/([0-9a-f]{8}\.)?ikirmikir\.pages\.dev$/.test(origin);
+}
+
+// src/index.ts
+var VERSION = "1.0.0";
+var HANDSHAKE_MS = 1500;
+var instance;
+function init(options) {
+  return instance ?? (instance = start(options));
+}
+async function start({ gameId }) {
+  const listeners = { pause: /* @__PURE__ */ new Set(), resume: /* @__PURE__ */ new Set(), mute: /* @__PURE__ */ new Set() };
+  const emit = (e, ...args) => listeners[e].forEach((fn) => {
+    try {
+      fn(...args);
+    } catch (err) {
+      console.error(err);
+    }
+  });
+  let env = "local", context = localContext(), muted = false, features = [];
+  let page;
+  const shares = /* @__PURE__ */ new Map();
+  let nextShare = 1, progress = -1, playing = false, done = false;
+  const send = (m) => {
+    if (page) try {
+      parent.postMessage({ ik: PROTOCOL, ...m }, page);
+    } catch {
+    }
+  };
+  if (typeof window !== "undefined" && window.parent !== window) {
+    const welcome = new Promise((resolve) => {
+      addEventListener("message", (e) => {
+        if (e.source !== window.parent || !isIkirmikirOrigin(e.origin) || page && e.origin !== page) return;
+        const m = readPageMessage(e.data);
+        if (!m) return;
+        if (m.type === "welcome") {
+          if (page) return;
+          page = e.origin;
+          env = "ikirmikir";
+          context = m.context;
+          muted = m.muted;
+          features = m.features;
+          return resolve(true);
+        }
+        if (!page) return;
+        if (m.type === "pause" || m.type === "resume") emit(m.type);
+        else if (m.type === "mute") {
+          if (m.muted !== muted) {
+            muted = m.muted;
+            emit("mute", muted);
+          }
+        } else if (m.type === "shared") {
+          shares.get(m.id)?.(m.shared);
+          shares.delete(m.id);
+        }
+      });
+      setTimeout(() => resolve(false), HANDSHAKE_MS);
+    });
+    try {
+      parent.postMessage({ ik: PROTOCOL, type: "hello", gameId: String(gameId).slice(0, 64), sdk: VERSION }, "*");
+    } catch {
+    }
+    await welcome;
+  }
+  if (env === "local") {
+    features = ["gameplay", "loading", "pause", "context", ...canShare() ? ["share"] : []];
+    if (typeof document !== "undefined")
+      document.addEventListener("visibilitychange", () => emit(document.hidden ? "pause" : "resume"));
+  }
+  return {
+    get env() {
+      return env;
+    },
+    get context() {
+      return { ...context };
+    },
+    get muted() {
+      return muted;
+    },
+    has: (f) => features.includes(f),
+    game: {
+      loadingProgress(percent) {
+        const p = Math.max(0, Math.min(100, Math.round(Number(percent) || 0)));
+        if (done || p === progress) return;
+        progress = p;
+        send({ type: "loading", progress: p });
+      },
+      loadingDone() {
+        if (!done) {
+          done = true;
+          send({ type: "ready" });
+        }
+      },
+      gameplayStart() {
+        if (!playing) {
+          playing = true;
+          send({ type: "gameplay", playing });
+        }
+      },
+      gameplayStop() {
+        if (playing) {
+          playing = false;
+          send({ type: "gameplay", playing });
+        }
+      }
+    },
+    on(event, listener) {
+      const set = listeners[event];
+      if (!set || typeof listener !== "function") return () => {
+      };
+      set.add(listener);
+      return () => {
+        set.delete(listener);
+      };
+    },
+    async share() {
+      if (env === "local") {
+        if (!canShare()) return { shared: false };
+        try {
+          await navigator.share({ url: location.href });
+          return { shared: true };
+        } catch {
+          return { shared: false };
+        }
+      }
+      const id = nextShare++;
+      return new Promise((resolve) => {
+        shares.set(id, (shared) => resolve({ shared }));
+        setTimeout(() => {
+          if (shares.delete(id)) resolve({ shared: false });
+        }, 6e4);
+        send({ type: "share", id });
+      });
+    }
+  };
+}
+function localContext() {
+  const nav = typeof navigator !== "undefined" ? navigator : void 0;
+  const touch = !!nav && nav.maxTouchPoints > 0;
+  const mobile = typeof matchMedia !== "undefined" && matchMedia("(pointer: coarse)").matches;
+  return { language: (nav?.language || "en").split("-")[0], device: mobile ? "mobile" : "desktop", touch };
+}
+var canShare = () => typeof navigator !== "undefined" && typeof navigator.share === "function";
+var Ikirmikir = { init, VERSION };
+var index_default = Ikirmikir;
+export {
+  Ikirmikir,
+  VERSION,
+  index_default as default
+};

package/dist/protocol.d.ts

@@ -0,0 +1,56 @@
+export declare const PROTOCOL = 1;
+export type Feature = "loading" | "gameplay" | "pause" | "mute" | "context" | "share";
+export interface Context {
+    language: string;
+    device: "mobile" | "desktop";
+    touch: boolean;
+}
+export type GameMessage = {
+    ik: 1;
+    type: "hello";
+    gameId: string;
+    sdk: string;
+} | {
+    ik: 1;
+    type: "loading";
+    progress: number;
+} | {
+    ik: 1;
+    type: "ready";
+} | {
+    ik: 1;
+    type: "gameplay";
+    playing: boolean;
+} | {
+    ik: 1;
+    type: "share";
+    id: number;
+};
+export type PageMessage = {
+    ik: 1;
+    type: "welcome";
+    features: Feature[];
+    context: Context;
+    muted: boolean;
+} | {
+    ik: 1;
+    type: "pause";
+} | {
+    ik: 1;
+    type: "resume";
+} | {
+    ik: 1;
+    type: "mute";
+    muted: boolean;
+} | {
+    ik: 1;
+    type: "shared";
+    id: number;
+    shared: boolean;
+};
+/** For the Ikirmikir page: a valid message from a game, or null. */
+export declare function readGameMessage(d: unknown): GameMessage | null;
+/** For the SDK: a valid message from the Ikirmikir page, or null. */
+export declare function readPageMessage(d: unknown): PageMessage | null;
+/** Origins allowed to act as the Ikirmikir page: the site, its Cloudflare Pages previews, and local development. */
+export declare function isIkirmikirOrigin(origin: string): boolean;

package/dist/protocol.js

@@ -0,0 +1,57 @@
+/*! @ikirmikir/game-sdk 1.0.0 | MIT | https://ikirmikir.com/developers/ */
+
+// src/protocol.ts
+var PROTOCOL = 1;
+var FEATURES = ["loading", "gameplay", "pause", "mute", "context", "share"];
+var obj = (d) => typeof d === "object" && d !== null && !Array.isArray(d);
+var str = (v, max) => typeof v === "string" && v.length > 0 && v.length <= max;
+var int = (v, min, max) => Number.isInteger(v) && v >= min && v <= max;
+var bool = (v) => typeof v === "boolean";
+function readGameMessage(d) {
+  if (!obj(d) || d.ik !== PROTOCOL) return null;
+  switch (d.type) {
+    case "hello":
+      return str(d.gameId, 64) && str(d.sdk, 32) ? { ik: 1, type: "hello", gameId: d.gameId, sdk: d.sdk } : null;
+    case "loading":
+      return int(d.progress, 0, 100) ? { ik: 1, type: "loading", progress: d.progress } : null;
+    case "ready":
+      return { ik: 1, type: "ready" };
+    case "gameplay":
+      return bool(d.playing) ? { ik: 1, type: "gameplay", playing: d.playing } : null;
+    case "share":
+      return int(d.id, 0, 1e9) ? { ik: 1, type: "share", id: d.id } : null;
+    default:
+      return null;
+  }
+}
+function readPageMessage(d) {
+  if (!obj(d) || d.ik !== PROTOCOL) return null;
+  switch (d.type) {
+    case "welcome": {
+      const c = d.context;
+      if (!Array.isArray(d.features) || !bool(d.muted) || !obj(c)) return null;
+      if (!str(c.language, 35) || c.device !== "mobile" && c.device !== "desktop" || !bool(c.touch)) return null;
+      const features = FEATURES.filter((f) => d.features.includes(f));
+      return { ik: 1, type: "welcome", features, context: { language: c.language, device: c.device, touch: c.touch }, muted: d.muted };
+    }
+    case "pause":
+      return { ik: 1, type: "pause" };
+    case "resume":
+      return { ik: 1, type: "resume" };
+    case "mute":
+      return bool(d.muted) ? { ik: 1, type: "mute", muted: d.muted } : null;
+    case "shared":
+      return int(d.id, 0, 1e9) && bool(d.shared) ? { ik: 1, type: "shared", id: d.id, shared: d.shared } : null;
+    default:
+      return null;
+  }
+}
+function isIkirmikirOrigin(origin) {
+  return origin === "https://ikirmikir.com" || origin === "http://localhost:3000" || origin === "http://127.0.0.1:3000" || /^https:\/\/([0-9a-f]{8}\.)?ikirmikir\.pages\.dev$/.test(origin);
+}
+export {
+  PROTOCOL,
+  isIkirmikirOrigin,
+  readGameMessage,
+  readPageMessage
+};

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@ikirmikir/game-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "Optional SDK for games on Ikirmikir: loading, gameplay, pause, sound, player context and share. Works standalone too.",
+  "license": "MIT",
+  "homepage": "https://ikirmikir.com/developers/",
+  "keywords": [
+    "html5-games",
+    "browser-games",
+    "game-sdk",
+    "ikirmikir"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./protocol": {
+      "types": "./dist/protocol.d.ts",
+      "default": "./dist/protocol.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "esbuild": "0.28.2",
+    "typescript": "5.9.3"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "tsc --noEmit"
+  },
+  "types": "./dist/index.d.ts"
 }