castle-web-sdk 0.4.9 → 0.4.11

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,8 @@
 export { isEdit } from "./context";
 export { CastleError } from "./errors";
+export { deckPrefixOf, IMPORTS_DIR, IMPORTS_PREFIX, isImportedFile, resolveDeckFile, } from "./files";
+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";

package/dist/castle.js

@@ -1,6 +1,8 @@
 // Castle Web SDK
 export { isEdit } from "./context";
 export { CastleError } from "./errors";
+export { deckPrefixOf, IMPORTS_DIR, IMPORTS_PREFIX, isImportedFile, resolveDeckFile, } from "./files";
+export { Haptics } from "./haptics";
 export { Leaderboard } from "./leaderboard";
 export { Lifecycle } from "./lifecycle";
 export { Pass } from "./passes";

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/files.d.ts

@@ -0,0 +1,15 @@
+export declare const IMPORTS_PREFIX = "@imports/";
+export declare const IMPORTS_DIR = "imports";
+export declare function deckPrefixOf(filePath: string): string;
+/**
+ * Resolve a reference to the key it names in the deck's file map.
+ *
+ * @param ref  the reference as written -- `drawings/rock.pxart` or
+ *             `@imports/someone.pack/drawings/rock.pxart`
+ * @param from the path of the file the reference was written in; a reference in
+ *             a deck's own file resolves against the deck root, one in an
+ *             import's file against that import.
+ */
+export declare function resolveDeckFile(ref: string, from?: string): string;
+/** Whether a path names a file some import owns (rather than the deck's own). */
+export declare function isImportedFile(filePath: string): boolean;

package/dist/files.js

@@ -0,0 +1,52 @@
+// How a deck names a file -- one rule, everywhere a path appears: in JS module
+// specifiers, in a scene's `blueprint`, in a Sprite's `file`, in anything a kit
+// invents later.
+//
+//   drawings/rock.pxart          a file of the deck the REFERENCE lives in
+//   @imports/<alias>/drawings/rock.pxart   a file of that import
+//
+// The unprefixed form is deck-relative, and "the deck" means whichever deck the
+// referencing file belongs to. So a kit's blueprint saying `drawings/cauldron.pxart`
+// means the kit's own drawing whether the kit is the deck being played or an
+// import of it -- the same text keeps meaning the same file after the kit is
+// imported by somebody else. That is what makes a deck publishable as a
+// dependency without rewriting its insides.
+//
+// `@imports/` is the only way to name someone else's file, so a cross-deck
+// reference is visible as one at a glance, and it means the same thing from any
+// depth: imports are flattened into one `imports/` at the deck root, so the
+// prefix is positional in nothing.
+export const IMPORTS_PREFIX = '@imports/';
+// Where imports live on disk, relative to the deck root. `@imports/x/y` is
+// exactly `imports/x/y` -- the alias exists so the reference reads as a
+// cross-deck one and does not depend on where the referencing file sits.
+export const IMPORTS_DIR = 'imports';
+function stripDotSlash(path) {
+    return path.replace(/^\.\//, '');
+}
+// The deck a file belongs to, as a path prefix: `imports/<alias>/` for a file of
+// an import, `''` for one of the deck's own.
+export function deckPrefixOf(filePath) {
+    const match = new RegExp(`^(${IMPORTS_DIR}/[^/]+/)`).exec(filePath ?? '');
+    return match ? match[1] : '';
+}
+/**
+ * Resolve a reference to the key it names in the deck's file map.
+ *
+ * @param ref  the reference as written -- `drawings/rock.pxart` or
+ *             `@imports/someone.pack/drawings/rock.pxart`
+ * @param from the path of the file the reference was written in; a reference in
+ *             a deck's own file resolves against the deck root, one in an
+ *             import's file against that import.
+ */
+export function resolveDeckFile(ref, from = '') {
+    const path = stripDotSlash(String(ref ?? ''));
+    if (path.startsWith(IMPORTS_PREFIX)) {
+        return `${IMPORTS_DIR}/${path.slice(IMPORTS_PREFIX.length)}`;
+    }
+    return deckPrefixOf(stripDotSlash(from)) + path;
+}
+/** Whether a path names a file some import owns (rather than the deck's own). */
+export function isImportedFile(filePath) {
+    return deckPrefixOf(filePath) !== '';
+}

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/package.json

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