@longstoryshort/vtt-sdk 0.3.0 → 0.5.0

package/README.md

@@ -1,15 +1,15 @@
 # @longstoryshort/vtt-sdk
 
-Embed a [longstoryshort.app](https://longstoryshort.app) character sheet in any virtual tabletop (VTT) via iframe and postMessage.
+Embed a [longstoryshort.app](https://longstoryshort.app) character sheet in any virtual tabletop via iframe and postMessage.
 
 ## How it works
 
-The SDK implements a postMessage-based protocol that lets a VTT extension (the "bridge") embed the LSS sheet in a nested iframe and receive dice rolls, manifests, and other events — without ever reading the sheet's DOM, cookies, or auth token.
+The sheet and your VTT run at different origins. They communicate only via `window.postMessage` — your code never reads the sheet's DOM, cookies, or auth token.
 
 ```
-OBR / Foundry / … ──► [bridge page, FOREIGN origin]
-                           │  embeds iframe ↓   ← trust boundary (postMessage only)
-                           └► [LSS sheet, lss origin]
+Your page (your origin)
+  └── LSS sheet iframe (longstoryshort.app)
+        └── postMessage ──→ your page
 ```
 
 ## Installation
@@ -18,7 +18,7 @@ OBR / Foundry / … ──► [bridge page, FOREIGN origin]
 npm install @longstoryshort/vtt-sdk
 ```
 
-The Owlbear adapter is an optional peer dependency:
+For Owlbear Rodeo, also install the peer dependency:
 
 ```sh
 npm install @owlbear-rodeo/sdk
@@ -28,82 +28,64 @@ npm install @owlbear-rodeo/sdk
 
 | Import | Contents |
 |--------|----------|
-| `@longstoryshort/vtt-sdk` | Core: types, `createRollBridge`, `createSheetClient`, `createBridgeSheetSource`, `formatRollMessage` |
-| `@longstoryshort/vtt-sdk/owlbear` | `OwlbearAdapter`, `syncObrref`, constants |
+| `@longstoryshort/vtt-sdk` | Core: protocol types, `createBridgeSheetSource`, `createSheetClient`, `formatRollMessage`, `SHEET_IFRAME_SANDBOX` |
+| `@longstoryshort/vtt-sdk/owlbear` | `OwlbearAdapter`, `ObrAdapter`, OBR bootstrap helpers |
 
-## Quick start — bridge side
+## Quick start
 
 ```ts
-import { createRollBridge, createBridgeSheetSource } from '@longstoryshort/vtt-sdk';
-import { OwlbearAdapter } from '@longstoryshort/vtt-sdk/owlbear';
+import { createBridgeSheetSource, SHEET_IFRAME_SANDBOX, formatRollMessage, rollVariant } from '@longstoryshort/vtt-sdk';
 
-const adapter = new OwlbearAdapter();
+// Embed the sheet
+const iframe = document.createElement('iframe');
+iframe.src = 'https://longstoryshort.app/iframe/characters/list/';
+iframe.setAttribute('sandbox', SHEET_IFRAME_SANDBOX);
+iframe.setAttribute('allow', 'clipboard-write');
+iframe.style.cssText = 'border:none;width:100%;height:100vh;display:block';
+document.body.appendChild(iframe);
+
+// Receive rolls
 const source = createBridgeSheetSource({
-    iframe: document.getElementById('sheet-frame') as HTMLIFrameElement,
+    iframe,
     allowedOrigins: ['https://longstoryshort.app'],
 });
 
-const dispose = createRollBridge(source, adapter, {
-    messages: {
-        connected: '🎲 Sheet connected',
-        labelHint: 'Select exactly one token to place a roll label',
-    },
-});
-
-// later:
-dispose();
-source.dispose();
-```
-
-## Quick start — sheet side
-
-```ts
-import { createSheetClient } from '@longstoryshort/vtt-sdk';
-
-const client = createSheetClient();
-
-// emit a roll to the bridge
-client.send({ type: 'dnd:roll', payload: { ... } });
-
-// receive inbound commands from the bridge
-const unsub = client.onEvent((event) => {
-    if (event.type === 'dnd:command') { /* handle damage, conditions, … */ }
+source.onRoll((roll) => {
+    // wire to your VTT — notification, chat, peer broadcast, etc.
+    console.log(formatRollMessage(roll), rollVariant(roll));
 });
 
 // cleanup
-client.dispose();
+source.dispose();
 ```
 
-## iframe sandbox requirements
-
-The bridge must embed the sheet iframe with at least these sandbox tokens:
+## Documentation
 
-```
-sandbox="allow-same-origin allow-scripts allow-popups allow-popups-to-escape-sandbox allow-forms allow-modals"
-```
-
-`allow-same-origin` is required so the sheet can read its auth cookie and access localStorage. Without it the sheet gets an opaque origin and auth breaks.
+- [SDK guide](docs/sdk-guide.md) — sandbox requirements, receiving events, protocol reference, utilities. Start here regardless of your VTT architecture.
+- [Bridge guide](docs/bridge-guide.md) — for VTTs that use an extension/plugin model and need a separate static bridge page. Includes the full annotated OBR bridge and `OwlbearAdapter` reference.
 
 ## Reference bridge — Owlbear Rodeo (D&D 5e)
 
-A deployable vanilla-TS bridge for Owlbear Rodeo lives in [`bridges/dnd/`](bridges/dnd/). It is automatically deployed to GitHub Pages on every push to `master`.
+A deployable bridge for Owlbear Rodeo lives in [`bridges/dnd/`](bridges/dnd/). Deployed automatically to GitHub Pages on every push to `master`.
 
 **Live manifest:** `https://bridge.longstoryshort.app/dnd/obr/manifest.json`
 
-To install the extension in OBR: Extensions → Add extension → paste the manifest URL above.
+To install in OBR: Extensions → Add extension → paste the manifest URL above.
+
+## Bridge template
 
-To adapt for your own VTT: copy `bridges/dnd/src/main.ts`, swap `OwlbearAdapter` for your own `VTTAdapter` implementation, and deploy as a static page.
+[`bridges/_template/`](bridges/_template/) is a minimal copy-and-modify skeleton — iframe embed + `createBridgeSheetSource` + `TODO` comments for your VTT's APIs, ready to build with Vite.
 
 ## Protocol events
 
 | 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, …) |
+| `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 | 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`.
+Reserved events are typed and wired end-to-end, but the bridge-side API is experimental. Subscribe via `source.onEvent` directly.
 
 ## License
 

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

@@ -1,16 +1,35 @@
-import { V as VTTAdapter, a as VTTUser, S as SheetEvent, N as NotifyVariant } from '../../types-w2_82sqo.js';
+import { S as SheetEvent, N as NotifyVariant } from '../../formatRoll-BhFkInCu.js';
+import * as _owlbear_rodeo_sdk from '@owlbear-rodeo/sdk';
+
+interface ObrPlayer {
+    id: string;
+    name: string;
+    role: 'gm' | 'player';
+}
+/** Public contract of {@link OwlbearAdapter} — use this type when you need to reference the adapter without importing the class. */
+interface ObrAdapter {
+    readonly isAvailable: boolean;
+    ready(): Promise<boolean>;
+    getSessionId(): string | undefined;
+    getCurrentUser(): ObrPlayer | undefined;
+    notify(message: string, variant?: 'info' | 'success' | 'warning' | 'error'): void;
+    broadcast(event: SheetEvent): void;
+    onEvent(handler: (event: SheetEvent) => void): () => void;
+    getRoomMetadata(): Promise<Record<string, unknown>>;
+    onRoomMetadataChange(handler: () => void): () => void;
+    dispose(): void;
+}
 
 /**
- * Owlbear Rodeo implementation of {@link VTTAdapter}.
+ * Owlbear Rodeo bridge helper.
  *
  * Owlbear exposes no public dice API (its 3D roller is first-party and closed),
- * so rendering a roll is our job: we broadcast a result for toasts/logs and add
- * a transient label item over the roller's token — scene items are shared, so
+ * so rendering a roll is the bridge's job: broadcast a result for toasts/logs and
+ * add a transient label item over the roller's token — scene items are shared, so
  * everyone at the table sees the floating number. All scene work is best-effort
  * and degrades silently; the broadcast/notification path is the guaranteed core.
  */
-declare class OwlbearAdapter implements VTTAdapter {
-    private sdk;
+declare class OwlbearAdapter implements ObrAdapter {
     private obr;
     private user;
     private sessionId;
@@ -19,13 +38,13 @@ declare class OwlbearAdapter implements VTTAdapter {
     get isAvailable(): boolean;
     ready(): Promise<boolean>;
     private init;
-    private loadSdk;
     getSessionId(): string | undefined;
-    getCurrentUser(): VTTUser | undefined;
+    getCurrentUser(): ObrPlayer | undefined;
     broadcast(event: SheetEvent): void;
     onEvent(handler: (event: SheetEvent) => void): () => void;
     notify(message: string, variant?: NotifyVariant): void;
-    labelOverSelection(text: string, ttlMs?: number): Promise<boolean>;
+    getRoomMetadata(): Promise<Record<string, unknown>>;
+    onRoomMetadataChange(handler: () => void): () => void;
     dispose(): void;
 }
 
@@ -43,9 +62,39 @@ declare function syncObrref(): void;
 
 /** Room-wide pub/sub channel for sheet events. Namespaced to avoid collisions. */
 declare const BROADCAST_CHANNEL = "rodeo.lss/sheet-events";
-/** Marks scene items we create (transient roll labels) so we own/clean them. */
-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;
+/** OBR room metadata key — false when Vortex is connected (logger active), true otherwise. */
+declare const NOTIFY_ROLLS_KEY = "rodeo.lss/notify-rolls";
+
+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, OwlbearAdapter, syncObrref };
+export { BROADCAST_CHANNEL, NOTIFY_ROLLS_KEY, type ObrAdapter, type ObrPlayer, type ObrPreloadWindow, OwlbearAdapter, loadObrSdk, preloadObrSdk, syncObrref, whenObrReady };

package/dist/adapters/owlbear/index.js

@@ -1,7 +1,6 @@
 // src/adapters/owlbear/constants.ts
 var BROADCAST_CHANNEL = "rodeo.lss/sheet-events";
-var LABEL_METADATA_KEY = "rodeo.lss/label";
-var DEFAULT_LABEL_TTL_MS = 4e3;
+var NOTIFY_ROLLS_KEY = "rodeo.lss/notify-rolls";
 
 // src/adapters/owlbear/obrref.ts
 var PARAM = "obrref";
@@ -44,8 +43,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",
@@ -54,7 +89,6 @@ var NOTIFY_VARIANT = {
 };
 var OwlbearAdapter = class {
   constructor() {
-    this.sdk = null;
     this.obr = null;
     this.readyPromise = null;
     this.disposed = false;
@@ -73,13 +107,12 @@ 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 +121,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 +143,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;
   }
@@ -160,43 +171,21 @@ var OwlbearAdapter = class {
     void this.obr?.notification.show(message, NOTIFY_VARIANT[variant]).catch(() => {
     });
   }
-  async labelOverSelection(text, ttlMs = DEFAULT_LABEL_TTL_MS) {
-    const { obr, sdk } = this;
-    if (!obr || !sdk) {
-      return false;
-    }
-    try {
-      const selection = await obr.player.getSelection();
-      if (!selection || selection.length !== 1) {
-        if (DEV2) {
-          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) {
-          console.warn("[OwlbearAdapter] label skipped \u2014 selected item not found in scene");
-        }
-        return false;
-      }
-      const label = sdk.buildLabel().plainText(text).position(token.position).attachedTo(token.id).pointerHeight(0).disableHit(true).locked(true).layer("TEXT").metadata({ [LABEL_METADATA_KEY]: true }).build();
-      await obr.scene.items.addItems([label]);
-      window.setTimeout(() => {
-        void obr.scene.items.deleteItems([label.id]).catch(() => {
-        });
-      }, ttlMs);
-      return true;
-    } catch (error) {
-      if (DEV2) {
-        console.warn("[OwlbearAdapter] label error:", error);
-      }
-      return false;
-    }
+  getRoomMetadata() {
+    if (!this.obr) return Promise.resolve({});
+    return this.obr.room.getMetadata().then(
+      (meta) => meta,
+      () => ({})
+    );
+  }
+  onRoomMetadataChange(handler) {
+    if (!this.obr) return () => {
+    };
+    return this.obr.room.onMetadataChange(handler);
   }
   dispose() {
     this.disposed = true;
   }
 };
 
-export { BROADCAST_CHANNEL, DEFAULT_LABEL_TTL_MS, LABEL_METADATA_KEY, OwlbearAdapter, syncObrref };
+export { BROADCAST_CHANNEL, NOTIFY_ROLLS_KEY, OwlbearAdapter, loadObrSdk, preloadObrSdk, syncObrref, whenObrReady };

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

@@ -4,13 +4,6 @@
  * This file must not import from any project outside this SDK directory —
  * only from other SDK files and external dependencies.
  */
-type VTTUserRole = 'gm' | 'player';
-interface VTTUser {
-    id: string;
-    name: string;
-    role: VTTUserRole;
-}
-type NotifyVariant = 'info' | 'success' | 'warning' | 'error';
 /** A single dice roll made on a character sheet, normalized for any VTT. */
 interface DiceRollPayload {
     characterId: string;
@@ -140,48 +133,6 @@ interface SheetSource {
     /** Subscribe to rolls made on the sheet. Returns an unsubscribe fn. */
     onRoll(handler: (roll: DiceRollPayload) => void): () => void;
 }
-/** Human-facing strings surfaced by the bridge — override to localize. */
-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 RollBridgeOptions {
-    messages?: Partial<RollBridgeMessages>;
-}
-/**
- * The seam every VTT implements. The sheet talks only to this interface; each
- * table (Owlbear, Foundry, …) ships a thin adapter that maps its own SDK onto
- * these methods.
- */
-interface VTTAdapter {
-    /** True only when the page actually runs inside this VTT. */
-    readonly isAvailable: boolean;
-    /**
-     * Loads and handshakes with the VTT SDK. Resolves `true` once ready, or
-     * `false` if the page is not running inside this VTT. Safe to call multiple
-     * times — the work happens once.
-     */
-    ready(): Promise<boolean>;
-    getSessionId(): string | undefined;
-    getCurrentUser(): VTTUser | undefined;
-    /** Send an event to every other client in the room (sender excluded). */
-    broadcast(event: SheetEvent): void;
-    /** Subscribe to events broadcast by other clients. Returns an unsubscribe fn. */
-    onEvent(handler: (event: SheetEvent) => void): () => void;
-    /** Local toast on this client. */
-    notify(message: string, variant?: NotifyVariant): void;
-    /**
-     * Float a transient text label over the player's currently selected token.
-     * Scene items are shared, so the label is visible to everyone at the table.
-     * Resolves `true` if a label was placed, `false` when there isn't exactly
-     * one token selected or the scene write was rejected (e.g. no permission).
-     */
-    labelOverSelection(text: string, ttlMs?: number): Promise<boolean>;
-    /** Tear down listeners / SDK handlers. */
-    dispose(): void;
-}
 /** Minimal "listen for messages" surface — the real `window` satisfies it. */
 interface MessageHost {
     addEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
@@ -218,4 +169,10 @@ interface SheetClient {
     dispose(): void;
 }
 
-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 };
+type NotifyVariant = 'info' | 'success' | 'warning' | 'error';
+/** Toast text for a roll, e.g. "🎲 Alice: Longsword Attack — 18 💥". */
+declare function formatRollMessage(payload: DiceRollPayload): string;
+/** Maps a roll's crit state onto a toast variant. */
+declare function rollVariant(payload: DiceRollPayload): NotifyVariant;
+
+export { type CapabilityDescriptor as C, type DiceRollPayload as D, type HealthChangedPayload as H, type MessageHost as M, type NotifyVariant as N, type SheetEvent as S, type SheetClientOptions as a, type SheetClient as b, type SheetSource as c, type CapabilityManifest as d, type CapabilityOpAddTag as e, type CapabilityOpAdjust as f, type CapabilityOpName as g, type CapabilityOpRemoveTag as h, type CapabilityOpRequestRoll as i, type CapabilityOpSet as j, type CapabilityOpToggle as k, type CapabilityOperation as l, type MessageTarget as m, formatRollMessage as n, rollVariant as r };

package/dist/index.d.ts

@@ -1,22 +1,12 @@
-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';
+import { a as SheetClientOptions, b as SheetClient, c as SheetSource, S as SheetEvent, M as MessageHost } from './formatRoll-BhFkInCu.js';
+export { C as CapabilityDescriptor, d as CapabilityManifest, e as CapabilityOpAddTag, f as CapabilityOpAdjust, g as CapabilityOpName, h as CapabilityOpRemoveTag, i as CapabilityOpRequestRoll, j as CapabilityOpSet, k as CapabilityOpToggle, l as CapabilityOperation, D as DiceRollPayload, H as HealthChangedPayload, m as MessageTarget, N as NotifyVariant, n as formatRollMessage, r as rollVariant } from './formatRoll-BhFkInCu.js';
 
 /**
- * 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.
+ * 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 function createRollBridge(source: SheetSource, adapter: VTTAdapter, options?: RollBridgeOptions): () => void;
+declare const SHEET_IFRAME_SANDBOX = "allow-same-origin allow-scripts allow-popups allow-popups-to-escape-sandbox allow-forms allow-modals";
 
 /**
  * Sheet-side half of the postMessage transport. The character sheet (running in
@@ -46,11 +36,9 @@ interface BridgeSheetSourceOptions {
     /** Origin to post inbound commands to. Default `'*'`. */
     targetOrigin?: string;
 }
-/** A `SheetSource` (for `createRollBridge`) plus raw access and inbound `send`. */
+/** Bridge-side source: `onRoll` convenience + full `onEvent` access + 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;
-    /** Subscribe to every event coming from the sheet (not only rolls). */
+    /** Subscribe to every event coming from the sheet. Returns an unsubscribe fn. */
     onEvent(handler: (event: SheetEvent) => void): () => void;
     /** Post an inbound command to the sheet (e.g. `dnd:command`). */
     send(event: SheetEvent): void;
@@ -58,18 +46,12 @@ 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 `createRollBridge` can drive the VTT adapter — without the
- * bridge ever touching the sheet's internals.
+ * VTT extension), listens to the embedded sheet iframe, and delivers typed
+ * `SheetEvent`s — without the bridge ever touching the sheet's internals.
  *
  * `contentWindow` is read live on every message/send, so it survives the sheet
  * iframe navigating or reloading (e.g. Gatsby dev's full-reload on navigation).
  */
 declare function createBridgeSheetSource(options: BridgeSheetSourceOptions): BridgeSheetSource;
 
-/** Toast text for a roll, e.g. "🎲 Alice: Longsword Attack — 18 💥". */
-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, RollBridgeOptions, SheetClient, SheetClientOptions, SheetEvent, type SheetFrameRef, SheetSource, VTTAdapter, createBridgeSheetSource, createRollBridge, createSheetClient, formatRollMessage, rollVariant };
+export { type BridgeSheetSource, type BridgeSheetSourceOptions, MessageHost, SHEET_IFRAME_SANDBOX, SheetClient, SheetClientOptions, SheetEvent, type SheetFrameRef, SheetSource, createBridgeSheetSource, createSheetClient };

package/dist/index.js

@@ -1,63 +1,5 @@
-// src/formatRoll.ts
-function formatRollMessage(payload) {
-  let crit = "";
-  if (payload.isCrit) {
-    if (payload.critKind === "success") {
-      crit = " \u{1F4A5}";
-    } else if (payload.critKind === "failure") {
-      crit = " \u{1F480}";
-    }
-  }
-  return `\u{1F3B2} ${payload.characterName}: ${payload.title} \u2014 ${payload.total}${crit}`;
-}
-function rollVariant(payload) {
-  if (payload.isCrit && payload.critKind === "success") {
-    return "success";
-  }
-  if (payload.isCrit && payload.critKind === "failure") {
-    return "warning";
-  }
-  return "info";
-}
-
-// 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 createRollBridge(source, adapter, options = {}) {
-  const messages = { ...DEFAULT_MESSAGES, ...options.messages };
-  const cleanups = [];
-  let cancelled = false;
-  cleanups.push(source.onRoll((roll) => {
-    if (!adapter.isAvailable) {
-      return;
-    }
-    adapter.notify(formatRollMessage(roll), rollVariant(roll));
-    adapter.broadcast({ type: "dnd:roll", payload: roll });
-    void adapter.labelOverSelection(roll.total).then((placed) => {
-      if (!placed) {
-        adapter.notify(messages.labelHint, "warning");
-      }
-    });
-  }));
-  void adapter.ready().then((available) => {
-    if (cancelled || !available) {
-      return;
-    }
-    adapter.notify(messages.connected, "success");
-    cleanups.push(adapter.onEvent((event) => {
-      if (event.type !== "dnd:roll") {
-        return;
-      }
-      adapter.notify(formatRollMessage(event.payload), rollVariant(event.payload));
-    }));
-  });
-  return () => {
-    cancelled = true;
-    cleanups.forEach((cleanup) => cleanup());
-  };
-}
+// src/constants.ts
+var SHEET_IFRAME_SANDBOX = "allow-same-origin allow-scripts allow-popups allow-popups-to-escape-sandbox allow-forms allow-modals";
 
 // src/postMessageProtocol.ts
 var MARKER = "__lssSheetSdk";
@@ -156,17 +98,6 @@ function createBridgeSheetSource(options) {
         handlers.delete(wrapped);
       };
     },
