@kabmo-labs/kabmo 0.0.0-stage → 0.1.0

package/src/client/lib/launch/types.ts

@@ -0,0 +1,67 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The Launch Handler / File Handling API surface, declared here because the
+ * DOM lib does not ship it.
+ *
+ * `Window.launchQueue` and `LaunchParams` are Chromium-only and were never
+ * merged into TypeScript's `lib.dom.d.ts`, so every use would otherwise be an
+ * unchecked cast. The surface is small and stable (Chrome 102+), so declaring
+ * the two shapes is more honest than `as unknown as { launchQueue: … }` at each
+ * call site.
+ *
+ * `setConsumer(null)` is part of the real signature — it is what clears a
+ * consumer — and is declared because this module relies on it.
+ */
+
+export interface LaunchParams {
+  /** The files a launch handed over. A directory launch carries handles too. */
+  files: FileSystemHandle[];
+}
+
+export interface LaunchQueue {
+  setConsumer(consumer: ((params: LaunchParams) => void) | null): void;
+}
+
+declare global {
+  interface Window {
+    launchQueue?: LaunchQueue;
+  }
+
+  /**
+   * The File System Access drop path, absent from `lib.dom.d.ts` for the same
+   * reason `launchQueue` is.
+   *
+   * This is the ONLY way to open a file dragged from Finder with write access:
+   * measured on Chrome for macOS, such a drag declares `types: ["Files"]` and
+   * NOTHING ELSE — no `text/uri-list`, no `text/plain` — so `getData()` yields
+   * no path, and `dataTransfer.files` is empty during the whole drag and only
+   * populated at `drop` (with a `File`, which is read-only). The handle is
+   * populated from the first `dragenter`, so it is also what makes a drop
+   * target able to accept the drag at all.
+   */
+  interface DataTransferItem {
+    getAsFileSystemHandle?(): Promise<FileSystemHandle | null>;
+  }
+
+  interface FileSystemHandlePermissionDescriptor {
+    mode?: 'read' | 'readwrite';
+  }
+
+  /**
+   * The permission pair, also missing from `lib.dom.d.ts`.
+   *
+   * These matter because a handle from a DROP is not writable by default:
+   * measured on Chrome for macOS, `queryPermission({mode:'read'})` is
+   * `"granted"` while `queryPermission({mode:'readwrite'})` is `"prompt"`, and
+   * `createWritable()` REFUSES while the state is `prompt`. `requestPermission`
+   * is what promotes it, and it needs a user gesture — see `writeThroughHandle`.
+   */
+  interface FileSystemHandle {
+    queryPermission?(descriptor?: FileSystemHandlePermissionDescriptor): Promise<PermissionState>;
+    requestPermission?(descriptor?: FileSystemHandlePermissionDescriptor): Promise<PermissionState>;
+  }
+}

package/src/client/lib/line-reveal.ts

@@ -0,0 +1,61 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The hand-off from an outline row to whichever editor is drawing its file.
+ *
+ * A symbol click has to do two things at different moments: the file is already
+ * the editor's tab, but the SELECTION can only be placed once that file's bytes
+ * are on screen. The request therefore cannot ride on the tab entry — that entry
+ * is persisted per session, so a reload would re-fire a jump the user already
+ * took.
+ *
+ * It is a separate store from `search-reveal` on purpose. A search jump also
+ * opens the find bar on its query and paints every occurrence, which is exactly
+ * what a symbol jump must NOT do: an outline row names a declaration, and
+ * covering it with a find bar would hide the line it was asked to show.
+ *
+ * The request names a LINE plus the NAME's span, not a document offset: an
+ * outline is computed from a document, and line/column is the unit both sides
+ * share. The editor resolves it against its own buffer at serve time, so the
+ * jump lands on the declaration the row pointed at even if the file was edited
+ * in between. Selecting the name's own span is what makes the click show the
+ * reader WHICH identifier it landed on — a bare caret at the start of
+ * `export class Widget {` sits on the word `export`.
+ */
+
+export interface LineRevealRequest {
+  /** Workspace-relative path of the file the line lives in. */
+  path: string;
+  /** 1-based line number. */
+  line: number;
+  /** 1-based column where the name starts; omitted means the line's start. */
+  column?: number;
+  /** Length of the name, so the selection covers the identifier itself. */
+  length?: number;
+}
+
+let pending: LineRevealRequest | null = null;
+const listeners = new Set<() => void>();
+
+function emit(): void {
+  for (const listener of [...listeners]) listener();
+}
+
+/** Publish a request; `null` clears it once an editor has served it. */
+export function setLineReveal(request: LineRevealRequest | null): void {
+  pending = request;
+  emit();
+}
+
+/** The pending request, for a consumer that has to re-check after its own load. */
+export function getLineReveal(): LineRevealRequest | null {
+  return pending;
+}
+
+export function subscribeLineReveal(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}

