castle-web-sdk 0.4.8 → 0.4.10

package/README.md

@@ -20,6 +20,7 @@ import { setup, initCard, Storage, Leaderboard } from "castle-web-sdk";
 - [User](#user)
 - [Pass](#pass)
 - [Portal](#portal)
+- [Haptics](#haptics)
 - [Lifecycle](#lifecycle)
 - [Setup](#setup)
 - [CastleError](#castleerror)
@@ -269,6 +270,41 @@ link.addEventListener("pointerenter", () => {
 });
 ```
 
+## Haptics
+
+`Haptics` plays a short device vibration ("buzz") for tactile feedback —
+a tap confirmation, a success chime, an error shake. The host owns the
+effect: the Castle mobile app plays a native haptic, the website uses the
+browser's vibration API where available, and the dev server or an
+unsupported device does nothing.
+
+### `Haptics.play(style): Promise<HapticsResult>`
+
+Plays a haptic in one of seven styles:
+
+- `'light'`, `'medium'`, `'heavy'` — impact taps of increasing strength.
+- `'selection'` — a light tick, e.g. moving through options.
+- `'success'`, `'warning'`, `'error'` — notification patterns.
+
+Usually you don't await it — fire it and move on:
+
+```js
+button.onclick = () => {
+  Haptics.play("light");
+  doTheThing();
+};
+```
+
+The returned `HapticsResult` has a `status`, if you want to branch on it:
+
+- `'triggered'` — the host played (or accepted) the haptic.
+- `'unavailable'` — this host or device can't play haptics (e.g. the dev
+  server, or a browser with no vibration support). Nothing was played.
+
+Haptics respect the player's settings — if a player has muted haptics,
+`play` does nothing and resolves `'unavailable'`. Rapid repeated calls may
+be coalesced, so it's safe to call on frequent events.
+
 ## Lifecycle
 
 `Lifecycle` tells the host when the deck has painted its first frame, so

package/dist/castle.d.ts

@@ -1,5 +1,7 @@
 export { isEdit } from "./context";
 export { CastleError } from "./errors";
+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 { Lifecycle } from "./lifecycle";
@@ -8,7 +10,8 @@ export { Pass } from "./passes";
 export type { CastlePassApi, PassOfferResult, PassOfferStatus, } from "./passes";
 export { Portal } from "./portal";
 export type { CastlePortalApi, PortalOpenResult, PortalOpenStatus, PortalPrefetchResult, PortalPrefetchStatus, } from "./portal";
-export { CARD_RATIO, initCard, onBeforeRestart, setup, writeFile } from "./runtime";
+export { CARD_RATIO, initCard, onBeforeRestart, onFilesChanged, onSaveReloadState, requestReload, setup, takeReloadState, writeFile, } from "./runtime";
+export type { FileChange, FilesChangedEvent } from "./runtime";
 export { SharedStorage, Storage } from "./storage";
 export { Time } from "./time";
 export type { CastleClockZone, CastleDateParts, CastleTimeApi } from "./time";

package/dist/castle.js

@@ -1,11 +1,12 @@
 // Castle Web SDK
 export { isEdit } from "./context";
 export { CastleError } from "./errors";
+export { Haptics } from "./haptics";
 export { Leaderboard } from "./leaderboard";
 export { Lifecycle } from "./lifecycle";
 export { Pass } from "./passes";
 export { Portal } from "./portal";
-export { CARD_RATIO, initCard, onBeforeRestart, setup, writeFile } from "./runtime";
+export { CARD_RATIO, initCard, onBeforeRestart, onFilesChanged, onSaveReloadState, requestReload, setup, takeReloadState, writeFile, } from "./runtime";
 export { SharedStorage, Storage } from "./storage";
 export { Time } from "./time";
 export { User } from "./user";

package/dist/commands.d.ts

@@ -32,6 +32,11 @@ export type PortalPrefetchStatus = "prefetching" | "rejected" | "unavailable";
 export interface PortalPrefetchResult {
     status: PortalPrefetchStatus;
 }
+export type HapticStyle = "light" | "medium" | "heavy" | "selection" | "success" | "warning" | "error";
+export type HapticsStatus = "triggered" | "unavailable";
+export interface HapticsResult {
+    status: HapticsStatus;
+}
 export interface CommandParams {
     "deckStorage.load": Record<string, never>;
     "deckStorage.update": {
@@ -71,6 +76,9 @@ export interface CommandParams {
     "portal.prefetch": {
         targetDeckId: string;
     };
+    "haptics.play": {
+        style: HapticStyle;
+    };
 }
 export interface CommandResult {
     "deckStorage.load": {
@@ -109,6 +117,7 @@ export interface CommandResult {
     "pass.offer": PassOfferResult;
     "portal.open": PortalOpenResult;
     "portal.prefetch": PortalPrefetchResult;
+    "haptics.play": HapticsResult;
 }
 export type CommandName = keyof CommandParams;
 export interface SerializedCommandError {

package/dist/haptics.d.ts

@@ -0,0 +1,6 @@
+import type { HapticStyle, HapticsResult } from "./commands";
+export type { HapticStyle, HapticsResult, HapticsStatus } from "./commands";
+export interface CastleHapticsApi {
+    play(style: HapticStyle): Promise<HapticsResult>;
+}
+export declare const Haptics: CastleHapticsApi;

package/dist/haptics.js

@@ -0,0 +1,36 @@
+// Haptics — a deck-facing capability for playing a device haptic (a "buzz").
+// Like pass and portal, the deck stays capability-AGNOSTIC: it asks for a
+// haptic and gets back one normalized outcome regardless of platform. The host
+// owns the effect:
+//   - mobile app : plays a native haptic (Taptic Engine / VibrationEffect),
+//                  subject to the host's own rate-limiting and device support
+//   - web player : best-effort navigator.vibrate; `unavailable` where the
+//                  browser has no vibration API (e.g. iOS Safari)
+//   - dev CLI    : no host handler, so `unavailable`
+// A haptic is a fleeting device effect, not deck-scoped state, so unlike
+// pass/portal the host requires no deckId. Decks usually fire-and-forget (don't
+// await); the returned status just says whether the host could play it.
+import { CastleError } from "./errors";
+import { hostRequest } from "./transport";
+const HAPTIC_STYLES = [
+    "light",
+    "medium",
+    "heavy",
+    "selection",
+    "success",
+    "warning",
+    "error",
+];
+export const Haptics = {
+    play,
+};
+async function play(style) {
+    if (!HAPTIC_STYLES.includes(style)) {
+        throw new CastleError({
+            code: "INVALID_ARGUMENT",
+            message: `Haptics.play style must be one of: ${HAPTIC_STYLES.join(", ")}.`,
+            operation: "Haptics.play",
+        });
+    }
+    return hostRequest("haptics.play", { style });
+}

package/dist/runtime.d.ts

@@ -7,9 +7,29 @@ interface LocalResponse {
     error?: string;
     [key: string]: unknown;
 }
+export interface FileChange {
+    /** Deck-relative POSIX path. */
+    path: string;
+    event: "add" | "change" | "delete";
+    /**
+     * Deck-relative paths affected via the Vite import graph: the changed file
+     * itself (when imported by anything) plus every transitive importer. Empty
+     * when the file isn't part of the module graph.
+     */
+    affected: string[];
+}
+export interface FilesChangedEvent {
+    changes: FileChange[];
+    /** Union of every change's path + affected set, deduped. */
+    affected: string[];
+}
 export declare function setup(): void;
 export declare function writeFile(path: string, contents: string): Promise<LocalResponse>;
 export declare function initCard(): HTMLDivElement;
 export declare function sendLocalCommand<C extends CommandName>(command: C, params: CommandParams[C]): Promise<CommandResponseEnvelope>;
+export declare function onFilesChanged(listener: (event: FilesChangedEvent) => void): () => void;
 export declare function onBeforeRestart(hook: () => void | Promise<void>): () => void;
+export declare function onSaveReloadState(key: string, save: () => unknown): () => void;
+export declare function takeReloadState<T = unknown>(key: string): T | null;
+export declare function requestReload(): void;
 export {};

package/dist/runtime.js

@@ -342,7 +342,10 @@ function handleLocalMessage(msg) {
         });
     }
     else if (msg.type === "restart") {
-        scheduleRestart();
+        scheduleReload(RESTART_DEBOUNCE_MS);
+    }
+    else if (msg.type === "files_changed") {
+        dispatchFilesChanged(msg);
     }
     else if (msg.type === "write_file_response") {
         resolveLocalRequest(msg);
@@ -351,18 +354,106 @@ function handleLocalMessage(msg) {
         resolveLocalCommand(msg);
     }
 }
+// Files-changed listeners, registered by consumers (the kit engine, editors).
+// The SDK only delivers the event; deciding what to re-read or reload is the
+// consumer's job.
+const filesChangedListeners = new Set();
+export function onFilesChanged(listener) {
+    filesChangedListeners.add(listener);
+    return () => filesChangedListeners.delete(listener);
+}
+function dispatchFilesChanged(msg) {
+    const rawChanges = Array.isArray(msg.changes) ? msg.changes : [];
+    const changes = [];
+    for (const raw of rawChanges) {
+        if (typeof raw?.path !== "string")
+            continue;
+        const event = raw.event;
+        if (event !== "add" && event !== "change" && event !== "delete")
+            continue;
+        changes.push({
+            path: raw.path,
+            event,
+            affected: Array.isArray(raw.affected)
+                ? raw.affected.filter((p) => typeof p === "string")
+                : [],
+        });
+    }
+    if (changes.length === 0)
+        return;
+    const affected = Array.isArray(msg.affected)
+        ? msg.affected.filter((p) => typeof p === "string")
+        : [];
+    const event = { changes, affected };
+    for (const listener of filesChangedListeners) {
+        try {
+            listener(event);
+        }
+        catch {
+            // one consumer's failure shouldn't starve the others
+        }
+    }
+}
 // Restart (from `castle-web restart` / task agents) is debounced so a burst
 // of reload requests -- several tasks finishing close together -- produces
 // one reload. Before reloading, registered hooks run (the kit editor flushes
-// its debounced unsaved edits there) so in-flight work isn't lost.
+// its debounced unsaved edits there, save-state hooks stash their state) so
+// in-flight work isn't lost.
 const RESTART_DEBOUNCE_MS = 1500;
+// Consumer-requested reloads (a code file changed) coalesce on a short window:
+// the serve already batched the fs events, so this only folds multiple
+// consumers requesting at once.
+const REQUEST_RELOAD_DEBOUNCE_MS = 250;
 let restartTimer = null;
 const beforeRestartHooks = new Set();
 export function onBeforeRestart(hook) {
     beforeRestartHooks.add(hook);
     return () => beforeRestartHooks.delete(hook);
 }
-function scheduleRestart() {
+// Save-state hooks: consumers register a saver keyed by a stable string; right
+// before a reload every saver runs and its value is stashed in sessionStorage.
+// After the reload the consumer calls takeReloadState(key) to pick it back up.
+// Simple stash — enough for editor selection / lightweight runtime state.
+const RELOAD_STATE_PREFIX = "castle-reload-state:";
+const reloadStateSavers = new Map();
+export function onSaveReloadState(key, save) {
+    reloadStateSavers.set(key, save);
+    return () => {
+        if (reloadStateSavers.get(key) === save)
+            reloadStateSavers.delete(key);
+    };
+}
+export function takeReloadState(key) {
+    try {
+        const raw = sessionStorage.getItem(RELOAD_STATE_PREFIX + key);
+        if (raw === null)
+            return null;
+        sessionStorage.removeItem(RELOAD_STATE_PREFIX + key);
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function stashReloadState() {
+    for (const [key, save] of reloadStateSavers) {
+        try {
+            const value = save();
+            if (value === undefined)
+                continue;
+            sessionStorage.setItem(RELOAD_STATE_PREFIX + key, JSON.stringify(value));
+        }
+        catch {
+            // a failed saver shouldn't block the reload
+        }
+    }
+}
+// Reload this page after honoring the save hooks. Consumers call this when a
+// files-changed event tells them code they run on has changed.
+export function requestReload() {
+    scheduleReload(REQUEST_RELOAD_DEBOUNCE_MS);
+}
+function scheduleReload(delayMs) {
     if (restartTimer !== null)
         clearTimeout(restartTimer);
     restartTimer = setTimeout(() => {
@@ -373,9 +464,10 @@ function scheduleRestart() {
             catch {
                 // a failed flush shouldn't block the reload
             }
+            stashReloadState();
             location.reload();
         })();
-    }, RESTART_DEBOUNCE_MS);
+    }, delayMs);
 }
 function localWsUrl(path) {
     const url = new URL(path, location.href);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-sdk",
-  "version": "0.4.8",
+  "version": "0.4.10",
   "type": "module",
   "main": "dist/castle.js",
   "types": "dist/castle.d.ts",