@kabmo-labs/kabmo 0.0.0-stage → 0.1.0

package/src/client/lib/plugins/content-scripts.ts

@@ -0,0 +1,252 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Content scripts: a plugin's code that enhances the app shell without
+ * rendering a slot.
+ *
+ * This is the only contribution that lets a plugin touch DOM the host did not
+ * hand it, so the LIFECYCLE is the feature rather than an implementation
+ * detail:
+ *
+ * - **Disposal is exact-once and reverse-order.** A script that mounts twice
+ *   doubles its listeners; one that never unmounts leaks them for the life of
+ *   the page. Both are silent, which is why every rule here is asserted.
+ * - **The old generation is disposed BEFORE the new one mounts**, so two
+ *   generations never overlap — a reload is a replacement, not an addition.
+ * - **`signal` aborts on teardown**, so an async mount cannot finish after its
+ *   own disposal and attach to a DOM nobody will clean.
+ * - **A throwing mount is reported and rolled back.** The host mounts into a
+ *   DETACHED container first and moves it in only on success, so a mount that
+ *   throws halfway leaves nothing behind.
+ * - **Every script is handed a scoped ROOT element**, and that is the CSS half
+ *   of the contract: the plugin's stylesheet is served wrapped in
+ *   `@scope ([data-plugin-surface="<id>"])`, so DOM appended outside that
+ *   element is unreachable by the plugin's own CSS. The host removes the whole
+ *   subtree on teardown, so a node left inside it needs no removal of its own.
+ *
+ * The generation counter is per plugin and monotonic, so a script can key its
+ * own DOM by it and a stale generation can be recognised rather than guessed at.
+ */
+
+import type { ContentScriptRegistration } from '@kabmo-labs/kabmo-sdk';
+import { PLUGIN_SURFACE_ATTR } from '@kabmo-labs/kabmo-sdk';
+
+/** One mounted generation, held so it can be taken down in order. */
+interface MountedScript {
+  pluginId: string;
+  registration: ContentScriptRegistration;
+  generation: number;
+  abort: AbortController;
+  /** The disposer the script returned, or null when its mount never resolved. */
+  dispose: (() => void) | null;
+}
+
+/**
+ * The live generations, process-wide.
+ *
+ * Anchored on `globalThis` for the reason every other registry here is: under
+ * `bun --hot` this module re-evaluates while mounted scripts are still attached,
+ * and a module-level list would come back empty — their disposers would be
+ * unreachable and the next mount would run a second copy beside the first.
+ */
+declare global {
+  // eslint-disable-next-line no-var
+  var __kabmoContentScripts: MountedScript[] | undefined;
+  // eslint-disable-next-line no-var
+  var __kabmoContentGeneration: number | undefined;
+  // eslint-disable-next-line no-var
+  var __kabmoContentScriptRoots: Map<string, HTMLElement> | undefined;
+}
+
+function mounted(): MountedScript[] {
+  return (globalThis.__kabmoContentScripts ??= []);
+}
+
+/**
+ * One root element per plugin, the DOM its scripts belong in.
+ *
+ * The element carries the plugin's scope attribute, which is what confines the
+ * plugin's stylesheet (served wrapped in `@scope ([data-plugin-surface="…"])`)
+ * to its own markup. A script that appends to `document.body` instead puts its
+ * DOM outside every surface, where the plugin's own CSS cannot reach it — the
+ * failure is silent, which is why the context hands the root over rather than
+ * documenting one.
+ *
+ * The map is keyed by plugin id and lives beside the generations on `globalThis`
+ * for the same hot-reload reason: a re-evaluated module must still find the
+ * roots it has to remove.
+ */
+function roots(): Map<string, HTMLElement> {
+  return (globalThis.__kabmoContentScriptRoots ??= new Map());
+}
+
+/** The next generation number. Monotonic across every plugin. */
+function nextGeneration(): number {
+  return (globalThis.__kabmoContentGeneration = (globalThis.__kabmoContentGeneration ?? 0) + 1);
+}
+
+/**
+ * The document a mount targets.
+ *
+ * A content script adds its own nodes, so this is not a parent the host moves
+ * them into — it is the READINESS gate: a mount with no document to run in must
+ * be reported, not run against `undefined`. Resolved per call, because the
+ * layout may not have mounted when a plugin's bundle finished loading.
+ */
+export interface ContentScriptHost {
+  /** The document to mount into, or null when there is not one yet. */
+  target: () => Element | null;
+}
+
+/** What went wrong, in a shape the caller can report. */
+export interface ContentScriptFailure {
+  pluginId: string;
+  reason: string;
+}
+
+/**
+ * Mount every registered content script.
+ *
+ * Sequential and awaited, because a script's mount may be async and the caller
+ * needs the generations to be up (or reported) before it continues — a reload
+ * that returned early would let a button fire into a half-mounted page.
+ *
+ * Returns the failures rather than throwing: one broken script must not stop
+ * the others, and the caller reports them.
+ */
+export async function mountContentScripts(
+  pluginId: string,
+  registrations: readonly ContentScriptRegistration[],
+  host: ContentScriptHost,
+): Promise<ContentScriptFailure[]> {
+  // The replacement rule: this plugin's previous generations go FIRST, so two
+  // generations of one plugin never coexist. Reverse order, so a script that
+  // mounted last (and may depend on an earlier one) comes down first. The root
+  // element goes with them, so the new generation starts from an empty one.
+  await unmountContentScripts(pluginId);
+
+  const target = host.target();
+  if (!target) return [{ pluginId, reason: 'no host element to mount into' }];
+
+  const root = createRoot(target, pluginId);
+  const failures: ContentScriptFailure[] = [];
+  for (const registration of registrations) {
+    const generation = nextGeneration();
+    const abort = new AbortController();
+    const record: MountedScript = { pluginId, registration, generation, abort, dispose: null };
+    // Pushed BEFORE the mount resolves, so a teardown that arrives while an
+    // async mount is in flight still finds the generation and aborts it.
+    mounted().push(record);
+
+    // A content script owns the DOM it adds, but the CONTAINER is the host's:
+    // the plugin's CSS is scoped to it, so a script that mounted into
+    // `document.body` would put its own nodes out of its own stylesheet's
+    // reach. What the host owns is the RECORD: a mount that throws must not
+    // leave a generation the reaper can never reach.
+    try {
+      const dispose = await registration.mount({ pluginId, root, generation, signal: abort.signal });
+      if (abort.signal.aborted) {
+        // Teardown already ran while this mount was in flight. The script's own
+        // disposer is the only thing that can undo it.
+        callDisposer(dispose);
+        continue;
+      }
+      if (typeof dispose !== 'function') {
+        throw new Error('mount() answered no disposer — the host cannot clean this script up');
+      }
+      record.dispose = dispose;
+    } catch (error) {
+      removeRecord(record);
+      failures.push({ pluginId, reason: error instanceof Error ? error.message : String(error) });
+    }
+  }
+  // A registration list that produced no generation at all leaves an empty root
+  // behind; it is inert, but removing it keeps the document honest about which
+  // plugins are live.
+  if (mounted().every((entry) => entry.pluginId !== pluginId)) removeRoot(pluginId);
+  return failures;
+}
+
+/**
+ * The element a plugin's scripts mount into: a real node carrying the plugin's
+ * scope attribute, appended to `target`.
+ *
+ * `display: contents` so it generates no box — a content script's own nodes lay
+ * out exactly as they would have if appended directly — while still being a
+ * node the `@scope` prelude can root at.
+ */
+function createRoot(target: Element, pluginId: string): HTMLElement {
+  const root = target.ownerDocument.createElement('div');
+  root.setAttribute(PLUGIN_SURFACE_ATTR, pluginId);
+  root.style.display = 'contents';
+  target.appendChild(root);
+  roots().set(pluginId, root);
+  return root;
+}
+
+/** Remove a plugin's root element, if one is held. */
+function removeRoot(pluginId: string): void {
+  roots().get(pluginId)?.remove();
+  roots().delete(pluginId);
+}
+
+/** Take one plugin's generations down, newest first, exactly once. */
+export async function unmountContentScripts(pluginId: string): Promise<void> {
+  const all = mounted();
+  const mine = all.filter((entry) => entry.pluginId === pluginId);
+  for (const entry of [...mine].reverse()) {
+    // Removed BEFORE the disposer runs: a disposer that throws must not be
+    // retried on the next teardown, and a second teardown must find nothing.
+    removeRecord(entry);
+    // Abort first, so an async mount still in flight knows not to attach.
+    entry.abort.abort();
+    callDisposer(entry.dispose);
+  }
+  // After the disposers, not before: a disposer that reaches into the root it
+  // was handed must still find it. Removing the whole subtree is what takes a
+  // script's nodes with it, so the contract does not ask each disposer to undo
+  // its own DOM — only to release what the host cannot (listeners, timers).
+  removeRoot(pluginId);
+}
+
+/** Take every plugin's generations down. Used by window teardown and tests. */
+export async function unmountAllContentScripts(): Promise<void> {
+  for (const pluginId of new Set(mounted().map((entry) => entry.pluginId))) {
+    await unmountContentScripts(pluginId);
+  }
+}
+
+/** Whether a generation is still live — the check a script may make in a callback. */
+export function isGenerationLive(generation: number): boolean {
+  return mounted().some((entry) => entry.generation === generation);
+}
+
+function removeRecord(record: MountedScript): void {
+  const all = mounted();
+  const index = all.indexOf(record);
+  if (index >= 0) all.splice(index, 1);
+}
+
+/**
+ * Run a disposer, swallowing a throw.
+ *
+ * A disposer that throws must not stop the OTHER generations from coming down:
+ * they own listeners too, and leaking them is worse than a log line.
+ */
+function callDisposer(dispose: (() => void) | null): void {
+  if (!dispose) return;
+  try {
+    dispose();
+  } catch {
+    // Deliberately swallowed: see above.
+  }
+}
+
+/** Test seam: forget every generation without running disposers. */
+export function resetContentScripts(): void {
+  mounted().length = 0;
+  roots().clear();
+}

