@triggery/devtools-bridge 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @triggery/devtools-bridge
+
+## 0.1.0
+
+First public preview release.
+
+Page-side bridge for Triggery devtools — broadcasts runtime events over window.postMessage for the Chrome extension / standalone panel to consume
+
+See the [repository-level CHANGELOG](../../CHANGELOG.md#010--2026-05-16) for the full set of packages and the umbrella feature list. Future entries on this file are appended automatically by changesets.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aleksey Skhomenko
+
+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,43 @@
+# @triggery/devtools-bridge
+
+Page-side bridge that makes a Triggery runtime observable to external tools — the [Chrome extension](../../extensions/chrome-devtools), a future standalone web panel, custom inspectors, etc.
+
+## Install
+
+```bash
+pnpm add @triggery/devtools-bridge
+```
+
+## Use
+
+```ts
+import { createRuntime } from '@triggery/core';
+import { installDevtoolsBridge } from '@triggery/devtools-bridge';
+
+const runtime = createRuntime();
+
+if (import.meta.env.DEV) {
+  installDevtoolsBridge(runtime);
+}
+```
+
+That's it. The bridge:
+
+1. Exposes a discovery handle on `window.__triggery_devtools__` so tools can detect the runtime.
+2. Broadcasts a `triggery:hello` `postMessage` with the current `graph()` + inspector buffer.
+3. Subscribes to the runtime and broadcasts a `triggery:snapshot` for every new run.
+4. On `dispose()`, removes the discovery handle and broadcasts a `triggery:bye`.
+
+In Node / SSR `installDevtoolsBridge` returns a no-op disposer.
+
+## Wire format
+
+```ts
+{ source: 'triggery-devtools', type: 'triggery:hello',    runtimeId, graph, buffer, at }
+{ source: 'triggery-devtools', type: 'triggery:snapshot', runtimeId, snapshot,     at }
+{ source: 'triggery-devtools', type: 'triggery:bye',      runtimeId,               at }
+```
+
+## License
+
+MIT © Aleksey Skhomenko

package/dist/index.d.ts

@@ -0,0 +1,68 @@
+import { RuntimeGraph, TriggerInspectSnapshot, Runtime } from '@triggery/core';
+
+/**
+ * @triggery/devtools-bridge — make a runtime observable to external tools.
+ *
+ * Install once per runtime in DEV builds. The bridge:
+ *   1. Stamps a discovery object onto `window[globalKey]` so tools can
+ *      detect that the page has Triggery running and read the runtime id.
+ *   2. Broadcasts an initial `triggery:hello` message with the current
+ *      graph + inspector buffer (so a panel opened mid-session has data).
+ *   3. Subscribes to the runtime and broadcasts every new inspector
+ *      snapshot as `triggery:snapshot`.
+ *
+ * Messages are sent via `window.postMessage(..., '*')` with a stable
+ * `source` field, which the Chrome extension's content script listens
+ * for. Same wire format works for a standalone WebSocket-backed panel
+ * (planned for V2).
+ *
+ * @example
+ * ```ts
+ * import { createRuntime } from '@triggery/core';
+ * import { installDevtoolsBridge } from '@triggery/devtools-bridge';
+ *
+ * const runtime = createRuntime();
+ * if (import.meta.env.DEV) installDevtoolsBridge(runtime);
+ * ```
+ */
+
+/** Default `source` used in the postMessage envelope. */
+declare const DEVTOOLS_SOURCE = "triggery-devtools";
+/** Default key on `window` for runtime discovery. */
+declare const DEVTOOLS_GLOBAL_KEY = "__triggery_devtools__";
+type DevtoolsBridgeOptions = {
+    /** Custom discovery key — only override if you need multiple bridges. */
+    readonly globalKey?: string;
+    /** Custom envelope `source` — must match what the consumer (extension) filters on. */
+    readonly source?: string;
+};
+/** Type of every message we publish. The extension content script switches on this. */
+type DevtoolsMessage = {
+    readonly source: string;
+    readonly type: 'triggery:hello';
+    readonly runtimeId: string;
+    readonly graph: RuntimeGraph;
+    readonly buffer: readonly TriggerInspectSnapshot[];
+    readonly at: number;
+} | {
+    readonly source: string;
+    readonly type: 'triggery:snapshot';
+    readonly runtimeId: string;
+    readonly snapshot: TriggerInspectSnapshot;
+    readonly at: number;
+} | {
+    readonly source: string;
+    readonly type: 'triggery:bye';
+    readonly runtimeId: string;
+    readonly at: number;
+};
+/**
+ * Install the bridge. Returns a `dispose` function that unsubscribes and
+ * removes the discovery key — call it when the runtime itself goes away.
+ *
+ * Calling `installDevtoolsBridge` on a non-browser environment (Node, SSR)
+ * is safe — it returns a no-op disposer.
+ */
+declare function installDevtoolsBridge(runtime: Runtime, options?: DevtoolsBridgeOptions): () => void;
+
+export { DEVTOOLS_GLOBAL_KEY, DEVTOOLS_SOURCE, type DevtoolsBridgeOptions, type DevtoolsMessage, installDevtoolsBridge };

package/dist/index.js

@@ -0,0 +1,63 @@
+// src/index.ts
+var DEVTOOLS_SOURCE = "triggery-devtools";
+var DEVTOOLS_GLOBAL_KEY = "__triggery_devtools__";
+var getWindow = () => {
+  const g = globalThis;
+  return g.window;
+};
+function installDevtoolsBridge(runtime, options = {}) {
+  const win = getWindow();
+  if (!win) return () => {
+  };
+  const globalKey = options.globalKey ?? DEVTOOLS_GLOBAL_KEY;
+  const source = options.source ?? DEVTOOLS_SOURCE;
+  globalThis[globalKey] = {
+    runtime,
+    runtimeId: runtime.id,
+    source,
+    version: 1
+  };
+  win.postMessage(
+    {
+      source,
+      type: "triggery:hello",
+      runtimeId: runtime.id,
+      graph: runtime.graph(),
+      buffer: runtime.getInspectorBuffer(),
+      at: Date.now()
+    },
+    "*"
+  );
+  const token = runtime.subscribe((snapshot) => {
+    win.postMessage(
+      {
+        source,
+        type: "triggery:snapshot",
+        runtimeId: runtime.id,
+        snapshot,
+        at: Date.now()
+      },
+      "*"
+    );
+  });
+  let disposed = false;
+  return () => {
+    if (disposed) return;
+    disposed = true;
+    token.unregister();
+    delete globalThis[globalKey];
+    win.postMessage(
+      {
+        source,
+        type: "triggery:bye",
+        runtimeId: runtime.id,
+        at: Date.now()
+      },
+      "*"
+    );
+  };
+}
+
+export { DEVTOOLS_GLOBAL_KEY, DEVTOOLS_SOURCE, installDevtoolsBridge };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";AA6BO,IAAM,eAAA,GAAkB;AAExB,IAAM,mBAAA,GAAsB;AA0CnC,IAAM,YAAY,MAA8B;AAC9C,EAAA,MAAM,CAAA,GAAI,UAAA;AACV,EAAA,OAAO,CAAA,CAAE,MAAA;AACX,CAAA;AASO,SAAS,qBAAA,CACd,OAAA,EACA,OAAA,GAAiC,EAAC,EACtB;AACZ,EAAA,MAAM,MAAM,SAAA,EAAU;AACtB,EAAA,IAAI,CAAC,GAAA,EAAK,OAAO,MAAM;AAAA,EAAC,CAAA;AAExB,EAAA,MAAM,SAAA,GAAY,QAAQ,SAAA,IAAa,mBAAA;AACvC,EAAA,MAAM,MAAA,GAAS,QAAQ,MAAA,IAAU,eAAA;AAKjC,EAAC,UAAA,CAA0B,SAAS,CAAA,GAAI;AAAA,IACtC,OAAA;AAAA,IACA,WAAW,OAAA,CAAQ,EAAA;AAAA,IACnB,MAAA;AAAA,IACA,OAAA,EAAS;AAAA,GACX;AAIA,EAAA,GAAA,CAAI,WAAA;AAAA,IACF;AAAA,MACE,MAAA;AAAA,MACA,IAAA,EAAM,gBAAA;AAAA,MACN,WAAW,OAAA,CAAQ,EAAA;AAAA,MACnB,KAAA,EAAO,QAAQ,KAAA,EAAM;AAAA,MACrB,MAAA,EAAQ,QAAQ,kBAAA,EAAmB;AAAA,MACnC,EAAA,EAAI,KAAK,GAAA;AAAI,KACf;AAAA,IACA;AAAA,GACF;AAGA,EAAA,MAAM,KAAA,GAAQ,OAAA,CAAQ,SAAA,CAAU,CAAC,QAAA,KAAa;AAC5C,IAAA,GAAA,CAAI,WAAA;AAAA,MACF;AAAA,QACE,MAAA;AAAA,QACA,IAAA,EAAM,mBAAA;AAAA,QACN,WAAW,OAAA,CAAQ,EAAA;AAAA,QACnB,QAAA;AAAA,QACA,EAAA,EAAI,KAAK,GAAA;AAAI,OACf;AAAA,MACA;AAAA,KACF;AAAA,EACF,CAAC,CAAA;AAED,EAAA,IAAI,QAAA,GAAW,KAAA;AACf,EAAA,OAAO,MAAM;AACX,IAAA,IAAI,QAAA,EAAU;AACd,IAAA,QAAA,GAAW,IAAA;AACX,IAAA,KAAA,CAAM,UAAA,EAAW;AACjB,IAAA,OAAQ,WAA0B,SAAS,CAAA;AAC3C,IAAA,GAAA,CAAI,WAAA;AAAA,MACF;AAAA,QACE,MAAA;AAAA,QACA,IAAA,EAAM,cAAA;AAAA,QACN,WAAW,OAAA,CAAQ,EAAA;AAAA,QACnB,EAAA,EAAI,KAAK,GAAA;AAAI,OACf;AAAA,MACA;AAAA,KACF;AAAA,EACF,CAAA;AACF","file":"index.js","sourcesContent":["/**\n * @triggery/devtools-bridge — make a runtime observable to external tools.\n *\n * Install once per runtime in DEV builds. The bridge:\n *   1. Stamps a discovery object onto `window[globalKey]` so tools can\n *      detect that the page has Triggery running and read the runtime id.\n *   2. Broadcasts an initial `triggery:hello` message with the current\n *      graph + inspector buffer (so a panel opened mid-session has data).\n *   3. Subscribes to the runtime and broadcasts every new inspector\n *      snapshot as `triggery:snapshot`.\n *\n * Messages are sent via `window.postMessage(..., '*')` with a stable\n * `source` field, which the Chrome extension's content script listens\n * for. Same wire format works for a standalone WebSocket-backed panel\n * (planned for V2).\n *\n * @example\n * ```ts\n * import { createRuntime } from '@triggery/core';\n * import { installDevtoolsBridge } from '@triggery/devtools-bridge';\n *\n * const runtime = createRuntime();\n * if (import.meta.env.DEV) installDevtoolsBridge(runtime);\n * ```\n */\n\nimport type { Runtime, RuntimeGraph, TriggerInspectSnapshot } from '@triggery/core';\n\n/** Default `source` used in the postMessage envelope. */\nexport const DEVTOOLS_SOURCE = 'triggery-devtools';\n/** Default key on `window` for runtime discovery. */\nexport const DEVTOOLS_GLOBAL_KEY = '__triggery_devtools__';\n\nexport type DevtoolsBridgeOptions = {\n  /** Custom discovery key — only override if you need multiple bridges. */\n  readonly globalKey?: string;\n  /** Custom envelope `source` — must match what the consumer (extension) filters on. */\n  readonly source?: string;\n};\n\n/** Type of every message we publish. The extension content script switches on this. */\nexport type DevtoolsMessage =\n  | {\n      readonly source: string;\n      readonly type: 'triggery:hello';\n      readonly runtimeId: string;\n      readonly graph: RuntimeGraph;\n      readonly buffer: readonly TriggerInspectSnapshot[];\n      readonly at: number;\n    }\n  | {\n      readonly source: string;\n      readonly type: 'triggery:snapshot';\n      readonly runtimeId: string;\n      readonly snapshot: TriggerInspectSnapshot;\n      readonly at: number;\n    }\n  | {\n      readonly source: string;\n      readonly type: 'triggery:bye';\n      readonly runtimeId: string;\n      readonly at: number;\n    };\n\ntype WindowLike = {\n  postMessage(data: unknown, targetOrigin: string): void;\n};\n\ntype GlobalLike = {\n  [key: string]: unknown;\n  window?: WindowLike;\n};\n\nconst getWindow = (): WindowLike | undefined => {\n  const g = globalThis as GlobalLike;\n  return g.window;\n};\n\n/**\n * Install the bridge. Returns a `dispose` function that unsubscribes and\n * removes the discovery key — call it when the runtime itself goes away.\n *\n * Calling `installDevtoolsBridge` on a non-browser environment (Node, SSR)\n * is safe — it returns a no-op disposer.\n */\nexport function installDevtoolsBridge(\n  runtime: Runtime,\n  options: DevtoolsBridgeOptions = {},\n): () => void {\n  const win = getWindow();\n  if (!win) return () => {};\n\n  const globalKey = options.globalKey ?? DEVTOOLS_GLOBAL_KEY;\n  const source = options.source ?? DEVTOOLS_SOURCE;\n\n  // Discovery handle for extension content scripts. Holds a reference to the\n  // live runtime so tools that can reach the main world (e.g. injected\n  // scripts) can subscribe directly without postMessage round-trips.\n  (globalThis as GlobalLike)[globalKey] = {\n    runtime,\n    runtimeId: runtime.id,\n    source,\n    version: 1,\n  };\n\n  // Initial hello with the current graph + buffer so a panel opened mid-session\n  // sees state immediately.\n  win.postMessage(\n    {\n      source,\n      type: 'triggery:hello',\n      runtimeId: runtime.id,\n      graph: runtime.graph(),\n      buffer: runtime.getInspectorBuffer(),\n      at: Date.now(),\n    } satisfies DevtoolsMessage,\n    '*',\n  );\n\n  // Per-event stream.\n  const token = runtime.subscribe((snapshot) => {\n    win.postMessage(\n      {\n        source,\n        type: 'triggery:snapshot',\n        runtimeId: runtime.id,\n        snapshot,\n        at: Date.now(),\n      } satisfies DevtoolsMessage,\n      '*',\n    );\n  });\n\n  let disposed = false;\n  return () => {\n    if (disposed) return;\n    disposed = true;\n    token.unregister();\n    delete (globalThis as GlobalLike)[globalKey];\n    win.postMessage(\n      {\n        source,\n        type: 'triggery:bye',\n        runtimeId: runtime.id,\n        at: Date.now(),\n      } satisfies DevtoolsMessage,\n      '*',\n    );\n  };\n}\n"]}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@triggery/devtools-bridge",
+  "version": "0.1.0",
+  "description": "Page-side bridge for Triggery devtools — broadcasts runtime events over window.postMessage for the Chrome extension / standalone panel to consume",
+  "license": "MIT",
+  "author": "Aleksey Skhomenko",
+  "homepage": "https://triggeryjs.github.io/triggery",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/triggeryjs/triggery.git",
+    "directory": "packages/devtools-bridge"
+  },
+  "bugs": "https://github.com/triggeryjs/triggery/issues",
+  "funding": [
+    {
+      "type": "patreon",
+      "url": "https://www.patreon.com/triggery"
+    },
+    {
+      "type": "boosty",
+      "url": "https://boosty.to/triggery"
+    }
+  ],
+  "keywords": [
+    "triggery",
+    "devtools",
+    "chrome-extension",
+    "bridge",
+    "inspector"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@triggery/core": "0.1.0"
+  },
+  "devDependencies": {
+    "happy-dom": "^20.9.0",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6",
+    "@triggery/core": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest --passWithNoTests",
+    "test:coverage": "vitest run --coverage --passWithNoTests",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}