@bountyboard/arcade-sdk 1.2.0 → 1.3.0

package/AGENTS.md

@@ -19,15 +19,24 @@ https://www.bountyboard.gg/arcade/sdk/llms.txt — this file is about using it C
    the pattern for new integrations.
 3. **Scores are integers and `gameOver` fires exactly once per run.** Don't submit
    post-game-over corrections; the server enforces per-game plausibility caps and rejects
-   implausible values. Call `submitScore` freely during play — the host throttles.
+   implausible values. Call `submitScore` freely during play — the host throttles. Wiring the
+   calls is only half of a leaderboard: the studio must also declare Leaderboards on the game
+   in its Arcade submission, or the host rejects every score and the game never learns why.
 4. **Always handle `getPlayer() === null`** (guests, standalone, off-host). The SDK never
    provides ids, emails, or roles — do not design features that need them.
 5. **One save blob.** Serialize the whole progress object into a single `save(string)` (~1MB
    cap). Save on checkpoints/game-over, never per frame. Handle all five rejection codes; keep
    localStorage as the standalone fallback (hosted builds have no localStorage — the sandbox is
-   opaque-origin — so the SDK save IS primary there).
+   opaque-origin, where reading it THROWS rather than returning empty — so the SDK save IS
+   primary there). **Exception: engine exports.** When the game is a GameMaker/Godot/Unity/
+   Construct build whose storage layer can't be rewired without patching engine internals, use
+   `storage.install()` instead: it swaps the throwing `localStorage` for a cloud-backed shim. The
+   script tag installs it for you; module consumers call it before boot. `getItem` is synchronous
+   and the cloud read is not, so anything reading progress at boot must await `storage.ready()`.
 6. **`lockToHost()` before boot** when the studio wants anti-theft, with their own domains in
-   `allow`. It's a deterrent, not DRM — never present it as more.
+   `allow`. It's a deterrent, not DRM — never present it as more. Bounty Board's own hosts and
+   localhost are always allowed, so a build Bounty Board hosts passes no `allow` entries; never
+   ship the `play.yourgame.com` placeholder from the docs as if it were a real value.
 7. **Multiplayer: clients send inputs, never state.** The approved room authority (a Bounty Board
    module or a registered external server) simulates and validates; design the game so all
    authority lives in that one server. Don't trust or display any value another client sent

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @bountyboard/arcade-sdk
 
+## 1.3.0
+
+### Minor Changes
+
+- 0f53ae3: Add `BBArcade.storage`, a localStorage compatibility shim for engine exports.
+
+  Bounty-Board-hosted builds run on an opaque origin where `localStorage` throws
+  rather than returning empty. Games that own their source can just call
+  `save()`/`load()`, but engine runtimes bake synchronous storage in: GameMaker
+  HTML5 routes `ini_open`/`ini_write_*`/`game_save` through it, as do Godot,
+  Unity, and Construct.
+
+  `storage.install()` swaps the throwing `localStorage` for a Storage-shaped
+  object backed by the SDK's cloud save, so those builds persist per player and
+  across devices with no engine changes. It is idempotent and a no-op wherever a
+  real Storage works, so standalone play and URL embeds are untouched. The
+  script-tag build installs it at load; module consumers keep a side-effect-free
+  import and call it themselves before boot.
+
+  `ready()` resolves once the cloud read lands (`getItem` is synchronous, the read
+  is not), `flush()` forces the debounced write out, and `mode` reports
+  `'native' | 'cloud' | 'memory'`. `sessionStorage` is shimmed memory-only. With
+  the shim active `save()`/`load()` share the player's one save slot through a
+  tagged envelope that `load()` unwraps; a raw blob written before the shim
+  existed reads back untouched.
+
+  The shim never writes over a save it has not successfully read. A read that
+  FAILS settles just like one that succeeds, so persisting on that basis would
+  serialize only the current session's keys and wipe the rest; instead a failed
+  read is retried on the next write, and a write that still cannot confirm what
+  the player had is refused rather than allowed to overwrite it blind. `save()`
+  is size-checked against the whole envelope before it commits, so a rejected
+  oversized blob cannot leave the session unable to write at all. Keys named
+  `__proto__` are stored and restored like any other, matching a real `Storage`.
+
 ## 1.2.0
 
 ### Minor Changes

package/README.md

