opencode-webui 3.0.0 → 3.0.1

package/README.md

@@ -22,8 +22,8 @@ First boot prints the URL and a generated password — **shown once**:
               generated for this install — shown once
               set WEBUI_PASSWORD to choose your own
   sessions    the same ones as your opencode TUI — same engine, same history
-  extensions  ~/.config/opencode/webui-extensions/<name>/main.tsx   per-user
-              <project>/.opencode/webui-extensions/<name>/main.tsx  per-project
+  extensions  ~/.config/opencode/webui-extensions/<name>/index.tsx   per-user
+              <project>/.opencode/webui-extensions/<name>/index.tsx  per-project
   skill       agent skill synced to ~/.config/opencode/skills/webui/ — your agent knows this UI exists
 ```
 
@@ -159,8 +159,8 @@ One extension = one folder, dropped in — no rebuild, no restart:
 
 ```
 my-extension/
-  manifest.json    id, version, description, disabled?
-  index.tsx        browser stratum (wrap / replace / contribute / hook / service)
+  manifest.json    id, version, description; optional disabled, settings, requires
+  index.tsx        browser stratum: register() and/or activate(ctx)
   dom.ts           DOM stratum (portals, canvas, post-render tweaks)
   server.ts        proxy stratum (routes, middleware, event tap, pollers)
   engine/          opencode plugin payload (model tools, prompt hints)
@@ -170,9 +170,10 @@ Presence = installed, `disabled: true` = paused, delete = uninstalled; a
 higher-precedence folder with the same id shadows the shipped one, so user
 customizations survive core updates with no forks. Hot reload everywhere:
 browser edits repaint live via the manifest SSE push, proxy edits reload
-with no restart. The full authoring guide — the five kinds, hook catalog,
-DOM kit, `server.ts` mounts, precedence, and the timestamp worked example —
-is [webui-extensions/README.md](webui-extensions/README.md).
+with no restart. The full authoring guide — the five kinds, the activation
+context, the event bus, declared settings + `requires`, slots, peer
+composition, the DOM kit, `server.ts` mounts, precedence, and the timestamp
+worked example — is [webui-extensions/README.md](webui-extensions/README.md).
 
 The built-in `/report` command files a prefilled GitHub issue with a diagnostics
 bundle (build version, enabled extensions, error ring); `--agent` hands it to the

package/package.json

