@ekrooh/bare 0.4.0 → 0.6.0

package/README.md

@@ -1,246 +1,190 @@
 # @ekrooh/bare
 
-**One soul, many platforms.** A single codebase and identity that lives
-across every platform at once — the same app, state, and soul on Android, iOS,
+**One soul, many platforms.** One codebase and identity across Android, iOS,
 web, and desktop.
 
-[![CI](https://github.com/AndersCan/ekrooh/actions/workflows/test.yml/badge.svg)](https://github.com/AndersCan/ekrooh/actions/workflows/test.yml)
+**Docs: <https://anderscan.github.io/ekrooh>**
 
-The **boring bootstrap** for cross-platform apps on the Bare runtime
-(holepunch): a binary wire protocol, plugin kernel, RPC messenger, transports,
-and native host bridges — plus a reference app that demonstrates all of it.
+[![CI](https://github.com/AndersCan/ekrooh/actions/workflows/test.yml/badge.svg)](https://github.com/AndersCan/ekrooh/actions/workflows/test.yml)
+[![Release](https://img.shields.io/github/v/release/AndersCan/ekrooh)](https://github.com/AndersCan/ekrooh/releases/latest)
 
-> Read `vision.md` for what this project is and is not, `AGENTS.md` for how to
-> develop it, `CONTRIBUTING.md` for how to contribute, and `RELEASING.md` for
-> how to cut a release.
+The boring bootstrap for cross-platform apps on the Bare runtime (holepunch): a
+binary wire protocol, plugin kernel, RPC messenger, transports, and native host
+bridges, plus a reference app.
 
-## The model (UI perspective)
+- [`vision.md`](vision.md): what this project is and is not.
+- [`AGENTS.md`](AGENTS.md): how to develop it and the canonical commands.
+- [`CONTRIBUTING.md`](CONTRIBUTING.md): how to contribute.
+- [`RELEASING.md`](RELEASING.md): how to cut a release.
+- `docs/`: internal ADRs (`docs/adr/`) and agent operations; not the public site.
 
-The **frontend** (browser or WebView) is written as if there is only a
-**backend** reachable over a **WebSocket** (binary framed messages). It picks a
-transport automatically:
+## Model
 
-- **WebSocket** everywhere on-device: the worklet runs **one loopback HTTP+WS
-  server** that serves the web app, the media files, and the protocol socket,
-  so the page connects to the same origin it was served from (`ws://location.host`).
-- **Mock transport** when `VITE_TRANSPORT_MODE=mock` (tests).
-- Browser dev points the WebSocket at the dev backend explicitly
-  (`VITE_BARE_WS_URL`).
+The frontend (browser or WebView) is written as if only a backend is reachable
+over a WebSocket carrying binary framed messages.
 
-The UI does **not** branch on worklets, Bare, or host IPC. Shared types and
-helpers (`@ekrooh/bare/core`) describe the **wire protocol** to the backend, not
-the runtime that implements it.
+- On device, the worklet runs one loopback HTTP+WS server that serves the web
+  app, media files, and the protocol socket. The page connects to
+  `ws://location.host`.
+- `VITE_TRANSPORT_MODE=mock` selects the mock transport (tests).
+- Browser dev points the WebSocket at the dev backend via `VITE_BARE_WS_URL`.
 
-## Glossary
+The UI never branches on worklets, Bare, or host IPC. `@ekrooh/bare/core`
+describes the wire protocol, not the runtime that implements it.
 
-| Term         | Meaning                                                                                      |
-| ------------ | -------------------------------------------------------------------------------------------- |
-| **Frontend** | Web UI: Vite bundle in the browser; same bundle in the Android/iOS WebView.                  |
-| **Backend**  | Logic that runs the core bundle and speaks the framed message protocol with the frontend.    |
-| **Host**     | Native shell (Android/iOS): starts the backend, owns system APIs, injects the session token. |
+| Term         | Meaning                                                                                          |
+| ------------ | ------------------------------------------------------------------------------------------------ |
+| **Frontend** | Web UI: Vite bundle in the browser, or the same bundle in a WebView.                             |
+| **Backend**  | Runs the core bundle and speaks the framed protocol with the frontend.                           |
+| **Host**     | Native shell (Android/iOS): starts the backend, owns system APIs, injects the session bootstrap. |
 
-## Repository structure
+## Repository layout
 
-- `core/` — framework: wire protocol codec, plugin router, RPC messenger, host
-  IPC (`core/messages`), the unified loopback server (HTTP + WS + cookie auth),
-  Bare worklet entry.
-- `plugins/` — framework: canonical plugins (`core.health`, `core.discovery`,
+- `core/`: wire codec, plugin router, RPC messenger, host IPC (`core/messages`),
+  loopback server (`core/server`), worklet entry (`core/main.core.ts`).
+- `plugins/`: canonical plugins (`core.health`, `core.discovery`,
   `core.permissions`, `vendor.media`) and typed event builders.
-- `web/transports/` — framework: `MessageTransport` plus WebSocket and mock
-  transports.
-- `android/` — framework: Android host **library** (`:bare-host`) — IPC
-  coordinator, host plugin registry, WebView client.
-- `ios/` — framework: iOS host **Swift package** (`BareHost`) — IPC
-  coordinator, host plugin registry.
-- `examples/` — reference app: `web/` (lit-html + nanostores + Tailwind UI),
-  `android-app/` (the Android shell that embeds the backend and WebView), and
-  `ios-app/` (the iOS shell).
-- `e2e/` — Playwright tests against the browser runtime on the mock transport.
-- `scripts/` — dev backend runner, Playwright browser wrapper, prebuilds
-  fetcher, loopback smoke test.
-- `prebuilds/` — Bare Kit prebuilds (build output, gitignored).
-
-The framework's public surface is the `exports` map of the root `package.json`
-(`@ekrooh/bare/core`, `/runtime`, `/plugins`, `/plugins/*/events`, `/transports`).
-The package ships **compiled ESM JavaScript + type declarations** (`dist/`,
-built with `vp pack`) — consumers never see TypeScript source.
+- `web/transports/`: `MessageTransport`, WebSocket and mock transports.
+- `android/`: host library `:bare-host` (IPC coordinator, plugin registry, WebView client).
+- `ios/`: host Swift package `BareHost` (root `Package.swift`).
+- `examples/`: `web/`, `android-app/`, `ios-app/`, `consumer-basic/`.
+- `e2e/`: Playwright specs on the mock transport. `scripts/`: dev runner, Playwright wrapper, prebuild fetcher.
+- `apps/docs/`: public docs site (Astro Starlight, GitHub Pages).
+- `templates/`, `research/`: shared deploy templates; design notes.
+- `prebuilds/`: Bare Kit prebuilds (gitignored build output).
+
+The public surface is the `exports` map in `package.json` (`@ekrooh/bare/core`,
+`/runtime`, `/plugins`, `/plugins/*/events`, `/transports`). It points at
+compiled ESM and type declarations in `dist/` (built with `vp pack`). Consumers
+never see TypeScript source.
 
 ## Support matrix
 
-| Runtime        | Status                         | Transport | Notes                                                                                                                                                           |
-| -------------- | ------------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Browser (dev)  | first-class                    | WebSocket | Vite + local backend server (`VITE_BARE_WS_URL`)                                                                                                                |
-| Browser (test) | first-class                    | Mock      | Deterministic Playwright runs                                                                                                                                   |
-| Android        | first-class                    | WebSocket | Same-origin loopback socket; cookie auth via the injected token                                                                                                 |
-| iOS            | first-class (reference parity) | WebSocket | Same-origin loopback socket + cookie auth; host ships as source (`ios/`, SPM) on the same release tag; native picker/camera + Maestro journeys land before beta |
-| Desktop        | contract                       | —         | Adapters follow the same plugin contracts                                                                                                                       |
-
-### Parity policy
-
-- Core protocol and plugin contracts are runtime-agnostic.
-- Capabilities are opt-in plugins and may be runtime-specific.
-- Plugins report unsupported behavior with deterministic errors.
-- Feature code calls plugin events, not raw platform APIs from shared UI code.
-
-## Architecture
-
-```mermaid
-flowchart LR
-  subgraph frontend [Frontend]
-    webUi[WebUI]
-  end
-  subgraph backend [Backend]
-    coreProtocol[Message protocol]
-    coreRuntime[Core + plugins]
-  end
-  subgraph host [Host native]
-    hostIpc[Host IPC]
-  end
-  webUi -->|WebSocket framed messages| coreProtocol
-  coreProtocol --> coreRuntime
-  coreRuntime <-->|delegation| hostIpc
-```
+| Runtime        | Status                         | Transport | Notes                                                                                           |
+| -------------- | ------------------------------ | --------- | ----------------------------------------------------------------------------------------------- |
+| Browser (dev)  | first-class                    | WebSocket | Vite + local backend (`VITE_BARE_WS_URL`)                                                       |
+| Browser (test) | first-class                    | Mock      | Deterministic Playwright runs                                                                   |
+| Android        | first-class                    | WebSocket | Same-origin loopback socket, cookie auth                                                        |
+| iOS            | first-class (reference parity) | WebSocket | Same-origin loopback socket, cookie auth; host ships as source (`ios/`, SPM) on the release tag |
+| Desktop        | reference (macOS)              | WebSocket | Zig host + system webview + sidecar `bare`; see `examples/desktop-app`                          |
+
+Parity policy: core protocol and plugin contracts are runtime-agnostic.
+Capabilities are opt-in plugins and may be runtime-specific. Plugins report
+unsupported behavior with deterministic errors. Feature code calls plugin
+events, never raw platform APIs.
 
 ## Message protocol
 
-Binary frame:
-
-- `version` (1 byte)
-- `type` (1 byte)
-- `headerLen` (2 bytes, big-endian)
-- `header` (UTF-8 JSON)
-- `payload` (optional)
-
-Implementation: `MessageProtocol` in `core/messages` (see `wire-codec.ts`).
-
-## Plugin-first architecture
-
-Core does not ship product features (camera, permissions, BLE, etc.). Teams
-add plugins with namespaced events and per-runtime handlers.
-
-- Plugin IDs: `vendor.plugin`; events are plugin-local (`health.ping`).
-- Header types: `DISPATCH`, `INVOKE_REQUEST`, `INVOKE_RESPONSE`; invoke
-  responses echo `requestId`.
-- `dispatch` is fire-and-forget; `invoke` is request/response and timeout-bound.
-- Runtime adapters: `web`, `android`, `ios`, `bare`.
-- Canonical plugins: `core.health`, `core.discovery`, `core.permissions`, and
-  `vendor.media` (reference for out-of-band binary transfer).
-
-### Loopback server + cookie auth
-
-One loopback HTTP+WS server (`core/server/static-file-server.ts`) serves the
-web app at `/`, the media files mounted by plugins, and the framed-protocol
-WebSocket socket. On device it binds `127.0.0.1` on an ephemeral port and every
-request is gated by a per-session token:
-
-- The shell injects `window.__ekrooh = { token }` (plus `window.BareShell` as
-  a presence marker) before the page loads.
-- The page exchanges it for a `bare_session` cookie via `POST /login`
-  (`HttpOnly; SameSite=Lax; Path=/`).
-- The cookie then authorizes `<img>`/`<video>`/`fetch` and the WebSocket
-  upgrade. `X-Bare-Token`/`?token=` remain as a fallback for non-browser
-  clients.
-- The worklet writes `{ origin, port, token }` to `handoff.json` in the
-  sandbox dir the host passed via `Worklet.Configuration.assets`; the host
-  reads it, injects the token, and loads `http://127.0.0.1:<port>/index.html`.
-
-The dev backend runs the same bundle with auth off on a fixed port
-(`ws://localhost:8080`), so browser dev needs no token.
-
-### Media (out-of-band bytes)
-
-Images/videos never cross the wire protocol (the frame cap is 16 MiB).
-`vendor.media` demonstrates the intended pattern: the host picks/captures a
-file natively and returns its path; the worklet mounts it on the loopback
-server and returns a URL. The web layer loads the URL directly (same-origin,
-cookie-authenticated) — one serving implementation for every runtime. The
-Android reference host wires a real native picker/camera; the iOS reference
-host's real picker/camera is part of the iOS parity worklist.
-
-## Scripts
-
-| Script                       | Purpose                                                |
-| ---------------------------- | ------------------------------------------------------ |
-| `npm run check`              | Format + lint + type-check (`vp check`)                |
-| `npm run typecheck`          | `tsc --noEmit` only                                    |
-| `npm run test`               | Unit tests + Playwright e2e                            |
-| `npm run test:unit`          | Unit tests (vitest)                                    |
-| `npm run test:e2e:web`       | Playwright e2e                                         |
-| `npm run dev`                | Vite dev server + Bare backend (watch restart)         |
-| `npm run dev:mock`           | Vite with mock transport                               |
-| `npm run dev:ws`             | Vite only (backend started separately)                 |
-| `npm run build`              | Core bundle + web assets for the Android app           |
-| `npm run build:core`         | Bundle `core/main.core.ts` with esbuild                |
-| `npm run build:web`          | Build `examples/web` into the Android app's assets     |
-| `npm run build:ios`          | iOS app inputs (addons, bundle, web assets) + xcodegen |
-| `npm run prebuilds`          | Fetch Bare Kit prebuilds (requires `gh`)               |
-| `npm run test:ios`           | XCTest + UI test on the iOS simulator                  |
-| `npm run playwright:install` | Download Chromium into `.playwright-browsers/`         |
-| `npm run smoke:loopback`     | Smoke-test the unified loopback server under `bare`    |
+Binary frame: `version` (1 byte), `type` (1 byte), `headerLen` (2 bytes, BE),
+`payloadLen` (3 bytes, BE), `header` (UTF-8 JSON), `payload` (optional).
+Implemented by `MessageProtocol` in `core/messages` (`wire-codec.ts`).
+
+Header types: `DISPATCH`, `INVOKE_REQUEST`, `INVOKE_RESPONSE` (responses echo
+`requestId`). `dispatch` is fire-and-forget; `invoke` is request/response and
+timeout-bound.
+
+## Plugins
+
+Core ships no product features. Plugin IDs are `vendor.plugin`; events are
+plugin-local (`health.ping`). Runtime adapters: `web`, `android`, `ios`, `bare`.
+Canonical plugins are listed under Repository layout.
+
+Media never crosses the wire (frame cap 16 MiB). `vendor.media` is the reference
+for out-of-band bytes: the host picks or captures a file natively, the worklet
+mounts it on the loopback server and returns a URL, and the web layer loads that
+URL with cookie auth.
+
+## Loopback server and auth
+
+One server (`core/server/static-file-server.ts`) serves the web app at `/`, plugin
+media mounts, and the WebSocket upgrade. On device it binds `127.0.0.1` on an
+ephemeral port. Every request is gated by a per-session token:
+
+1. The shell injects `window.__ekrooh = { bootstrap }`, a single-use nonce (never the raw token).
+2. The page calls `POST /login` with the nonce and receives a
+   `bare_session_<port>` cookie (`HttpOnly; SameSite=Strict; Path=/`). The port
+   in the name keeps two loopback servers in one cookie store apart. The raw
+   token is never a login credential.
+3. The cookie authorizes `<img>`, `<video>`, `fetch`, and the WS upgrade.
+   Non-browser clients send `X-Bare-Token`. There is no `?token=` fallback
+   (see `docs/adr/0003-loopback-auth-surface.md`).
+
+Only the bootstrap mount at `/` is public pre-auth. The worklet writes
+`{ origin, port, bootstrap }` to `handoff.json` in the host's sandbox dir (never
+the session token); the host loads `http://127.0.0.1:<port>/index.html` and
+deletes the file.
+
+Every request must also target the bound loopback server (`Host`), and a page
+`Origin` must be that server or an explicitly allowed one, in every mode.
+
+The dev backend (`mode=dev`) runs the same bundle with auth off on
+`ws://localhost:8080`, allowing the Vite dev origin (`origin=` tokens).
 
 ## Testing
 
-- **Unit** — vitest (`vp test`) for the protocol codec, plugin router, RPC
-  messenger, and transports; JUnit for the Kotlin host; XCTest for the Swift
-  host.
-- **Type check** — `tsc --noEmit` (part of `vp check`).
-- **Integration** — Playwright e2e against the mock transport exercising the
-  real binary protocol (`npm run test:e2e:web`). Browsers resolve through
-  `scripts/playwright-local-browsers.mjs`, which pins `PLAYWRIGHT_BROWSERS_PATH`
-  to the repo-local `.playwright-browsers/`.
-- **Native end-to-end** — `npm run test:ios` runs the Swift host's XCTest suite
-  plus a UI test against the reference app on the iOS simulator (discovery
-  summary, Ping / Payload Echo / Roundtrip / Storage permission).
+- Unit: vitest (`vp test`) for the codec, router, RPC messenger, transports;
+  JUnit for the Kotlin host; XCTest for the Swift host.
+- Type check: `tsc --noEmit`, part of `vp check`.
+- Integration: Playwright e2e on the mock transport (`npm run test:e2e:web`).
+  Browsers resolve through `scripts/playwright-local-browsers.mjs` into `.playwright-browsers/`.
+- Native: `npm run test:ios` runs the Swift XCTest suite and a UI test on the simulator.
+
+## Commands
+
+Canonical list: [`AGENTS.md`](AGENTS.md#canonical-commands). Common ones:
+
+| Command                      | Purpose                                            |
+| ---------------------------- | -------------------------------------------------- |
+| `vp check`                   | Format, lint, type-check                           |
+| `vp test`                    | Unit tests                                         |
+| `npm run test`               | Unit + Playwright e2e                              |
+| `npm run dev`                | Vite dev server + Bare backend (watch restart)     |
+| `npm run dev:mock`           | Vite with mock transport                           |
+| `npm run build:core`         | Bundle `core/main.core.ts` (esbuild)               |
+| `npm run build:web`          | Build `examples/web` into the Android app's assets |
+| `npm run build:ios`          | iOS inputs (addons, bundle, web assets, xcodegen)  |
+| `npm run prebuilds`          | Fetch Bare Kit prebuilds (requires `gh`)           |
+| `npm run playwright:install` | Download Chromium into `.playwright-browsers/`     |
+| `npm run smoke:loopback`     | Smoke-test the loopback server under `bare`        |
 
 ## Android build
 
-Prerequisites: Android SDK (`local.properties` with `sdk.dir=...`) and Bare Kit
-prebuilds.
+Needs the Android SDK (`local.properties` with `sdk.dir=...`) and Bare Kit prebuilds.
 
 ```bash
-npm ci
-npm run prebuilds   # fetches prebuilds into prebuilds/ (gitignored)
+vp install
+npm run prebuilds
 npm run build       # core bundle + web assets
 ./gradlew :examples:android-app:assembleDebug
 ```
 
-`./gradlew build` additionally runs the host library's JUnit tests.
+`./gradlew build` also runs the host library's JUnit tests.
 
 ### Consuming the published AAR
 
-`io.github.anderscan.ekrooh:bare-host` is published to **Maven Central** (no auth) on the same
-tag as the npm package — pin it to your `@ekrooh/bare` version:
+`io.github.anderscan.ekrooh:bare-host` is on Maven Central (no credentials).
+Pin it to the same version as `@ekrooh/bare`:
 
 ```gradle
-repositories {
-  mavenCentral() // default in modern Gradle; no credentials needed
-}
-
 dependencies {
   implementation "io.github.anderscan.ekrooh:bare-host:<version>"
 }
 ```
 
-GitHub Packages (`maven.pkg.github.com/AndersCan/ekrooh`) remains a fallback
-but requires a `read:packages` PAT — prefer Maven Central.
+GitHub Packages is a fallback that requires a `read:packages` token. Prefer Maven Central.
 
 ## iOS build
 
-Prerequisites: Xcode (macOS), Bare Kit prebuilds, and `xcodegen`.
+Needs Xcode, Bare Kit prebuilds, and `xcodegen`.
 
 ```bash
-npm ci
-npm run prebuilds   # fetches prebuilds/ios/BareKit.xcframework too
-npm run build:ios   # addons/, Resources/, and ios-app.xcodeproj
-npm run test:ios    # xcodebuild test on the simulator
+vp install
+npm run prebuilds   # also fetches prebuilds/ios/BareKit.xcframework
+npm run build:ios
+npm run test:ios
 ```
 
-`npm run test:ios` runs the Swift host's XCTest suite (hosted by the reference
-app) plus a UI test that verifies the health-checks page end to end.
-
-## Asset hygiene
+## Notes
 
-- Vite cleans hashed `examples/android-app/src/main/assets/assets/main-*.{js,css}`
-  before rebuilding web assets.
-- Treat files under `examples/android-app/src/main/assets/` as build output,
-  not source.
+- Treat `examples/android-app/src/main/assets/` as build output. Vite clears
+  hashed `assets/main-*.{js,css}` before rebuilding.

package/dist/{index-DjulYFJL.d.mts → index-BkwUzwVt.d.mts}

@@ -1,4 +1,3 @@
-//#region core/messages/constants.d.ts
 declare const VERSION = 1;
 declare const MessageType: {
   readonly ENVELOPE: 1;
@@ -25,8 +24,6 @@ declare const MAX_HEADER_BYTES = 65535;
 /** Upper bound on one encoded frame. Large binary transfers are a plugin-level
  * concern (out-of-band handles), not an in-band payload. */
 declare const MAX_FRAME_BYTES: number;
-//#endregion
-//#region core/messages/types.d.ts
 /** Decoded binary frame (version byte stripped); used by WebSocket and other transports. */
 interface WireMessage {
   type: MessageTypeValue;
@@ -126,6 +123,12 @@ type MessageHeader = PluginHeader | HostCapabilitiesQueryHeader | HostCapabiliti
 interface PluginContext {
   runtime: RuntimeTarget;
   payload: Uint8Array;
+  /** The registry-validated sender of the envelope. Always equals the
+   * wire `pluginId` once the router has matched a manifest — adapters can trust
+   * it without re-validating against the wire. */
+  sender?: {
+    pluginId: string;
+  };
 }
 interface PluginRuntimeAdapter {
   dispatch?: (event: string, args: Record<string, unknown> | undefined, context: PluginContext) => void | Promise<void>;
@@ -138,8 +141,6 @@ interface PluginManifest {
   events?: string[];
   runtimes: Partial<Record<RuntimeTarget, PluginRuntimeAdapter>>;
 }
-//#endregion
-//#region core/messages/errors.d.ts
 /** Success half of an `Either` tuple. */
 declare function ok<T>(result: T): [null, T];
 /** Failure half of an `Either` tuple. Accepts a canonical error code or any
@@ -153,8 +154,6 @@ declare function coerceErrorCode(code: string | undefined): ErrorCode;
 type Ok<T> = [null, T];
 type Err = [CoreError, null];
 type PluginResult<T> = Either<CoreError, T>;
-//#endregion
-//#region core/messages/rpc-messenger.d.ts
 type DistributiveOmit<T, K extends keyof any> = T extends any ? Omit<T, K> : never;
 type InternalDispatchRequest = (PluginDispatchHeader & {
   requestId: string;
@@ -169,8 +168,6 @@ interface ProtocolMessenger {
   handleIncoming(header: MessageHeader): void;
 }
 declare function createProtocolMessenger(send: (request: InternalDispatchRequest, payload?: Uint8Array | ArrayBuffer | string | null) => void): ProtocolMessenger;
-//#endregion
-//#region core/messages/plugin-kernel.d.ts
 interface PluginRegistry {
   register(plugin: PluginManifest): void;
   resolve(pluginId: string, runtime: RuntimeTarget): PluginManifest['runtimes'][RuntimeTarget] | undefined;
@@ -188,7 +185,27 @@ interface PluginRouter {
 }
 type PluginRouterOptions = {
   delegateToHost?: (header: PluginInvokeRequestHeader, payload: Uint8Array) => Promise<PluginInvokeResponseHeader | null>;
-  logger?: Pick<Console, 'warn' | 'error'>;
+  /** Host-registered capabilities (from `HOST_CAPABILITIES_RESPONSE`).
+   * Delegation to the host is only permitted for events the host announces
+   * here — a deny-by-default allowlist. When omitted or empty, no
+   * host-delegated invokes are allowed. */
+  getHostCapabilities?: () => Promise<CapabilityDescriptor[]>;
+  logger?: Pick<Console, 'warn' | 'error' | 'debug'>;
+  /** Global cap on calls routed at once (running or queued behind a serial
+   * plugin). A call over the cap is answered with a `TRANSPORT_ERROR` instead
+   * of being queued, so a flood cannot grow memory without bound. Defaults to
+   * `DEFAULT_MAX_INFLIGHT`. */
+  maxInflight?: number;
+  /** Plugin ids whose calls must run one at a time, in arrival order. Every
+   * other plugin's calls run concurrently, so a slow call never delays them. */
+  serialPlugins?: readonly string[];
+  /** How long (ms) the host's announced capabilities are reused before the
+   * host is asked again. Delegating an invoke otherwise costs an IPC round
+   * trip per call. Capabilities the host adds are still picked up within
+   * `NEGATIVE_REFRESH_MS`, and a failed delegation drops the cache at once.
+   * `0` disables caching (ask the host on every delegation). Defaults to
+   * `DEFAULT_HOST_CAPABILITIES_TTL_MS`. */
+  hostCapabilitiesTtlMs?: number;
 };
 declare function createPluginRouter(registry: PluginRegistry, runtime: RuntimeTarget, options?: PluginRouterOptions): PluginRouter;
 interface PluginBus {
@@ -196,28 +213,29 @@ interface PluginBus {
   invoke<TResult>(envelope: InvokeEnvelope<string, Record<string, unknown>, TResult>): Promise<Either<CoreError, TResult>>;
 }
 declare function createPluginBus(messenger: ProtocolMessenger): PluginBus;
-//#endregion
-//#region core/messages/wire-codec.d.ts
 type Encoder = (str: string) => Uint8Array;
 type Decoder = (bytes: Uint8Array) => string;
 interface ProtocolOptions {
   encode?: Encoder;
   decode?: Decoder;
   allowUnknownTypes?: boolean;
-  /** Override the default {@link MAX_FRAME_BYTES} cap. */
+  /** Override the default {@link MAX_FRAME_BYTES} cap. Clamped to a sane
+   * range: it must be large enough to hold the largest legal header, and never
+   * larger than {@link MAX_FRAME_BYTES}. `Infinity`/`NaN`/negative inputs
+   * collapse to the defaults so a caller cannot disable the decode-side cap. */
   maxFrameBytes?: number;
 }
 declare class MessageProtocol {
   private encodeStr;
   private decodeStr;
   private allowUnknownTypes;
-  private maxFrameBytes;
+  /** Resolved, clamped frame cap. Public so callers/tests can inspect the
+   * effective limit after clamping. */
+  readonly maxFrameBytes: number;
   constructor(options?: ProtocolOptions);
   encode(type: MessageTypeValue, header: MessageHeader, payload?: Uint8Array | ArrayBuffer | string | null): Uint8Array;
   decode(data: ArrayBuffer | Uint8Array): WireMessage;
 }
-//#endregion
-//#region core/messages/define-plugin.d.ts
 /**
  * One event's wire identity and type shape — the single source of truth for
  * the manifest `events` list, the generated handler table, and the typed
@@ -249,13 +267,69 @@ declare function definePlugin<const TSpecs extends Record<string, EventSpec<any,
 declare function invokeEvent<TSpec extends EventSpec<any, any>>(spec: TSpec, args: TSpec['args'], payload?: Uint8Array | ArrayBuffer | string | null, timeoutMs?: number): InvokeEnvelope<TSpec['name'], TSpec['args'], TSpec['result']>;
 /** Typed builder: a dispatch envelope for a spec's event. */
 declare function dispatchEvent<TSpec extends EventSpec<any, any>>(spec: TSpec, args: TSpec['args'], payload?: Uint8Array | ArrayBuffer | string | null): DispatchEnvelope<TSpec['name'], TSpec['args']>;
-//#endregion
-//#region core/messages/create-bare-runtime-context.d.ts
 interface BareRuntimeContext {
   protocol: MessageProtocol;
   pluginRegistry: PluginRegistry;
   pluginRouter: PluginRouter;
 }
 declare function createBareRuntimeContext(plugins?: PluginManifest[], routerOptions?: PluginRouterOptions): BareRuntimeContext;
-//#endregion
-export { MAX_HEADER_BYTES as $, CapabilityDescriptor as A, InvokeEnvelope as B, createProtocolMessenger as C, coerceErrorCode as D, PluginResult as E, ErrorCodeOrString as F, PluginInvokeRequestHeader as G, PluginContext as H, HostCapabilitiesQueryHeader as I, PluginRuntimeAdapter as J, PluginInvokeResponseHeader as K, HostCapabilitiesResponseHeader as L, CoreErrorWire as M, DispatchEnvelope as N, err as O, Either as P, MAX_FRAME_BYTES as Q, HostInvokeRequestHeader as R, ProtocolMessenger as S, Ok as T, PluginDispatchHeader as U, MessageHeader as V, PluginHeader as W, WireMessage as X, RuntimeTarget as Y, ErrorCode as Z, createPluginBus as _, InvokeHandler as a, DispatchRequest as b, invokeEvent as c, MessageProtocol as d, MessageType as et, ProtocolOptions as f, PluginRouterOptions as g, PluginRouter as h, EventSpec as i, CoreError as j, ok as k, Decoder as l, PluginRegistry as m, createBareRuntimeContext as n, VERSION as nt, definePlugin as o, PluginBus as p, PluginManifest as q, DispatchHandler as r, dispatchEvent as s, BareRuntimeContext as t, MessageTypeValue as tt, Encoder as u, createPluginRegistry as v, Err as w, InvokeRequest as x, createPluginRouter as y, HostInvokeResponseHeader as z };
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+type LogSource = 'backend' | 'web';
+interface LogEntry {
+  /** Monotonic sequence assigned by the store on append. */
+  seq: number;
+  /** Epoch millisecond timestamp. */
+  ts: number;
+  level: LogLevel;
+  source: LogSource;
+  tag?: string;
+  message: string;
+}
+interface LogViewOptions {
+  /** Most-recent N matching entries. Omit for all. */
+  tail?: number;
+  level?: LogLevel;
+  source?: LogSource;
+}
+interface LogStore {
+  /** Maximum number of entries retained (oldest dropped first). */
+  readonly capacity: number;
+  /** Appends an entry, assigning its `seq`. */
+  append(entry: Omit<LogEntry, 'seq'>): void;
+  /** Returns a snapshot of matching entries, newest-last, bounded by `tail`. */
+  view(options?: LogViewOptions): LogEntry[];
+  /** Empties the buffer. Returns the number of entries dropped. */
+  clear(): number;
+}
+type WebConsoleCaptureOptions = {
+  /** Ingest endpoint. Same-origin `/logs` on the loopback server. */
+  endpoint?: string;
+  /** Max entries buffered before a flush is issued. */
+  flushThreshold?: number;
+  /** Flush interval (ms); pass 0 to disable the interval. */
+  flushIntervalMs?: number;
+  /** Injectable ingest function (defaults to a same-origin POST fetch). */
+  ingest?: (payload: {
+    source: 'web';
+    entries: Array<{
+      level: LogLevel;
+      tag?: string;
+      message: string;
+    }>;
+  }) => void | Promise<void>;
+};
+type WebConsoleCapture = {
+  /** Flushes any buffered entries immediately (fire-and-forget). */
+  flush(): void;
+  /** Restores the original console methods captured at install time. */
+  restore(): void;
+};
+/**
+ * Web-side console capture: wraps the console methods, buffers formatted
+ * entries, and flushes them as a batch to the loopback `POST /logs` ingest
+ * route with `source: 'web'` (same-origin fetch). Every step is try/catch-
+ * wrapped so the seam can never break the app. Skip installing in mock mode,
+ * where there is no loopback backend to ingest into.
+ */
+declare function installWebConsoleCapture(options?: WebConsoleCaptureOptions): WebConsoleCapture;
+export { PluginRuntimeAdapter as $, Ok as A, ErrorCodeOrString as B, createPluginRegistry as C, ProtocolMessenger as D, InvokeRequest as E, CapabilityDescriptor as F, InvokeEnvelope as G, HostCapabilitiesResponseHeader as H, CoreError as I, PluginDispatchHeader as J, MessageHeader as K, CoreErrorWire as L, coerceErrorCode as M, err as N, createProtocolMessenger as O, ok as P, PluginManifest as Q, DispatchEnvelope as R, createPluginBus as S, DispatchRequest as T, HostInvokeRequestHeader as U, HostCapabilitiesQueryHeader as V, HostInvokeResponseHeader as W, PluginInvokeRequestHeader as X, PluginHeader as Y, PluginInvokeResponseHeader as Z, ProtocolOptions as _, LogStore as a, MessageType as at, PluginRouter as b, DispatchHandler as c, definePlugin as d, RuntimeTarget as et, dispatchEvent as f, MessageProtocol as g, Encoder as h, LogSource as i, MAX_HEADER_BYTES as it, PluginResult as j, Err as k, EventSpec as l, Decoder as m, LogEntry as n, ErrorCode as nt, BareRuntimeContext as o, MessageTypeValue as ot, invokeEvent as p, PluginContext as q, LogLevel as r, MAX_FRAME_BYTES as rt, createBareRuntimeContext as s, VERSION as st, installWebConsoleCapture as t, WireMessage as tt, InvokeHandler as u, PluginBus as v, createPluginRouter as w, PluginRouterOptions as x, PluginRegistry as y, Either as z };

package/dist/index.d.mts

@@ -1,2 +1,2 @@
-import { $ as MAX_HEADER_BYTES, A as CapabilityDescriptor, B as InvokeEnvelope, C as createProtocolMessenger, D as coerceErrorCode, E as PluginResult, F as ErrorCodeOrString, G as PluginInvokeRequestHeader, H as PluginContext, I as HostCapabilitiesQueryHeader, J as PluginRuntimeAdapter, K as PluginInvokeResponseHeader, L as HostCapabilitiesResponseHeader, M as CoreErrorWire, N as DispatchEnvelope, O as err, P as Either, Q as MAX_FRAME_BYTES, R as HostInvokeRequestHeader, S as ProtocolMessenger, T as Ok, U as PluginDispatchHeader, V as MessageHeader, W as PluginHeader, X as WireMessage, Y as RuntimeTarget, Z as ErrorCode, _ as createPluginBus, a as InvokeHandler, b as DispatchRequest, c as invokeEvent, d as MessageProtocol, et as MessageType, f as ProtocolOptions, g as PluginRouterOptions, h as PluginRouter, i as EventSpec, j as CoreError, k as ok, l as Decoder, m as PluginRegistry, n as createBareRuntimeContext, nt as VERSION, o as definePlugin, p as PluginBus, q as PluginManifest, r as DispatchHandler, s as dispatchEvent, t as BareRuntimeContext, tt as MessageTypeValue, u as Encoder, v as createPluginRegistry, w as Err, x as InvokeRequest, y as createPluginRouter, z as HostInvokeResponseHeader } from "./index-DjulYFJL.mjs";
-export { BareRuntimeContext, CapabilityDescriptor, CoreError, CoreErrorWire, Decoder, DispatchEnvelope, DispatchHandler, DispatchRequest, Either, Encoder, Err, ErrorCode, ErrorCodeOrString, EventSpec, HostCapabilitiesQueryHeader, HostCapabilitiesResponseHeader, HostInvokeRequestHeader, HostInvokeResponseHeader, InvokeEnvelope, InvokeHandler, InvokeRequest, MAX_FRAME_BYTES, MAX_HEADER_BYTES, MessageHeader, MessageProtocol, MessageType, MessageTypeValue, Ok, PluginBus, PluginContext, PluginDispatchHeader, PluginHeader, PluginInvokeRequestHeader, PluginInvokeResponseHeader, PluginManifest, PluginRegistry, PluginResult, PluginRouter, PluginRouterOptions, PluginRuntimeAdapter, ProtocolMessenger, ProtocolOptions, RuntimeTarget, VERSION, WireMessage, coerceErrorCode, createBareRuntimeContext, createPluginBus, createPluginRegistry, createPluginRouter, createProtocolMessenger, definePlugin, dispatchEvent, err, invokeEvent, ok };
+import { $ as PluginRuntimeAdapter, A as Ok, B as ErrorCodeOrString, C as createPluginRegistry, D as ProtocolMessenger, E as InvokeRequest, F as CapabilityDescriptor, G as InvokeEnvelope, H as HostCapabilitiesResponseHeader, I as CoreError, J as PluginDispatchHeader, K as MessageHeader, L as CoreErrorWire, M as coerceErrorCode, N as err, O as createProtocolMessenger, P as ok, Q as PluginManifest, R as DispatchEnvelope, S as createPluginBus, T as DispatchRequest, U as HostInvokeRequestHeader, V as HostCapabilitiesQueryHeader, W as HostInvokeResponseHeader, X as PluginInvokeRequestHeader, Y as PluginHeader, Z as PluginInvokeResponseHeader, _ as ProtocolOptions, at as MessageType, b as PluginRouter, c as DispatchHandler, d as definePlugin, et as RuntimeTarget, f as dispatchEvent, g as MessageProtocol, h as Encoder, it as MAX_HEADER_BYTES, j as PluginResult, k as Err, l as EventSpec, m as Decoder, nt as ErrorCode, o as BareRuntimeContext, ot as MessageTypeValue, p as invokeEvent, q as PluginContext, rt as MAX_FRAME_BYTES, s as createBareRuntimeContext, st as VERSION, t as installWebConsoleCapture, tt as WireMessage, u as InvokeHandler, v as PluginBus, w as createPluginRouter, x as PluginRouterOptions, y as PluginRegistry, z as Either } from "./index-BkwUzwVt.mjs";
+export { BareRuntimeContext, CapabilityDescriptor, CoreError, CoreErrorWire, Decoder, DispatchEnvelope, DispatchHandler, DispatchRequest, Either, Encoder, Err, ErrorCode, ErrorCodeOrString, EventSpec, HostCapabilitiesQueryHeader, HostCapabilitiesResponseHeader, HostInvokeRequestHeader, HostInvokeResponseHeader, InvokeEnvelope, InvokeHandler, InvokeRequest, MAX_FRAME_BYTES, MAX_HEADER_BYTES, MessageHeader, MessageProtocol, MessageType, MessageTypeValue, Ok, PluginBus, PluginContext, PluginDispatchHeader, PluginHeader, PluginInvokeRequestHeader, PluginInvokeResponseHeader, PluginManifest, PluginRegistry, PluginResult, PluginRouter, PluginRouterOptions, PluginRuntimeAdapter, ProtocolMessenger, ProtocolOptions, RuntimeTarget, VERSION, WireMessage, coerceErrorCode, createBareRuntimeContext, createPluginBus, createPluginRegistry, createPluginRouter, createProtocolMessenger, definePlugin, dispatchEvent, err, installWebConsoleCapture, invokeEvent, ok };