opencode-webui 1.0.9 → 2.1.0

package/server/userExtensions.ts

@@ -1,25 +1,47 @@
 /**
- * Phase C — USER extension dirs.
+ * Extension folder discovery — ONE loader, THREE sources (spec §4, §6, §11.3).
  *
- * Plugins ship browser halves discovered through the engine's /api/plugin
- * list (see index.ts). This module adds the user's own drop-in dirs, scanned
- * straight from disk with NO engine involvement:
+ * Sources, highest precedence first (same id = same swap point, higher wins):
+ *   1. user:    ~/.config/opencode/webui-extensions/<name>/   (global)
+ *   2. project: <cwd>/.opencode/webui-extensions/<name>/      (per project)
+ *   3. shipped: <app>/webui-extensions/<name>/                (ours, updates with the app)
  *
- *   ~/.config/opencode/webui-extensions/<name>/main.tsx   (global)
- *   <cwd>/.opencode/webui-extensions/<name>/main.tsx      (per project)
+ * One extension = one folder. Gating is owned by the folder itself:
+ * presence = installed; manifest.json `disabled: true` = paused; delete/move
+ * the folder to uninstall. No config.ts list, no per-browser localStorage.
  *
- * They ride the exact same pipeline as plugin UIs — mtime cache-busting and
- * Bun.build bundling via bundleUIEntry() in index.ts — so a user extension
- * is just `{ id, url, source: "user:<path>" }` appended to the existing
- * GET /api/webui/extensions manifest. Discovery is cached 5s, mirroring the
- * plugin discovery pattern.
+ * Folder anatomy (new format; legacy `main.tsx`-only folders still load):
+ *   manifest.json   { id?, name?, version?, description?, disabled? }
+ *   index.tsx       browser stratum entry (preferred)
+ *   main.tsx        legacy browser entry (fallback)
+ *   dom.ts          DOM stratum entry (spec §7 — post-render DOM changes)
+ *
+ * They ride the same pipeline as plugin UIs — mtime cache-busting and
+ * Bun.build bundling via bundleUIEntry() in index.ts — so an extension is
+ * just `{ id, url?, domUrl?, source }` (or `{ id, disabled: true, source }`
+ * when paused) in the GET /api/webui/extensions manifest. A dom-only folder
+ * (no index/main entry) still lists with only `domUrl`.
  */
 
