castle-web-sdk 0.4.5 → 0.4.7

package/README.md

@@ -0,0 +1,346 @@
+# Castle Web SDK Reference
+
+`castle-web-sdk` lets a deck use services provided by the Castle
+platform — for example, a deck can save per-player data, post and read
+scores on a leaderboard, or get a server-synced time for daily content.
+
+Comes with `castle-web init`. Import what you need from
+`castle-web-sdk`:
+
+```js
+import { setup, initCard, Storage, Leaderboard } from "castle-web-sdk";
+```
+
+## Contents
+
+- [Storage](#storage)
+- [SharedStorage](#sharedstorage)
+- [Leaderboard](#leaderboard)
+- [Time](#time)
+- [User](#user)
+- [Pass](#pass)
+- [Lifecycle](#lifecycle)
+- [Setup](#setup)
+- [CastleError](#castleerror)
+
+## Storage
+
+`Storage` saves data for the current player. Nobody else can read it.
+Use it for save files, settings, progress.
+
+### `Storage.get<T>(key): Promise<T | null>`
+
+Returns the value at `key`, or `null` if not set.
+
+```js
+const level = (await Storage.get("level")) ?? 1;
+```
+
+### `Storage.set(key, value)`
+
+Sets `key` to `value`. `value` must be something that can convert to
+JSON (`null`, booleans, finite numbers, strings, arrays, plain
+objects). The next `get(key)` returns the new value immediately. Writes
+save in the background.
+
+```js
+Storage.set("level", 7);
+Storage.set("settings", { sound: true, music: false });
+```
+
+### `Storage.remove(key)`
+
+Removes `key`.
+
+## SharedStorage
+
+`SharedStorage` saves data that other players can read. Values must
+be something that can convert to JSON, same as `Storage`.
+
+Scopes:
+
+- `'deck'` — one shared bucket for the whole deck. Any player can read
+  or write.
+- `'user'` — a per-player public bucket. Any player can read; only the
+  owning player can write.
+
+### `SharedStorage.get(scope, key): Promise<T | null>`
+
+Reads a shared value. For `'user'`, omit the user id to read the
+current player's bucket, or pass one to read someone else's:
+
+```js
+const worldHighScore = await SharedStorage.get("deck", "highScore");
+const myColor = await SharedStorage.get("user", "color");
+const theirColor = await SharedStorage.get("user", otherUserId, "color");
+```
+
+### `SharedStorage.set(scope, key, value)`
+
+Writes a shared value. `'user'` writes always go to the current
+player's bucket. Writes save in the background.
+
+```js
+SharedStorage.set("deck", "highScore", 9001);
+SharedStorage.set("user", "color", "red");
+```
+
+### `SharedStorage.remove(scope, key)`
+
+Removes a shared value.
+
+## Leaderboard
+
+`Leaderboard` ranks players by a numeric score, per deck and per
+variable name. Pick a variable name for each leaderboard the deck has
+(e.g. `'score'`, `'time'`).
+
+### `Leaderboard.write(variable, score, options?)`
+
+Submits a score. Only the player's best score for that `variable` (and
+scope) is kept. In the editor it does nothing — safe to call from
+gameplay code unconditionally.
+
+`options` is `{ scope?: string }`. By default the score goes to the
+deck's global leaderboard for `variable`; pass `scope` to write to a
+separate leaderboard (for example a daily one, or a custom id):
+
+```js
+Leaderboard.write("score", 1200);
+
+// A daily leaderboard: scope by the current Castle day so each day gets
+// its own board (see Time.getServerDate).
+const { daysSinceCastleEpoch } = await Time.getServerDate();
+Leaderboard.write("score", 1200, { scope: `daily-${daysSinceCastleEpoch}` });
+```
+
+### `Leaderboard.fetch(variable, type, options?): Promise<LeaderboardData>`
+
+Fetches the leaderboard for `variable`. `type` is `'high'` (highest
+first) or `'low'` (lowest first). `options.scope` works the same as in
+`write`.
+
+If the player has written a score this session, a `fetch` reflects
+**their own** new score right away — you can `write` then `fetch` and
+show the result without waiting. Other players' recent scores still
+appear on their own normal timing.
+
+The returned `LeaderboardData` has:
+
+- `list` — array of entries, each `{ place, value, username, userId? }`.
+- `playerRank` — the current player's place on the board (if they have
+  a score).
+- `playerValue` — the current player's score (if they have one).
+
+```js
+const data = await Leaderboard.fetch("score", "high");
+for (const entry of data.list) {
+  console.log(`${entry.place}. ${entry.username} — ${entry.value}`);
+}
+if (data.playerRank) {
+  console.log(`you are #${data.playerRank} with ${data.playerValue}`);
+}
+```
+
+## Time
+
+### `Time.getServerTime(): Promise<number>`
+
+Returns the current server time as a Unix timestamp in seconds.
+
+```js
+const now = await Time.getServerTime();
+```
+
+### `Time.getServerDate(timezone?): Promise<CastleDateParts>`
+
+Returns the current server time broken into date parts. `timezone` is
+`'Castle'` (default; Castle's server timezone, same for every player)
+or `'player'` (the player's local timezone).
+
+The returned `CastleDateParts` has:
+
+- `sec`, `min`, `hour` — time of day.
+- `day` (1-31), `month` (1-12), `year` — date.
+- `wday` — day of the week (1-7, Sunday = 1).
+- `yday` — day of the year (1-366).
+- `daysSinceCastleEpoch` — a day number that increments every day.
+  Use it for daily content.
+
+```js
+const date = await Time.getServerDate("player");
+const dailyPuzzle = (date.daysSinceCastleEpoch % 30) + 1;
+```
+
+## User
+
+### `User.getCurrent(): Promise<CastleUser>`
+
+Returns the signed-in player. Throws `CastleError`
+(`LOGIN_REQUIRED`) when nobody is signed in.
+
+The returned `CastleUser` has `userId`, `username`, and `isActive`.
+
+```js
+const me = await User.getCurrent();
+greet(me.username);
+```
+
+## Pass
+
+A pass is something a creator sells to players for Castle bricks (the
+in-app currency): buy it once, own it for good. Use one to gate part of a
+deck behind a purchase — bonus levels, a cosmetic, supporting the
+creator. Set up the pass (name, art, price) on Castle; a deck refers to
+it by id.
+
+### `Pass.has(passId): Promise<boolean>`
+
+Returns `true` if the current player owns the pass. No UI, nothing
+charged — use it to gate content.
+
+```js
+if (await Pass.has(bonusLevelsPassId)) {
+  showBonusLevels();
+}
+```
+
+### `Pass.offer(passId): Promise<PassOfferResult>`
+
+Presents the pass for the player to buy; resolves when they're done.
+Bricks cost real money, so this only works in the Castle mobile app —
+elsewhere (the website, the dev server) it resolves `unavailable`.
+`PassOfferResult` has a `status`:
+
+- `'purchased'` — just bought it; grant access.
+- `'alreadyOwned'` — already had it (not charged); grant access.
+- `'cancelled'` — dismissed without buying.
+- `'unavailable'` — can't buy here (e.g. the website).
+
+```js
+const { status } = await Pass.offer(bonusLevelsPassId);
+if (status === "purchased" || status === "alreadyOwned") {
+  showBonusLevels();
+}
+```
+
+## Lifecycle
+
+`Lifecycle` tells the host when the deck has painted its first frame, so
+the Castle feed can reveal it right away instead of waiting out a fixed
+delay.
+
+### `Lifecycle.ready()`
+
+Signal that the deck has painted its first presentable frame. Idempotent
+— only the first call has any effect.
+
+Kits already wire this up to fire as soon as the first frame paints; if
+you change how the deck first renders, make sure it still fires there. If
+nothing calls this, the feed reveals the deck on its own after a brief
+timeout.
+
+If you call it right after kicking off your initial render, wait for the
+next paint first so the host doesn't reveal a blank frame:
+
+```js
+createRoot(root).render(<App />);
+requestAnimationFrame(() => requestAnimationFrame(() => Lifecycle.ready()));
+```
+
+## Setup
+
+Startup, editor-mode check, and a file-write call for editor UI.
+
+### `setup()`
+
+Call this once at the start of the deck, before any other SDK call.
+`setup()` initializes the SDK so the rest of the API is usable and
+mounts the centered 5:7 card shell around whatever the deck renders
+into `#root` (when the deck is being played standalone in a browser).
+While running locally with `castle-web serve`, it also forwards
+`console` output to the CLI and reloads the page when `castle-web
+restart` runs.
+
+```js
+import { setup } from "castle-web-sdk";
+
+setup();
+```
+
+### `initCard(): HTMLDivElement`
+
+Use this when the deck draws into a `<canvas>` (or anything else)
+rather than into the React tree at `#root`. Returns a centered,
+viewport-sized `<div>` with the standard Castle 5:7 card aspect ratio.
+The div resizes itself when the window resizes.
+
+```js
+import { setup, initCard } from "castle-web-sdk";
+
+setup();
+const card = initCard();
+
+const canvas = document.createElement("canvas");
+canvas.style.cssText = "width: 100%; height: 100%; display: block;";
+card.appendChild(canvas);
+```
+
+If the deck mounts a React tree into `#root` instead, you don't need
+`initCard()` — `setup()` already wraps `#root`'s children in a card.
+
+### `CARD_RATIO`
+
+The card aspect ratio (`5 / 7`). Use this if you need to size something
+to match the card.
+
+### `isEdit(): boolean`
+
+`true` when the deck is being edited, `false` when it's being played.
+Use this to show editor UI only in edit mode.
+
+```js
+import { isEdit, setup } from "castle-web-sdk";
+
+setup();
+if (isEdit()) {
+  mountEditor();
+} else {
+  startGame();
+}
+```
+
+### `writeFile(path, contents): Promise<void>`
+
+Writes a file in the deck directory. `path` is relative to the deck
+root, `contents` is a string. Use this from editor UI to save scenes,
+drawings, or generated source.
+
+```js
+import { writeFile } from "castle-web-sdk";
+
+await writeFile("scenes/main.scene", JSON.stringify(scene, null, 2));
+```
+
+Only works while editing locally with `castle-web serve`. Calls from a
+published deck fail.
+
+## CastleError
+
+Every error the SDK throws is a `CastleError`. Check `code` to tell
+the kinds apart.
+
+Common codes:
+
+- `LOGIN_REQUIRED` — the player needs to be signed in.
+- `MISSING_DECK_ID` — the deck hasn't been saved to Castle yet, so it
+  has no id.
+- `CASTLE_STORAGE_SERIALIZE_FAILED` — value isn't plain JSON (e.g. a
+  class instance, a function, a non-finite number, or a cycle).
+- `INVALID_LEADERBOARD_VARIABLE`, `INVALID_LEADERBOARD_SCORE`,
+  `INVALID_LEADERBOARD_TYPE` — bad argument to a `Leaderboard` call.
+- `UNSUPPORTED_TIMEZONE` — `Time.getServerDate` got a zone other than
+  `'Castle'` or `'player'`.
+- `CASTLE_HOST_UNAVAILABLE` — the Castle host (the app or website running
+  the deck) didn't handle the request — e.g. it timed out or wasn't
+  reachable. Usually transient; retry or surface a gentle error.

package/dist/castle.d.ts

@@ -2,6 +2,8 @@ export { isEdit } from "./context";
 export { CastleError } from "./errors";
 export { Leaderboard } from "./leaderboard";
 export type { LeaderboardData, LeaderboardEntry, LeaderboardOptions, LeaderboardScope, LeaderboardSort, } from "./leaderboard";
+export { Lifecycle } from "./lifecycle";
+export type { CastleLifecycleApi } from "./lifecycle";
 export { Pass } from "./passes";
 export type { CastlePassApi, PassOfferResult, PassOfferStatus, } from "./passes";
 export { CARD_RATIO, initCard, onBeforeRestart, setup, writeFile } from "./runtime";

package/dist/castle.js

@@ -2,6 +2,7 @@
 export { isEdit } from "./context";
 export { CastleError } from "./errors";
 export { Leaderboard } from "./leaderboard";
+export { Lifecycle } from "./lifecycle";
 export { Pass } from "./passes";
 export { CARD_RATIO, initCard, onBeforeRestart, setup, writeFile } from "./runtime";
 export { SharedStorage, Storage } from "./storage";

package/dist/commands.d.ts

@@ -115,3 +115,8 @@ export interface CommandResponseEnvelope {
     error?: SerializedCommandError;
 }
 export declare function isResponseEnvelope(value: unknown): value is CommandResponseEnvelope;
+export type LifecycleEvent = "ready";
+export interface LifecycleEnvelope {
+    castleSdk: typeof CASTLE_SDK_PROTOCOL;
+    lifecycle: LifecycleEvent;
+}

package/dist/lifecycle.d.ts

@@ -0,0 +1,4 @@
+export interface CastleLifecycleApi {
+    ready(): void;
+}
+export declare const Lifecycle: CastleLifecycleApi;

package/dist/lifecycle.js

@@ -0,0 +1,13 @@
+// Deck-side lifecycle signals. The feed reveals the deck when it reports `ready`
+// (its first presentable frame) instead of waiting out a fixed timer.
+import { hostNotify } from "./transport";
+let readySent = false;
+function ready() {
+    if (readySent)
+        return;
+    readySent = true;
+    hostNotify("ready");
+}
+export const Lifecycle = {
+    ready,
+};

package/dist/runtime.js

@@ -250,26 +250,34 @@ async function captureWithHtml2Canvas(target) {
         return null;
     }
 }
+function cropCanvasToCard(card, canvas) {
+    const cardRect = card.getBoundingClientRect();
+    const c = document.createElement("canvas");
+    c.width = cardRect.width * devicePixelRatio;
+    c.height = cardRect.height * devicePixelRatio;
+    const ctx = c.getContext("2d");
+    const canvasRect = canvas.getBoundingClientRect();
+    const dx = (canvasRect.left - cardRect.left) * devicePixelRatio;
+    const dy = (canvasRect.top - cardRect.top) * devicePixelRatio;
+    ctx.drawImage(canvas, dx, dy, canvasRect.width * devicePixelRatio, canvasRect.height * devicePixelRatio);
+    return c.toDataURL("image/png");
+}
 async function captureScreenshot() {
-    const card = document.getElementById("castle-card");
-    const canvas = document.querySelector("canvas");
+    const card = document.querySelector("#castle-card, [data-castle-card]");
+    if (card) {
+        const cardCanvas = card.querySelector("canvas");
+        if (cardCanvas)
+            return cropCanvasToCard(card, cardCanvas);
+        const cropped = await captureWithHtml2Canvas(card);
+        if (cropped)
+            return cropped;
+    }
     if (document.body?.dataset.castleScreenshotTarget === "viewport") {
         const viewportCapture = await captureWithHtml2Canvas(document.body);
         if (viewportCapture)
             return viewportCapture;
     }
-    if (card && canvas) {
-        const cardRect = card.getBoundingClientRect();
-        const c = document.createElement("canvas");
-        c.width = cardRect.width * devicePixelRatio;
-        c.height = cardRect.height * devicePixelRatio;
-        const ctx = c.getContext("2d");
-        const canvasRect = canvas.getBoundingClientRect();
-        const dx = (canvasRect.left - cardRect.left) * devicePixelRatio;
-        const dy = (canvasRect.top - cardRect.top) * devicePixelRatio;
-        ctx.drawImage(canvas, dx, dy, canvasRect.width * devicePixelRatio, canvasRect.height * devicePixelRatio);
-        return c.toDataURL("image/png");
-    }
+    const canvas = document.querySelector("canvas");
     if (canvas)
         return canvas.toDataURL("image/png");
     return captureWithHtml2Canvas(card || document.body);

package/dist/transport.d.ts

@@ -1,4 +1,4 @@
-import { type CommandName, type CommandParams, type CommandResult } from "./commands";
+import { type CommandName, type CommandParams, type CommandResult, type LifecycleEvent } from "./commands";
 type PostChannel = "mobile" | "web";
 interface ReactNativeWebViewBridge {
     postMessage: (message: string) => void;
@@ -13,4 +13,5 @@ declare global {
 }
 export declare function hostRequest<C extends CommandName>(command: C, params: CommandParams[C]): Promise<CommandResult[C]>;
 export declare function getCommandChannel(): PostChannel | "local";
+export declare function hostNotify(event: LifecycleEvent): void;
 export {};

package/dist/transport.js

@@ -52,6 +52,20 @@ export async function hostRequest(command, params) {
 export function getCommandChannel() {
     return resolveChannel();
 }
+// Fire-and-forget counterpart to hostRequest: no reply, no timeout. The local
+// dev server has no surface to react to lifecycle events, so it's skipped.
+export function hostNotify(event) {
+    if (typeof window === "undefined")
+        return;
+    const channel = resolveChannel();
+    if (channel === "local")
+        return;
+    const envelope = {
+        castleSdk: CASTLE_SDK_PROTOCOL,
+        lifecycle: event,
+    };
+    sendEnvelope(channel, envelope);
+}
 function resolveChannel() {
     if (typeof window === "undefined")
         return "local";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-sdk",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "type": "module",
   "main": "dist/castle.js",
   "types": "dist/castle.d.ts",
@@ -13,10 +13,9 @@
   "//host": "host.{js,d.ts} is the host-side executor — deliberately NOT exported and NOT packaged. It is vendored into host repos via scripts/copy-host-module.mjs; decks must never receive it.",
   "files": [
     "dist",
-    "src",
+    "README.md",
     "!dist/host.js",
-    "!dist/host.d.ts",
-    "!src/host.ts"
+    "!dist/host.d.ts"
   ],
   "scripts": {
     "build": "rm -rf dist && tsc",

package/src/castle.ts

@@ -1,25 +0,0 @@
-// Castle Web SDK
-
-export { isEdit } from "./context";
-export { CastleError } from "./errors";
-export { Leaderboard } from "./leaderboard";
-export type {
-  LeaderboardData,
-  LeaderboardEntry,
-  LeaderboardOptions,
-  LeaderboardScope,
-  LeaderboardSort,
-} from "./leaderboard";
-export { Pass } from "./passes";
-export type {
-  CastlePassApi,
-  PassOfferResult,
-  PassOfferStatus,
-} from "./passes";
-export { CARD_RATIO, initCard, onBeforeRestart, setup, writeFile } from "./runtime";
-export { SharedStorage, Storage } from "./storage";
-export { Time } from "./time";
-export type { CastleClockZone, CastleDateParts, CastleTimeApi } from "./time";
-export type { Json } from "./types";
-export { User } from "./user";
-export type { CastleUser, CastleUserApi } from "./user";

package/src/commands.ts

@@ -1,136 +0,0 @@
-// The SDK↔host command contract. This is the single source of truth for the
-// wire protocol shared by the deck-side command-poster (`transport.ts`) and the
-// host-side executor (`host.ts`). It carries ONLY names and types — no GraphQL
-// query strings and no auth — so importing it into a deck bundle reveals
-// nothing privileged.
-
-import type { Json } from "./types";
-
-// Marker + protocol version. Doubles as a discriminator so host messages can't
-// be confused with embed.js `castlexyz:` strings or RN console messages.
-export const CASTLE_SDK_PROTOCOL = 1;
-
-export type StorageBlob = Record<string, string>;
-export type SharedScope = "deck" | "user";
-
-export interface StorageUpdate {
-  key: string;
-  value: string | null;
-}
-
-// The raw GraphQL leaderboard shape the host returns; the SDK normalizes it
-// (and computes playerRank from `currentUserId`) into the public LeaderboardData.
-export interface RawLeaderboardEntry {
-  place?: string | number | null;
-  score?: string | number | null;
-  user?: { userId?: string | null; username?: string | null } | null;
-}
-
-export interface RawLeaderboard {
-  list?: RawLeaderboardEntry[] | null;
-  yourScore?: { score?: string | number | null } | null;
-}
-
-export type PassOfferStatus =
-  | "purchased"
-  | "alreadyOwned"
-  | "cancelled"
-  | "unavailable";
-
-export interface PassOfferResult {
-  status: PassOfferStatus;
-}
-
-export interface CommandParams {
-  "deckStorage.load": Record<string, never>;
-  "deckStorage.update": { updates: StorageUpdate[] };
-  "sharedDeckStorage.load": {
-    scope: SharedScope;
-    userId?: string | null;
-    keys: string[];
-  };
-  "sharedDeckStorage.update": { scope: SharedScope; updates: StorageUpdate[] };
-  "leaderboard.fetch": {
-    variable: string;
-    type: "high" | "low";
-    scope?: string | null;
-    // When present, the deck has a freshly-written score for this
-    // variable+scope that hasn't settled server-side yet. The host routes
-    // through the leaderboardV2 mutation, which writes this score and returns
-    // the post-write leaderboard atomically, so the player's own score shows
-    // up immediately. Absent → a plain read of the settled leaderboard.
-    score?: number | null;
-  };
-  "leaderboard.save": { variable: string; score: number; scope?: string | null };
-  "user.getCurrent": Record<string, never>;
-  "time.getServerTime": Record<string, never>;
-  "pass.has": { passId: string };
-  // Platform/interactive command — dispatched to the host's platformHandler,
-  // not graphqlFetch. Unlike the data commands above, this one can stay open
-  // for a long time (the player interacting with a native sheet), so the
-  // deck-side transport gives it no timeout.
-  "pass.offer": { passId: string };
-}
-
-export interface CommandResult {
-  "deckStorage.load": { blob: StorageBlob };
-  "deckStorage.update": { blob: StorageBlob };
-  "sharedDeckStorage.load": { blob: StorageBlob };
-  "sharedDeckStorage.update": { ok: true };
-  "leaderboard.fetch": {
-    leaderboard: RawLeaderboard;
-    currentUserId: string | null;
-  };
-  "leaderboard.save": { ok: true };
-  "user.getCurrent": { user: { userId: string; username: string } | null };
-  "time.getServerTime": {
-    timestamp: number;
-    timezoneOffset: number;
-    castleEpochData: Json;
-  };
-  "pass.has": { hasPass: boolean };
-  "pass.offer": PassOfferResult;
-}
-
-export type CommandName = keyof CommandParams;
-
-// NB: the runtime command allowlist (COMMAND_NAMES / isCommandName) lives in
-// host.ts, not here, so that host.ts can keep ALL of its imports type-only and
-// compile to a single self-contained file (zero runtime imports) that vendors
-// cleanly into Node-ESM / webpack / Metro hosts in other repos.
-
-// Serializable error that survives the postMessage boundary. The deck-side
-// rebuilds a real CastleError from it, preserving `code` so decks can branch.
-export interface SerializedCommandError {
-  code: string;
-  message: string;
-  command?: string;
-  extensions?: Record<string, unknown>;
-}
-
-export interface CommandRequestEnvelope {
-  castleSdk: typeof CASTLE_SDK_PROTOCOL;
-  requestId: string;
-  command: CommandName;
-  params: unknown;
-}
-
-export interface CommandResponseEnvelope {
-  castleSdk: typeof CASTLE_SDK_PROTOCOL;
-  requestId: string;
-  ok: boolean;
-  data?: unknown;
-  error?: SerializedCommandError;
-}
-
-export function isResponseEnvelope(
-  value: unknown,
-): value is CommandResponseEnvelope {
-  if (typeof value !== "object" || value === null) return false;
-  const record = value as Record<string, unknown>;
-  return (
-    record.castleSdk === CASTLE_SDK_PROTOCOL &&
-    typeof record.requestId === "string" &&
-    typeof record.ok === "boolean"
-  );
-}

package/src/context.ts

@@ -1,30 +0,0 @@
-// Which outer runtime is hosting the deck. Set by each host alongside the
-// (now non-secret) CastleEmbed flags; used by transport.ts to pick a channel.
-export type CastleHost = "web" | "mobile" | "dev";
-
-export interface CastleEmbed {
-  edit?: boolean;
-  feed?: boolean;
-  host?: CastleHost;
-}
-
-declare global {
-  interface Window {
-    CastleEmbed?: CastleEmbed;
-  }
-}
-
-export function getCastleEmbed(): CastleEmbed | undefined {
-  return typeof window === "undefined" ? undefined : window.CastleEmbed;
-}
-
-export function isEdit(): boolean {
-  try {
-    const params = new URLSearchParams(window.location.search);
-    const override = params.get("edit");
-    if (override === "0" || override === "false") return false;
-  } catch {
-    // ignore -- window.location may be unavailable
-  }
-  return !!getCastleEmbed()?.edit;
-}