@@ -3,7 +3,7 @@
   "description": "Web UI for the OpenCode coding agent — chat, streaming, tool cards, and extensions over the OpenCode engine's HTTP API.",
   "private": false,
   "type": "module",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "license": "MIT",
   "repository": {
     "type": "git",

package/skills/webui/SKILL.md

@@ -25,7 +25,7 @@ optional (`auth: none`) for private networks/proxies, but reachable-without-a-
 password changes need explicit confirmation.
 
 - **Repo**: https://github.com/AbdelftahZowail/opencode-webui
-- **This skill's version**: 3.0.0 (matches the `v3.0.0` git tag —
+- **This skill's version**: 3.0.1 (matches the `v3.0.1` 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` →
@@ -38,15 +38,20 @@ fetch the exact file at the pinned tag instead of reading a local clone:
 
 | File | Purpose |
 | --- | --- |
-| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.0/webui-extensions/README.md | Full authoring guide — the source of truth for strata/kinds/hooks/anchors |
-| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.0/src/extensions/registry.tsx | The extension registry — exact register() shapes per kind |
-| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.0/src/extensions/slots.tsx | Slot ids (placement contract) + the Slot renderer |
-| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.0/src/extensions/manifest.ts | Manifest contract — settings schema + requires parsing/checks |
-| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.0/src/extensions/hooks.ts | Shared fireHooks runner — how open hook events fire |
-| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.0/src/lib/domKit.ts | DOM-stratum kit (foreign/watch/styles) + the data-oc-* anchor table |
-| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.0/server/ext/types.ts | Proxy-stratum types — server.ts routes/middleware/onEvent/pollers shapes |
-| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.0/docs/extension-system-spec.md | The v2 decision record — strata, precedence, deletions, acceptance checks |
-| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.0/src/store.ts | The store — actions useStore exposes to extensions |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.1/webui-extensions/README.md | Full authoring guide — the source of truth for strata/kinds/hooks/anchors |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.1/src/extensions/registry.tsx | The extension registry — exact register() shapes per kind |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.1/src/extensions/context.ts | Activation context — the `activate(ctx)` entry, disposal, and the full `ctx` surface |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.1/src/extensions/slots.tsx | Slot ids (placement contract) + the Slot renderer |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.1/src/extensions/manifest.ts | Manifest contract — settings schema + requires parsing/checks |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.1/src/extensions/hooks.ts | Shared fireHooks runner — how open hook events fire |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.1/src/lib/domKit.ts | DOM-stratum kit (foreign/watch/styles) + the data-oc-* anchor table |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.1/src/lib/storeFacade.ts | Curated store surface extensions get as `store` (raw module = `advanced.store`) |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.1/src/lib/eventBus.ts | Event bus — raw engine events + derived lifecycle, frame-batched |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.1/src/lib/extSettings.ts | Per-extension declared settings — schema, resolve, persist, subscribe |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.1/src/lib/extBus.ts | Extension-to-extension peer bus (publish/subscribe) |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.1/server/ext/types.ts | Proxy-stratum types — server.ts routes/middleware/onEvent/pollers shapes |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.1/docs/extension-system-spec.md | The v2 decision record — strata, precedence, deletions, acceptance checks |
+| https://raw.githubusercontent.com/AbdelftahZowail/opencode-webui/v3.0.1/src/store.ts | The raw store module (reachable as `advanced.store`; prefer the facade) |
 
 ## Environment
 
@@ -130,6 +135,25 @@ register({
 });
 ```
 
+### Activation context (browser stratum)
+
+Prefer `export function activate(ctx)` over module-scope `register()` — the
+context owns lifecycle + disposal. On it: `ctx.register(entry)` (the five
+kinds); `ctx.poll({ name, minInterval, run })` and `ctx.after(ms, fn)` (the
+shared tier-aware scheduler, auto-stopped); `ctx.on(name, fn)` (event bus —
+a raw engine type or a derived name: `run.started`, `run.ended`,
+`tool.called`, `tool.completed`, `message.appended`; `"*"` = all);
+`ctx.subscribe(selector, fn)` (derived store read); `ctx.store` (curated
+store facade — selectors + actions); `ctx.settings` (declared settings);
+`ctx.collections` / `ctx.bus` (peer composition); `ctx.onDispose(fn)` or
+returning a teardown. Everything a context creates is disposed on hot-swap,
+`disabled`, and delete. Module-scope `register()` still works but is being
+deprecated.
+
+Manifest `settings` declares options core renders in Settings › Extensions;
+`requires` (`api`/`targets`/`slots`/`services`) is checked on every
+sync and an unmet reference is a visible warning, not a silent blank spot.
+
 ## Five kinds, one job each (the contract)
 
 | Kind | Job | Staleness |

package/webui-extensions/README.md

@@ -62,7 +62,11 @@ extension code is not sandboxed (same model as host plugins).
 > browser loader + manifest SSE, proxy-stratum mounts, `dom.ts` loader wiring
 > + `data-oc-*` stamping, core self-registration, and the `ui-extensions/` →
 > `webui-extensions/` rename are landed (`docs/extension-system-spec.md` §11).
-> The contract below is what that work converged on — write to it.
+> The **roadmap seams are landed too** (`docs/extension-roadmap.md` items 1–9,
+> `EXT_API_VERSION` 2): prop-transforming wraps, the activation context +
+> disposal, scheduler access, the event bus, the curated store facade,
+> declared settings, thin slots, manifest `requires` diagnostics, and peer
+> composition. The contract below is what that work converged on — write to it.
 
 ## Choosing a stratum (framing rule)
 
@@ -579,7 +583,8 @@ One folder becomes pixels through four files — follow them in order:
 3. **Manifest + SSE + bundling (proxy).** `server/index.ts` merges folder
    entries with engine-plugin UI halves, serves
    `GET /api/webui/extensions` (`{ id, url?v=mtime, domUrl?v=mtime,
-   source, origin }`), pushes a `{ type: "webui.extensions", version }`
+   source, origin, name?, description?, disabled?, settings?, requires?,
+   capabilities? }`), pushes a `{ type: "webui.extensions", version }`
    event per manifest change on `GET /api/webui/extensions/events`, and
    bundles each entry standalone with `Bun.build` (`bundleUIEntry` —
    react external, build logs printed loudly, never silent).
@@ -590,7 +595,10 @@ One folder becomes pixels through four files — follow them in order:
    `domUrl` via the DOM kit, and disposes + unregisters ids that vanish or
    flip `disabled: true`. Shipped browser bundles are skipped here (the glob
    owns them — importing twice would run side effects twice) but shipped
-   `domUrl` still mounts and `disabled` still pauses them.
+   `domUrl` still mounts and `disabled` still pauses them. Each sync also
+   parses the declared contract: the settings schema is registered for
+   `ctx.settings`, and unmet `requires` / malformed shapes become visible
+   diagnostics (see **Declared settings + requirements**).
 
 ## What extensions can use (browser stratum)