@longstoryshort/vtt-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tldrpg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# @longstoryshort/vtt-sdk
+
+Embed a [longstoryshort.app](https://longstoryshort.app) character sheet in any virtual tabletop (VTT) 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.
+
+```
+OBR / Foundry / … ──► [bridge page, FOREIGN origin]
+                           │  embeds iframe ↓   ← trust boundary (postMessage only)
+                           └► [LSS sheet, lss origin]
+```
+
+## Installation
+
+```sh
+npm install @longstoryshort/vtt-sdk
+```
+
+The Owlbear adapter is an optional peer dependency:
+
+```sh
+npm install @owlbear-rodeo/sdk
+```
+
+## Packages
+
+| Import | Contents |
+|--------|----------|
+| `@longstoryshort/vtt-sdk` | Core: types, `createSheetBridge`, `createSheetClient`, `createBridgeSheetSource`, `formatRollMessage` |
+| `@longstoryshort/vtt-sdk/owlbear` | `OwlbearAdapter`, `syncObrref`, constants |
+
+## Quick start — bridge side
+
+```ts
+import { createSheetBridge, createBridgeSheetSource } from '@longstoryshort/vtt-sdk';
+import { OwlbearAdapter } from '@longstoryshort/vtt-sdk/owlbear';
+
+const adapter = new OwlbearAdapter();
+const source = createBridgeSheetSource({
+    iframe: document.getElementById('sheet-frame') as HTMLIFrameElement,
+    allowedOrigins: ['https://longstoryshort.app'],
+});
+
+const dispose = createSheetBridge(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: 'DICE_ROLL', payload: { ... } });
+
+// receive inbound commands from the bridge
+const unsub = client.onEvent((event) => {
+    if (event.type === 'CAPABILITY_COMMAND') { /* handle damage, conditions, … */ }
+});
+
+// cleanup
+client.dispose();
+```
+
+## iframe sandbox requirements
+
+The bridge must embed the sheet iframe with at least these sandbox tokens:
+
+```
+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.
+
+## Reference bridge
+
+A ready-to-adapt React bridge page for Owlbear Rodeo lives in [`bridges/owlbear/index.tsx`](bridges/owlbear/index.tsx). It is NOT published to npm — deploy it as a separate page from your own infrastructure.
+
+## 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, …) |
+
+## License
+
+MIT

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

@@ -0,0 +1,51 @@
+import { V as VTTAdapter, a as VTTUser, S as SheetEvent, N as NotifyVariant } from '../../types-CS2uTxCW.js';
+
+/**
+ * Owlbear Rodeo implementation of {@link VTTAdapter}.
+ *
+ * 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
+ * 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;
+    private obr;
+    private user;
+    private sessionId;
+    private readyPromise;
+    private disposed;
+    get isAvailable(): boolean;
+    ready(): Promise<boolean>;
+    private init;
+    private loadSdk;
+    getSessionId(): string | undefined;
+    getCurrentUser(): VTTUser | undefined;
+    broadcast(event: SheetEvent): void;
+    onEvent(handler: (event: SheetEvent) => void): () => void;
+    notify(message: string, variant?: NotifyVariant): void;
+    labelOverSelection(text: string, ttlMs?: number): Promise<boolean>;
+    dispose(): void;
+}
+
+/**
+ * Keep the Owlbear handshake (`obrref`) reachable by the SDK across client-side
+ * navigation.
+ *
+ * The OBR SDK reads `obrref` from the URL once, at module-import time, and
+ * freezes `isAvailable` from it. But in-app links drop the param, and the host
+ * app may load a fresh SDK copy on the next page. So: when we see the param
+ * (entry page) we stash it; when it's missing (after navigation) we put it back
+ * via `replaceState` before the SDK loads.
+ */
+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;
+
+export { BROADCAST_CHANNEL, DEFAULT_LABEL_TTL_MS, LABEL_METADATA_KEY, OwlbearAdapter, syncObrref };

package/dist/adapters/owlbear/index.js

@@ -0,0 +1,202 @@
+// 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;
+
+// src/adapters/owlbear/obrref.ts
+var PARAM = "obrref";
+var STORAGE_KEY = "lss-obrref";
+var DEV = process.env["NODE_ENV"] !== "production";
+function syncObrref() {
+  if (typeof window === "undefined") {
+    return;
+  }
+  let url;
+  try {
+    url = new URL(window.location.href);
+  } catch {
+    return;
+  }
+  const current = url.searchParams.get(PARAM);
+  if (current) {
+    try {
+      window.sessionStorage.setItem(STORAGE_KEY, current);
+      if (DEV) {
+        console.info("[LSS/OBR] obrref captured from URL");
+      }
+    } catch {
+    }
+    return;
+  }
+  let stashed = null;
+  try {
+    stashed = window.sessionStorage.getItem(STORAGE_KEY);
+  } catch {
+  }
+  if (stashed) {
+    url.searchParams.set(PARAM, stashed);
+    window.history.replaceState(window.history.state, "", url.toString());
+    if (DEV) {
+      console.info("[LSS/OBR] obrref restored from stash");
+    }
+  } else if (DEV) {
+    console.warn("[LSS/OBR] obrref missing and no stash to restore");
+  }
+}
+
+// src/adapters/owlbear/OwlbearAdapter.ts
+var DEV2 = process.env["NODE_ENV"] !== "production";
+var NOTIFY_VARIANT = {
+  info: "INFO",
+  success: "SUCCESS",
+  warning: "WARNING",
+  error: "ERROR"
+};
+var OwlbearAdapter = class {
+  constructor() {
+    this.sdk = null;
+    this.obr = null;
+    this.readyPromise = null;
+    this.disposed = false;
+  }
+  get isAvailable() {
+    return this.obr?.isAvailable ?? false;
+  }
+  ready() {
+    if (!this.readyPromise) {
+      this.readyPromise = this.init();
+    }
+    return this.readyPromise;
+  }
+  async init() {
+    if (typeof window === "undefined") {
+      return false;
+    }
+    syncObrref();
+    const sdk = await this.loadSdk();
+    if (!sdk) {
+      return false;
+    }
+    this.sdk = sdk;
+    this.obr = sdk.default;
+    if (DEV2) {
+      console.info(
+        "[LSS/OBR] init \u2014 isAvailable:",
+        this.obr.isAvailable,
+        "| isReady:",
+        this.obr.isReady
+      );
+    }
+    if (!this.obr.isAvailable) {
+      if (DEV2) {
+        console.warn("[LSS/OBR] not embedded (origin empty) \u2014 obrref missing at SDK load.");
+      }
+      return false;
+    }
+    if (DEV2) {
+      console.info("[LSS/OBR] awaiting onReady (isReady =", this.obr.isReady, ")");
+    }
+    await new Promise((resolve) => {
+      this.obr.onReady(resolve);
+    });
+    if (DEV2) {
+      console.info("[LSS/OBR] onReady fired \u2014 fetching player\u2026");
+    }
+    if (this.disposed) {
+      return false;
+    }
+    this.sessionId = this.obr.room.id;
+    const [id, name, role] = await Promise.all([
+      this.obr.player.getId(),
+      this.obr.player.getName(),
+      this.obr.player.getRole()
+    ]);
+    this.user = { id, name, role: role === "GM" ? "gm" : "player" };
+    if (DEV2) {
+      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;
+  }
+  getCurrentUser() {
+    return this.user;
+  }
+  broadcast(event) {
+    void this.obr?.broadcast.sendMessage(BROADCAST_CHANNEL, event).catch(() => {
+    });
+  }
+  onEvent(handler) {
+    if (!this.obr) {
+      return () => {
+      };
+    }
+    return this.obr.broadcast.onMessage(BROADCAST_CHANNEL, (message) => {
+      handler(message.data);
+    });
+  }
+  notify(message, variant = "info") {
+    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;
+    }
+  }
+  dispose() {
+    this.disposed = true;
+  }
+};
+
+export { BROADCAST_CHANNEL, DEFAULT_LABEL_TTL_MS, LABEL_METADATA_KEY, OwlbearAdapter, syncObrref };

package/dist/index.d.ts

@@ -0,0 +1,72 @@
+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-CS2uTxCW.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-CS2uTxCW.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:
+ *
+ *  - 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.
+ *
+ * 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;
+
+/**
+ * Sheet-side half of the postMessage transport. The character sheet (running in
+ * its own origin, embedded by a VTT bridge in a foreign origin) uses this to push
+ * outbound events (rolls) to the bridge and to receive inbound commands — the
+ * frame boundary keeps the sheet's DOM, cookies, and token unreadable to the
+ * bridge, so only the explicit protocol crosses.
+ *
+ * Inbound is honored only from the same window we post to (the bridge) and,
+ * optionally, an origin allowlist. Returns a safe no-op client during SSR / when
+ * no message host is available. The counterpart on the bridge side is
+ * `createBridgeSheetSource`.
+ */
+declare function createSheetClient(options?: SheetClientOptions): SheetClient;
+
+/** A reference to the embedded sheet iframe — only `contentWindow` is read (live). */
+interface SheetFrameRef {
+    contentWindow: Window | null;
+}
+interface BridgeSheetSourceOptions {
+    /** The embedded sheet iframe. Its *live* `contentWindow` is the message peer. */
+    iframe: SheetFrameRef;
+    /** Window to listen on. Default: `window`. */
+    host?: MessageHost;
+    /** Honor inbound only from these origins (the sheet's origin). */
+    allowedOrigins?: string[];
+    /** Origin to post inbound commands to. Default `'*'`. */
+    targetOrigin?: string;
+}
+/** A `SheetSource` (for `createSheetBridge`) 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;
+    /** Subscribe to every event coming from the sheet (not only rolls). */
+    onEvent(handler: (event: SheetEvent) => void): () => void;
+    /** Post an inbound command to the sheet (e.g. `CAPABILITY_COMMAND`). */
+    send(event: SheetEvent): void;
+    dispose(): void;
+}
+/**
+ * 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
+ * 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, SheetBridgeOptions, SheetClient, SheetClientOptions, SheetEvent, type SheetFrameRef, SheetSource, VTTAdapter, createBridgeSheetSource, createSheetBridge, createSheetClient, formatRollMessage, rollVariant };

package/dist/index.js

@@ -0,0 +1,188 @@
+// 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/createSheetBridge.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 = {}) {
+  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: "DICE_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 !== "DICE_ROLL") {
+        return;
+      }
+      adapter.notify(formatRollMessage(event.payload), rollVariant(event.payload));
+    }));
+  });
+  return () => {
+    cancelled = true;
+    cleanups.forEach((cleanup) => cleanup());
+  };
+}
+
+// src/postMessageProtocol.ts
+var MARKER = "__lssSheetSdk";
+var VERSION = 1;
+function wrapEnvelope(event) {
+  return { __lssSheetSdk: VERSION, event };
+}
+function readEnvelope(data) {
+  if (typeof data === "object" && data !== null) {
+    const record = data;
+    if (record[MARKER] === VERSION && "event" in record) {
+      return record.event;
+    }
+  }
+  return null;
+}
+
+// src/createSheetClient.ts
+function createSheetClient(options = {}) {
+  const host = options.host ?? (typeof window !== "undefined" ? window : void 0);
+  const target = options.target ?? (typeof window !== "undefined" ? window.parent : void 0);
+  const targetOrigin = options.targetOrigin ?? "*";
+  const { allowedOrigins } = options;
+  if (!host) {
+    return { send: () => {
+    }, onEvent: () => () => {
+    }, dispose: () => {
+    } };
+  }
+  const handlers = /* @__PURE__ */ new Set();
+  const listener = (event) => {
+    if (target && event.source !== target) {
+      return;
+    }
+    if (allowedOrigins && !allowedOrigins.includes(event.origin)) {
+      return;
+    }
+    const sheetEvent = readEnvelope(event.data);
+    if (!sheetEvent) {
+      return;
+    }
+    handlers.forEach((handler) => handler(sheetEvent));
+  };
+  host.addEventListener("message", listener);
+  return {
+    send(event) {
+      if (!target) {
+        return;
+      }
+      target.postMessage(wrapEnvelope(event), targetOrigin);
+    },
+    onEvent(handler) {
+      handlers.add(handler);
+      return () => {
+        handlers.delete(handler);
+      };
+    },
+    dispose() {
+      handlers.clear();
+      host.removeEventListener("message", listener);
+    }
+  };
+}
+
+// src/createBridgeSheetSource.ts
+function createBridgeSheetSource(options) {
+  const host = options.host ?? (typeof window !== "undefined" ? window : void 0);
+  const targetOrigin = options.targetOrigin ?? "*";
+  const { iframe, allowedOrigins } = options;
+  const handlers = /* @__PURE__ */ new Set();
+  const listener = (event) => {
+    if (event.source !== iframe.contentWindow) {
+      return;
+    }
+    if (allowedOrigins && !allowedOrigins.includes(event.origin)) {
+      return;
+    }
+    const sheetEvent = readEnvelope(event.data);
+    if (!sheetEvent) {
+      return;
+    }
+    handlers.forEach((handler) => handler(sheetEvent));
+  };
+  if (host) {
+    host.addEventListener("message", listener);
+  }
+  return {
+    onRoll(handler) {
+      const wrapped = (event) => {
+        if (event.type === "DICE_ROLL") {
+          handler(event.payload);
+        }
+      };
+      handlers.add(wrapped);
+      return () => {
+        handlers.delete(wrapped);
+      };
+    },
+    onManifest(handler) {
+      const wrapped = (event) => {
+        if (event.type === "MANIFEST") {
+          handler(event.payload);
+        }
+      };
+      handlers.add(wrapped);
+      return () => {
+        handlers.delete(wrapped);
+      };
+    },
+    onEvent(handler) {
+      handlers.add(handler);
+      return () => {
+        handlers.delete(handler);
+      };
+    },
+    send(event) {
+      iframe.contentWindow?.postMessage(wrapEnvelope(event), targetOrigin);
+    },
+    dispose() {
+      handlers.clear();
+      if (host) {
+        host.removeEventListener("message", listener);
+      }
+    }
+  };
+}
+
+export { createBridgeSheetSource, createSheetBridge, createSheetClient, formatRollMessage, rollVariant };

package/dist/types-CS2uTxCW.d.ts

@@ -0,0 +1,207 @@
+/**
+ * LSS Sheet SDK — public types.
+ *
+ * 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;
+    characterName: string;
+    /** Human label, e.g. "Атака Длинный меч" or "Спасбросок Ловкость". */
+    title: string;
+    /** Dice notation as shown, e.g. "(1к20) + 5". */
+    formula: string;
+    /** Rolled breakdown, e.g. "(15) + 5". */
+    breakdown: string;
+    /** Final total as a string — supports advantage pairs like "18 | 7". */
+    total: string;
+    isCrit: boolean;
+    critKind?: 'success' | 'failure';
+    timestamp: number;
+}
+type CapabilityOpName = 'adjust' | 'set' | 'toggle' | 'add-tag' | 'remove-tag' | 'request-roll';
+/**
+ * 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).
+ */
+interface CapabilityOpAdjust {
+    op: 'adjust';
+    capabilityId: string;
+    delta: number;
+}
+/** set: overwrite a capability value outright. */
+interface CapabilityOpSet {
+    op: 'set';
+    capabilityId: string;
+    value: number | boolean | string;
+}
+/** toggle: flip a boolean capability. */
+interface CapabilityOpToggle {
+    op: 'toggle';
+    capabilityId: string;
+}
+/**
+ * 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.
+ */
+interface CapabilityOpAddTag {
+    op: 'add-tag';
+    capabilityId: string;
+    value: string;
+}
+/**
+ * remove-tag: remove a label from a tag-track capability.
+ * Removes the first occurrence. Assumes a well-behaved set (no duplicates in DnD5e conditions).
+ */
+interface CapabilityOpRemoveTag {
+    op: 'remove-tag';
+    capabilityId: string;
+    value: string;
+}
+/** request-roll: ask the sheet to roll a d20 check against an optional DC. */
+interface CapabilityOpRequestRoll {
+    op: 'request-roll';
+    capabilityId: string;
+    rollType: string;
+    dc?: number;
+}
+type CapabilityOperation = CapabilityOpAdjust | CapabilityOpSet | CapabilityOpToggle | CapabilityOpAddTag | CapabilityOpRemoveTag | CapabilityOpRequestRoll;
+/** One capability entry in the sheet manifest. */
+interface CapabilityDescriptor {
+    id: string;
+    operations: CapabilityOpName[];
+}
+/**
+ * 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
+ * CAPABILITY_COMMAND operations are valid for this member.
+ */
+interface CapabilityManifest {
+    version: '1';
+    /** Short identifier for the sheet system, e.g. 'dnd5e' or 'anima'. */
+    sheetSystem: string;
+    capabilities: CapabilityDescriptor[];
+}
+/** Outbound fact: HP values after the sheet has applied an adjust/set command. */
+interface HealthChangedPayload {
+    characterId: string;
+    current: number;
+    max: number;
+    temp: number;
+}
+/**
+ * Everything that crosses the sheet↔VTT boundary.
+ *
+ * Outbound (sheet → host):  DICE_ROLL · MANIFEST · HEALTH_CHANGED
+ * Inbound  (host → sheet):  CAPABILITY_COMMAND
+ */
+type SheetEvent = {
+    type: 'DICE_ROLL';
+    payload: DiceRollPayload;
+} | {
+    type: 'MANIFEST';
+    payload: CapabilityManifest;
+} | {
+    type: 'HEALTH_CHANGED';
+    payload: HealthChangedPayload;
+} | {
+    type: 'CAPABILITY_COMMAND';
+    payload: CapabilityOperation;
+};
+/**
+ * Implemented by the host (the character-sheet app) so the bridge stays
+ * agnostic of any specific app. The host normalizes its own roll representation
+ * into a {@link DiceRollPayload} and pushes it through `onRoll`.
+ */
+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 SheetBridgeMessages {
+    /** 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>;
+}
+/**
+ * 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;
+    removeEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
+}
+/** Minimal "post a message" surface — a real `Window` (e.g. `window.parent`) satisfies it. */
+interface MessageTarget {
+    postMessage(message: unknown, targetOrigin: string): void;
+}
+interface SheetClientOptions {
+    /** Window to post outbound events to (the embedding bridge). Default: `window.parent`. */
+    target?: MessageTarget;
+    /** Window to listen on for inbound events. Default: `window`. */
+    host?: MessageHost;
+    /** If set, inbound events are honored only from these origins. */
+    allowedOrigins?: string[];
+    /**
+     * Origin to post outbound events to. Default `'*'`. Override with the bridge's
+     * origin once known — outbound carries only non-sensitive data, never the token.
+     */
+    targetOrigin?: string;
+}
+/**
+ * Sheet-side half of the postMessage transport. The sheet (its own origin,
+ * embedded by a VTT bridge) emits outbound events and receives inbound ones
+ * without exposing DOM/cookies/token across the frame boundary.
+ */
+interface SheetClient {
+    /** Send an outbound event (e.g. a dice roll or manifest) to the embedding bridge. */
+    send(event: SheetEvent): void;
+    /** Subscribe to inbound events/commands from the bridge. Returns an unsubscribe fn. */
+    onEvent(handler: (event: SheetEvent) => void): () => void;
+    /** Remove the inbound listener. */
+    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 };

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@longstoryshort/vtt-sdk",
+  "version": "0.1.0",
+  "description": "Embed a longstoryshort.app character sheet in any virtual tabletop via iframe and postMessage",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./owlbear": {
+      "import": "./dist/adapters/owlbear/index.js",
+      "types": "./dist/adapters/owlbear/index.d.ts"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "owlbear": ["./dist/adapters/owlbear/index.d.ts"]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src"
+  },
+  "peerDependencies": {
+    "@owlbear-rodeo/sdk": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@owlbear-rodeo/sdk": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@owlbear-rodeo/sdk": "^3.1.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^9.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  }
+}