@longstoryshort/vtt-sdk 0.2.0 → 0.4.0

package/README.md

@@ -28,13 +28,13 @@ npm install @owlbear-rodeo/sdk
 
 | Import | Contents |
 |--------|----------|
-| `@longstoryshort/vtt-sdk` | Core: types, `createSheetBridge`, `createSheetClient`, `createBridgeSheetSource`, `formatRollMessage` |
+| `@longstoryshort/vtt-sdk` | Core: types, `createRollBridge`, `createSheetClient`, `createBridgeSheetSource`, `formatRollMessage` |
 | `@longstoryshort/vtt-sdk/owlbear` | `OwlbearAdapter`, `syncObrref`, constants |
 
 ## Quick start — bridge side
 
 ```ts
-import { createSheetBridge, createBridgeSheetSource } from '@longstoryshort/vtt-sdk';
+import { createRollBridge, createBridgeSheetSource } from '@longstoryshort/vtt-sdk';
 import { OwlbearAdapter } from '@longstoryshort/vtt-sdk/owlbear';
 
 const adapter = new OwlbearAdapter();
@@ -43,7 +43,7 @@ const source = createBridgeSheetSource({
     allowedOrigins: ['https://longstoryshort.app'],
 });
 
-const dispose = createSheetBridge(source, adapter, {
+const dispose = createRollBridge(source, adapter, {
     messages: {
         connected: '🎲 Sheet connected',
         labelHint: 'Select exactly one token to place a roll label',
@@ -63,11 +63,11 @@ import { createSheetClient } from '@longstoryshort/vtt-sdk';
 const client = createSheetClient();
 
 // emit a roll to the bridge
-client.send({ type: 'DICE_ROLL', payload: { ... } });
+client.send({ type: 'dnd:roll', payload: { ... } });
 
 // receive inbound commands from the bridge
 const unsub = client.onEvent((event) => {
-    if (event.type === 'CAPABILITY_COMMAND') { /* handle damage, conditions, … */ }
+    if (event.type === 'dnd:command') { /* handle damage, conditions, … */ }
 });
 
 // cleanup
@@ -96,12 +96,14 @@ To adapt for your own VTT: copy `bridges/dnd/src/main.ts`, swap `OwlbearAdapter`
 
 ## Protocol events
 
-| Type | Direction | Description |
-|------|-----------|-------------|
-| `DICE_ROLL` | sheet → bridge | A roll result |
-| `MANIFEST` | sheet → bridge | Sheet capabilities at handshake |
-| `HEALTH_CHANGED` | sheet → bridge | HP after an adjust/set |
-| `CAPABILITY_COMMAND` | bridge → sheet | Narrow inbound ops (adjust HP, toggle condition, …) |
+| Type | Status | Direction | Description |
+|------|--------|-----------|-------------|
+| `dnd:roll`     | ✅ stable       | sheet → host | A roll result |
+| `dnd:manifest` | 🧪 reserved     | sheet → host | Sheet capabilities at handshake |
+| `dnd:health`   | 🧪 reserved     | sheet → host | HP after an adjust/set |
+| `dnd:command`  | 🧪 reserved     | host → sheet | Narrow inbound ops (adjust HP, toggle condition, …) |
+
+Reserved events are typed and functional — the sheet implements them — but the bridge-side wiring is considered experimental API and may change. Wire them directly via `BridgeSheetSource.onEvent` rather than through `createRollBridge`.
 
 ## License
 

package/dist/adapters/owlbear/index.d.ts

@@ -1,4 +1,5 @@
-import { V as VTTAdapter, a as VTTUser, S as SheetEvent, N as NotifyVariant } from '../../types-DQndRf3e.js';
+import { V as VTTAdapter, a as VTTUser, S as SheetEvent, N as NotifyVariant } from '../../types-w2_82sqo.js';
+import * as _owlbear_rodeo_sdk from '@owlbear-rodeo/sdk';
 
 /**
  * Owlbear Rodeo implementation of {@link VTTAdapter}.
@@ -19,7 +20,6 @@ declare class OwlbearAdapter implements VTTAdapter {
     get isAvailable(): boolean;
     ready(): Promise<boolean>;
     private init;
-    private loadSdk;
     getSessionId(): string | undefined;
     getCurrentUser(): VTTUser | undefined;
     broadcast(event: SheetEvent): void;
@@ -48,4 +48,36 @@ declare const LABEL_METADATA_KEY = "rodeo.lss/label";
 /** How long a roll label floats over a token before it is removed. */
 declare const DEFAULT_LABEL_TTL_MS = 4000;
 
-export { BROADCAST_CHANNEL, DEFAULT_LABEL_TTL_MS, LABEL_METADATA_KEY, OwlbearAdapter, syncObrref };
+interface ObrLike {
+    onReady(cb: () => void): void;
+}
+/** Promisifies `OBR.onReady` — resolves once the OBR_READY handshake completes. */
+declare function whenObrReady(obr: ObrLike): Promise<void>;
+
+type OwlbearSdk = typeof _owlbear_rodeo_sdk;
+/**
+ * The window shape expected by the SDK preload contract.
+ * Set `__lssObrSdk` at the app entry (before any navigation) so
+ * `loadObrSdk` can reuse the already-imported module and avoid missing
+ * the one-shot OBR_READY handshake.
+ */
+interface ObrPreloadWindow {
+    __lssObrSdk?: OwlbearSdk;
+}
+/**
+ * Call this at the bridge entry module — before any client-side navigation —
+ * to stash the already-imported OBR SDK so `loadObrSdk` can find it.
+ */
+declare function preloadObrSdk(sdk: OwlbearSdk): void;
+/**
+ * Retrieves the OBR SDK for use inside an OBR extension frame.
+ *
+ * Prefers the copy stashed by `preloadObrSdk` (imported early enough to catch
+ * the one-shot OBR_READY handshake). Falls back to a dynamic import if the
+ * stash is absent, with a warning — the dynamic path may miss OBR_READY.
+ *
+ * Returns `null` when not running in a browser or when the import fails.
+ */
+declare function loadObrSdk(): Promise<OwlbearSdk | null>;
+
+export { BROADCAST_CHANNEL, DEFAULT_LABEL_TTL_MS, LABEL_METADATA_KEY, type ObrPreloadWindow, OwlbearAdapter, loadObrSdk, preloadObrSdk, syncObrref, whenObrReady };

package/dist/adapters/owlbear/index.js

@@ -44,8 +44,44 @@ function syncObrref() {
   }
 }
 
-// src/adapters/owlbear/OwlbearAdapter.ts
+// src/adapters/owlbear/loadObrSdk.ts
 var DEV2 = process.env["NODE_ENV"] !== "production";
+function preloadObrSdk(sdk) {
+  window.__lssObrSdk = sdk;
+}
+async function loadObrSdk() {
+  if (typeof window === "undefined") {
+    return null;
+  }
+  const host = window;
+  for (let i = 0; i < 10 && !host.__lssObrSdk; i += 1) {
+    await new Promise((resolve) => {
+      window.setTimeout(resolve, 50);
+    });
+  }
+  if (host.__lssObrSdk) {
+    return host.__lssObrSdk;
+  }
+  if (DEV2) {
+    console.warn("[LSS/OBR] no preloaded SDK \u2014 importing now (may miss OBR_READY)");
+  }
+  try {
+    return await import('@owlbear-rodeo/sdk');
+  } catch (error) {
+    console.error("[LSS/OBR] SDK import failed:", error);
+    return null;
+  }
+}
+
+// src/adapters/owlbear/whenObrReady.ts
+function whenObrReady(obr) {
+  return new Promise((resolve) => {
+    obr.onReady(resolve);
+  });
+}
+
+// src/adapters/owlbear/OwlbearAdapter.ts
+var DEV3 = process.env["NODE_ENV"] !== "production";
 var NOTIFY_VARIANT = {
   info: "INFO",
   success: "SUCCESS",
@@ -73,13 +109,13 @@ var OwlbearAdapter = class {
       return false;
     }
     syncObrref();
-    const sdk = await this.loadSdk();
+    const sdk = await loadObrSdk();
     if (!sdk) {
       return false;
     }
     this.sdk = sdk;
     this.obr = sdk.default;
-    if (DEV2) {
+    if (DEV3) {
       console.info(
         "[LSS/OBR] init \u2014 isAvailable:",
         this.obr.isAvailable,
@@ -88,18 +124,16 @@ var OwlbearAdapter = class {
       );
     }
     if (!this.obr.isAvailable) {
-      if (DEV2) {
+      if (DEV3) {
         console.warn("[LSS/OBR] not embedded (origin empty) \u2014 obrref missing at SDK load.");
       }
       return false;
     }
-    if (DEV2) {
+    if (DEV3) {
       console.info("[LSS/OBR] awaiting onReady (isReady =", this.obr.isReady, ")");
     }
-    await new Promise((resolve) => {
-      this.obr.onReady(resolve);
-    });
-    if (DEV2) {
+    await whenObrReady(this.obr);
+    if (DEV3) {
       console.info("[LSS/OBR] onReady fired \u2014 fetching player\u2026");
     }
     if (this.disposed) {
@@ -112,31 +146,11 @@ var OwlbearAdapter = class {
       this.obr.player.getRole()
     ]);
     this.user = { id, name, role: role === "GM" ? "gm" : "player" };
-    if (DEV2) {
+    if (DEV3) {
       console.info("[LSS/OBR] ready \u2014 room:", this.sessionId, "user:", this.user);
     }
     return true;
   }
-  async loadSdk() {
-    const host = window;
-    for (let i = 0; i < 10 && !host.__lssObrSdk; i += 1) {
-      await new Promise((resolve) => {
-        window.setTimeout(resolve, 50);
-      });
-    }
-    if (host.__lssObrSdk) {
-      return host.__lssObrSdk;
-    }
-    if (DEV2) {
-      console.warn("[LSS/OBR] no preloaded SDK \u2014 importing now (may miss OBR_READY)");
-    }
-    try {
-      return await import('@owlbear-rodeo/sdk');
-    } catch (error) {
-      console.error("[LSS/OBR] SDK import failed:", error);
-      return null;
-    }
-  }
   getSessionId() {
     return this.sessionId;
   }
@@ -168,14 +182,14 @@ var OwlbearAdapter = class {
     try {
       const selection = await obr.player.getSelection();
       if (!selection || selection.length !== 1) {
-        if (DEV2) {
+        if (DEV3) {
           console.warn("[OwlbearAdapter] label skipped \u2014 selected tokens:", selection?.length ?? 0);
         }
         return false;
       }
       const [token] = await obr.scene.items.getItems(selection);
       if (!token) {
-        if (DEV2) {
+        if (DEV3) {
           console.warn("[OwlbearAdapter] label skipped \u2014 selected item not found in scene");
         }
         return false;
@@ -188,7 +202,7 @@ var OwlbearAdapter = class {
       }, ttlMs);
       return true;
     } catch (error) {
-      if (DEV2) {
+      if (DEV3) {
         console.warn("[OwlbearAdapter] label error:", error);
       }
       return false;
@@ -199,4 +213,4 @@ var OwlbearAdapter = class {
   }
 };
 
-export { BROADCAST_CHANNEL, DEFAULT_LABEL_TTL_MS, LABEL_METADATA_KEY, OwlbearAdapter, syncObrref };
+export { BROADCAST_CHANNEL, DEFAULT_LABEL_TTL_MS, LABEL_METADATA_KEY, OwlbearAdapter, loadObrSdk, preloadObrSdk, syncObrref, whenObrReady };

package/dist/index.d.ts

@@ -1,19 +1,29 @@
-import { b as SheetSource, V as VTTAdapter, c as SheetBridgeOptions, d as SheetClientOptions, e as SheetClient, C as CapabilityManifest, S as SheetEvent, M as MessageHost, D as DiceRollPayload, N as NotifyVariant } from './types-DQndRf3e.js';
-export { f as CapabilityDescriptor, g as CapabilityOpAddTag, h as CapabilityOpAdjust, i as CapabilityOpName, j as CapabilityOpRemoveTag, k as CapabilityOpRequestRoll, l as CapabilityOpSet, m as CapabilityOpToggle, n as CapabilityOperation, H as HealthChangedPayload, o as MessageTarget, p as SheetBridgeMessages, a as VTTUser, q as VTTUserRole } from './types-DQndRf3e.js';
+import { b as SheetSource, V as VTTAdapter, R as RollBridgeOptions, c as SheetClientOptions, d as SheetClient, C as CapabilityManifest, S as SheetEvent, M as MessageHost, D as DiceRollPayload, N as NotifyVariant } from './types-w2_82sqo.js';
+export { e as CapabilityDescriptor, f as CapabilityOpAddTag, g as CapabilityOpAdjust, h as CapabilityOpName, i as CapabilityOpRemoveTag, j as CapabilityOpRequestRoll, k as CapabilityOpSet, l as CapabilityOpToggle, m as CapabilityOperation, H as HealthChangedPayload, n as MessageTarget, o as RollBridgeMessages, a as VTTUser, p as VTTUserRole } from './types-w2_82sqo.js';
 
 /**
- * Wires a host {@link SheetSource} to a {@link VTTAdapter}. This is the whole
- * integration in one place, and it knows nothing about any specific sheet app or
- * any specific VTT:
+ * Minimum sandbox tokens required on the sheet iframe.
+ * `allow-same-origin` is essential — without it the sheet gets an opaque origin
+ * and auth (cookies / localStorage) breaks entirely.
+ */
+declare const SHEET_IFRAME_SANDBOX = "allow-same-origin allow-scripts allow-popups allow-popups-to-escape-sandbox allow-forms allow-modals";
+
+/**
+ * The default roll bridge — one opinionated policy, not the full protocol.
  *
+ * Wires {@link SheetSource} → {@link VTTAdapter} for the `dnd:roll` event only:
  *  - a roll on the sheet → local toast for the roller + broadcast to other
  *    clients + a transient label over the roller's selected token;
  *  - a roll broadcast by another client → local toast.
  *
+ * Inbound capability wiring (`dnd:command`, `dnd:manifest`, `dnd:health`) is
+ * deliberately out of scope here — wire those directly via
+ * {@link BridgeSheetSource.onEvent} when your bridge needs them.
+ *
  * Returns a dispose fn that tears down every subscription it created. The
  * adapter is left untouched — it may be shared and longer-lived than the bridge.
  */
-declare function createSheetBridge(source: SheetSource, adapter: VTTAdapter, options?: SheetBridgeOptions): () => void;
+declare function createRollBridge(source: SheetSource, adapter: VTTAdapter, options?: RollBridgeOptions): () => void;
 
 /**
  * Sheet-side half of the postMessage transport. The character sheet (running in
@@ -43,7 +53,7 @@ interface BridgeSheetSourceOptions {
     /** Origin to post inbound commands to. Default `'*'`. */
     targetOrigin?: string;
 }
-/** A `SheetSource` (for `createSheetBridge`) plus raw access and inbound `send`. */
+/** A `SheetSource` (for `createRollBridge`) plus raw access and inbound `send`. */
 interface BridgeSheetSource extends SheetSource {
     /** Subscribe to the sheet's capability manifest (sent once at handshake). Returns an unsubscribe fn. */
     onManifest(handler: (manifest: CapabilityManifest) => void): () => void;
@@ -56,7 +66,7 @@ interface BridgeSheetSource extends SheetSource {
 /**
  * Bridge-side half of the postMessage transport. Runs in the bridge frame (the
  * VTT extension), listens to the embedded sheet iframe, and exposes a
- * `SheetSource` so `createSheetBridge` can drive the VTT adapter — without the
+ * `SheetSource` so `createRollBridge` can drive the VTT adapter — without the
  * bridge ever touching the sheet's internals.
  *
  * `contentWindow` is read live on every message/send, so it survives the sheet
@@ -69,4 +79,4 @@ declare function formatRollMessage(payload: DiceRollPayload): string;
 /** Maps a roll's crit state onto a toast variant. */
 declare function rollVariant(payload: DiceRollPayload): NotifyVariant;
 
-export { type BridgeSheetSource, type BridgeSheetSourceOptions, CapabilityManifest, DiceRollPayload, MessageHost, NotifyVariant, SheetBridgeOptions, SheetClient, SheetClientOptions, SheetEvent, type SheetFrameRef, SheetSource, VTTAdapter, createBridgeSheetSource, createSheetBridge, createSheetClient, formatRollMessage, rollVariant };
+export { type BridgeSheetSource, type BridgeSheetSourceOptions, CapabilityManifest, DiceRollPayload, MessageHost, NotifyVariant, RollBridgeOptions, SHEET_IFRAME_SANDBOX, SheetClient, SheetClientOptions, SheetEvent, type SheetFrameRef, SheetSource, VTTAdapter, createBridgeSheetSource, createRollBridge, createSheetClient, formatRollMessage, rollVariant };

package/dist/index.js

@@ -1,3 +1,6 @@
+// src/constants.ts
+var SHEET_IFRAME_SANDBOX = "allow-same-origin allow-scripts allow-popups allow-popups-to-escape-sandbox allow-forms allow-modals";
+
 // src/formatRoll.ts
 function formatRollMessage(payload) {
   let crit = "";
@@ -20,12 +23,12 @@ function rollVariant(payload) {
   return "info";
 }
 
-// src/createSheetBridge.ts
+// src/createRollBridge.ts
 var DEFAULT_MESSAGES = {
   connected: "\u{1F3B2} Sheet connected to the table",
   labelHint: "No label placed \u2014 select exactly one of your tokens on the map"
 };
-function createSheetBridge(source, adapter, options = {}) {
+function createRollBridge(source, adapter, options = {}) {
   const messages = { ...DEFAULT_MESSAGES, ...options.messages };
   const cleanups = [];
   let cancelled = false;
@@ -185,4 +188,4 @@ function createBridgeSheetSource(options) {
   };
 }
 
-export { createBridgeSheetSource, createSheetBridge, createSheetClient, formatRollMessage, rollVariant };
+export { SHEET_IFRAME_SANDBOX, createBridgeSheetSource, createRollBridge, createSheetClient, formatRollMessage, rollVariant };

package/dist/{types-DQndRf3e.d.ts → types-w2_82sqo.d.ts}

@@ -29,6 +29,7 @@ interface DiceRollPayload {
 }
 type CapabilityOpName = 'adjust' | 'set' | 'toggle' | 'add-tag' | 'remove-tag' | 'request-roll';
 /**
+ * @experimental
  * adjust: apply a signed delta to a numeric capability.
  * Sign convention: negative delta = subtract (damage), positive delta = add (heal/gain).
  * The sheet applies its own rules (temp HP absorption, resistances, clamping).
@@ -38,18 +39,19 @@ interface CapabilityOpAdjust {
     capabilityId: string;
     delta: number;
 }
-/** set: overwrite a capability value outright. */
+/** @experimental set: overwrite a capability value outright. */
 interface CapabilityOpSet {
     op: 'set';
     capabilityId: string;
     value: number | boolean | string;
 }
-/** toggle: flip a boolean capability. */
+/** @experimental toggle: flip a boolean capability. */
 interface CapabilityOpToggle {
     op: 'toggle';
     capabilityId: string;
 }
 /**
+ * @experimental
  * add-tag: append a label to a tag-track capability (e.g. a condition).
  * Idempotent — if the value is already present, the sheet must ignore the command.
  */
@@ -59,6 +61,7 @@ interface CapabilityOpAddTag {
     value: string;
 }
 /**
+ * @experimental
  * remove-tag: remove a label from a tag-track capability.
  * Removes the first occurrence. Assumes a well-behaved set (no duplicates in DnD5e conditions).
  */
@@ -67,7 +70,7 @@ interface CapabilityOpRemoveTag {
     capabilityId: string;
     value: string;
 }
-/** request-roll: ask the sheet to roll a d20 check against an optional DC. */
+/** @experimental request-roll: ask the sheet to roll a d20 check against an optional DC. */
 interface CapabilityOpRequestRoll {
     op: 'request-roll';
     capabilityId: string;
@@ -75,12 +78,13 @@ interface CapabilityOpRequestRoll {
     dc?: number;
 }
 type CapabilityOperation = CapabilityOpAdjust | CapabilityOpSet | CapabilityOpToggle | CapabilityOpAddTag | CapabilityOpRemoveTag | CapabilityOpRequestRoll;
-/** One capability entry in the sheet manifest. */
+/** @experimental One capability entry in the sheet manifest. */
 interface CapabilityDescriptor {
     id: string;
     operations: CapabilityOpName[];
 }
 /**
+ * @experimental
  * Capability manifest — the sheet's public declaration of what the host may do.
  * Sent outbound by the sheet at handshake time; the host reads it to know which
  * dnd:command operations are valid for this member.
@@ -91,7 +95,7 @@ interface CapabilityManifest {
     sheetSystem: string;
     capabilities: CapabilityDescriptor[];
 }
-/** Outbound fact: HP values after the sheet has applied an adjust/set command. */
+/** @experimental Outbound fact: HP values after the sheet has applied an adjust/set command. */
 interface HealthChangedPayload {
     characterId: string;
     current: number;
@@ -101,19 +105,29 @@ interface HealthChangedPayload {
 /**
  * Everything that crosses the sheet↔VTT boundary.
  *
- * Outbound (sheet → host):  dnd:roll · dnd:manifest · dnd:health
- * Inbound  (host → sheet):  dnd:command
+ * | Type | Status | Direction |
+ * |------|--------|-----------|
+ * | `dnd:roll`     | stable       | sheet → host |
+ * | `dnd:manifest` | experimental | sheet → host |
+ * | `dnd:health`   | experimental | sheet → host |
+ * | `dnd:command`  | experimental | host → sheet |
  */
 type SheetEvent = {
     type: 'dnd:roll';
     payload: DiceRollPayload;
-} | {
+}
+/** @experimental */
+ | {
     type: 'dnd:manifest';
     payload: CapabilityManifest;
-} | {
+}
+/** @experimental */
+ | {
     type: 'dnd:health';
     payload: HealthChangedPayload;
-} | {
+}
+/** @experimental */
+ | {
     type: 'dnd:command';
     payload: CapabilityOperation;
 };
@@ -127,14 +141,14 @@ interface SheetSource {
     onRoll(handler: (roll: DiceRollPayload) => void): () => void;
 }
 /** Human-facing strings surfaced by the bridge — override to localize. */
-interface SheetBridgeMessages {
+interface RollBridgeMessages {
     /** Toast shown once the sheet connects to the table. */
     connected: string;
     /** Toast shown to the roller when a token label could not be placed. */
     labelHint: string;
 }
-interface SheetBridgeOptions {
-    messages?: Partial<SheetBridgeMessages>;
+interface RollBridgeOptions {
+    messages?: Partial<RollBridgeMessages>;
 }
 /**
  * The seam every VTT implements. The sheet talks only to this interface; each
@@ -204,4 +218,4 @@ interface SheetClient {
     dispose(): void;
 }
 
-export type { CapabilityManifest as C, DiceRollPayload as D, HealthChangedPayload as H, MessageHost as M, NotifyVariant as N, SheetEvent as S, VTTAdapter as V, VTTUser as a, SheetSource as b, SheetBridgeOptions as c, SheetClientOptions as d, SheetClient as e, CapabilityDescriptor as f, CapabilityOpAddTag as g, CapabilityOpAdjust as h, CapabilityOpName as i, CapabilityOpRemoveTag as j, CapabilityOpRequestRoll as k, CapabilityOpSet as l, CapabilityOpToggle as m, CapabilityOperation as n, MessageTarget as o, SheetBridgeMessages as p, VTTUserRole as q };
+export type { CapabilityManifest as C, DiceRollPayload as D, HealthChangedPayload as H, MessageHost as M, NotifyVariant as N, RollBridgeOptions as R, SheetEvent as S, VTTAdapter as V, VTTUser as a, SheetSource as b, SheetClientOptions as c, SheetClient as d, CapabilityDescriptor as e, CapabilityOpAddTag as f, CapabilityOpAdjust as g, CapabilityOpName as h, CapabilityOpRemoveTag as i, CapabilityOpRequestRoll as j, CapabilityOpSet as k, CapabilityOpToggle as l, CapabilityOperation as m, MessageTarget as n, RollBridgeMessages as o, VTTUserRole as p };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@longstoryshort/vtt-sdk",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Embed a longstoryshort.app character sheet in any virtual tabletop via iframe and postMessage",
   "license": "MIT",
   "type": "module",