@@ -18,7 +18,10 @@ npm install @bountyboard/arcade-sdk
 ```ts
 import { BBArcade } from '@bountyboard/arcade-sdk';
 
-BBArcade.lockToHost({ allow: ['play.yourgame.com'] }); // optional; call before boot
+// Optional; call before boot. 'play.yourgame.com' is a placeholder: allow lists
+// the domains YOU host on, and Bounty Board plus localhost are always allowed,
+// so a Bounty-hosted build needs no allow list (or no call at all).
+BBArcade.lockToHost({ allow: ['play.yourgame.com'] });
 void BBArcade.init(); // host handshake; awaiting is optional
 
 export function onGameReady() {
@@ -65,7 +68,7 @@ specifically needs the global build, import `@bountyboard/arcade-sdk/global`.
 Bundle note: importing the package attaches the host `postMessage` listeners
 immediately (the host pushes its config at load time, so listener timing is
 part of the protocol), so the package is honestly marked `sideEffects: true`
-and will not tree-shake. The full script-tag build is ~47 KB unminified;
+and will not tree-shake. The full script-tag build is ~55 KB unminified;
 module consumers who only use multiplayer still get the whole core.
 
 ## Runtime support
@@ -79,6 +82,7 @@ the game runs determines which host-backed features are available.
 | Player identity                   | Player or `null`     | Player or `null`                       | `null`                |
 | A/B variants                      | Stable assignment    | Stable assignment                      | Alphabetical control  |
 | Cloud save / load                 | Logged-in players    | Unsupported                            | Unsupported           |
+| Native `localStorage`             | Throws (opaque)      | Works on your origin                   | Works                 |
 | Rewarded ads                      | Approved games       | Unavailable (no payable attribution)   | Unavailable           |
 | Multiplayer                       | Enabled authority    | Enabled authority                      | Unsupported           |
 
@@ -148,6 +152,47 @@ save/load rejection is a real `Error` with a typed `code`:
 unsupported | unauthenticated | too_large | rejected | error
 ```
 