package/src/client/lib/outline-stores.test.ts

@@ -0,0 +1,94 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The two hand-off stores an outline row relies on.
+ *
+ * `editor-document` is what the Files panel describes, and `line-reveal` is what
+ * a row asks the editor to do. Both are process-wide singletons, so the tests
+ * that matter are the ones about LIFETIME and IDENTITY:
+ *
+ * - a replaced publisher must not blank the slot on unmount (a workspace switch
+ *   mounts the next editor before the previous one's cleanup runs);
+ * - a re-render with an unchanged document must not notify (otherwise every
+ *   hover re-scanned the buffer);
+ * - a served request must be cleared exactly once, or a remount re-fires a jump
+ *   the reader already took.
+ */
+
+import { afterEach, describe, expect, test } from 'bun:test';
+import {
+  clearEditorDocument,
+  getEditorDocument,
+  publishEditorDocument,
+  resetEditorDocument,
+  subscribeEditorDocument,
+  type EditorDocument,
+} from '@/client/lib/editor-document';
+import { getLineReveal, setLineReveal, subscribeLineReveal } from '@/client/lib/line-reveal';
+
+const DOC: EditorDocument = {
+  path: 'src/a.ts',
+  name: 'a.ts',
+  content: 'export const a = 1;',
+  language: 'typescript',
+  state: 'ready',
+  note: null,
+};
+
+afterEach(() => {
+  resetEditorDocument();
+  setLineReveal(null);
+});
+
+describe('editor document slot', () => {
+  test('publishing notifies subscribers once, and an unchanged document does not', () => {
+    let calls = 0;
+    const unsubscribe = subscribeEditorDocument(() => { calls += 1; });
+    const owner = {};
+
+    publishEditorDocument(owner, DOC);
+    expect(calls).toBe(1);
+    expect(getEditorDocument()).toEqual(DOC);
+
+    // Same content, fresh object — the shape of every re-render.
+    publishEditorDocument(owner, { ...DOC });
+    expect(calls).toBe(1);
+
+    publishEditorDocument(owner, { ...DOC, content: 'export const a = 2;' });
+    expect(calls).toBe(2);
+    unsubscribe();
+  });
+
+  test('a replaced publisher keeps the slot when the older one clears', () => {
+    const first = {};
+    const second = {};
+    publishEditorDocument(first, DOC);
+    publishEditorDocument(second, { ...DOC, path: 'src/b.ts', name: 'b.ts' });
+
+    // The first editor unmounts after the second mounted over it.
+    clearEditorDocument(first);
+    expect(getEditorDocument().path).toBe('src/b.ts');
+
+    clearEditorDocument(second);
+    expect(getEditorDocument().path).toBeNull();
+    expect(getEditorDocument().state).toBe('idle');
+  });
+});
+
+describe('line reveal store', () => {
+  test('a request is published, read and cleared once', () => {
+    const seen: Array<string | null> = [];
+    const unsubscribe = subscribeLineReveal(() => seen.push(getLineReveal()?.path ?? null));
+
+    setLineReveal({ path: 'src/a.ts', line: 42 });
+    expect(getLineReveal()).toEqual({ path: 'src/a.ts', line: 42 });
+
+    setLineReveal(null);
+    expect(getLineReveal()).toBeNull();
+    expect(seen).toEqual(['src/a.ts', null]);
+    unsubscribe();
+  });
+});

package/src/client/lib/plugins/bootstrap.test.ts

@@ -0,0 +1,258 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The plugin bootstrap's reconcile, driven through a real realtime server.
+ *
+ * Two bugs this suite pins, both silent in production:
+ *
+ * - **A disabled plugin's content script stayed mounted.** The reconcile keyed
+ *   its live set on the SLOT ROWS, which nothing clears when a plugin is
+ *   switched off — only a re-import does. Its `<link>` was removed (that hook
+ *   reads the registry) while its DOM, listeners and scoping attribute stayed
+ *   until a reload. Measured before the fix: `link=[]` and `generations=[…]`
+ *   in the same snapshot. The registry payload is the whole truth, so the live
+ *   set now comes from there.
+ * - **A plugin's DOM had no CSS surface.** A content script is handed a `root`
+ *   element carrying `data-plugin-surface`, which is what the served stylesheet
+ *   is scoped to. A script that mounted into `document.body` was unreachable by
+ *   its own CSS.
+ *
+ * The topic a plugin is subscribed to IS the assertion here: a bootstrap that
+ * read the rows instead of the registry would keep the generation alive after
+ * the payload moved.
+ *
+ * Rendered with `h()` (no JSX) against happy-dom.
+ */
+
+import { afterAll, afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import { h, render } from 'preact';
+import { act } from 'preact/test-utils';
+import type { PanelRegistryPayload } from '@/shared/types';
+import { PluginBootstrap } from '@/client/lib/plugins/bootstrap';
+import { SessionStateProvider } from '@/client/components/common/session-state-provider/index';
+import { registerListSlot, resetListSlots } from '@/client/lib/plugins/list-slots';
+import { resetContentScripts } from '@/client/lib/plugins/content-scripts';
+import { resetPluginSlots } from '@/client/lib/plugins/slots';
+import { resetPluginStylesheets } from '@/client/lib/plugins/stylesheets';
+import { resetLoadedBundles } from '@/client/lib/plugins/loader';
+import { pluginContext } from '@/client/lib/plugins/context';
+import { resetRealtimeClient } from '@/shared/lib/realtime/client';
+import { TOPIC_PANELS } from '@/shared/lib/realtime/protocol';
+import type { ContentScriptContext } from '@kabmo-labs/kabmo-sdk';
+import { startRealtimeTestServer, type RealtimeTestServer } from '@/test-support/realtime-server';
+import { installDomGlobals, pristineWebSocket, restoreDomGlobals } from '@/test-support/pristine-globals';
+import type { TopicResolver } from '@/server/lib/realtime/hub.server';
+
+const nativeFetch = Bun.fetch;
+
+let container: HTMLElement;
+let server: RealtimeTestServer;
+
+/** A payload naming the plugin, or an empty one when it is switched off. */
+function payload(enabled: boolean): PanelRegistryPayload {
+  return {
+    panels: enabled
+      ? [{ pluginId: 'demo', name: 'Demo', version: '1.0.0', appUrl: '/api/panels/bundle/demo.js', cssUrl: '/api/panels/css/demo.css' }]
+      : [],
+    marketplaces: [],
+    errors: [],
+    plugins: [{ pluginId: 'demo', name: 'Demo', version: '1.0.0', isPackage: true, built: true, enabled, bundled: false, gitOrigin: null }],
+    catalog: [],
+    disabledPanels: enabled ? [] : ['plugin:demo'],
+    gitStatus: {},
+    autoUpdate: false,
+    syncBlocked: {},
+  };
+}
+
+beforeEach(async () => {
+  const resolver: TopicResolver = async () => payload(true);
+  server = await startRealtimeTestServer(new Map<string, TopicResolver>([[TOPIC_PANELS, resolver]]));
+  installDomGlobals(new Window({ url: `http://127.0.0.1:${server.port}` }));
+  const target = globalThis as unknown as Record<string, unknown>;
+  target.WebSocket = pristineWebSocket;
+  target.fetch = async () => new Response('{}', { status: 200, headers: { 'content-type': 'application/json' } });
+
+  resetListSlots();
+  resetPluginSlots();
+  resetContentScripts();
+  resetPluginStylesheets();
+  resetLoadedBundles();
+  document.head.replaceChildren();
+});
+
+afterAll(() => {
+  (globalThis as unknown as Record<string, unknown>).fetch = nativeFetch;
+  restoreDomGlobals();
+});
+
+afterEach(() => {
+  if (container) {
+    render(null, container);
+    container.remove();
+  }
+  resetListSlots();
+  resetPluginSlots();
+  resetContentScripts();
+  resetPluginStylesheets();
+  resetLoadedBundles();
+  resetRealtimeClient();
+  server?.stop();
+});
+
+/**
+ * Let Preact's scheduled effects run until `done` holds.
+ *
+ * Preact schedules passive effects on a macrotask (`requestAnimationFrame`
+ * where available, a `setTimeout` otherwise — and happy-dom has no rAF), and a
+ * topic snapshot arrives over the socket, so the mount lands a tick or two
+ * after `waitForTopic` resolves. Awaiting a FIXED number of ticks is what made
+ * the first version of this suite assert against an empty registry: it read the
+ * effect's own scheduling rather than the condition under test.
+ *
+ * So this waits on the condition. `setTimeout(0)` is the same mechanism Preact
+ * uses, and the bound turns a never-satisfied condition into a fast failure
+ * rather than a hang.
+ */
+async function waitFor(done: () => boolean, attempts = 60): Promise<void> {
+  for (let i = 0; i < attempts; i += 1) {
+    if (done()) return;
+    await act(async () => {});
+    const tick = Promise.withResolvers<void>();
+    setTimeout(tick.resolve, 0);
+    await tick.promise;
+  }
+}
+
+/** Wait until the bootstrap has mounted exactly `count` content-script generations. */
+function waitForGenerations(count: number): Promise<void> {
+  return waitFor(() => generations().length === count);
+}
+
+/** Mount the bootstrap with a live content-script registration in the store. */
+async function mountWithContentScript(): Promise<void> {
+  registerListSlot('demo', 'contentScript', {
+    id: 'shell',
+    mount: (context: ContentScriptContext) => {
+      const node = context.root.ownerDocument.createElement('span');
+      node.id = 'demo-node';
+      context.root.appendChild(node);
+      return () => node.remove();
+    },
+  });
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  await act(async () => {
+    render(
+      h(SessionStateProvider, { sessionId: 's1', children: h(PluginBootstrap, { workspacePath: null }) }),
+      container,
+    );
+  });
+  await server.waitForTopic(TOPIC_PANELS, (value) => value !== null);
+  await waitForGenerations(1);
+}
+
+/** The plugin's mounted generations, read off the host's own registry. */
+function generations(): number[] {
+  return (globalThis.__kabmoContentScripts ?? []).map((entry) => entry.generation);
+}
+
+describe('PluginBootstrap', () => {
+  test('mounts a live plugin into a scoped root', async () => {
+    await mountWithContentScript();
+
+    expect(generations()).toHaveLength(1);
+    const surface = document.querySelector('[data-plugin-surface="demo"]');
+    expect(surface).not.toBeNull();
+    // The script's node is inside the surface, which is what its own CSS is
+    // scoped to.
+    expect(surface?.querySelector('#demo-node')).not.toBeNull();
+  });
+
+  test('disabling the plugin unmounts its content script without a reload', async () => {
+    await mountWithContentScript();
+    expect(generations()).toHaveLength(1);
+
+    // The user's own switch: the registry payload moves, nothing re-imports.
+    await act(async () => {
+      server.publish(TOPIC_PANELS, payload(false));
+    });
+    await waitForGenerations(0);
+
+    // Before the fix this stayed at 1: the rows were never cleared, so the
+    // reconcile saw the plugin as still live and never ran its disposer.
+    expect(generations()).toHaveLength(0);
+    expect(document.querySelector('[data-plugin-surface="demo"]')).toBeNull();
+    expect(document.getElementById('demo-node')).toBeNull();
+  });
+
+  test('re-enabling the plugin mounts it again', async () => {
+    await mountWithContentScript();
+    await act(async () => {
+      server.publish(TOPIC_PANELS, payload(false));
+    });
+    await waitForGenerations(0);
+    expect(generations()).toHaveLength(0);
+
+    await act(async () => {
+      server.publish(TOPIC_PANELS, payload(true));
+    });
+    await waitForGenerations(1);
+
+    expect(generations()).toHaveLength(1);
+    expect(document.querySelector('[data-plugin-surface="demo"]')).not.toBeNull();
+  });
+
+  /**
+   * The workspace the bootstrap was HANDED reaches the plugin context.
+   *
+   * This is what the phone layout was missing entirely: it mounted no
+   * `PluginBootstrap`, so `usePanelInfo()` answered the kit's module default
+   * (`workspacePath: null`) and every plugin panel drew "no workspace" over a
+   * real one — while the panel itself still rendered, because the panel catalog
+   * loads bundles on its own. The failure therefore looked like a plugin that
+   * half worked rather than a missing mount.
+   *
+   * `workspacePath` is asserted through the context the KIT reads, not through
+   * the bootstrap's own props, because the context is the only thing a plugin
+   * can see.
+   */
+  test('publishes the workspace it was given into the plugin context', async () => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    await act(async () => {
+      render(
+        h(SessionStateProvider, { sessionId: 's1', children: h(PluginBootstrap, { workspacePath: '/tmp/ws-demo' }) }),
+        container,
+      );
+    });
+
+    // Read through the module the kit's services are installed from — the same
+    // value `usePanelInfo()` returns to a plugin.
+    expect(pluginContext()).toEqual({ sessionId: 's1', workspacePath: '/tmp/ws-demo', theme: expect.any(String) });
+  });
+
+  test('a later workspace change reaches the context', async () => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    const renderWith = (workspacePath: string | null) =>
+      act(async () => {
+        render(
+          h(SessionStateProvider, { sessionId: 's1', children: h(PluginBootstrap, { workspacePath }) }),
+          container,
+        );
+      });
+
+    await renderWith('/tmp/ws-a');
+    expect(pluginContext().workspacePath).toBe('/tmp/ws-a');
+
+    // Re-rendered with a different root: the effect republishes, so a plugin
+    // that reads the hook sees the new workspace without a reload.
+    await renderWith('/tmp/ws-b');
+    expect(pluginContext().workspacePath).toBe('/tmp/ws-b');
+  });
+});