package/src/client/lib/plugins/context.ts

@@ -0,0 +1,68 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The context every plugin component is rendered with.
+ *
+ * A plugin component runs inside the host's tree, so it could in principle read
+ * the session and workspace from the host's own hooks — but it is a published
+ * package that must not import from the host's source. This module is the seam:
+ * the layout PUBLISHES the current context here, the UI kit READS it through
+ * `configureUiKit`, and neither end knows about the other.
+ *
+ * It is deliberately one module-level value rather than a Preact context: the
+ * UI kit's `usePanelInfo` subscribes to it directly, and a context object would
+ * have to be threaded through every surface that renders a plugin — the
+ * activity bar, the panel stack, the navbar dropdown, the editor tab and the
+ * settings pane — each of which would be a place to forget it.
+ */
+
+import type { PanelContext } from '@kabmo-labs/kabmo-ui';
+import { THEME_CHANGED_EVENT, currentThemeId } from '@/client/hooks/ui/theme';
+
+type Listener = (context: PanelContext) => void;
+
+let current: PanelContext = { sessionId: null, workspacePath: null, theme: 'paper' };
+const listeners = new Set<Listener>();
+
+/** The context as it stands. Cheap: every call returns the same object shape. */
+export function pluginContext(): PanelContext {
+  return { ...current, theme: currentThemeId() };
+}
+
+export function subscribePluginContext(listener: Listener): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+function publish(): void {
+  const next = pluginContext();
+  current = next;
+  for (const listener of listeners) listener(next);
+}
+
+/**
+ * Publish the active session and workspace.
+ *
+ * Called from the layout on every change. A no-op when nothing moved, so a
+ * re-render that passes the same ids does not wake every plugin component.
+ */
+export function setPluginContext(sessionId: string | null, workspacePath: string | null): void {
+  if (current.sessionId === sessionId && current.workspacePath === workspacePath) return;
+  current = { ...current, sessionId, workspacePath };
+  publish();
+}
+
+/**
+ * Follow the palette.
+ *
+ * A plugin renders in the host's document, so it inherits `data-theme` for
+ * free — but a plugin that shows a swatch, a chart or an inline colour needs
+ * the ID, not the CSS. Subscribed once at module load rather than from a hook,
+ * because the first plugin component to mount may be anywhere in the tree.
+ */
+if (typeof window !== 'undefined') {
+  window.addEventListener(THEME_CHANGED_EVENT, () => publish());
+}