+## Engine exports: the localStorage shim
+
+Prefer `save()`/`load()` when you control the source. The shim is for engine
+runtimes whose storage layer can't be rewired without patching engine
+internals — GameMaker HTML5 (`ini_open`, `ini_write_*`, and `game_save` all sit
+on `localStorage`), Godot, Unity, Construct. It replaces the throwing
+`localStorage` with a Storage-shaped object backed by your cloud save, so those
+builds persist per player and across devices with no engine changes.
+
+The script-tag build installs it at load, so the only requirement is load order:
+
+```html
+<script src="https://www.bountyboard.gg/arcade-sdk/v1.js"></script>
+<script src="html5game/YourGame.js"></script>
+```
+
+Module consumers keep a side-effect-free import and install it themselves,
+before any engine code runs:
+
+```ts
+BBArcade.storage.install(); // idempotent; no-op where a real Storage works
+
+// getItem() is synchronous but the cloud read that fills it is not.
+const mode = await BBArcade.storage.ready(); // 'cloud' | 'memory' | 'native'
+startGame();
+```
+
+Writes made before hydration are kept and merged with the cloud read (your
+write wins; a `removeItem` isn't resurrected), and nothing is pushed to the
+server until that read has SUCCEEDED — a failed read is retried, and a write
+that still can't confirm what the player had is refused rather than allowed to
+overwrite it blind, so neither a fresh-start write at boot nor a transport blip
+can wipe an existing save. `sessionStorage` is shimmed too, but memory-only. Guests and
+standalone play settle in `memory` mode: storage works for the session and is
+never persisted. `setItem` throws `QuotaExceededError` past the save cap, like
+a real Storage.
+
+`save()`/`load()` keep working alongside it: the player has one save slot, so
+both halves share it inside a tagged envelope that `load()` unwraps. A raw blob
+written before the shim existed reads back untouched.
+
 ## Player identity and A/B variants
 
 The SDK only provides public display identity. It never exposes account ids,
@@ -325,6 +370,8 @@ before adapting an existing server.
 // Anti-rehosting deterrent, not DRM. Call before boot. When the embedder
 // can't be read from browser signals (opaque-origin sandbox), the SDK asks
 // the embedding page and blocks if nothing answers within ~5 seconds.
+// The allowed domains below are placeholders for your own; Bounty Board and
+// localhost are allowed by default, so a Bounty-hosted build passes none.
 BBArcade.lockToHost({
   allow: ['play.yourgame.com', 'preview.yourgame.com'],
   signed: true,
@@ -357,7 +404,7 @@ Give coding agents the public
 | ------------- | ------------------------------------------------------------------------------------- |
 | Lifecycle     | `init`, `configure`, `ready` / `gameLoadingFinished`, `gameplayStart`, `gameplayStop` |
 | Scores        | `submitScore`, `gameOver`                                                             |
-| Player data   | `save`, `load`, `getPlayer`, `onPlayerChange`, `getVariant`                           |
+| Player data   | `save`, `load`, `storage.install` / `ready` / `flush`, `getPlayer`, `onPlayerChange`, `getVariant` |
 | Rewarded ads  | `prepareRewardedAd`, `rewardedAd`, `rewardedBreak`, `preloadRewardedAds`              |
 | Security / XR | `lockToHost`, `xrSessionStart`, `xrSessionEnd`                                        |
 | Multiplayer   | `joinRoom`, `room.trySend`, `room.on`, `room.leave`, `room.latencyMs`                 |

package/dist/{chunk-KDBBR532.js → chunk-PYW5F45R.js}

@@ -3,6 +3,316 @@ var VERSION = 1;
 var SDK_MESSAGE_SOURCE = "bb-arcade";
 var HOST_MESSAGE_SOURCE = "bb-arcade-host";
 
+// src/storage.ts
+var FLUSH_DELAY_MS = 400;
+var ENVELOPE_TAG = "__bbArcadeStorage";
+var ENVELOPE_VERSION = 1;
+function hasOwn(target, key) {
+  return Object.prototype.hasOwnProperty.call(target, key);
+}
+function emptyMap() {
+  return /* @__PURE__ */ Object.create(null);
+}
+function storageError(code) {
+  const err = new Error(code);
+  err.code = code;
+  return err;
+}
+function parseEnvelope(raw) {
+  if (raw == null) return { ls: {}, app: null };
+  if (raw.charAt(0) !== "{") return { ls: {}, app: raw };
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    return { ls: {}, app: raw };
+  }
+  if (!parsed || typeof parsed !== "object") return { ls: {}, app: raw };
+  const record = parsed;
+  if (record[ENVELOPE_TAG] !== ENVELOPE_VERSION) return { ls: {}, app: raw };
+  const ls = emptyMap();
+  const source = record.ls;
+  if (source && typeof source === "object") {
+    const entries = source;
+    for (const key in entries) {
+      if (hasOwn(entries, key) && typeof entries[key] === "string") {
+        ls[key] = entries[key];
+      }
+    }
+  }
+  return { ls, app: typeof record.app === "string" ? record.app : null };
+}
+function buildEnvelope(ls, app) {
+  const envelope = {};
+  envelope[ENVELOPE_TAG] = ENVELOPE_VERSION;
+  envelope.ls = ls;
+  envelope.app = app;
+  return JSON.stringify(envelope);
+}
+function quotaError() {
+  try {
+    return new DOMException("Cloud save quota exceeded", "QuotaExceededError");
+  } catch (err) {
+    const fallback = new Error("Cloud save quota exceeded");
+    fallback.name = "QuotaExceededError";
+    return fallback;
+  }
+}
+var RESERVED = {
+  getItem: true,
+  setItem: true,
+  removeItem: true,
+  clear: true,
+  key: true,
+  length: true
+};
+function createStorageShim(backend = {}) {
+  const map = emptyMap();
+  const localWrites = emptyMap();
+  function keys() {
+    return Object.keys(map);
+  }
+  function changed() {
+    if (backend.onChange) backend.onChange();
+  }
+  const api = {
+    getItem: function(key) {
+      const name = String(key);
+      return hasOwn(map, name) ? map[name] : null;
+    },
+    setItem: function(key, value) {
+      const name = String(key);
+      const next = String(value);
+      if (backend.wouldOverflow && backend.wouldOverflow(name, next)) throw quotaError();
+      map[name] = next;
+      localWrites[name] = true;
+      changed();
+    },
+    removeItem: function(key) {
+      const name = String(key);
+      localWrites[name] = true;
+      if (!hasOwn(map, name)) return;
+      delete map[name];
+      changed();
+    },
+    clear: function() {
+      const existing = keys();
+      for (let i = 0; i < existing.length; i++) {
+        delete map[existing[i]];
+        localWrites[existing[i]] = true;
+      }
+      changed();
+    },
+    key: function(index) {
+      const existing = keys();
+      const at = Number(index);
+      return at >= 0 && at < existing.length ? existing[at] : null;
+    },
+    get length() {
+      return keys().length;
+    }
+  };
+  const storage = new Proxy(api, {
+    get(target, prop, receiver) {
+      if (typeof prop !== "string") return Reflect.get(target, prop, receiver);
+      if (hasOwn(RESERVED, prop)) return Reflect.get(target, prop, receiver);
+      return hasOwn(map, prop) ? map[prop] : void 0;
+    },
+    set(target, prop, value) {
+      if (typeof prop !== "string" || hasOwn(RESERVED, prop)) return true;
+      api.setItem(prop, value);
+      return true;
+    },
+    has(target, prop) {
+      if (typeof prop !== "string") return Reflect.has(target, prop);
+      return hasOwn(RESERVED, prop) || hasOwn(map, prop);
+    },
+    deleteProperty(target, prop) {
+      if (typeof prop === "string" && !hasOwn(RESERVED, prop)) api.removeItem(prop);
+      return true;
+    },
+    ownKeys() {
+      return keys();
+    },
+    getOwnPropertyDescriptor(target, prop) {
+      if (typeof prop !== "string" || !hasOwn(map, prop)) return void 0;
+      return { value: map[prop], writable: true, enumerable: true, configurable: true };
+    }
+  });
+  return {
+    storage,
+    entries: function() {
+      const copy = emptyMap();
+      const existing = keys();
+      for (let i = 0; i < existing.length; i++) copy[existing[i]] = map[existing[i]];
+      return copy;
+    },
+    hydrate: function(values) {
+      for (const key in values) {
+        if (hasOwn(values, key) && !hasOwn(localWrites, key)) map[key] = values[key];
+      }
+    }
+  };
+}
+function settled(promise) {
+  return promise.then(
+    function() {
+    },
+    function() {
+    }
+  );
+}
+function installSessionStorageShim() {
+  if (nativeStorageWorks("sessionStorage")) return;
+  try {
+    Object.defineProperty(window, "sessionStorage", {
+      value: createStorageShim().storage,
+      configurable: true
+    });
+  } catch (err) {
+  }
+}
+function nativeStorageWorks(area) {
+  try {
+    const store = window[area];
+    if (!store) return false;
+    const probe = "__bb_arcade_probe__";
+    store.setItem(probe, "1");
+    store.removeItem(probe);
+    return true;
+  } catch (err) {
+    return false;
+  }
+}
+function createStorageController(options) {
+  let shim = null;
+  let mode = "native";
+  let appBlob = null;
+  let hydration = null;
+  let flushTimer = null;
+  let inFlight = Promise.resolve();
+  let dirty = false;
+  let hydrated = false;
+  function serialize() {
+    return buildEnvelope(shim ? shim.entries() : {}, appBlob);
+  }
+  function hydrateFromCloud() {
+    hydration = options.load().then(
+      function(raw) {
+        const envelope = parseEnvelope(raw);
+        if (shim) shim.hydrate(envelope.ls);
+        if (appBlob === null) appBlob = envelope.app;
+        hydrated = true;
+        return mode;
+      },
+      function(err) {
+        const code = err && err.code;
+        if (code === "unsupported" || code === "unauthenticated") mode = "memory";
+        return mode;
+      }
+    );
+    return hydration;
+  }
+  function wouldOverflow(key, value) {
+    if (!shim) return false;
+    const next = shim.entries();
+    next[key] = value;
+    return options.byteLength(buildEnvelope(next, appBlob)) > options.maxBytes;
+  }
+  function persist() {
+    return whenHydrated().then(function() {
+      if (mode === "memory") return;
+      if (hydrated) return options.save(serialize());
+      return hydrateFromCloud().then(function() {
+        if (mode === "memory") return;
+        if (!hydrated) throw storageError("error");
+        return options.save(serialize());
+      });
+    }).then(void 0, function(err) {
+      dirty = true;
+      throw err;
+    });
+  }
+  function flushNow() {
+    if (flushTimer !== null) {
+      clearTimeout(flushTimer);
+      flushTimer = null;
+    }
+    dirty = false;
+    const next = inFlight.then(persist, persist);
+    inFlight = settled(next);
+    return next;
+  }
+  function scheduleFlush() {
+    dirty = true;
+    if (flushTimer !== null) return;
+    flushTimer = setTimeout(function() {
+      flushTimer = null;
+      void settled(flushNow());
+    }, FLUSH_DELAY_MS);
+  }
+  function whenHydrated() {
+    return hydration ? hydration : Promise.resolve(mode);
+  }
+  function attachUnloadFlush() {
+    const flushIfDirty = function() {
+      if (dirty) void settled(flushNow());
+    };
+    try {
+      window.addEventListener("pagehide", flushIfDirty);
+      window.addEventListener("visibilitychange", function() {
+        if (document.visibilityState === "hidden") flushIfDirty();
+      });
+    } catch (err) {
+    }
+  }
+  function install() {
+    if (shim) return mode;
+    installSessionStorageShim();
+    if (nativeStorageWorks("localStorage")) {
+      mode = "native";
+      return mode;
+    }
+    const handle = createStorageShim({ onChange: scheduleFlush, wouldOverflow });
+    try {
+      Object.defineProperty(window, "localStorage", {
+        value: handle.storage,
+        configurable: true
+      });
+    } catch (err) {
+      return mode;
+    }
+    shim = handle;
+    mode = "cloud";
+    attachUnloadFlush();
+    void hydrateFromCloud();
+    return mode;
+  }
+  return {
+    install,
+    active: function() {
+      return shim !== null;
+    },
+    ready: function() {
+      return whenHydrated();
+    },
+    flush: function() {
+      if (!shim && appBlob === null) return Promise.resolve();
+      return flushNow();
+    },
+    writeApp: function(blob) {
+      if (options.byteLength(buildEnvelope(shim ? shim.entries() : {}, blob)) > options.maxBytes) {
+        return Promise.reject(storageError("too_large"));
+      }
+      appBlob = blob;
+      return flushNow();
+    },
+    get mode() {
+      return mode;
+    }
+  };
+}
+
 // src/core.ts
 var BOUNTY_BOARD_URL = "https://www.bountyboard.gg/arcade";
 var ADSENSE_CLIENT_ID = "ca-pub-7727110228190547";
@@ -791,6 +1101,16 @@ function createBBArcade() {
     if (!hostnameAllowed(event.origin, DEFAULT_ALLOW)) return;
     applyHostConfig(event.data);
   });
+  const storage = createStorageController({
+    save: function(blob) {
+      return request("save", blob);
+    },
+    load: function() {
+      return request("load");
+    },
+    byteLength: utf8ByteLength,
+    maxBytes: MAX_SAVE_BYTES
+  });
   const sdk = {
     lockToHost,
     init,
@@ -827,11 +1147,15 @@ function createBBArcade() {
       if (utf8ByteLength(data) > MAX_SAVE_BYTES) {
         return Promise.reject(sdkError("too_large"));
       }
+      if (storage.active()) return storage.writeApp(data);
       return request("save", data);
     },
     load: function() {
-      return request("load");
+      return request("load").then(function(raw) {
+        return parseEnvelope(raw).app;
+      });
     },
+    storage,
     getPlayer,
     onPlayerChange: function(handler) {
       if (typeof handler !== "function") return function() {
@@ -907,6 +1231,14 @@ function createInertBBArcade() {
     rewardedBreak: () => Promise.resolve(false),
     save: () => Promise.reject(sdkError2("unsupported")),
     load: () => Promise.reject(sdkError2("unsupported")),
+    // No window to shim and nothing to persist to: report the honest mode
+    // rather than pretending an install succeeded.
+    storage: {
+      install: () => "memory",
+      ready: () => Promise.resolve("memory"),
+      flush: () => Promise.resolve(),
+      mode: "memory"
+    },
     getPlayer: () => Promise.resolve(null),
     onPlayerChange: () => () => {
     },
@@ -927,4 +1259,4 @@ export {
   BBArcade,
   src_default
 };
-//# sourceMappingURL=chunk-KDBBR532.js.map
+//# sourceMappingURL=chunk-PYW5F45R.js.map