@fluixi/vite-plugin 1.0.0-alpha.82 → 1.0.0-alpha.84

package/README.md

@@ -60,6 +60,24 @@ Options are [`@fluixi/compiler`](../compiler)'s `CompilerOptions`:
 | `delegateEvents` | `true` | event delegation |
 | `sourceMaps` | `true` | emit source maps |
 | `babel` | `false` | compile through the babel front-end instead, for a project whose own babel plugins have to see the output. Needs `@babel/core`, which is an optional peer |
+| `devtools` | on in dev | serve the running app's reactive graph, and mark where each node was created. `{ external: true }` marks dependencies too |
+
+## 🕸️ Reactive graph
+
+The plugin adds a small agent to the page in development mode, which reports the reactive graph at `GET /__fluixi/graph`. This graph is available as plain JSON, making it easy to read and use in tools like editor extensions or panels. The agent comes with the plugin, so a project needs nothing else installed; only the framework itself is resolved from the project, since watching a second copy of the runtime would watch a graph nothing is using.
+
+Here is how you can configure the plugin:
+
+```ts
+// vite.config.ts
+plugins: [fluixi()],                            // graph on in dev
+plugins: [fluixi({ devtools: false })],         // off
+plugins: [fluixi({ devtools: { external: true } })],  // dependencies too
+```
+
+Each node in the graph carries the file, line, and column it was created at, named relative to the project root. By default, nodes from dependencies are not marked, which keeps the graph focused on the code you are editing.
+
+The `external` option is useful for working on the framework itself. It marks nodes from `node_modules` and outside the project root as `external`, allowing you to see which nodes were created by libraries and which by your application. The application's call site takes precedence over the wrapper that created the node, so `count` appears as the line you wrote it on, not the line inside `signal()`.
 
 ## 📄 License
 

package/dist/graph-channel.cjs