-    onManifest(handler) {
-      const wrapped = (event) => {
-        if (event.type === "dnd:manifest") {
-          handler(event.payload);
-        }
-      };
-      handlers.add(wrapped);
-      return () => {
-        handlers.delete(wrapped);
-      };
-    },
     onEvent(handler) {
       handlers.add(handler);
       return () => {
@@ -185,4 +116,26 @@ function createBridgeSheetSource(options) {
   };
 }
 
-export { createBridgeSheetSource, createRollBridge, createSheetClient, formatRollMessage, rollVariant };
+// src/formatRoll.ts
+function formatRollMessage(payload) {
+  let crit = "";
+  if (payload.isCrit) {
+    if (payload.critKind === "success") {
+      crit = " \u{1F4A5}";
+    } else if (payload.critKind === "failure") {
+      crit = " \u{1F480}";
+    }
+  }
+  return `\u{1F3B2} ${payload.characterName}: ${payload.title} \u2014 ${payload.total}${crit}`;
+}
+function rollVariant(payload) {
+  if (payload.isCrit && payload.critKind === "success") {
+    return "success";
+  }
+  if (payload.isCrit && payload.critKind === "failure") {
+    return "warning";
+  }
+  return "info";
+}
+
+export { SHEET_IFRAME_SANDBOX, createBridgeSheetSource, createSheetClient, formatRollMessage, rollVariant };

package/package.json

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