package/src/client/lib/plugins/bootstrap.tsx

@@ -0,0 +1,158 @@
+import { useEffect } from 'preact/hooks';
+import { useRef } from 'preact/hooks';
+import { usePanelRegistry } from '@/client/hooks/workspace/panel-registry';
+import { setPluginContext } from '@/client/lib/plugins/context';
+import { useSessionStateContext } from '@/client/hooks/workspace/session-state/context';
+import { useListSlotRows } from '@/client/hooks/workspace/list-slots';
+import type { ContentScriptRegistration } from '@kabmo-labs/kabmo-sdk';
+import {
+  mountContentScripts,
+  unmountAllContentScripts,
+  unmountContentScripts,
+} from '@/client/lib/plugins/content-scripts';
+import { reconcilePluginStylesheets } from '@/client/lib/plugins/stylesheets';
+
+/**
+ * Boot the plugin system, once, from the layout.
+ *
+ * Three things have to happen before a plugin can contribute anything:
+ *
+ * 1. The registry read, which names the bundles to import. The import runs each
+ *    plugin's `setup`, and that is what registers its components.
+ * 2. The context the components read, published from here because it comes from
+ *    the SESSION the layout owns — a plugin cannot resolve it, and a surface
+ *    that forgot to publish it would show "no workspace" over a real one.
+ * 3. The content scripts, mounted per plugin. They render nothing, so no slot
+ *    surface can own them; this is the earliest point that knows both the
+ *    registrations and a document to mount into.
+ *
+ * Mounted at the top of the workspace, so all three are in place before any
+ * panel that would draw a plugin.
+ */
+export function PluginBootstrap({ workspacePath }: { workspacePath: string | null }) {
+  const { sessionId } = useSessionStateContext();
+
+  // The read is what triggers the imports; nothing else has to call it, and
+  // calling it twice would be one request behind a shared cache.
+  usePanelRegistry();
+
+  useEffect(() => {
+    setPluginContext(sessionId ?? null, workspacePath);
+  }, [sessionId, workspacePath]);
+
+  useContentScripts();
+  usePluginStylesheets();
+
+  return null;
+}
+
+/**
+ * Load a plugin's declared stylesheet while it has a live content-script
+ * generation, and unload it when it does not.
+ *
+ * A plugin's imported CSS is otherwise inert (see `stylesheets.ts`), so this is
+ * what makes `css` in the manifest do anything. The gate is the content-script
+ * registration itself: a plugin that ships app-shell styling mounts app-shell
+ * code, and one that renders only into a slot uses the host's own utilities and
+ * needs no stylesheet of its own.
+ *
+ * Reconciled from the whole registry payload rather than per plugin, so a
+ * plugin that was disabled or removed loses its `<link>` in the same pass. The
+ * RULES are scoped now (the server wraps every stylesheet in
+ * `@scope ([data-plugin-surface="<id>"])`), but the link still has to go: a
+ * switched-off plugin must stop shipping bytes, and an unloaded one must not
+ * keep a stale stylesheet alive.
+ */
+function usePluginStylesheets(): void {
+  const { panels } = usePanelRegistry();
+  const rows = useListSlotRows<ContentScriptRegistration>('contentScript');
+  // A stable signature: the same live set must not churn the links on every
+  // render, and a rebuild's new URL is already handled by the loader.
+  const livePlugins = [...new Set(rows.map((row) => row.pluginId))].sort().join('|');
+  const signature = panels
+    .map((panel) => `${panel.pluginId}:${panel.cssUrl ?? ''}`)
+    .sort()
+    .join('|');
+
+  useEffect(() => {
+    const withContentScripts = new Set(livePlugins ? livePlugins.split('|') : []);
+    reconcilePluginStylesheets(
+      panels
+        .filter((panel) => withContentScripts.has(panel.pluginId))
+        .map((panel) => ({ pluginId: panel.pluginId, cssUrl: panel.cssUrl })),
+    );
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [signature, livePlugins]);
+}
+
+/**
+ * Mount each plugin's content scripts, and take down the ones that go away.
+ *
+ * Mounting is a REPLACEMENT per plugin (`mountContentScripts` disposes that
+ * plugin's previous generation first), so the effect only has to mount what is
+ * registered now and unmount what is no longer there — taking everything down
+ * on every change would tear down a script that is still registered and
+ * immediately mount it again, which is a visible flash and a lost listener
+ * registration for the script that did nothing wrong.
+ *
+ * **The live set is the REGISTRY's, not the slot store's.** The slot rows are
+ * what a bundle registered, and nothing clears them when a plugin is switched
+ * off — only a re-import does (`clearPluginListSlots`). Keying the effect on
+ * the rows alone therefore left a disabled plugin's content script mounted:
+ * its `<link>` was removed (that hook reads `panels`) while its DOM, listeners
+ * and scoping attribute stayed until a reload. The registry payload is the
+ * whole truth about which plugins are live, so it is what the reconcile reads.
+ *
+ * The dependency is a SIGNATURE rather than the row array: a re-read that
+ * produces the same rows is the same set of scripts, and re-running for it
+ * would churn every generation for nothing.
+ *
+ * Reported, never thrown: a script that cannot mount is a plugin bug, and it
+ * must not take Kabmo's boot with it.
+ */
+function useContentScripts(): void {
+  const { panels } = usePanelRegistry();
+  const rows = useListSlotRows<ContentScriptRegistration>('contentScript');
+  const enabled = panels.map((panel) => panel.pluginId).sort().join('|');
+  const signature = rows.map((row) => `${row.pluginId}:${row.registration.id}`).join('|');
+  /** The plugins mounted by the PREVIOUS run, so a vanished one is unmounted. */
+  const live = useRef<Set<string>>(new Set());
+
+  useEffect(() => {
+    const enabledSet = new Set(enabled ? enabled.split('|') : []);
+    // Read through the closure the effect was created in: the rows that belong
+    // to this signature, not whatever the next render holds.
+    const byPlugin = new Map<string, ContentScriptRegistration[]>();
+    for (const row of rows) {
+      if (!enabledSet.has(row.pluginId)) continue;
+      const list = byPlugin.get(row.pluginId) ?? [];
+      list.push(row.registration);
+      byPlugin.set(row.pluginId, list);
+    }
+
+    // A plugin whose registrations all left — or that the registry no longer
+    // reports as enabled — is the one that needs taking down.
+    for (const pluginId of live.current) {
+      if (!byPlugin.has(pluginId)) void unmountContentScripts(pluginId);
+    }
+    live.current = new Set(byPlugin.keys());
+
+    void (async () => {
+      for (const [pluginId, registrations] of byPlugin) {
+        const failures = await mountContentScripts(pluginId, registrations, { target: () => document.body });
+        for (const failure of failures) {
+          console.error(`[plugins] ${failure.pluginId}: content script failed — ${failure.reason}`);
+        }
+      }
+    })();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [signature, enabled]);
+
+  // Window teardown: nothing else runs a disposer on an unload, and a script
+  // holding listeners past it leaks them into whatever replaces the document.
+  useEffect(() => {
+    const onUnload = () => void unmountAllContentScripts();
+    window.addEventListener('pagehide', onUnload);
+    return () => window.removeEventListener('pagehide', onUnload);
+  }, []);
+}