@@ -0,0 +1,181 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/graph-channel.ts
+var graph_channel_exports = {};
+__export(graph_channel_exports, {
+  withGraphChannel: () => withGraphChannel
+});
+module.exports = __toCommonJS(graph_channel_exports);
+var import_node_module = require("node:module");
+var import_node_path = require("node:path");
+var import_meta = {};
+var VIRTUAL = "virtual:fluixi/devtools-agent";
+var RESOLVED = `\0${VIRTUAL}`;
+var ENDPOINT = "/__fluixi/graph";
+var EVENT = "fluixi:graph";
+var MISSING = "the plugin could not load @fluixi/devtools from its own dependencies";
+var WAITING = "no page has reported yet — open the application in a browser";
+var INTERVAL = 100;
+var HISTORY = 500;
+var agentSource = (devtools, plugins, signal, reactive) => `
+import { installDevtoolsHook, observeGraph } from ${JSON.stringify(devtools)};
+import ${JSON.stringify(plugins)};
+import { observeReactiveNodes } from ${JSON.stringify(signal)};
+import { VERSION } from ${JSON.stringify(reactive)};
+
+// The runtime this module imports is the application's own — same module graph, same nodes.
+// Nothing waits for the runtime to offer itself; that path is for a tool loaded from outside.
+//
+// \`watch\` is this copy of devtools, handed over with the runtime. A browser extension
+// installs a hook at document_start and so owns it; without this the graph would be built
+// by that extension's build rather than the one shipped alongside this application.
+const hook = installDevtoolsHook();
+hook.inject({ observeReactiveNodes, version: VERSION, watch: observeGraph });
+
+const send = (kind, snapshot) => import.meta.hot?.send(${JSON.stringify(EVENT)}, { kind, snapshot });
+
+const first = hook.snapshot();
+// Kept and handed back, so a browser panel polling the same hook cannot consume what this
+// one has not been told about yet.
+let cursor = first?.cursor;
+send('full', first);
+const timer = setInterval(() => {
+  const delta = hook.snapshot({ partial: true, since: cursor });
+  if (!delta) return;
+  cursor = delta.cursor;
+  // Events count on their own: an effect that ran without changing a value moves no node.
+  if (delta.nodes.length || delta.removed?.length || delta.events?.length) send('delta', delta);
+}, ${INTERVAL});
+
+import.meta.hot?.dispose(() => clearInterval(timer));
+`;
+function ownDevtools() {
+  try {
+    return (0, import_node_module.createRequire)(import_meta.url).resolve("@fluixi/devtools");
+  } catch {
+    return null;
+  }
+}
+function ownPlugins() {
+  try {
+    return (0, import_node_module.createRequire)(import_meta.url).resolve("@fluixi/devtools/plugins");
+  } catch {
+    return null;
+  }
+}
+function withGraphChannel(base, enabled, start) {
+  let wire = null;
+  let available = false;
+  let reason = MISSING;
+  let root = process.cwd();
+  let log;
+  let graph = /* @__PURE__ */ new Map();
+  let stamp = 0;
+  let events = [];
+  const baseResolveId = base.resolveId;
+  const baseTransformIndexHtml = base.transformIndexHtml;
+  return {
+    ...base,
+    resolveId(id, importer) {
+      if (id === VIRTUAL) return RESOLVED;
+      return baseResolveId?.call(this, id, importer) ?? null;
+    },
+    async load(id) {
+      if (id !== RESOLVED) return null;
+      const from = (0, import_node_path.join)(root, "fluixi-devtools-agent.js");
+      const specs = ["@fluixi/reactive/signal", "@fluixi/reactive"];
+      const ids = await Promise.all(specs.map((spec) => this.resolve?.(spec, from, { skipSelf: true })));
+      const missing = specs.filter((_, i) => !ids[i]?.id);
+      const devtools = ownDevtools();
+      const plugins = ownPlugins();
+      if (missing.length || !devtools || !plugins) {
+        reason = missing.length ? `${missing.join(", ")} did not resolve from ${root}` : MISSING;
+        log?.(`[fluixi] reactive graph off — ${reason}`);
+        return "export {};";
+      }
+      return agentSource(`/@fs/${devtools}`, `/@fs/${plugins}`, ids[0].id, ids[1].id);
+    },
+    async configureServer(server) {
+      if (!enabled()) return;
+      root = server.config?.root ?? root;
+      log = server.config?.logger?.info.bind(server.config.logger);
+      wire = await import("@fluixi/devtools/wire").catch(() => null);
+      available = wire !== null;
+      if (wire) start();
+      if (wire) reason = WAITING;
+      else {
+        log?.(`[fluixi] reactive graph off — ${MISSING}`);
+      }
+      server.middlewares.use(ENDPOINT, (_req, res) => {
+        const snapshot = wire ? { ...wire.serializeGraph(graph, stamp || Date.now()), events } : { t: Date.now(), nodes: [] };
+        const body = JSON.stringify(reason ? { ...snapshot, reason } : snapshot);
+        res.setHeader("Content-Type", "application/json");
+        res.setHeader("Access-Control-Allow-Origin", "*");
+        res.setHeader("Cache-Control", "no-store");
+        res.end(body);
+      });
+      if (!wire) return;
+      server.ws.on(EVENT, (payload) => {
+        const message = payload;
+        if (!message?.snapshot || !wire) return;
+        const full = message.kind === "full";
+        graph = wire.applySnapshot(full ? /* @__PURE__ */ new Map() : graph, message.snapshot);
+        if (full) events = [];
+        const arriving = message.snapshot.events;
+        if (arriving?.length) events = [...events, ...arriving].slice(-HISTORY);
+        stamp = Date.now();
+        reason = null;
+      });
+    },
+    transformIndexHtml: {
+      order: "pre",
+      handler(html, ctx) {
+        const inherited = callInheritedHtml(baseTransformIndexHtml, html, ctx);
+        if (!enabled() || !available || !wire) return inherited;
+        return {
+          html: typeof inherited === "string" ? inherited : html,
+          tags: [
+            {
+              tag: "script",
+              // First in the head, so the entry cannot create a node before the agent runs.
+              injectTo: "head-prepend",
+              attrs: { type: "module", src: `/@id/${VIRTUAL}` }
+            }
+          ]
+        };
+      }
+    }
+  };
+}
+function callInheritedHtml(hook, html, ctx) {
+  if (typeof hook === "function") return hook(html, ctx);
+  const handler = hook?.handler;
+  return handler?.(html, ctx);
+}

