@desplega.ai/agent-swarm 1.79.0 → 1.79.2

package/plugin/skills/kv-storage/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: kv-storage
+description: Use the swarm KV store (Redis-like, namespaced) for cross-task / cross-session / per-page state. Auto-scoped to your context (Slack thread / PR / Linear issue / agent / page). Use for counters, cursors, page state. Do NOT use for secrets (`swarm_config`), embedded knowledge (`memory`), or files (`agent-fs`).
+---
+
+# KV Storage
+
+Namespaced key/value store inside the swarm SQLite DB. Auto-scoped to your
+calling context — same string used by `agent_tasks.contextKey`.
+
+> **Capability gate**: the `kv-*` MCP tools are only available when your
+> `CAPABILITIES` includes `kv` (default-on; check `my-agent-info`). The REST
+> endpoints under `/api/kv/*` are always present on the API server.
+
+## When to use KV
+
+| You need… | Use this | Not this |
+|---|---|---|
+| Count something in this Slack thread / PR / Linear issue | **KV** (auto-scoped) | memory / agent-fs |
+| Save a cursor / last-seen state for a recurring schedule | **KV** | swarm_config |
+| Page-internal counter / vote / state across reloads | **KV** via `swarmSdk.kv` | memory |
+| Cross-task state in the same conversation | **KV** (auto-scoped to `task:slack:...`) | parentTaskId only |
+| Secrets, API tokens, OAuth creds | `swarm_config` (encrypted + masked) | **NOT KV** |
+| Cross-session knowledge for this agent ("how do I…") | `memory_search` / `memory-get` | **NOT KV** |
+| Files, binaries, long documents | `agent-fs` | **NOT KV** |
+| Workflow run state | workflow vars (own KV) | **NOT KV** |
+
+Rule of thumb:
+- If a future invocation should *find this without knowing the key* → memory.
+- If a future invocation will *know exactly which key to read* → KV.
+- If it has secrets in it → `swarm_config`.
+- If it's bytes (image, pdf, large doc) → agent-fs.
+
+## Namespacing
+
+Namespace is just a string. It mirrors the `contextKey` schema
+(`src/tasks/context-key.ts`). When you don't pass one, the server resolves it
+from request headers in this order:
+
+1. `X-Page-Id` (only the page-proxy sets this) → `task:page:<id>`
+2. `X-Source-Task-Id` → that task's `contextKey` (e.g. `task:slack:C123:1776...`)
+3. `X-Agent-ID` → `task:agent:<id>` (per-agent scratchpad)
+
+So **inside a session triggered by a Slack thread, KV is automatically scoped
+to that thread** — your sibling tasks (re-runs, retries, follow-ups in the same
+thread) read the same store with no setup. Same for PRs (`task:trackers:github:owner:repo:pr:N`),
+Linear issues (`task:trackers:linear:DES-42`), schedules, workflows.
+
+You can override the namespace explicitly when you need to — see "Explicit
+override" below.
+
+## Quick recipes
+
+### MCP — inside any agent session
+
+```
+kv-set    key="vote-count" value=0 valueType="integer"     # → namespace = task:slack:...
+kv-incr   key="vote-count"                                  # → 1
+kv-incr   key="vote-count" by=5                             # → 6
+kv-get    key="vote-count"                                  # → entry with value=6
+kv-list   prefix="vote-"                                    # → all matching entries
+kv-delete key="vote-count"                                  # → done
+```
+
+`kv-set` defaults to `valueType: 'json'` and JSON-encodes whatever you pass.
+Use `'string'` to skip encoding (good for short tokens, URLs) and
+`'integer'` for counters (required by `kv-incr`).
+
+### REST — humans, scripts, external clients
+
+```bash
+# Header-resolved namespace (recommended for in-session calls)
+curl -H "Authorization: Bearer $API_KEY" \
+     -H "X-Agent-ID: $AGENT_ID" \
+     "$MCP_BASE_URL/api/kv/last-cursor"
+
+# Explicit namespace
+curl -H "Authorization: Bearer $API_KEY" \
+     "$MCP_BASE_URL/api/kv/_/task:trackers:linear:DES-42/last-comment-id"
+
+# PUT a JSON value with a 10-minute TTL
+curl -X PUT -H "Authorization: Bearer $API_KEY" -H "X-Agent-ID: $AGENT_ID" \
+     -H "Content-Type: application/json" \
+     -d '{"value":{"n":42},"valueType":"json","expiresInSec":600}' \
+     "$MCP_BASE_URL/api/kv/snapshot"
+
+# List with a prefix
+curl -H "Authorization: Bearer $API_KEY" -H "X-Agent-ID: $AGENT_ID" \
+     "$MCP_BASE_URL/api/kv?prefix=daily-&limit=50"
+```
+
+### Pages browser SDK — inside an authed page
+
+Page proxy forces the namespace to `task:page:<id>` — no namespace argument is
+exposed. Use it for page-local counters, vote tallies, multi-step form state,
+"remember this number from last refresh" UX:
+
+```js
+// Inside a page's <script> tag
+const count = await swarmSdk.kv.incr('clicks');           // → number-valued entry
+await swarmSdk.kv.set('lastSeen', Date.now());            // → 'json' by default
+const entry = await swarmSdk.kv.get('clicks');            // → { value, valueType, ... } or null
+await swarmSdk.kv.del('clicks');
+const all = await swarmSdk.kv.list({ prefix: 'click', limit: 50 });
+```
+
+Public pages (`authMode: 'public'`) cannot reach `/@swarm/api/*` and so cannot
+use KV. Promote to `authed` or `password` mode if the page needs state.
+
+## Explicit override
+
+Pass `namespace` to read/write somewhere other than your auto-context:
+
+```
+kv-get key="seed" namespace="swarm:experiments"            # ad-hoc namespace
+kv-set key="note" value="hi" namespace="task:agent:OTHER-AGENT-ID"
+# → 403 unless caller is lead
+```
+
+Rules:
+- **Reads:** any authenticated caller can read any namespace.
+- **Writes to `task:agent:<X>`** where X ≠ caller agentId: **403** unless lead.
+- **Writes to `task:page:<X>`** from anywhere except a page-proxy request: **403**.
+- Everything else: writable by any authenticated caller.
+
+## TTL & expiry
+
+Default = **no expiry**. Opt in by passing `expiresInSec`:
+
+```
+kv-set key="lock-token" value="xyz" valueType="string" expiresInSec=60
+```
+
+Expiry is *lazy*: reads on an expired key return null and delete the row;
+`kv-list` filters expired rows out of the SELECT but doesn't delete them
+(keeps cursor pagination stable). No background sweeper — expired rows that
+never get touched stay on disk harmlessly.
+
+## Body cap
+
+2 MiB per value. Over the cap returns 413. If you want to store something
+larger, write it to `agent-fs` and stash the path in KV.
+
+## Gotchas
+
+- **Namespaces ARE contextKey strings.** The same string that lets the swarm
+  find sibling tasks for a PR also indexes KV for that PR.
+- **Reads return `null` for missing AND expired keys** — you can't tell the
+  difference from one call. (If you need to know, list the key.)
+- **INCR collides** if the existing row has `valueType` `'json'` or `'string'`
+  (409 / `KvTypeCollisionError`). Delete and re-create as `'integer'` first,
+  or use a different key.
+- **JSON values round-trip** through `JSON.parse` on read. If you wrote
+  `{a:1}`, you'll get back the object — not the raw string. Use
+  `valueType: 'string'` if you want byte-exact storage.
+- **No CAS / SETNX yet.** Use `kv-incr` for atomic counters; for
+  "claim a token" patterns, set with a short TTL and re-check.
+- **Page SDK has no `namespace` argument.** Pages are always scoped to
+  `task:page:<id>`. Don't try to encode another namespace in the key path —
+  the URL gets rewritten anyway.
+
+## See also
+
+- `src/be/migrations/061_kv_store.sql` — schema (`kv_entries`)
+- `src/http/kv.ts` — REST handler + namespace resolution
+- `src/tools/kv/*` — MCP tool registrars
+- `src/artifact-sdk/browser-sdk.ts` — `swarmSdk.kv` for pages
+- `plugin/skills/pages/SKILL.md` — companion skill for authed pages