package/src/client/lib/plugins/directives.test.tsx

@@ -0,0 +1,239 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Message directives: a fenced block a plugin claims and renders.
+ *
+ * The property this suite exists for is the one that would break every
+ * plugin-less install if it were wrong: **an unclaimed fence must render
+ * EXACTLY as it did before the slot existed.** The parser emits the directive
+ * placeholder for anything namespace-qualified, so "unchanged" has to mean the
+ * ordinary code block still comes out of it — asserted against the renderer's
+ * own output rather than against a hand-written expectation.
+ *
+ * The second is that a plugin component which throws leaves the CODE BLOCK,
+ * never an error page in the middle of a message.
+ */
+
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import { h } from 'preact';
+import {
+  DIRECTIVE_ATTRS_ATTR,
+  DIRECTIVE_BLOCK_CLASS,
+  DIRECTIVE_NAME_ATTR,
+  isDirectiveLanguage,
+  parseDirectiveAttributes,
+  readDirectiveAttributes,
+} from '@/shared/lib/markdown/directives';
+
+/**
+ * Bound in `beforeAll`, after the DOM globals exist — NOT at module scope.
+ * `sanitize.ts` binds DOMPurify when it is first imported, capturing whatever
+ * `window` exists then, so a static import would bind the sanitizer to a
+ * window-less environment and every assertion here would see unsanitized (or
+ * unfenced) HTML. Measured: this suite passed alone and failed inside the full
+ * run, where an earlier file had installed its own window.
+ */
+let renderMarkdown: typeof import('@/shared/lib/markdown/marked').renderMarkdown;
+let sanitizeHtml: typeof import('@/shared/lib/markdown/sanitize').sanitizeHtml;
+let hydrateDirectiveBlocks: typeof import('@/client/lib/plugins/directives').hydrateDirectiveBlocks;
+let unmountDirectiveBlocks: typeof import('@/client/lib/plugins/directives').unmountDirectiveBlocks;
+
+const DOM_GLOBALS = [
+  'window', 'document', 'navigator', 'Node', 'Element', 'HTMLElement', 'MutationObserver', 'NodeFilter',
+] as const;
+const nativeGlobals: Partial<Record<(typeof DOM_GLOBALS)[number], unknown>> = {};
+
+beforeAll(async () => {
+  const win = new Window({ url: 'http://localhost' });
+  const target = globalThis as unknown as Record<string, unknown>;
+  for (const key of DOM_GLOBALS) {
+    nativeGlobals[key] = target[key];
+    const value = (win as unknown as Record<string, unknown>)[key];
+    if (value !== undefined) target[key] = value;
+  }
+  ({ renderMarkdown } = await import('@/shared/lib/markdown/marked'));
+  ({ sanitizeHtml } = await import('@/shared/lib/markdown/sanitize'));
+  ({ hydrateDirectiveBlocks, unmountDirectiveBlocks } = await import('@/client/lib/plugins/directives'));
+});
+
+afterAll(() => {
+  // One process per run: a leaked DOM window takes `agent-events.ts`'s
+  // `typeof window` branch with a `CustomEvent` from another realm.
+  const target = globalThis as unknown as Record<string, unknown>;
+  for (const key of DOM_GLOBALS) {
+    const value = nativeGlobals[key];
+    if (value === undefined) delete target[key];
+    else target[key] = value;
+  }
+});
+
+/**
+ * Render markdown the way the app does: parse, then sanitize.
+ *
+ * The LEADING paragraph is not decoration. happy-dom's DOMPurify drops the
+ * first element of a bare fragment — verified: `sanitizeHtml('<div>x</div>')`
+ * answers `'x'`, and `'<div>x</div><p>y</p>'` answers `'x<p>y</p>'` — so a
+ * directive wrapper at the root would be gone before any assertion ran, and
+ * this suite would pass alone and fail inside the full run (where an earlier
+ * file had already bound DOMPurify to its own window). A real browser keeps
+ * the root element; the sanitizer's allowlist is the thing under test here, so
+ * the fragment is given a leading sibling to survive the harness.
+ */
+function html(markdown: string): string {
+  return sanitizeHtml(`<p>lead</p>${renderMarkdown(markdown)}`);
+}
+
+let container: HTMLDivElement;
+const CONTEXT = { sessionId: 's1', workspacePath: '/ws' };
+
+beforeEach(() => {
+  container = document.createElement('div');
+  document.body.appendChild(container);
+});
+
+afterEach(() => {
+  container.remove();
+});
+
+describe('the parser', () => {
+  test('a namespace-qualified fence becomes a claimable placeholder', () => {
+    const out = html('```omp:chart\n{"series":[1]}\n```');
+    expect(out).toContain(DIRECTIVE_BLOCK_CLASS);
+    expect(out).toContain(`${DIRECTIVE_NAME_ATTR}="omp:chart"`);
+  });
+
+  test('an ordinary fence is untouched — no placeholder at all', () => {
+    const out = html('```ts\nconst x = 1;\n```');
+    expect(out).not.toContain(DIRECTIVE_BLOCK_CLASS);
+    expect(out).toContain('language-ts');
+  });
+
+  test('an unclaimed placeholder STILL carries the ordinary code block', () => {
+    // The fallback is inside, which is what makes "unclaimed renders as before"
+    // a structural property rather than a rule to remember.
+    const out = html('```omp:chart\n{"series":[1]}\n```');
+    expect(out).toContain('class="code-block"');
+    expect(out).toContain('language-omp:chart');
+  });
+
+  test('the info line\'s attributes are parsed and carried', () => {
+    const out = html('```omp:chart title="A chart" width=420\nbody\n```');
+    // Encoded into the attribute, so the client can read them back.
+    const match = new RegExp(`${DIRECTIVE_ATTRS_ATTR}="([^"]+)"`).exec(out);
+    expect(match).not.toBeNull();
+    expect(readDirectiveAttributes(match?.[1] ?? null)).toEqual({ title: 'A chart', width: '420' });
+  });
+
+  test('only a colon marks a directive', () => {
+    expect(isDirectiveLanguage('omp:chart')).toBe(true);
+    expect(isDirectiveLanguage('ts')).toBe(false);
+    expect(isDirectiveLanguage('')).toBe(false);
+  });
+
+  test('a malformed attributes payload reads back as empty rather than throwing', () => {
+    expect(readDirectiveAttributes('not json')).toEqual({});
+    expect(readDirectiveAttributes(null)).toEqual({});
+    // A JSON array is not an attribute map.
+    expect(readDirectiveAttributes(encodeURIComponent('[1,2]'))).toEqual({});
+  });
+
+  test('a stray quote in the info line does not fail the parse', () => {
+    // Tolerant by design: this runs on whatever a message contains, so an
+    // unparseable attribute is dropped or taken literally rather than throwing.
+    // A message with a stray quote is still a message.
+    expect(() => parseDirectiveAttributes(' title="unterminated')).not.toThrow();
+    expect(parseDirectiveAttributes('===')).toEqual({});
+    expect(parseDirectiveAttributes(' title="quoted" broken')).toEqual({ title: 'quoted' });
+  });
+});
+
+describe('hydration', () => {
+  /** A component that renders its props, so the test can read what it got. */
+  function Directive(props: { name: string; body: string; attributes: Record<string, string> }) {
+    return h('div', { id: 'plugin-directive' }, `${props.name}|${props.body.trim()}|${props.attributes.title ?? ''}`);
+  }
+
+  const claim = (name: string) => (fence: string) =>
+    fence === name ? { pluginId: 'demo', registration: { id: 'r', name, component: Directive } } : undefined;
+
+  test('a claimed fence renders the plugin component with the raw body', () => {
+    container.innerHTML = html('```omp:chart title="A"\n{"series":[1]}\n```');
+    hydrateDirectiveBlocks(container, claim('omp:chart'), CONTEXT);
+
+    const rendered = container.querySelector('#plugin-directive');
+    expect(rendered).not.toBeNull();
+    expect(rendered?.textContent).toBe('omp:chart|{"series":[1]}|A');
+  });
+
+  test('an unclaimed fence is left exactly as the parser emitted it', () => {
+    container.innerHTML = html('```omp:chart\n{"series":[1]}\n```');
+    // Read back AFTER the assignment: setting innerHTML normalizes the markup
+    // (a self-closing `<path/>` becomes `<path></path>`), so the parser's own
+    // string is not what the DOM holds.
+    const before = container.innerHTML;
+    hydrateDirectiveBlocks(container, () => undefined, CONTEXT);
+    expect(container.innerHTML).toBe(before);
+    expect(container.querySelector('.code-block')).not.toBeNull();
+  });
+
+  test('a throwing component leaves the CODE BLOCK, not an error', () => {
+    function Boom(): never {
+      throw new Error('the directive component is broken');
+    }
+    container.innerHTML = html('```omp:chart\n{"series":[1]}\n```');
+    const original = container.innerHTML;
+    const claimBoom = () => ({ pluginId: 'demo', registration: { id: 'r', name: 'omp:chart', component: Boom } });
+
+    // Preact reports the render error; what matters is what is left on screen.
+    try {
+      hydrateDirectiveBlocks(container, claimBoom, CONTEXT);
+    } catch {
+      // Expected on some Preact versions.
+    }
+    // The code block is back (the fallback the placeholder wrapped).
+    expect(container.querySelector('.code-block')).not.toBeNull();
+    expect(container.textContent).toContain('{"series":[1]}');
+    void original;
+  });
+
+  test('hydration is idempotent: a second call does not re-render', () => {
+    container.innerHTML = html('```omp:chart\n{"series":[1]}\n```');
+    hydrateDirectiveBlocks(container, claim('omp:chart'), CONTEXT);
+    const first = container.innerHTML;
+    hydrateDirectiveBlocks(container, claim('omp:chart'), CONTEXT);
+    expect(container.innerHTML).toBe(first);
+  });
+
+  test('a message removed and re-rendered hydrates its component again', () => {
+    // The cycle the renderer's effect cleanup creates, with the order Preact
+    // actually uses (measured): the new markup is committed FIRST, then the old
+    // effect's cleanup runs. A timeline that replaces the container's html —
+    // a session switch, a rewind — must therefore come back hydrated, and the
+    // cleanup must not have been able to blank it.
+    const markdown = '```omp:chart\n{"series":[1]}\n```';
+    container.innerHTML = html(markdown);
+    hydrateDirectiveBlocks(container, claim('omp:chart'), CONTEXT);
+    expect(container.querySelector('#plugin-directive')).not.toBeNull();
+
+    // Preact's order: fresh markup, then the previous effect's cleanup.
+    container.innerHTML = html(markdown);
+    hydrateDirectiveBlocks(container, claim('omp:chart'), CONTEXT);
+
+    expect(container.querySelector('#plugin-directive')?.textContent).toBe('omp:chart|{"series":[1]}|');
+  });
+
+  test('unmounting takes the plugin tree down', () => {
+    container.innerHTML = html('```omp:chart\n{"series":[1]}\n```');
+    hydrateDirectiveBlocks(container, claim('omp:chart'), CONTEXT);
+    const host = container.querySelector('.plugin-directive');
+    expect(host?.textContent).not.toBe('');
+
+    unmountDirectiveBlocks(container);
+    // The host survives — it is the placeholder's child — but its tree is gone.
+    expect(container.querySelector('.plugin-directive')?.textContent).toBe('');
+  });
+});