package/dist/graph-channel.d.ts

@@ -0,0 +1,7 @@
+import type { Plugin } from 'vite';
+/**
+ * Add the graph channel to a plugin, keeping whatever hooks it already has. Composed rather
+ * than returned alongside so `fluixi()` stays one plugin.
+ */
+export declare function withGraphChannel(base: Plugin, enabled: () => boolean, start: () => void): Plugin;
+//# sourceMappingURL=graph-channel.d.ts.map

package/dist/graph-channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-channel.d.ts","sourceRoot":"","sources":["../src/graph-channel.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AA4EnC;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,OAAO,EAAE,KAAK,EAAE,MAAM,IAAI,GAAG,MAAM,CAyHhG"}

package/dist/graph-channel.js

@@ -0,0 +1,210 @@
+// The running app's reactive graph, offered to whatever wants to draw it.
+//
+// A dev-only agent module goes into the page ahead of the entry, so no node is created
+// before something is watching. It pushes the graph over the channel Vite already keeps open
+// for HMR, and the dev server holds the latest state and answers a plain GET — so an editor
+// extension, a panel, or curl all read the same thing without speaking HMR.
+//
+//   GET /__fluixi/graph  →  { t, nodes: [...] }
+//
+// Off in a build. The agent's own half comes from this package's dependency rather than from
+// the application, so a project gets the graph by having the plugin and nothing else; only
+// the framework itself is resolved from the project, because watching a second copy of the
+// runtime would watch a graph nobody is using.
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+const VIRTUAL = 'virtual:fluixi/devtools-agent';
+const RESOLVED = `\0${VIRTUAL}`;
+const ENDPOINT = '/__fluixi/graph';
+const EVENT = 'fluixi:graph';
+/** Why a project that runs the plugin might still have nothing to show. */
+const MISSING = 'the plugin could not load @fluixi/devtools from its own dependencies';
+const WAITING = 'no page has reported yet — open the application in a browser';
+/** How often the agent looks for movement. Fast enough to watch, slow enough to ignore. */
+const INTERVAL = 100;
+/** A few hundred interactions' worth. */
+const HISTORY = 500;
+/** Written with the ids resolved: a virtual module has no directory to resolve a bare one from. */
+const agentSource = (devtools, plugins, signal, reactive) => `
+import { installDevtoolsHook, observeGraph } from ${JSON.stringify(devtools)};
+import ${JSON.stringify(plugins)};
+import { observeReactiveNodes } from ${JSON.stringify(signal)};
+import { VERSION } from ${JSON.stringify(reactive)};
+
+// The runtime this module imports is the application's own — same module graph, same nodes.
+// Nothing waits for the runtime to offer itself; that path is for a tool loaded from outside.
+//
+// \`watch\` is this copy of devtools, handed over with the runtime. A browser extension
+// installs a hook at document_start and so owns it; without this the graph would be built
+// by that extension's build rather than the one shipped alongside this application.
+const hook = installDevtoolsHook();
+hook.inject({ observeReactiveNodes, version: VERSION, watch: observeGraph });
+
+const send = (kind, snapshot) => import.meta.hot?.send(${JSON.stringify(EVENT)}, { kind, snapshot });
+
+const first = hook.snapshot();
+// Kept and handed back, so a browser panel polling the same hook cannot consume what this
+// one has not been told about yet.
+let cursor = first?.cursor;
+send('full', first);
+const timer = setInterval(() => {
+  const delta = hook.snapshot({ partial: true, since: cursor });
+  if (!delta) return;
+  cursor = delta.cursor;
+  // Events count on their own: an effect that ran without changing a value moves no node.
+  if (delta.nodes.length || delta.removed?.length || delta.events?.length) send('delta', delta);
+}, ${INTERVAL});
+
+import.meta.hot?.dispose(() => clearInterval(timer));
+`;
+/**
+ * The devtools bundle this plugin depends on, as a path the dev server can serve.
+ *
+ * Asking the application to install it as well made the graph depend on a devDependency
+ * nobody knew to add, and in a workspace it resolved for one project and not the one beside
+ * it — which reads as the feature being broken rather than absent.
+ */
+function ownDevtools() {
+    try {
+        return createRequire(import.meta.url).resolve('@fluixi/devtools');
+    }
+    catch {
+        return null;
+    }
+}
+/** The built-in plugins, beside the bundle they extend. Collecting happens in the agent. */
+function ownPlugins() {
+    try {
+        return createRequire(import.meta.url).resolve('@fluixi/devtools/plugins');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Add the graph channel to a plugin, keeping whatever hooks it already has. Composed rather
+ * than returned alongside so `fluixi()` stays one plugin.
+ */
+export function withGraphChannel(base, enabled, start) {
+    let wire = null;
+    let available = false;
+    /** What to say when the graph is empty. Cleared once a page has reported. */
+    let reason = MISSING;
+    let root = process.cwd();
+    let log;
+    let graph = new Map();
+    let stamp = 0;
+    /**
+     * Kept, not drained: this endpoint has no single reader, and an editor panel draining it
+     * would blank a browser panel's timeline. Every event carries a seq, so consumers dedupe.
+     */
+    let events = [];
+    const baseResolveId = base.resolveId;
+    const baseTransformIndexHtml = base.transformIndexHtml;
+    return {
+        ...base,
+        resolveId(id, importer) {
+            if (id === VIRTUAL)
+                return RESOLVED;
+            return baseResolveId?.call(this, id, importer) ?? null;
+        },
+        async load(id) {
+            if (id !== RESOLVED)
+                return null;
+            const from = join(root, 'fluixi-devtools-agent.js');
+            // Only the framework comes from the application: the hook hands over that runtime's
+            // own registration, and a second copy would report a graph nothing is using.
+            const specs = ['@fluixi/reactive/signal', '@fluixi/reactive'];
+            const ids = await Promise.all(specs.map((spec) => this.resolve?.(spec, from, { skipSelf: true })));
+            const missing = specs.filter((_, i) => !ids[i]?.id);
+            const devtools = ownDevtools();
+            const plugins = ownPlugins();
+            // Nothing to watch with is not an error worth breaking the page over.
+            if (missing.length || !devtools || !plugins) {
+                reason = missing.length
+                    ? `${missing.join(', ')} did not resolve from ${root}`
+                    : MISSING;
+                log?.(`[fluixi] reactive graph off — ${reason}`);
+                return 'export {};';
+            }
+            // Served by path: it is this package's copy, not one the application imports.
+            return agentSource(`/@fs/${devtools}`, `/@fs/${plugins}`, ids[0].id, ids[1].id);
+        },
+        async configureServer(server) {
+            if (!enabled())
+                return;
+            root = server.config?.root ?? root;
+            log = server.config?.logger?.info.bind(server.config.logger);
+            wire = await import('@fluixi/devtools/wire').catch(() => null);
+            available = wire !== null;
+            // Source marks cost something, so they wait until there is a server watching for them.
+            if (wire)
+                start();
+            if (wire)
+                reason = WAITING;
+            else {
+                // Said once, not per request: without the package there is no agent to inject and
+                // nothing to report, and that is a missing devDependency rather than a failure.
+                log?.(`[fluixi] reactive graph off — ${MISSING}`);
+            }
+            // The endpoint answers either way. A tool asking for the graph of a project that has
+            // not turned it on deserves to be told which of the two it is, and 404 says neither —
+            // it reads the same as a dev server that is not a fluixi project at all.
+            server.middlewares.use(ENDPOINT, (_req, res) => {
+                const snapshot = wire
+                    ? { ...wire.serializeGraph(graph, stamp || Date.now()), events }
+                    : { t: Date.now(), nodes: [] };
+                const body = JSON.stringify(reason ? { ...snapshot, reason } : snapshot);
+                res.setHeader('Content-Type', 'application/json');
+                // Read by an editor extension and by panels served from another origin.
+                res.setHeader('Access-Control-Allow-Origin', '*');
+                res.setHeader('Cache-Control', 'no-store');
+                res.end(body);
+            });
+            if (!wire)
+                return;
+            server.ws.on(EVENT, (payload) => {
+                const message = payload;
+                if (!message?.snapshot || !wire)
+                    return;
+                // A reload sends a full snapshot, which replaces whatever the last page left behind.
+                const full = message.kind === 'full';
+                graph = wire.applySnapshot(full ? new Map() : graph, message.snapshot);
+                // The history goes with it: its ids name nodes the previous page had.
+                if (full)
+                    events = [];
+                const arriving = message.snapshot.events;
+                if (arriving?.length)
+                    events = [...events, ...arriving].slice(-HISTORY);
+                stamp = Date.now();
+                reason = null;
+            });
+        },
+        transformIndexHtml: {
+            order: 'pre',
+            handler(html, ctx) {
+                const inherited = callInheritedHtml(baseTransformIndexHtml, html, ctx);
+                if (!enabled() || !available || !wire)
+                    return inherited;
+                return {
+                    html: typeof inherited === 'string' ? inherited : html,
+                    tags: [
+                        {
+                            tag: 'script',
+                            // First in the head, so the entry cannot create a node before the agent runs.
+                            injectTo: 'head-prepend',
+                            attrs: { type: 'module', src: `/@id/${VIRTUAL}` },
+                        },
+                    ],
+                };
+            },
+        },
+    };
+}
+/** A plugin may declare transformIndexHtml as a function or as an object with a handler. */
+function callInheritedHtml(hook, html, ctx) {
+    if (typeof hook === 'function')
+        return hook(html, ctx);
+    const handler = hook?.handler;
+    return handler?.(html, ctx);
+}

package/dist/graph-channel.mjs

@@ -0,0 +1,149 @@
+// src/graph-channel.ts
+import { createRequire } from "node:module";
+import { join } from "node:path";
+var VIRTUAL = "virtual:fluixi/devtools-agent";
+var RESOLVED = `\0${VIRTUAL}`;
+var ENDPOINT = "/__fluixi/graph";
+var EVENT = "fluixi:graph";
+var MISSING = "the plugin could not load @fluixi/devtools from its own dependencies";
+var WAITING = "no page has reported yet — open the application in a browser";
+var INTERVAL = 100;
+var HISTORY = 500;
+var agentSource = (devtools, plugins, signal, reactive) => `
+import { installDevtoolsHook, observeGraph } from ${JSON.stringify(devtools)};
+import ${JSON.stringify(plugins)};
+import { observeReactiveNodes } from ${JSON.stringify(signal)};
+import { VERSION } from ${JSON.stringify(reactive)};
+
+// The runtime this module imports is the application's own — same module graph, same nodes.
+// Nothing waits for the runtime to offer itself; that path is for a tool loaded from outside.
+//
+// \`watch\` is this copy of devtools, handed over with the runtime. A browser extension
+// installs a hook at document_start and so owns it; without this the graph would be built
+// by that extension's build rather than the one shipped alongside this application.
+const hook = installDevtoolsHook();
+hook.inject({ observeReactiveNodes, version: VERSION, watch: observeGraph });
+
+const send = (kind, snapshot) => import.meta.hot?.send(${JSON.stringify(EVENT)}, { kind, snapshot });
+
+const first = hook.snapshot();
+// Kept and handed back, so a browser panel polling the same hook cannot consume what this
+// one has not been told about yet.
+let cursor = first?.cursor;
+send('full', first);
+const timer = setInterval(() => {
+  const delta = hook.snapshot({ partial: true, since: cursor });
+  if (!delta) return;
+  cursor = delta.cursor;
+  // Events count on their own: an effect that ran without changing a value moves no node.
+  if (delta.nodes.length || delta.removed?.length || delta.events?.length) send('delta', delta);
+}, ${INTERVAL});
+
+import.meta.hot?.dispose(() => clearInterval(timer));
+`;
+function ownDevtools() {
+  try {
+    return createRequire(import.meta.url).resolve("@fluixi/devtools");
+  } catch {
+    return null;
+  }
+}
+function ownPlugins() {
+  try {
+    return createRequire(import.meta.url).resolve("@fluixi/devtools/plugins");
+  } catch {
+    return null;
+  }
+}
+function withGraphChannel(base, enabled, start) {
+  let wire = null;
+  let available = false;
+  let reason = MISSING;
+  let root = process.cwd();
+  let log;
+  let graph = /* @__PURE__ */ new Map();
+  let stamp = 0;
+  let events = [];
+  const baseResolveId = base.resolveId;
+  const baseTransformIndexHtml = base.transformIndexHtml;
+  return {
+    ...base,
+    resolveId(id, importer) {
+      if (id === VIRTUAL) return RESOLVED;
+      return baseResolveId?.call(this, id, importer) ?? null;
+    },
+    async load(id) {
+      if (id !== RESOLVED) return null;
+      const from = join(root, "fluixi-devtools-agent.js");
+      const specs = ["@fluixi/reactive/signal", "@fluixi/reactive"];
+      const ids = await Promise.all(specs.map((spec) => this.resolve?.(spec, from, { skipSelf: true })));
+      const missing = specs.filter((_, i) => !ids[i]?.id);
+      const devtools = ownDevtools();
+      const plugins = ownPlugins();
+      if (missing.length || !devtools || !plugins) {
+        reason = missing.length ? `${missing.join(", ")} did not resolve from ${root}` : MISSING;
+        log?.(`[fluixi] reactive graph off — ${reason}`);
+        return "export {};";
+      }
+      return agentSource(`/@fs/${devtools}`, `/@fs/${plugins}`, ids[0].id, ids[1].id);
+    },
+    async configureServer(server) {
+      if (!enabled()) return;
+      root = server.config?.root ?? root;
+      log = server.config?.logger?.info.bind(server.config.logger);
+      wire = await import("@fluixi/devtools/wire").catch(() => null);
+      available = wire !== null;
+      if (wire) start();
+      if (wire) reason = WAITING;
+      else {
+        log?.(`[fluixi] reactive graph off — ${MISSING}`);
+      }
+      server.middlewares.use(ENDPOINT, (_req, res) => {
+        const snapshot = wire ? { ...wire.serializeGraph(graph, stamp || Date.now()), events } : { t: Date.now(), nodes: [] };
+        const body = JSON.stringify(reason ? { ...snapshot, reason } : snapshot);
+        res.setHeader("Content-Type", "application/json");
+        res.setHeader("Access-Control-Allow-Origin", "*");
+        res.setHeader("Cache-Control", "no-store");
+        res.end(body);
+      });
+      if (!wire) return;
+      server.ws.on(EVENT, (payload) => {
+        const message = payload;
+        if (!message?.snapshot || !wire) return;
+        const full = message.kind === "full";
+        graph = wire.applySnapshot(full ? /* @__PURE__ */ new Map() : graph, message.snapshot);
+        if (full) events = [];
+        const arriving = message.snapshot.events;
+        if (arriving?.length) events = [...events, ...arriving].slice(-HISTORY);
+        stamp = Date.now();
+        reason = null;
+      });
+    },
+    transformIndexHtml: {
+      order: "pre",
+      handler(html, ctx) {
+        const inherited = callInheritedHtml(baseTransformIndexHtml, html, ctx);
+        if (!enabled() || !available || !wire) return inherited;
+        return {
+          html: typeof inherited === "string" ? inherited : html,
+          tags: [
+            {
+              tag: "script",
+              // First in the head, so the entry cannot create a node before the agent runs.
+              injectTo: "head-prepend",
+              attrs: { type: "module", src: `/@id/${VIRTUAL}` }
+            }
+          ]
+        };
+      }
+    }
+  };
+}
+function callInheritedHtml(hook, html, ctx) {
+  if (typeof hook === "function") return hook(html, ctx);
+  const handler = hook?.handler;
+  return handler?.(html, ctx);
+}
+export {
+  withGraphChannel
+};