-import { existsSync, readdirSync, statSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 
-export type UIEntry = { id: string; entry: string; mtimeMs: number; source?: string };
+export type UIEntry = {
+  id: string;
+  /** Browser-stratum bundle entry file; "" when none exists (or disabled). */
+  entry: string;
+  mtimeMs: number;
+  /** DOM-stratum bundle entry (`dom.ts`); absent when the folder has none. */
+  domEntry?: string;
+  domMtimeMs?: number;
+  source?: string;
+  /** manifest.json `disabled: true` — paused, never bundled or imported. */
+  disabled?: boolean;
+  /** Which of the three sources won for this id. */
+  origin?: "user" | "project" | "shipped";
+};
 
 export const USER_EXT_LIST_TTL_MS = 5_000;
 
@@ -38,9 +60,26 @@ export function projectUserExtensionsDir(): string | null {
   return join(process.cwd(), ".opencode", "webui-extensions");
 }
 
+/** Shipped extensions live next to the app and update with it. Resolved from
+ * this module's location (not cwd — the proxy may be launched from any
+ * project directory; only the PROJECT source is cwd-relative). */
+export function shippedExtensionsDir(): string {
+  try {
+    return join(dirname(fileURLToPath(import.meta.url)), "..", "webui-extensions");
+  } catch {
+    return join(process.cwd(), "webui-extensions");
+  }
+}
+
+/** Every source root the proxy watches (existing or not — watchers attach lazily). */
+export function extensionSourceRoots(): string[] {
+  const roots = [globalUserExtensionsDir(), projectUserExtensionsDir(), shippedExtensionsDir()];
+  return roots.filter((r): r is string => !!r);
+}
+
 const warned = new Set<string>();
 
-/** Console.warn at most once per key per process — discovery re-runs every 5s. */
+/** Console.warn at most once per key per process — discovery re-runs often. */
 export function warnOnce(key: string, message: string): void {
   if (warned.has(key)) return;
   warned.add(key);
@@ -49,10 +88,124 @@ export function warnOnce(key: string, message: string): void {
 
 let cache: { at: number; entries: UIEntry[] } | null = null;
 
+/** Drop the discovery cache so the next read re-scans disk (watcher path). */
+export function invalidateExtensionCache(): void {
+  cache = null;
+}
+
+function readManifest(dir: string): { id?: unknown; disabled?: unknown } | null {
+  try {
+    const raw = readFileSync(join(dir, "manifest.json"), "utf8");
+    const parsed: unknown = JSON.parse(raw);
+    if (parsed && typeof parsed === "object") return parsed as { id?: unknown; disabled?: unknown };
+    return null;
+  } catch {
+    return null; // absent or unreadable — legacy folder, id falls back to dir name
+  }
+}
+
+/** DOM-stratum entry: exactly `dom.ts` — one method per concern. */
+function folderDomEntry(dir: string): string | null {
+  const candidate = join(dir, "dom.ts");
+  try {
+    if (existsSync(candidate)) return candidate;
+  } catch {
+    /* unreadable — no DOM stratum */
+  }
+  return null;
+}
+
+function mtimeOf(path: string): number | null {
+  try {
+    return statSync(path).mtimeMs;
+  } catch {
+    return null; // vanished mid-scan
+  }
+}
+/** Preferred-first browser entry candidates for one extension folder. */
+function folderEntry(dir: string): string | null {
+  for (const name of ["index.tsx", "index.ts", "main.tsx", "main.ts"]) {
+    const candidate = join(dir, name);
+    try {
+      if (existsSync(candidate)) return candidate;
+    } catch {
+      /* unreadable — try the next */
+    }
+  }
+  return null;
+}
+
+function scanRoot(root: string, origin: UIEntry["origin"], entries: UIEntry[], seen: Set<string>): void {
+  let names: string[];
+  try {
+    names = readdirSync(root, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+  } catch {
+    return; // absent root is the normal case
+  }
+  for (const name of names.sort()) {
+    if (seen.has(name)) {
+      warnOnce(
+        `ext-dup:${name}`,
+        `extension "${name}" shadowed — keeping the higher-precedence copy`,
+      );
+      continue;
+    }
+    const dir = join(root, name);
+    let manifest: { id?: unknown; disabled?: unknown } | null = null;
+    try {
+      manifest = readManifest(dir);
+    } catch {
+      /* unreadable entry — skip */
+      continue;
+    }
+    const id = typeof manifest?.id === "string" && manifest.id.length > 0 ? manifest.id : name;
+    if (seen.has(id)) {
+      warnOnce(`ext-dup:${id}`, `extension "${id}" shadowed — keeping the higher-precedence copy`);
+      continue;
+    }
+    const disabled = manifest?.disabled === true;
+    const entry = disabled ? null : folderEntry(dir);
+    const dom = disabled ? null : folderDomEntry(dir);
+    // A paused extension needs no entry file; an enabled one without any
+    // entry file is skipped silently (mid-write folder, or server-only —
+    // note a dom-only folder DOES list, with only `domEntry` set).
+    if (!disabled && !entry && !dom) continue;
+    let mtimeMs = 0;
+    if (entry) {
+      const mtime = mtimeOf(entry);
+      if (mtime === null) continue; // vanished mid-scan
+      mtimeMs = mtime;
+    }
+    let domEntry: string | undefined;
+    let domMtimeMs: number | undefined;
+    if (dom) {
+      const mtime = mtimeOf(dom);
+      if (mtime !== null) {
+        domEntry = dom;
+        domMtimeMs = mtime;
+      }
+    }
+    entries.push({
+      id,
+      entry: entry ?? "",
+      mtimeMs,
+      domEntry,
+      domMtimeMs,
+      source: `webui-extensions:${dir}`,
+      disabled: disabled || undefined,
+      origin,
+    });
+    seen.add(name);
+    seen.add(id);
+  }
+}
+
 /**
- * User UI entries, global root first. Absent roots and unreadable entries are
- * skipped silently (that is the normal case); duplicate ids across roots warn
- * once and keep the first.
+ * All three sources merged, user root first. Absent roots and unreadable
+ * entries are skipped silently; duplicate ids across roots warn once and
+ * keep the higher-precedence copy (user > project > shipped).
  */
 export function discoverUserUIEntries(): UIEntry[] {
   const now = Date.now();
@@ -60,36 +213,10 @@ export function discoverUserUIEntries(): UIEntry[] {
 
   const entries: UIEntry[] = [];
   const seen = new Set<string>();
-  for (const root of [globalUserExtensionsDir(), projectUserExtensionsDir()]) {
-    if (!root) continue;
-    let names: string[];
-    try {
-      names = readdirSync(root, { withFileTypes: true })
-        .filter((d) => d.isDirectory())
-        .map((d) => d.name);
-    } catch {
-      continue; // absent root is the normal case
-    }
-    for (const name of names) {
-      if (seen.has(name)) {
-        warnOnce(`user-dup:${name}`, `user extension "${name}" exists in two roots — keeping the first`);
-        continue;
-      }
-      const entry = join(root, name, "main.tsx");
-      try {
-        if (!existsSync(entry)) continue;
-        entries.push({
-          id: name,
-          entry,
-          mtimeMs: statSync(entry).mtimeMs,
-          source: `user:${entry}`,
-        });
-        seen.add(name);
-      } catch {
-        /* unreadable entry — skip */
-      }
-    }
-  }
+  scanRoot(globalUserExtensionsDir(), "user", entries, seen);
+  const projectRoot = projectUserExtensionsDir();
+  if (projectRoot) scanRoot(projectRoot, "project", entries, seen);
+  scanRoot(shippedExtensionsDir(), "shipped", entries, seen);
   cache = { at: now, entries };
   return entries;
 }

package/skills/webui/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: webui
-description: opencode-webui — the browser frontend for the OpenCode engine. Load when the user mentions the webui/web frontend, asks about webui extensions, or wants to report a webui bug (/report does it).
+description: opencode-webui — the browser frontend for the OpenCode engine. Load when the user mentions the webui/web frontend, asks about webui extensions, wants to BUILD, ADD, CHANGE, DEBUG, or TEST a webui extension, or wants to report a webui bug (/report does it).
 ---
 
 # OpenCode webui (opencode-webui)
@@ -11,7 +11,7 @@ service credentials. One port for UI + `/api/*`: http://localhost:4097
 (`WEBUI_PROXY_PORT`).
 
 - **Repo**: https://github.com/AbdelftahZowail/opencode-webui
-- **This skill's version**: 1.0.9 (matches the `v1.0.9` git tag —
+- **This skill's version**: 2.1.0 (matches the `v2.1.0` git tag —
   the file links below are pinned to it, so they always describe the code
   this skill was generated with)
 - **A running instance exposes its version** at `GET /api/webui/config` →
@@ -24,12 +24,13 @@ fetch the exact file at the pinned tag instead of reading a local clone:
 
 | File | Purpose |
 | --- | --- |
-| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v1.0.9/ui-extensions/README.md | Full authoring guide — the source of truth for kinds/hooks/regions |
-| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v1.0.9/src/extensions/registry.tsx | The slot registry — exact register() shapes per kind |
-| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v1.0.9/src/components/Composer.tsx | Where slash entries / prompt hooks / composer regions live |
-| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v1.0.9/src/components/MessageItem.tsx | Where message/message.decoration/message.part render |
-| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v1.0.9/src/lib/composerHandoff.ts | Type-anywhere → composer behavior (if your extension competes for keys) |
-| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v1.0.9/src/store.ts | The store — actions useStore exposes to extensions |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v2.1.0/webui-extensions/README.md | Full authoring guide — the source of truth for strata/kinds/hooks/anchors |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v2.1.0/src/extensions/registry.tsx | The extension registry — exact register() shapes per kind |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v2.1.0/src/extensions/hooks.ts | Shared fireHooks runner — how open hook events fire |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v2.1.0/src/lib/domKit.ts | DOM-stratum kit (foreign/watch/styles) + the data-oc-* anchor table |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v2.1.0/server/ext/types.ts | Proxy-stratum types — server.ts routes/middleware/onEvent/pollers shapes |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v2.1.0/docs/extension-system-spec.md | The v2 decision record — strata, precedence, deletions, acceptance checks |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v2.1.0/src/store.ts | The store — actions useStore exposes to extensions |
 
 ## Environment
 
@@ -38,9 +39,26 @@ fetch the exact file at the pinned tag instead of reading a local clone:
 | `WEBUI_PASSWORD` | generated on first boot, printed once | Shared login passphrase. |
 | `WEBUI_HOST` | `127.0.0.1` | Bind address — a wildcard is refused without a password. |
 | `WEBUI_PROXY_PORT` | `4097` | Port for the UI and `/api/*`. |
+| `WEBUI_EXTENSION_DIR` | the global + project dirs | Replace both with ONE directory (the sandbox does this to keep WIP isolated). |
+| `WEBUI_ENGINE_URL` | `service.json` discovery | Aim the proxy at a chosen engine — skips `Service.ensure()`, so a stale pid can never spawn a rogue serve. Explicit env wins. |
+| `WEBUI_ENGINE_PASSWORD` | `service.json` password | Engine password for the override above (no file fallback when the URL is overridden — a chosen engine has its own credential). |
+| `WEBUI_SANDBOX_NOVITE` | unset | `1` — sandbox boots the proxy only, no Vite (`--no-vite` flag does the same). |
+| `WEBUI_CRASH_LOG` | `$XDG_STATE_HOME/opencode-webui/proxy-crash.log` | File fatal proxy errors (`uncaughtException`/`unhandledRejection`) are appended to; the last entry prints on next boot. |
 | `WEBUI_DEBUG` | unset | `1` — server/proxy debug logs to stdout. |
 | `WEBUI_DEBUG_LOG` | `/tmp/webui-debug.log` | File the frontend log sink (`POST /api/debug`) appends to. |
 
+### Parallel sandboxes (one per extension under test)
+
+Yes — run as many sandboxes at once as you need. `bun run sandbox` stacks
+with no flags: the first instance takes the fixed defaults (`:4099`/`:5175`
++ shared scratch dir); every further instance detects the busy ports and
+auto-isolates onto free ports + a fresh mkdtemp extension dir, printing what
+it picked. Explicit env (`WEBUI_PROXY_PORT` / `WEBUI_VITE_PORT` /
+`WEBUI_EXTENSION_DIR`) always wins per knob. The engine stays shared
+(same sessions everywhere, by design) — only ports + extension dirs are
+isolated. Rules: one sandbox per extension, never two writers to one ext
+dir, never reuse a port.
+
 ## What you can do for the user
 
 - **File a webui bug** — the composer ships a built-in `/report` command that
@@ -48,117 +66,120 @@ fetch the exact file at the pinned tag instead of reading a local clone:
   ring) into a prefilled GitHub issue for AbdelftahZowail/opencode-webui (see
   Reporting bugs below).
 - **Explain the extension system** from the tables below — they are extracted
-  verbatim from the authoring guide (`ui-extensions/README.md`), which is the
+  verbatim from the authoring guide (`webui-extensions/README.md`), which is the
   source of truth.
-- **Author a user-dir extension** for the user — a folder, no build step, no
-  restart.
+- **Author an extension folder** for the user — one folder, no build step, no
+  restart. Pick the stratum that matches the job (React tree → browser,
+  portals/canvas/post-render → dom.ts, headless/always-on → server.ts,
+  model tools → engine/).
 
-### Dev extensions vs user extensions (two homes, one contract)
+## The model in one minute
 
-| | Dev (app repo) | User (any machine) |
-| --- | --- | --- |
-| Where | `ui-extensions/<name>/` in the webui checkout | `~/.config/opencode/webui-extensions/<name>/main.tsx` (per-user) or `<project>/.opencode/webui-extensions/<name>/main.tsx` (per-project) |
-| How it loads | Bundled into the app build, listed in `ui-extensions/index.ts` | The proxy bundles it on the fly; page picks it up within ~8s |
-| On/off | `enabled` list in `ui-extensions/config.ts` | Settings › Extensions toggle |
-| API surface | Full app internals (imports, `useStore`, `api`) | ONLY the `window.__opencodeUI` bridge (`register`, `react`, `useStore`, `api`, `notify`, `getHooks`, `version`) |
+One extension = **one folder**: `manifest.json` (id, version, description,
+`disabled`?) + `index.tsx` (browser stratum) + `dom.ts` (DOM stratum) +
+`server.ts` (proxy stratum) + `engine/` (opencode plugin payload).
+Presence = installed; `disabled: true` = paused; delete the folder =
+uninstalled. Precedence, highest wins: `~/.config/opencode/webui-extensions/`
+(user) → `<project>/.opencode/webui-extensions/` (project) → shipped
+`webui-extensions/` (ours). Dropping a folder in the extension dir is an
+act of trust — extension code is not sandboxed.
 
-Authoring rules (kinds, hook events) are identical in both homes — the tables
-below apply to each.
+### Add / pause / remove
+
+| Action | How |
+| --- | --- |
+| Add | Create `webui-extensions/<name>/` with `manifest.json` + `index.tsx` calling `register({ kind, ... })`. Loads without rebuild/refresh/restart (manifest SSE push, same-id swap). |
+| Pause | Set `"disabled": true` in its `manifest.json` — gone on the next manifest push. |
+| Remove | Delete/move the folder — the id vanishes from the manifest. |
+| Shadow | Same id at higher precedence wins; core updates still flow everywhere else. |
 
-### Minimal user-dir extension
+Authoring rules (kinds, hook events) are identical in every source — the
+tables below apply to each. Full hot-reload guarantees and the timestamp
+worked example are in the authoring guide.
 
-Drop a folder — `~/.config/opencode/webui-extensions/<name>/main.tsx`
-(per-user) or `<project>/.opencode/webui-extensions/<name>/main.tsx`
-(per-project). The proxy bundles it and the page loads it within a poll cycle
-`~8s` — see the dev-vs-user split above). Runtime extensions reach
-the app ONLY through the `window.__opencodeUI` bridge (`register`,
-`react`, `useStore`, `api`, `notify`, `getHooks`, `version`):
+### Minimal extension (wrap — the default path for edits)
 
 ```tsx
-// ~/.config/opencode/webui-extensions/hello/main.tsx
-const { register, react } = window.__opencodeUI;
+// ~/.config/opencode/webui-extensions/my-time/{manifest.json,index.tsx}
+import { register } from "opencode-webui/extensions"; // shipped dirs import from src; external dirs use the extension API surface
 
 register({
-  kind: "region",
-  id: "hello",
-  region: "footer",
-  render: () => react.createElement("span", null, "hello from a user extension"),
+  kind: "wrap",
+  id: "my-time",
+  target: "Timestamp",
+  render: (props, next) => <span className="tabular-nums">{next()}</span>,
 });
 ```
 
-## Sandbox (iterate without touching the user's webui)
+## Five kinds, one job each (the contract)
 
-A second, private instance for authoring/testing user extensions — no repo
-needed. Start it the same way the package runs, plus `sandbox`:
-`bunx opencode-webui sandbox` (or `./opencode-webui-<target> sandbox`).
-It binds `127.0.0.1:4099` — loopback-only, NO password (a non-loopback
-sandbox is refused) — and loads extensions from an ISOLATED scratch dir
-(`~/.local/state/opencode-webui/sandbox-extensions/<name>/main.tsx`), so WIP
-is invisible to the user's main instance. Same engine, same sessions as the
-main instance. Workflow: write the extension in the scratch dir → watch it
-load in the sandbox within its poll cycle (~8s) → fix until right → then copy
-the folder into `~/.config/opencode/webui-extensions/<name>/` to ship it to
-the user (or `<project>/.opencode/webui-extensions/<name>/` for one project).
-Do not write user extensions directly into the real dirs while iterating —
-that exposes WIP to the user's browser immediately.
+| Kind | Job | Staleness |
+| --- | --- | --- |
+| `wrap` | Flow-through tweak of any registered target: `render(props, next)` — transform props/output, delegate to live core by default | **Stale-proof by construction.** Core updates always render *through* it. The default path for edits. |
+| `replace` | Take ownership of one registered target: `render(props, core)` wins outright at its priority; return `null` to fall through to the next candidate / core | **Frozen snapshot.** You opt out of core updates for that target — the marked escape hatch. Still receives `core` so you *can* compose. |
+| `contribute` | Add an item to a named collection (`collection` + `item`, `order` sorts, lower first) | Data, not code — core owns the list, you own your row. |
+| `hook` | Interception at instrumented boundaries: `{ event, handler(ctx, next) }` — `event` is an open string | New seams are new event names, never a registry change. |
+| `service` | Provide named logic: `{ service, value, precedence }` — consume via `getService(id)`; highest precedence wins | **Value overrides.** Core consults services for pluggable values (e.g. the timestamp formatter), so tiny logic tweaks never touch markup. |
 
-## Extension kinds (the contract)
+Contribute collections (registry-owned lists — data, not new kinds):
+`palette`, `slash` (UI-only; engine commands win name clashes),
+`pages` (routed at `/ext/{id}`), `settings`,
+`contextMenu.message` / `contextMenu.session` / `contextMenu.file`.
 
-| Kind | What it does | Where it surfaces |
-| --- | --- | --- |
-| `region` | render into any `<Slot region="…">` marker placed by core (see generated table below) | wherever core placed a `<Slot>` |
-| `command` | entry in the palette's "Extension commands" group (`run({ sessionID })`; `keybind` like `ctrl+shift+k` for global hotkey) | command palette (⌘/ctrl-K) + keybind |
-| `slash` | **UI-only** slash entry for Composer `/name` (local `run(args,{sessionID})`; not engine) | Composer autocomplete (`/` menu) |
-| `message` | full replacement for any message type (`type:"system"\|"synthetic"\|"shell"\|"compaction"\|"user"\|"assistant"\|…\|"*"`, `render({message, sessionID}) => node\|null`); first non-null wins, else core `renderMessageBody` | `MessageItem` per message |
-| `message.decoration` | small extras under message rows; `render({ messageID, message }) => node\|null` | under every message row |
-| `message.part` | inject after *each* part (text/tool/reasoning) inside a message; `render({messageID, message, part, partIndex})` | inside `MessageItem` per part |
-| `tool.renderer` | custom card for a specific tool name (`toolName:"bash"\|"edit"\|…`, `render(part)`) | `ToolCard` per tool call |
-| `contextMenu` | right-click menu item (`target:"message"\|"session"\|"file"`, `label`, `run`, `order`) | context menu |
-| `hook` | intercept/behavior (`event:string`, `handler(ctx,next)`) — see Hook events below | store / Composer / MessageItem |
-| `page` | full surface at `/ext/{id}` (route derived from the id) | sidebar links + direct URL |
-| `settings` | titled section inside Settings › Extensions (`render: () => ReactNode`) | Settings dialog |
-
-### Hook events
+### Hook catalog
 
 | Event | `ctx` shape | When |
 | --- | --- | --- |
-| `session.prompt` | `{ text: string, sessionID: string }` — mutate `ctx.text` to transform; call `next()` to continue | Composer `submit` before `POST /api/session/{id}/prompt` |
-| `message.render` | `{ message: MessageInfo, sessionID?: string }` — mutate `ctx.message` (shallow clone) before render | `MessageItem` before `message` renderer |
-| `store.dispatch` | `{ action, ... }` | store middleware observer |
-
-## Regions (render points)
-
-| Region | Render point |
+| `api.pre` | `{ name, args }` — MUTATE `ctx.args` (unknown[] spread into the endpoint) | Before every api client call; `await`ed so mutations apply |
+| `api.post` | `{ name, args, result }` — observe | After every successful api call |
+| `api.error` | `{ name, args, error }` — observe; the original error is rethrown | After every failed api call |
+| `store.dispatch` | `{ patch, state }` — observe | Store middleware, every action (sync site — `void fireHooks`) |
+| `session.prompt` | `{ text, sessionID }` — mutate `ctx.text` to transform; `await`ed | Composer submit before `POST /api/session/{id}/prompt` |
+| `session.adopted` | `{ sessionID }` | Session becomes the focused session |
+| `pane.focused` | `{ paneID, sessionID }` | Split-view focus moves to a pane |
+| `extension.loaded` | `{ id, url }` | A browser extension bundle finished loading |
+| `message.render` | `{ message, sessionID? }` — mutate `ctx.message` (shallow clone) before render | `MessageItem` before the message renderer |
+
+Browser hooks affect only their own browser — transforms affecting *all*
+clients go in proxy `server.ts` middleware. Proxy mounts (`server/ext/`):
+`routes` at `/api/webui/ext/<id>/…`, `middleware` over `/api/*`,
+`onEvent` tap (works with all tabs closed), `pollers`, per-extension KV.
+
+## DOM anchors (the free layer)
+
+`dom.ts` + the kit (`foreign`/`watch`/`styles`, mount/dispose) covers
+what the React tree cannot: mid-component DOM, portals, canvas/xterm,
+iframes. Stable anchors below are contract — renaming one is a version bump
++ migration note. DOM is the marked last resort ("outside the contract; you
+own the fragility").
+
+| Anchor | Site |
 | --- | --- |
-| `app.header` | `src/App.tsx:238` |
-| `composer.above` | `src/components/Composer.tsx:932` |
-| `composer.below` | `src/components/Composer.tsx:1252` |
-| `composer.toolbar` | `src/components/Composer.tsx:1240` |
-| `footer` | `src/App.tsx:303` |
-| `header.session.actions` | `src/components/Conversation.tsx:572` |
-| `header.session.before` | `src/components/Conversation.tsx:520` |
-| `message.after` | `src/components/MessageItem.tsx:258` |
-| `message.before` | `src/components/MessageItem.tsx:239` |
-| `sidebar` | `src/components/Sidebar.tsx:682` |
-| `sidebar.session.after` | `src/components/Sidebar.tsx:982` |
-| `sidebar.session.before` | `src/components/Sidebar.tsx:914` |
-| `tool.after` | `src/components/ToolCard.tsx:58` |
-| `tool.before` | `src/components/ToolCard.tsx:57` |
-| `transcript.above` | `src/components/Conversation.tsx:128` |
-| `transcript.below` | `src/components/Conversation.tsx:155` |
-| `transcript.empty` | `src/components/Conversation.tsx:434` |
-
-## Add / remove / disable (app repo)
+| `data-oc-transcript` | MessageScroller content |
+| `data-oc-message` + `data-oc-message-id` + `data-oc-message-type` | MessageItem root per type branch |
+| `data-oc-composer` + `data-oc-composer-input` + `data-oc-composer-send` | Composer card, textarea, send button |
+| `data-oc-tool-card` + `data-oc-tool-name` | ToolCard root + tool call name |
+| `data-oc-session-header` | Conversation header bar |
+| `data-oc-sidebar` | Sidebar root |
+| `data-oc-queue-strip` | QueueStrip (steer/queue rows) |
+| `data-oc-subagent-strip` | SubagentStrip |
+| `data-oc-runs-panel` | RunsPanel |
 
-| Action | How |
-| --- | --- |
-| Add | Create `ui-extensions/<name>/`, add one import to `ui-extensions/index.ts`. Appears instantly via HMR. |
-| Remove | Delete the import line and the folder. |
-| Disable | Remove its id from the `enabled` list in `ui-extensions/config.ts` — one line, applies instantly via HMR, no reload. |
+## Sandbox (iterate without touching the user's webui)
 
-The `enabled` list in `ui-extensions/config.ts` is the runtime switch: only
-ids listed there are rendered, even if the code is bundled. (A settings-panel
-UI could drive the same list later — the mechanism is already in place.)
+A second, private instance for authoring/testing extensions — no repo
+needed. Start it the same way the package runs, plus `sandbox`:
+`bunx opencode-webui sandbox` (or `./opencode-webui-<target> sandbox`).
+It binds `127.0.0.1:4099` — loopback-only, NO password (a non-loopback
+sandbox is refused) — and loads extensions from an ISOLATED scratch dir
+(`~/.local/state/opencode-webui/sandbox-extensions/<name>/`), so WIP
+is invisible to the user's main instance. Same engine, same sessions as the
+main instance. Workflow: write the extension folder in the scratch dir →
+watch it load in the sandbox via the manifest push (sub-second) → fix until
+right → then copy the folder into `~/.config/opencode/webui-extensions/<name>/`
+to ship it to the user (or `<project>/.opencode/webui-extensions/<name>/`
+for one project). Do not write user extensions directly into the real dirs
+while iterating — that exposes WIP to the user's browser immediately.
 
 ## Reporting bugs