@longstoryshort/vtt-sdk 0.2.0 → 0.3.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,4 @@
-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';
 
 /**
  * Owlbear Rodeo implementation of {@link VTTAdapter}.

package/dist/index.d.ts

@@ -1,19 +1,22 @@
-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:
+ * 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 +46,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 +59,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 +72,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, SheetClient, SheetClientOptions, SheetEvent, type SheetFrameRef, SheetSource, VTTAdapter, createBridgeSheetSource, createRollBridge, createSheetClient, formatRollMessage, rollVariant };

package/dist/index.js

@@ -20,12 +20,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 +185,4 @@ function createBridgeSheetSource(options) {
   };
 }
 
-export { createBridgeSheetSource, createSheetBridge, createSheetClient, formatRollMessage, rollVariant };
+export { 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.3.0",
   "description": "Embed a longstoryshort.app character sheet in any virtual tabletop via iframe and postMessage",
   "license": "MIT",
   "type": "module",