@fluixi/vite-plugin 1.0.0-alpha.100

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ibrahima Touré
+
+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,84 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/fluixi/assets/main/logos/128x128.png" alt="Fluixi" width="120" height="120" />
+</p>
+
+# @fluixi/vite-plugin
+
+**The Vite plugin for Fluixi — compiles JSX and `` html`` `` templates.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-22c55e.svg)](./LICENSE)
+![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white)
+[![npm](https://img.shields.io/npm/v/@fluixi/vite-plugin?logo=npm)](https://www.npmjs.com/package/@fluixi/vite-plugin)
+![Vite](https://img.shields.io/badge/built%20on-Vite-646cff?logo=vite&logoColor=white)
+
+---
+
+## ✨ Overview
+
+`@fluixi/vite-plugin` sets the esbuild `jsxImportSource` and runs the Fluixi compile
+(via [`@fluixi/compiler`](../compiler)) — JSX and `` html`...` `` both, straight into
+`@fluixi/dom` runtime calls. It rewrites the source in place, so output carries a source
+map and holes keep the text the author wrote. Nothing from babel is installed for it.
+`@fluixi/core`
+re-exports `fluixi`/`createVitePlugin` from here, and [`@fluixi/start`](../start) wires it
+in automatically — use this plugin directly for a plain (non-meta-framework) Vite app.
+
+## 📦 Installation
+
+```sh
+pnpm add -D @fluixi/vite-plugin
+```
+
+## 🚀 Usage
+
+```ts
+import { defineConfig } from 'vite';
+import { fluixi } from '@fluixi/vite-plugin';
+
+export default defineConfig({
+  plugins: [
+    // JSX and html`` templates both compile straight into @fluixi/dom runtime
+    // calls (createNativeElement/spread/insert/…). No options required.
+    fluixi(),
+  ],
+});
+```
+
+## ⚙️ Options
+
+Options are [`@fluixi/compiler`](../compiler)'s `CompilerOptions`:
+
+| Option | Default | What |
+| --- | --- | --- |
+| `importSource` | `@fluixi/jsx` | where the JSX *types* come from; also the `jsxImportSource` given to esbuild |
+| `format` | `both` | which syntaxes to compile — `jsx`, `lit`, or `both` |
+| `signalModule` / `controlFlowModule` | `@fluixi/dom` | where emitted runtime symbols come from |
+| `resolve` | – | rules that supply a component import from a bare tag |
+| `globals` | `fluixi.d.ts` | where to write the generated ambient types (the resolved components and the `$signal`-style intrinsics). `false` skips it |
+| `propsDestructure` | `true` | rewrite a component's destructured props into property reads, so `function Card({ title })` keeps updating. A pattern it can't prove is left as written. Turn off for a package that ships its source |
+| `templateClone` / `partialTemplates` | `true` | clone static subtrees instead of building them |
+| `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
+
+[MIT](./LICENSE) © [Fluixi](https://fluixi.dev)

package/dist/graph-channel.cjs

@@ -0,0 +1,196 @@
+"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_fs = require("node:fs");
+var import_node_path = require("node:path");
+var import_node_url = require("node:url");
+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() {
+  return resolveForBrowser("@fluixi/devtools");
+}
+function ownPlugins() {
+  return resolveForBrowser("@fluixi/devtools/plugins");
+}
+function resolveForBrowser(spec) {
+  try {
+    const resolved = import_meta.resolve?.(spec);
+    if (resolved) return (0, import_node_url.fileURLToPath)(resolved);
+  } catch {
+  }
+  try {
+    const required = (0, import_node_module.createRequire)(import_meta.url).resolve(spec);
+    if (!required.endsWith(".cjs")) return required;
+    for (const ext of [".mjs", ".js"]) {
+      const sibling = required.slice(0, -".cjs".length) + ext;
+      if ((0, import_node_fs.existsSync)(sibling)) return sibling;
+    }
+    return required;
+  } 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;
+  const baseLoad = base.load;
+  const baseConfigureServer = base.configureServer;
+  return {
+    ...base,
+    resolveId(id, importer) {
+      if (id === VIRTUAL) return RESOLVED;
+      return baseResolveId?.call(this, id, importer) ?? null;
+    },
+    async load(id) {
+      if (id !== RESOLVED) return await baseLoad?.call(this, id) ?? 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) {
+      await baseConfigureServer?.call(this, 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":"AAiBA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC;AAqGnC;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,OAAO,EAAE,KAAK,EAAE,MAAM,IAAI,GAAG,MAAM,CA8HhG"}

package/dist/graph-channel.js

@@ -0,0 +1,243 @@
+// 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 { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+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() {
+    return resolveForBrowser('@fluixi/devtools');
+}
+/** The built-in plugins, beside the bundle they extend. Collecting happens in the agent. */
+function ownPlugins() {
+    return resolveForBrowser('@fluixi/devtools/plugins');
+}
+/**
+ * A package's ESM entry, by path.
+ *
+ * The agent below is served to a browser as an ES module and imports these by `/@fs/`
+ * path, so the file has to be the one with the named exports. `createRequire().resolve`
+ * answers with the `require` condition instead: the CJS build, and a `.cjs` file
+ * offers nothing to import, which surfaces as "does not provide an export named
+ * 'installDevtoolsHook'". It only started happening when devtools gained a CJS build;
+ * before that there was one file and either resolver found it.
+ */
+function resolveForBrowser(spec) {
+    // Honours the `import` condition, which is the one that matches how this is loaded.
+    try {
+        const resolved = import.meta.resolve?.(spec);
+        if (resolved)
+            return fileURLToPath(resolved);
+    }
+    catch {
+        // Fall through to the require-based resolution below.
+    }
+    try {
+        const required = createRequire(import.meta.url).resolve(spec);
+        if (!required.endsWith('.cjs'))
+            return required;
+        // Landed on the CJS build. Prefer its ESM sibling when the package ships one.
+        for (const ext of ['.mjs', '.js']) {
+            const sibling = required.slice(0, -'.cjs'.length) + ext;
+            if (existsSync(sibling))
+                return sibling;
+        }
+        return required;
+    }
+    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;
+    // The compiler plugin serves component styles through these hooks: the channel's own
+    // handling comes on top, never instead.
+    const baseLoad = base.load;
+    const baseConfigureServer = base.configureServer;
+    return {
+        ...base,
+        resolveId(id, importer) {
+            if (id === VIRTUAL)
+                return RESOLVED;
+            return baseResolveId?.call(this, id, importer) ?? null;
+        },
+        async load(id) {
+            if (id !== RESOLVED)
+                return (await baseLoad?.call(this, id)) ?? 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) {
+            await baseConfigureServer?.call(this, 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);
+}