castle-web-sdk 0.4.12 → 0.4.14

package/README.md

@@ -95,7 +95,8 @@ Removes a shared value.
 
 `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'`).
+(e.g. `'score'`, `'time'`). `show` opens Castle's own leaderboard screen;
+reach for `fetch` only if the deck draws the scores itself.
 
 ### `Leaderboard.write(variable, score, options?)`
 
@@ -116,16 +117,42 @@ const { daysSinceCastleEpoch } = await Time.getServerDate();
 Leaderboard.write("score", 1200, { scope: `daily-${daysSinceCastleEpoch}` });
 ```
 
+### `Leaderboard.show(variable, type, options?): Promise<LeaderboardShowResult>`
+
+Opens Castle's own leaderboard screen for `variable` — the same board
+players see on other Castle decks, with FOR YOU and GLOBAL tabs, sharing,
+and profile links. This is the normal way to show a leaderboard: Castle
+draws it and owns the data, so the deck gets no entries back.
+
+`type` is `'high'` (highest first) or `'low'` (lowest first). `options` is
+`{ scope?, label? }` — `scope` works as it does in `write`, and `label`
+titles the column of scores (default `'Score'`; e.g. `'Time'`, `'Coins'`).
+
+Opening the board also submits the score the player has written this
+session, so their own result is on it right away. The board appears
+immediately, on a loading spinner; the promise resolves once the scores
+are in. The player closes it themselves — there's no `hide`.
+
+`LeaderboardShowResult` has a `status`:
+
+- `'shown'` — Castle opened the leaderboard.
+- `'unavailable'` — this host has no leaderboard screen, or can't show
+  one right now. Nothing was submitted; the score still saves normally.
+
+```js
+Leaderboard.write("score", finalScore);
+gameOverButton.onclick = () => Leaderboard.show("score", "high");
+```
+
 ### `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`.
+Fetches the leaderboard's entries so the deck can draw them itself — use
+this only when Castle's own screen isn't what you want. `type` and
+`options.scope` work as they do in `show`.
 
-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.
+Like `show`, a fetch reflects **the player's own** score written this
+session right away. Other players' recent scores still appear on their own
+normal timing.
 
 The returned `LeaderboardData` has:
 

package/dist/castle.d.ts

@@ -4,7 +4,7 @@ export { deckPrefixOf, IMPORTS_DIR, IMPORTS_PREFIX, isImportedFile, resolveDeckF
 export { Haptics } from "./haptics";
 export type { CastleHapticsApi, HapticsResult, HapticsStatus, HapticStyle } from "./haptics";
 export { Leaderboard } from "./leaderboard";
-export type { LeaderboardData, LeaderboardEntry, LeaderboardOptions, LeaderboardScope, LeaderboardSort, } from "./leaderboard";
+export type { LeaderboardData, LeaderboardEntry, LeaderboardOptions, LeaderboardScope, LeaderboardShowOptions, LeaderboardShowResult, LeaderboardShowStatus, LeaderboardSort, } from "./leaderboard";
 export { Lifecycle } from "./lifecycle";
 export type { CastleLifecycleApi } from "./lifecycle";
 export { Pass } from "./passes";

package/dist/commands.d.ts

@@ -20,6 +20,16 @@ export interface RawLeaderboard {
         score?: string | number | null;
     } | null;
 }
+export type LeaderboardShowStatus = "shown" | "unavailable";
+export interface LeaderboardShowResult {
+    status: LeaderboardShowStatus;
+}
+export interface LeaderboardStreakCredit {
+    deckId: string | null;
+    kind: string;
+    priorStreak: number;
+    newStreak: number;
+}
 export type PassOfferStatus = "purchased" | "alreadyOwned" | "cancelled" | "unavailable";
 export interface PassOfferResult {
     status: PassOfferStatus;
@@ -62,6 +72,13 @@ export interface CommandParams {
         score: number;
         scope?: string | null;
     };
+    "leaderboard.show": {
+        variable: string;
+        type: "high" | "low";
+        scope?: string | null;
+        label?: string | null;
+        score?: number | null;
+    };
     "user.getCurrent": Record<string, never>;
     "time.getServerTime": Record<string, never>;
     "pass.has": {
@@ -100,6 +117,7 @@ export interface CommandResult {
     "leaderboard.save": {
         ok: true;
     };
+    "leaderboard.show": LeaderboardShowResult;
     "user.getCurrent": {
         user: {
             userId: string;

package/dist/leaderboard.d.ts

@@ -1,8 +1,13 @@
+import { type LeaderboardShowResult } from "./commands";
+export type { LeaderboardShowResult, LeaderboardShowStatus } from "./commands";
 export type LeaderboardSort = "high" | "low";
 export type LeaderboardScope = string;
 export interface LeaderboardOptions {
     scope?: LeaderboardScope | null;
 }
+export interface LeaderboardShowOptions extends LeaderboardOptions {
+    label?: string | null;
+}
 export interface LeaderboardEntry {
     place: number;
     value: number;
@@ -17,4 +22,5 @@ export interface LeaderboardData {
 export declare const Leaderboard: {
     readonly write: (variable: string, score: number, options?: LeaderboardOptions) => void;
     readonly fetch: (variable: string, type: LeaderboardSort, options?: LeaderboardOptions) => Promise<LeaderboardData>;
+    readonly show: (variable: string, type: LeaderboardSort, options?: LeaderboardShowOptions) => Promise<LeaderboardShowResult>;
 };

package/dist/leaderboard.js

@@ -15,6 +15,9 @@ export const Leaderboard = {
     fetch(variable, type, options = {}) {
         return fetchLeaderboardData(variable, type, options);
     },
+    show(variable, type, options = {}) {
+        return showLeaderboard(variable, type, options);
+    },
 };
 function writeLeaderboard(variable, score, options) {
     if (isEdit())
@@ -30,17 +33,8 @@ async function fetchLeaderboardData(variable, type, options) {
     assertLeaderboardVariable(variable, "Leaderboard.fetch");
     assertLeaderboardType(type, "Leaderboard.fetch");
     const scope = leaderboardScope(options);
-    // If the deck has written a score for this variable+scope this session, send
-    // it so the host writes-and-reads via leaderboardV2 and the player's own
-    // score shows up immediately (mirrors getLeaderboard in
-    // core/src/leaderboards.cpp — presence of a buffered score, not dirtiness,
-    // gates the write-through). Otherwise a plain read of the settled board.
-    const record = leaderboardWrites.get(leaderboardWriteKey(variable, scope));
-    const score = record
-        ? type === "high"
-            ? record.highScore
-            : record.lowScore
-        : null;
+    const record = pendingLeaderboardWrite(variable, scope);
+    const score = bufferedScore(record, type);
     const { leaderboard, currentUserId } = await hostRequest("leaderboard.fetch", {
         variable,
         type,
@@ -52,6 +46,57 @@ async function fetchLeaderboardData(variable, type, options) {
     }
     return normalizeLeaderboard(leaderboard, currentUserId);
 }
+// Opening the host's leaderboard UI takes the same write-through shortcut a
+// fetch does: the buffered score rides along so the player's own just-played
+// score is on the board immediately, matching what opening the classic
+// leaderboard does. The panel and its data stay host-side — a deck that calls
+// this receives no leaderboard rows, only whether it was presented.
+async function showLeaderboard(variable, type, options) {
+    assertLeaderboardVariable(variable, "Leaderboard.show");
+    assertLeaderboardType(type, "Leaderboard.show");
+    const scope = leaderboardScope(options);
+    const record = pendingLeaderboardWrite(variable, scope);
+    const score = bufferedScore(record, type);
+    const label = typeof options.label === "string" ? options.label : null;
+    let result;
+    try {
+        result = await hostRequest("leaderboard.show", {
+            variable,
+            type,
+            scope,
+            ...(label === null ? {} : { label }),
+            ...(score === null ? {} : { score }),
+        });
+    }
+    catch (error) {
+        // An app build older than this command rejects it outright; that is
+        // capability divergence, not a failure the deck should have to handle.
+        if (error instanceof CastleError && error.code === "UNKNOWN_COMMAND") {
+            return { status: "unavailable" };
+        }
+        throw error;
+    }
+    // Only a host that actually presented the board wrote the score, so only
+    // then is the buffered write settled; otherwise the periodic flush delivers
+    // it and a duplicate write (double streak credit) is avoided either way.
+    if (result.status === "shown" && record && score !== null) {
+        clearLeaderboardDirtyAfterFetch(record, type, score);
+    }
+    return result;
+}
+function pendingLeaderboardWrite(variable, scope) {
+    return leaderboardWrites.get(leaderboardWriteKey(variable, scope));
+}
+// The value to send along with a read: if the deck has written a score for this
+// variable+scope this session, the host writes-and-reads via leaderboardV2 so
+// the player's own score shows up immediately. Mirrors getLeaderboard in
+// core/src/leaderboards.cpp — presence of a buffered score, not dirtiness,
+// gates the write-through. No buffered score → a plain read of the settled board.
+function bufferedScore(record, type) {
+    if (!record)
+        return null;
+    return type === "high" ? record.highScore : record.lowScore;
+}
 // After a write-through fetch, clear the dirty flag for the side we just sent
 // (so the periodic flush won't re-send it via saveVariableToLeaderboard). If
 // the other side's buffered value matches what we sent (the common single-score

package/dist/runtime.js

@@ -1,6 +1,10 @@
 import { CASTLE_SDK_PROTOCOL, } from "./commands";
 import { getCastleEmbed, isEdit } from "./context";
 export const CARD_RATIO = 5 / 7;
+// Host -> deck capture request, and the deck's answer. Kept in sync with the
+// editor shell (cli/src/shell/coverApi.ts).
+const HOST_CAPTURE_REQUEST = "castle-capture-cover";
+const HOST_CAPTURE_RESULT = "castle-capture-cover-result";
 let ws = null;
 let logBuffer = [];
 let nextRequestId = 1;
@@ -21,6 +25,8 @@ const dynamicImport = new Function("u", "return import(u)");
 export function setup() {
     interceptConsole();
     connectLocal();
+    initHostCapture();
+    initPlaySelection();
     initPlayCard();
 }
 export function writeFile(path, contents) {
@@ -64,6 +70,35 @@ export function initCard() {
     window.addEventListener("resize", resize);
     return card;
 }
+// A deck being PLAYED is a game, not a document: dragging across it should move
+// a paddle, not blue-highlight the score, and a long press on a phone should not
+// raise the copy/define callout over the card.
+//
+// It belongs here rather than in a host. Selection is decided inside the deck's
+// own document, so neither the website's iframe nor the app's WebView can reach
+// it from outside -- and doing it once in the SDK covers the play panel,
+// castle.xyz and the feed together.
+//
+// Play mode only: in edit mode the same document hosts kit editors and deck UI,
+// where selecting text is the point. Form fields keep selection either way, so a
+// deck that asks for a name still works.
+function initPlaySelection() {
+    if (isEdit())
+        return;
+    const style = document.createElement("style");
+    style.textContent = `
+    html, body {
+      -webkit-user-select: none;
+      user-select: none;
+      -webkit-touch-callout: none;
+    }
+    input, textarea, [contenteditable=""], [contenteditable="true"] {
+      -webkit-user-select: text;
+      user-select: text;
+    }
+  `;
+    document.head.appendChild(style);
+}
 // Constrains whatever the deck renders into #root to a 5:7 card in play mode.
 // Hosts own max size and padding; the SDK only preserves the card aspect ratio.
 function initPlayCard() {
@@ -85,6 +120,26 @@ function initPlayCard() {
     }
   `;
     document.head.appendChild(style);