package/plugin/skills/pages/SKILL.md

@@ -210,6 +210,155 @@ For the full list of fields each endpoint accepts/returns, see
 [**docs.agent-swarm.dev/docs/api-reference**](https://docs.agent-swarm.dev/docs/api-reference).
 The SDK is a thin domain wrapper — anything documented there is reachable.
 
+## Built-in primitives
+
+Every HTML page automatically gets a small set of zero-dep web components
+auto-injected alongside the Browser SDK. Drop them into your page body —
+no `<script>` import, no bundling, no Tailwind required (though Tailwind
+Play CDN is loaded, so utility classes work too).
+
+### `<swarm-diff>` — unified diff renderer
+
+Render a unified diff with a two-column gutter, severity annotations, and a
+deterministic anchor id per hunk (so deep-linking + jump lists work). The
+element reads its payload from its `textContent` as JSON of shape
+`{ hunks: [{ old_start, old_lines, new_start, new_lines, lines, annotations? }] }`.
+
+```html
+<swarm-diff
+  file="src/foo.ts"
+  base-sha="abc123"
+  head-sha="def456">
+{ "hunks": [
+    { "old_start": 10, "old_lines": 3, "new_start": 10, "new_lines": 4,
+      "lines": [
+        { "type": "context", "text": "  const x = 1;" },
+        { "type": "del",     "text": "- console.log(x);" },
+        { "type": "add",     "text": "+ logger.info({ x });" },
+        { "type": "add",     "text": "+ return x;" }
+      ],
+      "annotations": [
+        { "line": 12, "severity": "warn", "text": "Avoid raw console.log" }
+      ]
+    }
+] }
+</swarm-diff>
+```
+
+**Inputs**
+
+| Attribute | Required | Notes |
+|---|---|---|
+| `file` | yes | Path label rendered in the hunk header. Used for the anchor id slug. |
+| `base-sha` | no | Pre-change SHA. Rendered in the header next to `head-sha`. |
+| `head-sha` | no | Post-change SHA. |
+
+**Line shape**
+
+| Field | Values | Notes |
+|---|---|---|
+| `type` | `context` \| `add` \| `del` | Drives row tint (green / red / neutral) and gutter line numbering. |
+| `text` | string | Rendered verbatim (HTML-escaped). |
+
+**Annotation shape** — attaches to a NEW-side line by line number; rendered
+as a margin badge on that row.
+
+| Field | Values | Notes |
+|---|---|---|
+| `line` | integer | New-side line number (falls back to old-side if no add for that line). |
+| `severity` | `error` \| `warn` \| `info` | Drives badge color. |
+| `text` | string | Badge body. |
+
+**Anchor id**
+
+Each hunk gets `id="swarm-diff-<file-slug>-<old_start>"` for deep-linking.
+Use `<swarm-diff-jumps></swarm-diff-jumps>` anywhere in the page body to
+render a tiny "Jump to" navigation of every diff hunk on the page —
+handy when an agent ships a multi-file annotated PR.
+
+**Programmatic form**
+
+If you need to render a diff from a fetch response (rather than inline JSON),
+use `window.swarmUi.renderDiff(rootEl, diffData)`:
+
+```html
+<div id="diff-target"></div>
+<script>
+  const data = await fetch('/some/diff.json').then(r => r.json());
+  window.swarmUi.renderDiff(document.getElementById('diff-target'), data);
+</script>
+```
+
+**Annotated-PR example**
+
+```html
+<!doctype html>
+<html><head><title>PR #1234 — `console.log` cleanup</title></head>
+<body>
+  <h1>PR #1234 — cleanup raw <code>console.log</code> calls</h1>
+  <p>Replaces ad-hoc logging with the project logger.</p>
+
+  <swarm-diff-jumps></swarm-diff-jumps>
+
+  <swarm-diff file="src/foo.ts" base-sha="abc123" head-sha="def456">
+    { "hunks": [
+        { "old_start": 10, "old_lines": 3, "new_start": 10, "new_lines": 4,
+          "lines": [
+            { "type": "context", "text": "  const x = 1;" },
+            { "type": "del",     "text": "- console.log(x);" },
+            { "type": "add",     "text": "+ logger.info({ x });" },
+            { "type": "add",     "text": "+ return x;" }
+          ],
+          "annotations": [
+            { "line": 12, "severity": "warn", "text": "Avoid raw console.log" }
+          ]
+        }
+    ] }
+  </swarm-diff>
+
+  <swarm-diff file="src/bar.ts" base-sha="abc123" head-sha="def456">
+    { "hunks": [
+        { "old_start": 5, "old_lines": 1, "new_start": 5, "new_lines": 1,
+          "lines": [
+            { "type": "del", "text": "- console.error('boom');" },
+            { "type": "add", "text": "+ logger.error('boom');" }
+          ]
+        }
+    ] }
+  </swarm-diff>
+</body></html>
+```
+
+## Print / PDF export
+
+Every HTML page also gets a `@media print` rule baked into the head defaults:
+- Light theme on print (white background, black text, underlined black links).
+- Anything with the `.no-print` class is hidden (annotation badges and the
+  jump list already carry this class — use it on agent-emitted chrome you
+  want suppressed in PDF exports).
+- `.swarm-card` and `<swarm-diff>` get `break-inside: avoid` so they don't
+  split mid-element across pages.
+
+Trigger the export from the SPA's "Export PDF" button on `/pages/:id` — it
+opens the iframe's native print dialog (HTML pages) or the SPA's print
+dialog (JSON pages). The browser's "Print → Save as PDF" handles the actual
+file. No headless Chromium, no server-side rendering — zero infra weight.
+
+> Want a custom print layout? Override the print styles in your page's own
+> `<style>` block — agent CSS always wins over the head defaults.
+
+## View counter
+
+Every successful `200` from `GET /p/:id` (HTML inline) and `GET /p/:id.json`
+(JSON metadata) bumps a `view_count` field on the page. `302` (JSON pages
+redirecting to the SPA), `401`/`403` (auth gate), and `404` do NOT bump.
+The count is exposed on `GET /api/pages` listing (`viewCount` field) and the
+SPA `/pages` index renders it as a small eye-count badge per row.
+
+No per-viewer dedup — this is a coarse popularity signal, not analytics.
+Bumps are best-effort (wrapped in try/catch so a counter write never fails
+the response).
+
 ## JSON Renderer
 
 JSON pages are rendered via [`@json-render/react`](https://json-render.dev)

package/src/artifact-sdk/browser-sdk.ts

@@ -14,6 +14,9 @@
 //   - repos            list, get, create, update, delete
 //   - schedules        list, get, create, update, delete, run
 //   - approvalRequests list, get, create, respond
+//   - kv               get, set, del, incr, list  (namespace is forced server-
+//                      side to the page's own `task:page:<id>` — no namespace
+//                      argument is exposed)
 //
 // Full HTTP API reference: https://docs.agent-swarm.dev/docs/api-reference
 export const BROWSER_SDK_JS = `
@@ -103,6 +106,22 @@ class SwarmSDK {
       create: (body) => call('POST', '/approval-requests', body),
       respond: (id, body) => call('POST', '/approval-requests/' + enc(id) + '/respond', body),
     };
+
+    // KV store. The namespace is FORCED by the page-proxy to \`task:page:<id>\`
+    // (it injects X-Page-Id which the kv handler treats as highest priority).
+    // No namespace argument is exposed — pages cannot read/write any other
+    // namespace via this SDK.
+    this.kv = {
+      get: (key) => call('GET', '/kv/' + enc(key)),
+      set: (key, value, opts) => call('PUT', '/kv/' + enc(key), {
+        value,
+        valueType: opts && opts.valueType,
+        expiresInSec: opts && opts.expiresInSec,
+      }),
+      del: (key) => call('DELETE', '/kv/' + enc(key)),
+      incr: (key, by) => call('POST', '/kv/' + enc(key) + '/incr', { by: by == null ? 1 : by }),
+      list: (opts) => call('GET', '/kv' + qs(opts)),
+    };
   }
 }
 
@@ -112,3 +131,276 @@ class SwarmSDK {
 window.SwarmSDK = SwarmSDK;
 window.swarmSdk = new SwarmSDK();
 `;
+
+// ─── UI primitives ──────────────────────────────────────────────────────────
+//
+// Auto-injected alongside the SDK. Exposes a tiny set of declarative web
+// components agents can drop into HTML pages without bundling anything. v1:
+// only \`<swarm-diff>\` (unified-diff renderer) + \`<swarm-diff-jumps>\` (a
+// sibling-anchor jump list). All zero-dep, pure DOM — Tailwind utility
+// classes are used freely since the Play CDN is already loaded by
+// PAGE_HEAD_DEFAULTS, but every visual aspect has inline-style fallbacks so
+// the component is still legible if Tailwind fails to load.
+
+/**
+ * Renders a unified diff as a two-column-gutter HTML table inside a
+ * `<swarm-diff>` custom element. Reads `file`, `base-sha`, `head-sha`
+ * attributes and parses the element's text content as JSON of shape
+ * `{ hunks: [{ old_start, old_lines, new_start, new_lines, lines:
+ * [{ type: 'context' | 'add' | 'del', text }], annotations?: [{ line,
+ * severity, text }] }] }`. Severity ∈ `error|warn|info`. Each hunk gets a
+ * deterministic anchor id so deep-linking + the sibling `<swarm-diff-jumps>`
+ * component works.
+ *
+ * Pure JS, no deps. Tailwind utility classes are sprinkled in but every
+ * critical visual property has an inline-style fallback.
+ */
+export const SWARM_UI_JS = `
+(function() {
+  if (typeof window === 'undefined' || !window.customElements) return;
+  if (window.customElements.get('swarm-diff')) return;
+
+  var SEV_COLOR = {
+    error: '#ef4444',
+    warn:  '#f59e0b',
+    info:  '#3b82f6',
+  };
+
+  function esc(s) {
+    return String(s == null ? '' : s)
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&#39;');
+  }
+
+  function slugifyAttr(s) {
+    return String(s || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  }
+
+  function parseHunks(jsonText) {
+    var trimmed = (jsonText || '').trim();
+    if (!trimmed) return [];
+    try {
+      var parsed = JSON.parse(trimmed);
+      if (parsed && Array.isArray(parsed.hunks)) return parsed.hunks;
+      if (Array.isArray(parsed)) return parsed;
+      return [];
+    } catch (e) {
+      console.warn('[swarm-diff] failed to parse JSON body:', e);
+      return [];
+    }
+  }
+
+  function renderAnnotation(ann) {
+    var color = SEV_COLOR[ann && ann.severity] || SEV_COLOR.info;
+    return (
+      '<span class="swarm-diff-annot no-print" '
+      + 'style="display:inline-block;margin-left:8px;padding:1px 6px;'
+      + 'border-radius:4px;font-size:11px;font-weight:600;'
+      + 'background:' + color + '22;color:' + color + ';border:1px solid ' + color + '55;">'
+      + esc((ann && ann.severity ? ann.severity.toUpperCase() : 'INFO')) + ' · ' + esc(ann && ann.text || '')
+      + '</span>'
+    );
+  }
+
+  function renderHunk(hunk, hunkIdx, file) {
+    var oldLines = hunk.old_lines || 0;
+    var newLines = hunk.new_lines || 0;
+    var oldStart = hunk.old_start || 0;
+    var newStart = hunk.new_start || 0;
+    var lines = Array.isArray(hunk.lines) ? hunk.lines : [];
+    var annotations = Array.isArray(hunk.annotations) ? hunk.annotations : [];
+    // Index annotations by new-side line number for fast lookup per row.
+    var annByLine = {};
+    for (var i = 0; i < annotations.length; i++) {
+      var a = annotations[i];
+      if (a && typeof a.line === 'number') {
+        if (!annByLine[a.line]) annByLine[a.line] = [];
+        annByLine[a.line].push(a);
+      }
+    }
+
+    var rowsHtml = '';
+    var oldN = oldStart;
+    var newN = newStart;
+    for (var j = 0; j < lines.length; j++) {
+      var line = lines[j] || {};
+      var type = line.type || 'context';
+      var text = line.text == null ? '' : line.text;
+      var bg, oldCell, newCell, sign;
+      if (type === 'add') {
+        bg = 'rgba(34,197,94,0.10)';
+        oldCell = '';
+        newCell = String(newN++);
+        sign = '+';
+      } else if (type === 'del') {
+        bg = 'rgba(239,68,68,0.10)';
+        oldCell = String(oldN++);
+        newCell = '';
+        sign = '-';
+      } else {
+        bg = 'transparent';
+        oldCell = String(oldN++);
+        newCell = String(newN++);
+        sign = ' ';
+      }
+
+      var annHtml = '';
+      var anns = annByLine[Number(newCell)] || annByLine[Number(oldCell)] || [];
+      for (var k = 0; k < anns.length; k++) annHtml += renderAnnotation(anns[k]);
+
+      rowsHtml += (
+        '<tr style="background:' + bg + ';">'
+        + '<td class="swarm-diff-gutter" style="user-select:none;text-align:right;padding:0 8px;color:#7c8aa6;font-size:12px;width:48px;">' + esc(oldCell) + '</td>'
+        + '<td class="swarm-diff-gutter" style="user-select:none;text-align:right;padding:0 8px;color:#7c8aa6;font-size:12px;width:48px;">' + esc(newCell) + '</td>'
+        + '<td class="swarm-diff-sign" style="user-select:none;text-align:center;padding:0 4px;color:#7c8aa6;font-size:12px;width:18px;">' + esc(sign) + '</td>'
+        + '<td class="swarm-diff-code" style="padding:0 8px;white-space:pre-wrap;word-break:break-word;font-family:\\'Space Mono\\',ui-monospace,monospace;font-size:12px;">' + esc(text) + annHtml + '</td>'
+        + '</tr>'
+      );
+    }
+
+    var anchorSlug = slugifyAttr((file || 'hunk') + '-' + (oldStart || hunkIdx + 1));
+    var anchorId = 'swarm-diff-' + anchorSlug;
+    var header = (
+      '@@ -' + oldStart + ',' + oldLines + ' +' + newStart + ',' + newLines + ' @@'
+    );
+
+    return (
+      '<a id="' + esc(anchorId) + '" class="swarm-diff-anchor" data-hunk="' + esc(anchorSlug) + '"></a>'
+      + '<div class="swarm-diff-hunk-header" style="padding:6px 12px;background:rgba(124,138,166,0.10);color:#7c8aa6;font-family:\\'Space Mono\\',ui-monospace,monospace;font-size:11px;border-top:1px solid var(--swarm-border,#22304a);">'
+      + esc(header)
+      + '</div>'
+      + '<table class="swarm-diff-table" style="width:100%;border-collapse:collapse;table-layout:fixed;">'
+      + '<tbody>' + rowsHtml + '</tbody>'
+      + '</table>'
+    );
+  }
+
+  function renderDiff(rootEl, diffData) {
+    var hunks = (diffData && Array.isArray(diffData.hunks)) ? diffData.hunks : (Array.isArray(diffData) ? diffData : []);
+    var file = rootEl.getAttribute('file') || '';
+    var baseSha = rootEl.getAttribute('base-sha') || '';
+    var headSha = rootEl.getAttribute('head-sha') || '';
+
+    var shaLine = '';
+    if (baseSha || headSha) {
+      shaLine = '<span class="swarm-diff-sha" style="font-family:\\'Space Mono\\',ui-monospace,monospace;font-size:11px;color:#7c8aa6;">'
+        + esc(baseSha) + ' → ' + esc(headSha)
+        + '</span>';
+    }
+
+    var hunksHtml = '';
+    for (var i = 0; i < hunks.length; i++) {
+      hunksHtml += renderHunk(hunks[i] || {}, i, file);
+    }
+
+    rootEl.innerHTML = (
+      '<div class="swarm-diff-root" style="border:1px solid var(--swarm-border,#22304a);border-radius:8px;background:var(--swarm-card,#121826);overflow:hidden;margin:12px 0;break-inside:avoid;">'
+      + '<div class="swarm-diff-header" style="display:flex;align-items:center;justify-content:space-between;padding:10px 12px;background:rgba(59,130,246,0.10);border-bottom:1px solid var(--swarm-border,#22304a);">'
+      + '<span class="swarm-diff-file" style="font-family:\\'Space Mono\\',ui-monospace,monospace;font-size:13px;font-weight:700;color:var(--swarm-text,#e6eaf2);">' + esc(file || '(untitled)') + '</span>'
+      + shaLine
+      + '</div>'
+      + hunksHtml
+      + '</div>'
+    );
+  }
+
+  // Public function form lives on window.swarmUi so callers can render an
+  // arbitrary root element programmatically. The custom element below is just
+  // a declarative wrapper around the same render function.
+  window.swarmUi = window.swarmUi || {};
+  window.swarmUi.renderDiff = renderDiff;
+
+  // Defer the parse-and-render so the HTML parser has time to finish
+  // appending JSON text children. \`connectedCallback\` fires on the opening
+  // tag — \`this.textContent\` is empty until children parse. Without a
+  // defer, every declarative <swarm-diff> renders an empty header and the
+  // JSON text remains visible as orphan children.
+  //
+  // queueMicrotask alone is NOT enough — Chrome's streaming parser drains
+  // microtasks between chunks, so the microtask can run BEFORE the JSON
+  // child is appended. We need to wait for the parser to finish the current
+  // document load, then read textContent.
+  //
+  //  * \`document.readyState === 'loading'\` ⇒ parser still streaming →
+  //    wait for DOMContentLoaded (fires after all children are parsed).
+  //  * otherwise (element was created/inserted dynamically post-load) ⇒
+  //    queueMicrotask is fine — DOM is stable, just give the caller a tick.
+  //
+  // Re-entrancy (element moved/reconnected) re-fires connectedCallback so
+  // we re-render against current textContent.
+  class SwarmDiffElement extends HTMLElement {
+    connectedCallback() {
+      var self = this;
+      var doRender = function() {
+        if (!self.isConnected) return;
+        var raw = self.textContent || '';
+        renderDiff(self, { hunks: parseHunks(raw) });
+        // Notify <swarm-diff-jumps> instances so they can pick up new anchors.
+        self.dispatchEvent(new CustomEvent('swarm-diff:rendered', { bubbles: true }));
+      };
+      if (typeof document !== 'undefined' && document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', doRender, { once: true });
+      } else {
+        queueMicrotask(doRender);
+      }
+    }
+  }
+  window.customElements.define('swarm-diff', SwarmDiffElement);
+
+  // Sibling-anchor jump list. Walks subsequent siblings, finds every
+  // <swarm-diff data-hunk=...> anchor, and renders a small list of links.
+  //
+  // Same parse-order hazard as <swarm-diff>: <swarm-diff-jumps> usually
+  // appears in the document BEFORE the <swarm-diff> elements it indexes, so
+  // we also defer to a microtask AND re-render whenever a <swarm-diff> in the
+  // document finishes rendering its anchors.
+  class SwarmDiffJumpsElement extends HTMLElement {
+    connectedCallback() {
+      var self = this;
+      var renderJumps = function() {
+        var anchors = document.querySelectorAll('.swarm-diff-anchor[data-hunk]');
+        if (!anchors.length) {
+          self.innerHTML = '<span class="no-print" style="color:#7c8aa6;font-size:12px;">No hunks yet.</span>';
+          return;
+        }
+        var items = '';
+        for (var i = 0; i < anchors.length; i++) {
+          var a = anchors[i];
+          var slug = a.getAttribute('data-hunk') || ('hunk-' + i);
+          // Hunk title = nearest preceding diff's file attribute if available.
+          var diff = a.closest && a.closest('swarm-diff');
+          var file = (diff && diff.getAttribute('file')) || slug;
+          items += '<li style="margin:0;padding:2px 0;"><a href="#' + esc(a.id) + '" style="color:#3b82f6;text-decoration:none;font-family:\\'Space Mono\\',ui-monospace,monospace;font-size:12px;">' + esc(file) + '</a></li>';
+        }
+        self.innerHTML = (
+          '<nav class="swarm-diff-jumps no-print" style="padding:8px 12px;border:1px dashed var(--swarm-border,#22304a);border-radius:8px;background:rgba(124,138,166,0.05);">'
+          + '<div style="font-size:10px;text-transform:uppercase;letter-spacing:0.08em;color:#7c8aa6;margin-bottom:4px;">Jump to</div>'
+          + '<ul style="list-style:none;padding:0;margin:0;">' + items + '</ul>'
+          + '</nav>'
+        );
+      };
+      // Wait for the parser to finish initial load before first query —
+      // <swarm-diff> elements also defer to DOMContentLoaded so we must
+      // run AFTER they finish rendering their anchors. The event listener
+      // below handles the live-update case.
+      if (typeof document !== 'undefined' && document.readyState === 'loading') {
+        document.addEventListener('DOMContentLoaded', function() { queueMicrotask(renderJumps); }, { once: true });
+      } else {
+        queueMicrotask(renderJumps);
+      }
+      // Re-render whenever a sibling <swarm-diff> finishes its async render.
+      self._onDiffRendered = function() { renderJumps(); };
+      document.addEventListener('swarm-diff:rendered', self._onDiffRendered);
+    }
+    disconnectedCallback() {
+      if (this._onDiffRendered) {
+        document.removeEventListener('swarm-diff:rendered', this._onDiffRendered);
+      }
+    }
+  }
+  window.customElements.define('swarm-diff-jumps', SwarmDiffJumpsElement);
+})();
+`;