+    // Mark whatever this turns into a card, the way `initCard` marks the one it
+    // creates. Anything looking for "the card" -- a capture cropping to it, in
+    // page or headless -- otherwise finds nothing here and has to guess at the
+    // viewport, which is not the same rectangle: standalone chrome insets the
+    // card, so a viewport shot carries a border the card does not have.
+    //
+    // Runs on a timer as well as now because `setup()` is called before a deck
+    // renders, so #root is usually still empty at this point; a deck that mounts
+    // later still gets its card marked.
+    function markCard() {
+        const el = document.querySelector("#root > *");
+        if (el)
+            el.dataset.castleCard = "";
+    }
+    markCard();
+    requestAnimationFrame(markCard);
+    new MutationObserver(markCard).observe(document.documentElement, {
+        childList: true,
+        subtree: true,
+    });
     function resize() {
         const { w, h } = computeCardSize();
         document.documentElement.style.setProperty("--castle-card-w", w + "px");
@@ -240,9 +295,36 @@ function formatConsoleArgs(args) {
     })
         .join(" ");
 }
+// Compositing a card needs html2canvas, and where it comes from decides whether
+// a capture can fail for reasons that have nothing to do with the deck.
+//
+// The serve lends it from its own origin (`castle-web serve`, so: the editor,
+// the dev server, a cloud sandbox) -- same origin, no third party, and it works
+// with no internet at all. Every caller that captures runs against a serve, so
+// this is the path in practice.
+//
+// The CDN is the fallback for a deck with no serve behind it, which today means
+// a published deck -- where nothing captures. Keeping it costs nothing and means
+// a capture from somewhere unforeseen still degrades to "slow" rather than
+// "canvas-only". Loaded once and reused: html2canvas is ~194KB.
+let html2canvasPromise = null;
+function loadHtml2Canvas() {
+    if (!html2canvasPromise) {
+        const local = new URL("/__castle/vendor/html2canvas.js", location.origin)
+            .href;
+        html2canvasPromise = dynamicImport(local)
+            .catch(() => dynamicImport("https://esm.sh/html2canvas"))
+            .catch((err) => {
+            // Don't cache a failure -- a later capture may have a serve, or a network.
+            html2canvasPromise = null;
+            throw err;
+        });
+    }
+    return html2canvasPromise;
+}
 async function captureWithHtml2Canvas(target) {
     try {
-        const mod = (await dynamicImport("https://esm.sh/html2canvas"));
+        const mod = await loadHtml2Canvas();
         const c = await mod.default(target, {
             backgroundColor: null,
             scale: devicePixelRatio,
@@ -266,15 +348,54 @@ function cropCanvasToCard(card, canvas) {
     ctx.drawImage(canvas, dx, dy, canvasRect.width * devicePixelRatio, canvasRect.height * devicePixelRatio);
     return c.toDataURL("image/png");
 }
+// Does the card show anything the canvas didn't draw? A deck is free to put raw
+// DOM in the card -- a HUD, a title, a button -- and that DOM is part of what the
+// player sees, so a canvas-only capture would be a cover that doesn't match the
+// deck. Walks the card for any rendered node outside the canvas: an element with
+// a non-empty box, or visible text.
+function hasContentBesidesCanvas(card, canvas) {
+    const isRenderedBox = (el) => {
+        const style = getComputedStyle(el);
+        if (style.display === "none" ||
+            style.visibility === "hidden" ||
+            style.opacity === "0") {
+            return false;
+        }
+        const rect = el.getBoundingClientRect();
+        return rect.width > 0 && rect.height > 0;
+    };
+    for (const el of Array.from(card.querySelectorAll("*"))) {
+        if (el === canvas || canvas.contains(el))
+            continue;
+        if (isRenderedBox(el))
+            return true;
+    }
+    // Text put straight in the card (or in a zero-box wrapper) renders without any
+    // element of its own to measure.
+    const walker = document.createTreeWalker(card, NodeFilter.SHOW_TEXT);
+    for (let n = walker.nextNode(); n; n = walker.nextNode()) {
+        if ((n.textContent || "").trim())
+            return true;
+    }
+    return false;
+}
 async function captureScreenshot() {
     const card = document.querySelector("#castle-card, [data-castle-card]");
     if (card) {
         const cardCanvas = card.querySelector("canvas");
+        // Cropping the canvas is exact and needs no network, but it only tells the
+        // truth when the canvas IS the card. Otherwise composite the whole card --
+        // html2canvas draws canvases into its output, so nothing is lost by it.
+        if (cardCanvas && !hasContentBesidesCanvas(card, cardCanvas)) {
+            return cropCanvasToCard(card, cardCanvas);
+        }
+        const composited = await captureWithHtml2Canvas(card);
+        if (composited)
+            return composited;
+        // html2canvas is fetched at capture time, so it can fail closed (offline, a
+        // host CSP). A canvas-only cover beats no cover.
         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);
@@ -286,6 +407,36 @@ async function captureScreenshot() {
         return canvas.toDataURL("image/png");
     return captureWithHtml2Canvas(card || document.body);
 }
+// A framing host (the editor shell, for a deck's cover image) asks the deck for
+// a capture instead of reaching into the frame for its canvas: the canvas is
+// only part of what a deck renders, and only the deck can composite the rest.
+// Answers the window that asked, falling back to the parent frame.
+function initHostCapture() {
+    if (typeof window === "undefined" || window.parent === window)
+        return;
+    // A host re-asks while it waits, in case its first request landed before this
+    // handler existed. Same id means same request, so the repeat is dropped rather
+    // than starting a second capture alongside the one already running.
+    const inFlight = new Set();
+    window.addEventListener("message", (event) => {
+        const data = event.data;
+        if (!data || data.type !== HOST_CAPTURE_REQUEST)
+            return;
+        const requestId = typeof data.requestId === "string" ? data.requestId : undefined;
+        if (requestId) {
+            if (inFlight.has(requestId))
+                return;
+            inFlight.add(requestId);
+        }
+        const reply = (dataUrl) => {
+            if (requestId)
+                inFlight.delete(requestId);
+            const target = event.source ?? window.parent;
+            target.postMessage({ type: HOST_CAPTURE_RESULT, requestId, dataUrl, ok: !!dataUrl }, "*");
+        };
+        void captureScreenshot().then(reply, () => reply(null));
+    });
+}
 function connectLocal() {
     fetch("/__castle/ws-port")
         .then((r) => r.json())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-sdk",
-  "version": "0.4.12",
+  "version": "0.4.14",
   "type": "module",
   "main": "dist/castle.js",
   "types": "dist/castle.d.ts",
@@ -10,12 +10,14 @@
       "default": "./dist/castle.js"
     }
   },
-  "//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.",
+  "//host": "host.{js,d.ts} is the host-side executor and leaderboardPanel.{js,d.ts} is the host-side leaderboard UI \u2014 both deliberately NOT exported and NOT packaged. They are vendored into host repos via scripts/copy-host-module.mjs; decks must never receive them.",
   "files": [
     "dist",
     "README.md",
     "!dist/host.js",
-    "!dist/host.d.ts"
+    "!dist/host.d.ts",
+    "!dist/leaderboardPanel.js",
+    "!dist/leaderboardPanel.d.ts"
   ],
   "scripts": {
     "build": "rm -rf dist && tsc",