@aibranch/llm-meta-widget 0.10.1 → 0.11.1

package/README.md

@@ -12,13 +12,13 @@ npm for any host, and in a Rails gem whose helper serves it for you.
 
 **No** Devise, DB migrations, ChatManager, or PromptNavigator. The gem adds only `rails >= 8.0` as a runtime dep — so hosts that haven't bumped to 8.1 can adopt it without a Rails upgrade — and hosts that do not use Rails do not need the gem.
 
-## What you need first
+## Requirement
 
-The widget is a browser front end: it needs something to answer the chat. That
-can be **[llm_meta_server](https://github.com/pubannotation)** — a hub that
-holds provider credentials and streams responses back — or **an Ollama**,
-which the widget talks to directly with no server component of ours in
-between.
+The widget is a browser front end: it needs something to answer the chat. One
+option is **[llm_meta_server](https://github.com/pubannotation)**, a hub that
+holds provider credentials and streams responses back. The other is **an
+Ollama**, which the widget talks to directly, with no server component of ours
+in between.
 
 Those are separate from where tools come from. A hub also registers MCP tools
 (Class 1 below), and you can point at one for tools while a local Ollama
@@ -32,29 +32,39 @@ step, no Node at runtime.
 |---|---|---|
 | A browser with custom elements + ES modules | any current | always |
 | An llm_meta_server **or** an Ollama | any | always — something has to answer the chat |
-| Ruby | >= 3.2 | only if you install the gem |
-| Rails | >= 8.0 (8.1 not required) | only if you install the gem |
 
-## Two ways to add the widget — choose one
+Nothing is required of your server: the widget runs in the browser, and your
+page only has to send the file and write one tag. The Rails gem is one
+convenient way to do that, not a requirement — it needs Ruby >= 3.2 and
+Rails >= 8.0, and only if you choose it.
 
-You do **not** need both. Pick the row that matches your app, then read only
-that section.
+## Installation — choose one
 
-| Your app | What you add | What you write |
+You need only one. Find the row whose condition matches your app, then read only
+that option's section.
+
+| Option | Use it when | What you do |
 |---|---|---|
-| **Rails** | the gem, one line in your `Gemfile` | one helper call in a view. The helper writes the `<llm-meta-widget>` tag for you, so you never write that tag yourself |
-| **Anything else** — Python, Go, PHP, plain HTML… | one `<script>` tag from the CDN, or an npm dependency you bundle | the `<llm-meta-widget>` tag yourself |
+| **gem** | your app is Rails | add one line to your `Gemfile`, then make one helper call in a view. The helper writes the `<llm-meta-widget>` tag for you, so you never write that tag yourself |
+| **npm** | your app already builds JavaScript — Vite, webpack, esbuild, Next.js… | install the package, import it once at your entry point, and write the `<llm-meta-widget>` tag yourself |
+| **CDN** | neither of the above applies — Python, Go, PHP, plain HTML… | add one `<script>` tag and write the `<llm-meta-widget>` tag yourself. No install, no build step |
+
+All three load the same file and run the same widget. The first two pin the
+version for you — Bundler for the gem, your lockfile for npm — which is why they
+come first here. The CDN pins only a range written into a URL, so the last row
+trades that check for needing nothing installed.
 
-Both ways load the same file and run the same widget.
+## Option 1. gem (when your app is Rails)
 
-## Rails apps: install the gem
+**Not using Rails?** Skip to Option 2 if your app builds JavaScript, or to
+Option 3 if it does not.
 
 ```ruby
 # Gemfile
-gem "llm_meta_widget", "~> 0.7"
+gem "llm_meta_widget", "~> 0.11.1"
 ```
 
-```
+```bash
 bundle install
 ```
 
@@ -83,7 +93,7 @@ simpler way to deliver and configure the widget:
 - **The defaults are set for you**, so your view names only the options you
   want to change.
 
-## Rails apps: a minimal working example
+### A minimal working example for Rails apps
 
 Put this on any view — a fresh `pages/demo.html.erb` is fine:
 
@@ -91,75 +101,19 @@ Put this on any view — a fresh `pages/demo.html.erb` is fine:
 <h1>Demo</h1>
 
 <%= llm_meta_widget(llm_url:  "https://your-meta-server.example",
-                    model:    "qwen3-6-35b-fast",
+                    model:    "gpt-oss-120b",
                     greeting: "Hi — ask me anything about this page.") %>
 ```
 
 Start the app, open that page, and click the round toggle at the bottom right.
-**Success looks like:** a panel opens showing your greeting, you type "hello",
-the role label turns into a spinning gear reading "Working…", and the reply
-streams in.
-
-If the panel opens but nothing comes back, it is almost always CORS. The hub
-must list your app's origin in its `CORS_ORIGINS` environment variable for
-the `/api/*` resource, because the widget calls the hub **from the visitor's
-browser**, not from your server. Open the browser console: a blocked request
-says so explicitly.
-
-Two more things worth knowing before you go further:
-
-- `llm_url` must be reachable from your visitors' browsers, not just from
-  your server. `localhost` works only while you are the visitor — which is
-  fine when each visitor runs their own Ollama.
-- The model name is the hub's name for it (`GET /api/llms` lists them), not
-  the provider's.
+What success looks like, and what to check when nothing comes back, is in
+"When it does not answer" below — the causes are the same for every route.
 
 Once that works, the widget can talk, but it cannot *do* anything yet. To let the
 LLM act on your page or call your own services, declare tools using any of the
 **three tool classes** below.
 
-## Non-Rails hosts: write the element yourself
-
-**If your app is Rails, you can skip this section.** The gem already does
-everything described here: its helper writes this tag for you and its engine
-sends this file. Read on if your app is not Rails — or if you use Rails but
-prefer the CDN to the gem, which the `element_path:` option allows.
-
-The widget is a custom element in a single self-contained ES module, so a host
-that is not Rails needs no gem, no template engine and no asset pipeline — two
-lines of HTML:
-
-```html
-<script type="module" src="https://cdn.jsdelivr.net/npm/@aibranch/llm-meta-widget@0.8"></script>
-<llm-meta-widget llm-url="https://your-meta-server.example"
-                 model="qwen3-6-35b-fast"
-                 greeting="Hi — ask me anything about this page."></llm-meta-widget>
-```
-
-This is the same configuration as the Rails example above, written in HTML
-instead of ERB. Both produce the same widget, so the advice in that section
-— CORS, a reachable `llm_url`, the hub's name for the model — applies here
-too.
-
-**`@0.8` is a version range, and it stops at 0.8.x on purpose.** You receive bug
-fixes without editing your page, and a release that breaks your page cannot
-arrive on its own.
-
-Moving to 0.9 is therefore a change you make yourself. Read
-[CHANGELOG.md](CHANGELOG.md) before you do, because this is where what your page
-must provide can change. For example, 0.8.0 changed the shape of
-`window.aiState`. A page that used the new shape while still loading `@0.7`
-would have shown an error string in place of every value, with no other warning.
-
-A Rails app is protected from that mismatch, because the `Gemfile` will not
-resolve a widget version the page cannot use. A page that loads the widget from
-the CDN has no such check, so the version you write in that URL is the only
-protection you have.
-
-Nothing else is needed: the stylesheets and the markdown renderer are bundled
-in, and the element injects its own styles. The host serves no CSS and no JS.
-
-### If you have a JS build pipeline, install it instead
+## Option 2. npm (if you bundle your JavaScript)
 
 Vite, webpack, esbuild, Next.js, SvelteKit, Astro — if your app already builds
 JavaScript, take the widget as a dependency rather than a script tag:
@@ -174,8 +128,8 @@ npm install @aibranch/llm-meta-widget
 import "@aibranch/llm-meta-widget";
 ```
 
-Then write the `<llm-meta-widget>` tag exactly as above — same attributes, same
-behaviour.
+Then write the `<llm-meta-widget>` tag yourself — see "Writing the element
+yourself" below for the tag and its attributes.
 
 **Why do this, when the script tag is only one line?** Because your build then
 checks the version for you. The version is pinned in your lockfile and installed by `npm ci`
@@ -185,15 +139,57 @@ that nothing checks. That matters most at a breaking release: 0.8.0 changed the
 shape of `window.aiState`, and a lockfile makes the upgrade a deliberate, visible
 step instead of a URL someone edits.
 
-The only cost is that this path needs a build pipeline. The CDN path needs none,
-which is why it is listed first.
+The only cost is that this path needs a build pipeline. If your app does not
+build JavaScript, the CDN route below needs none.
 
-Four ways to get that one file, in descending order of convenience:
+## Option 3. CDN
 
-- **the CDN**, as above — `@aibranch/llm-meta-widget` on npm, no path needed
-  because the package's `main` is the bundle;
-- **npm install plus your own bundler**, as above — the same package, resolved
-  through `exports` and pinned by your lockfile;
+This is the shortest route and it works anywhere — Python, Go, PHP, plain
+HTML, or Rails if you would rather not add the gem (the `element_path:` option
+allows that). It needs no install, no build step and no Node at runtime.
+
+The widget is a custom element in a single self-contained ES module, so the
+whole integration is two lines of HTML:
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@aibranch/llm-meta-widget@0.11"></script>
+<llm-meta-widget llm-url="https://your-meta-server.example"
+                 model="gpt-oss-120b"
+                 greeting="Hi — ask me anything about this page."></llm-meta-widget>
+```
+
+**`@0.11` is a version range, and it stops at 0.11.x on purpose.** You receive
+bug fixes without editing your page, and a release that breaks your page cannot
+arrive on its own.
+
+Moving to 0.12 is therefore a change you make yourself. Read
+[CHANGELOG.md](CHANGELOG.md) before you do, because this is where what your page
+must provide can change. For example, 0.10.0 changed how the widget finds a page
+card: by media type rather than by element id. A page that declared its card the
+new way while still loading `@0.9` lost every tool, prompt and resource it had
+declared. Nothing failed, anywhere. The CHANGELOG entry for 0.10.0 describes it.
+
+A Rails app is protected from that mismatch, because the `Gemfile` will not
+resolve a widget version the page cannot use. A page that loads the widget from
+the CDN has no such check, so the version you write in that URL is the only
+protection you have.
+
+Nothing else is needed: the stylesheets and the markdown renderer are bundled
+in, and the element injects its own styles. The host serves no CSS and no JS.
+
+## Writing the element yourself
+
+Both the npm and CDN routes end the same way: your page writes one
+`<llm-meta-widget>` tag. This section is the reference for that tag, whichever
+route brought you here. (Rails users can skip it — the helper writes the tag.)
+
+The tag needs one file: the bundled custom element. Four ways to get it, in
+descending order of convenience:
+
+- **the CDN** — `@aibranch/llm-meta-widget` on npm, no path needed because the
+  package's `main` is the bundle;
+- **npm install plus your own bundler** — the same package, resolved through
+  `exports` and pinned by your lockfile;
 - **the gem**, which serves the identical file at
   `/llm_meta_widget_assets/llm-meta-widget.js` for Rails hosts, and is what the
   `llm_meta_widget` helper points at;
@@ -202,9 +198,8 @@ Four ways to get that one file, in descending order of convenience:
 
 Going without the gem removes the Rails parts: the helper and the partial. It
 does not change what your page itself must provide, because those parts belong to
-the page, not to Rails. You declare the `#ai-actions` JSON block, `window.aiState`
-and `window.aiActions` exactly as a Rails page does — see the three tool classes
-below.
+the page, not to Rails. You declare the page card and its handler maps exactly as
+a Rails page does — see the three tool classes below.
 
 **Attributes** match the helper's keyword options one to one. Three of them are
 easy to get wrong:
@@ -235,21 +230,110 @@ result is committed and shipped in the gem, because a gem cannot run a build
 step on install — and `npm test` fails if the committed bundle has drifted from
 its sources.
 
+## When it does not answer
+
+**Success looks like this:** the panel opens showing your greeting, you type
+"hello", the role label turns into a spinning gear reading "Working…", and the
+reply streams in.
+
+If the panel opens but nothing comes back, it is almost always CORS. The hub
+must list your app's origin in its `CORS_ORIGINS` environment variable for
+the `/api/*` resource, because the widget calls the hub **from the visitor's
+browser**, not from your server. Open the browser console: a blocked request
+says so explicitly.
+
+Two more things worth knowing before you go further:
+
+- `llm_url` must be reachable from your visitors' browsers, not just from
+  your server. `localhost` works only while you are the visitor — which is
+  fine when each visitor runs their own Ollama.
+- The model name is the hub's name for it (`GET /api/llms` lists them), not
+  the provider's.
+
 ## Three tool classes
 
 The widget classifies every tool_call the LLM emits by name and dispatches to one of three execution paths. Each class has a different declaration, different visibility to the LLM, and different execution semantics.
 
-### Class 3 — Page-embedded actions (`window.aiActions`)
+### Class 3 — Page-embedded primitives (the page card)
 
 Declared inline on the same view as the widget. Runs as JavaScript in the browser — no HTTP hop, no server involvement. Best for actions that mutate the page's own state ("click this button", "add to selection", "scroll to X").
 
-**Declaration** — three script blocks on the view:
+The same block declares the page's other primitives too: resources, which are what the model may read from the page, and prompts, which are templates the visitor can run. So everything the page offers is in one place, and each kind has one handler map.
+
+**Declaration — the page card.** The page declares what it offers in one block
+of JSON, found by its media type, and implements it in one handler map per
+primitive type:
+
+```html
+<script type="application/mcp-static-primitives+json">
+{
+  "name": "org.example/your-page",
+  "remotes": [ { "type": "page-global", "global": "mcp" } ],
+  "_meta": { "io.modelcontextprotocol/static-primitives": {
+    "tools": [
+      { "name": "add_dictionaries",
+        "description": "Add the named dictionaries to the current selection.",
+        "inputSchema": {
+          "type": "object",
+          "properties": { "names": { "type": "array", "items": { "type": "string" } } },
+          "required": [ "names" ] } }
+    ],
+    "resources": [
+      { "uri": "page:selected_dictionaries",
+        "name": "Selected dictionaries",
+        "description": "the dictionaries the user has chosen for annotation",
+        "volatility": "volatile" }
+    ]
+  } }
+}
+</script>
+
+<script>
+  // The card named this global; each map inside it is keyed by the identifier
+  // its own MCP operation takes — a tool by name, a resource by uri.
+  window.mcp = {
+    tools:     { add_dictionaries: function (args) { /* mutate the page */ } },
+    resources: { "page:selected_dictionaries": function () { return getSelected(); } }
+  };
+</script>
+```
+
+A tool's schema may be spelled `inputSchema`, as MCP spells it, or
+`input_schema`. Both are accepted.
+
+`remotes` is how a consumer other than this widget finds your handlers, so the
+global is declared rather than assumed. Leave it out and the widget reads
+`window.aiActions`, `window.aiPrompts` and `window.aiResources` instead — see
+"Say where your handlers live".
+
+A page may declare `prompts` in the same block. See [The page card](#the-page-card)
+for prompts, for the size and volatility hints on a resource, and for what
+happens when a document holds several blocks.
+
+**What the LLM sees.** Declared tools are passed to the meta-server as
+`local_tools` for every turn. Every declared resource is read and rendered into
+the `Current page state:` block of the system prompt, one line per resource,
+with its description beside its value:
+
+```
+Current page state:
+- Selected dictionaries (the dictionaries the user has chosen for annotation): ["uberon"]
+```
+
+So the LLM can answer from page state directly instead of tool-calling for a
+lookup, and it knows what each value *means* rather than guessing from a key.
+A resource marked `"volatility": "volatile"` is re-read every turn, which is
+what a form field needs: a value read once at boot is already stale by the time
+anyone sends a message.
+
+**The older channels — `#ai-actions` and `window.aiState`.** These came before
+the page card and still work. A page that declares no card, or a card with no
+`tools`, falls back to them. Use them if you have them already; use the card for
+a new page, because it is the only channel that can also declare prompts and
+resources.
 
 ```html
-<!-- (a) Tool schemas the LLM sees. JSON Schema vocabulary — in practice
-     type, properties, required, description, items, enum. No $schema is
-     declared and nothing here validates one: the object is forwarded to
-     the provider as-is, and each provider accepts its own subset. -->
+<!-- Tool schemas. Note input_schema, not inputSchema, in this channel. -->
 <script type="application/json" id="ai-actions">
 [
   { "name": "add_dictionaries",
@@ -257,28 +341,22 @@ Declared inline on the same view as the widget. Runs as JavaScript in the browse
     "input_schema": {
       "type": "object",
       "properties": { "names": { "type": "array", "items": { "type": "string" } } },
-      "required": ["names"]
+      "required": [ "names" ]
     } }
 ]
 </script>
 
-<!-- (b) State readers folded into the LLM's system prompt EVERY turn, -->
-<!--     so the LLM can answer from page state without a tool_call. -->
-<!--     Each reader declares what it returns, like every other channel. -->
+<!-- State readers, folded into the system prompt every turn. -->
 <script>
   window.aiState = {
     text: {
       description: "the text the user wants to annotate",
       read: function() { return $("#text").val() || ""; }
-    },
-    selected_dictionaries: {
-      description: "the dictionaries the user has chosen for annotation",
-      read: function() { return getSelected(); }
     }
   };
 </script>
 
-<!-- (c) Action implementations invoked when the LLM emits a matching tool_call. -->
+<!-- Action implementations. The card uses this same map. -->
 <script>
   window.aiActions = {
     add_dictionaries: function(args) { /* mutate the page here */ }
@@ -286,26 +364,28 @@ Declared inline on the same view as the widget. Runs as JavaScript in the browse
 </script>
 ```
 
-**What the LLM sees.** The `ai-actions` JSON is passed to the meta-server as `local_tools` for every turn. Alongside it, every reader in `window.aiState` is invoked (each turn) and rendered into a `Current page state:` block appended to the system prompt, one line per reader, with its description beside its value:
+Where both a card and these blocks exist, the card's `tools` replace the
+`#ai-actions` block. They are not merged. Two sources for one list would leave a
+reader guessing which one the page meant. For the same reason, an explicit
+`window.aiState` entry is used in place of a page resource of the same name.
 
-```
-Current page state:
-- text (the text the user wants to annotate): "The stomach was examined."
-- selected_dictionaries (the dictionaries the user has chosen for annotation): ["uberon"]
-```
-
-So the LLM can answer from state directly instead of tool-calling for lookups, and knows what each value *means* rather than guessing from the key.
-
-**Breaking change in 0.8.0.** A reader must be `{ description, read }`. The bare-function form — `text: function() {…}` — is removed, with no fallback. A key that still uses it is reported to the console by name, with the shape it should have, and skipped; the page's other readers keep working. Descriptions are not decoration: every other channel the widget declares to the model already carries one (Class 3 tool schemas, Class 2 `.well-known` tools, Class 1 hub tools, resources), and state readers were the exception.
+**Breaking change in 0.8.0.** An `aiState` reader must be
+`{ description, read }`. The bare-function form — `text: function() {…}` — is
+removed, with no fallback. A key that still uses it is reported to the console by
+name, with the shape it should have, and skipped; the page's other readers keep
+working. Descriptions are not decoration: every other channel the widget
+declares to the model already carries one, and state readers were the exception.
 
 **When the tool_call fires.** During the turn, as soon as the LLM emits the
-call. Since 0.4.0 the action's outcome — `{ok: true, applied: "<name>"}`, or
-the error message if it raised — is fed back to the LLM as a tool result, and
-the turn continues. Before 0.4.0 these were fire-and-forget, which meant a
-turn whose only calls were page actions ended there: any task shaped *change
-the page, then do something with it* was cut off after the write. The change
-also means the LLM can see that an action failed and correct itself, instead
-of the failure being visible only to the visitor.
+call. Since 0.4.0 the action's result is given back to the model and the turn
+continues. The result is `{ok: true, applied: "<name>"}`, or the error message
+if the action raised one.
+
+Before 0.4.0 the widget did not wait for that result. A turn whose only calls
+were page actions therefore ended at the write, and a task of the form *change
+the page, then do something with it* stopped half way. The model can now also
+see that an action failed and correct itself, instead of the failure being
+visible only to the visitor.
 
 Budget for it: every page action now costs a round, so a flow that writes twice
 and then calls a tool needs roughly five or six. See `max_rounds:` below.
@@ -337,11 +417,11 @@ Declared once per host origin via a well-known manifest. Widget fetches the mani
 
 **Auto-discovery.** By default the widget fetches `<same-origin>/.well-known/mcp.json` at boot. To override, pass `well_known_urls:` to the helper: an explicit array (e.g. `["https://other.example/.well-known/mcp.json"]`) or `[]` to disable entirely.
 
-**What the LLM sees.** Every tool listed in every discovered manifest is exposed as a callable. Names must be unique across manifests (if a name collides with a Class 1 or Class 3 tool, Class 3 wins, then Class 2, then Class 1).
+**What the LLM sees.** Every tool listed in every discovered manifest is offered to the model. Names must be unique across manifests. If two classes declare the same name, the widget uses Class 3 first, then Class 2, then Class 1.
 
-**When the tool_call fires.** Synchronously during the turn — widget POSTs `{ jsonrpc, method: "tools/call", params: { name, arguments } }` to the tool's URL, awaits the JSON-RPC response, and feeds the result back to the LLM as tool output for the next round. Standard MCP loop.
+**When the tool_call fires.** During the turn. The widget POSTs `{ jsonrpc, method: "tools/call", params: { name, arguments } }` to the tool's URL and waits for the JSON-RPC response. It then gives the result to the model as tool output for the next round. This is the standard MCP loop.
 
-**Error path.** HTTP 4xx/5xx, network failure, or an MCP JSON-RPC error → widget marks that dispatch as errored; visitor sees a red chip in the message footer; the LLM's next round sees the error as the tool's return value (so it can explain what went wrong instead of pretending it worked).
+**Error path.** An HTTP 4xx or 5xx, a network failure, or an MCP JSON-RPC error all count as a failed call. The visitor sees a red chip in the message footer. The model receives the error as the tool's return value, so it can explain what went wrong instead of pretending the call worked.
 
 ### Class 1 — Hub-registered MCP (via the meta-server)
 
@@ -351,15 +431,15 @@ Declared out-of-band on the meta-server (via the hub's admin UI or `/user/:id/mc
 
 **What the LLM sees.** Only tools the visitor has **enabled via the tool picker** (see "Level-1 pickers" below) — nothing is auto-selected, the visitor opts in per session. A page can set the starting selection instead, with `remote_tools_schema_id:`: those tools arrive already ticked, and the visitor can still untick them.
 
-**When the tool_call fires.** Synchronously during the turn — widget POSTs to the hub's `/api/llm_api_keys/:uuid/models/:name/single_llm_calls` endpoint with `tool_ids: [...]`; the hub proxies to each MCP server and streams results back through SSE.
+**When the tool_call fires.** During the turn. The widget POSTs to the hub's `/api/llm_api_keys/:uuid/models/:name/single_llm_calls` endpoint with `tool_ids: [...]`. The hub calls each MCP server and streams the results back over SSE.
 
-**Error path.** Hub-side errors (rate limit, timeout, MCP server unavailable, upstream failure) arrive as SSE `event: error` frames with typed codes (`mcp_unavailable`, `timeout`, `rate_limit`, …); the widget surfaces them in the message bubble with a per-code prefix.
+**Error path.** Errors from the hub arrive as SSE `event: error` frames, each with a code such as `mcp_unavailable`, `timeout` or `rate_limit`. They cover a rate limit, a timeout, an MCP server that is unavailable, and a failure further upstream. The widget shows each one in the message bubble, with a prefix for its code.
 
 ## Level-1 pickers
 
 By default the widget renders two pickers below the input textarea:
 
-- **Model dropdown** — populated from the hub's `GET /api/llms` (anon path returns Ollama-only, since the widget's LLM calls use `api_key_uuid: "ollama-local"`).
+- **Model dropdown** — populated from the hub's `GET /api/llms`. The anonymous path returns every model the hub serves free, which may include hosted ones, not only a local Ollama.
 - **Tool picker** — populated from the hub's `GET /api/mcp_servers` (anon path returns `public_to_anonymous: true` servers). Two-level UX: server bulk-toggle + individual tool checkboxes on expand.
 
 Both pickers require **CORS**, the same way the chat itself does: the hub must list your page's origin in its `CORS_ORIGINS` environment variable for the `/api/*` resource. Without that the fetches are blocked silently and both pickers simply stay empty.
@@ -370,10 +450,10 @@ To adjust picker behavior at the helper call site:
 <%= llm_meta_widget(
       llm_url:             "https://your-meta-server.example",
       tool_hub_url:        "https://your-meta-server.example",
-      model:               "qwen3-6-35b-fast",   # initial selection
+      model:               "gpt-oss-120b",   # initial selection
       enable_model_picker: true,                 # false → omit picker, use fixed `model:`
       enable_tool_picker:  true,                 # false → omit picker, no Class-1 tools
-      models:              nil,                  # nil = all anon models; ["qwen3-6-35b-fast", …] = allowlist
+      models:              nil,                  # nil = all anon models; ["gpt-oss-120b", …] = allowlist
       hub_tools:           nil                   # nil = all anon-public MCPs; ["togomcp", …] = allowlist by server name
     ) %>
 ```
@@ -401,11 +481,11 @@ translate directly.
 | `model:` | required | Initial model (also the fallback when picker is disabled) |
 | `api_key_uuid:` | `"ollama-local"` | Hub API-key uuid to invoke |
 | `element_path:` | `"/llm_meta_widget_assets/llm-meta-widget.js"` | The bundled element the page loads. Served by the gem's engine; override to load it from elsewhere |
-| `actions_schema_id:` | `"ai-actions"` | DOM id of the Class-3 schema block |
+| `actions_schema_id:` | `"ai-actions"` | DOM id of the older Class-3 schema block, used when the page declares no card tools |
 | `page_card_id:` | `"ai-page"` | **Fallback only.** A card is normally found by its media type (see "The page card"); this id is read when the page has no block with that type. Its tools replace the `actions_schema_id` block |
 | `prompts_global:` | `"aiPrompts"` | Global object holding page prompt handlers, keyed by prompt name |
 | `resources_global:` | `"aiResources"` | Global object holding page resource readers, keyed by resource URI |
-| `state_global:` | `"aiState"` | Global window object holding Class-3 state readers, each `{ description, read }` (see the breaking change in 0.8.0) |
+| `state_global:` | `"aiState"` | Global holding the older Class-3 state readers, each `{ description, read }` (see the breaking change in 0.8.0). A page card declares state as resources instead |
 | `actions_global:` | `"aiActions"` | Global window object holding Class-3 implementations |
 | `remote_tools_schema_id:` | `"remote-mcp-tools"` | DOM id of a JSON block listing Class-1 tools (`{id, name, description, input_schema}`) to start with. They seed the picker rather than bypassing it — shown ticked, and the visitor may untick them. Read once, at boot |
 | `well_known_urls:` | `nil` | `nil` = auto-discover same-origin; explicit array = fetch those; `[]` = disable |
@@ -419,34 +499,49 @@ translate directly.
 ## The page card
 
 Since 0.9.0 a page can declare what it offers in one block of JSON, instead of
-using a separate channel for each kind of thing. The block uses the same envelope
-an MCP server puts in its Server Card, so the page and the server describe
-themselves the same way.
+using a separate channel for each kind of thing. **That block is a Server Card** —
+the same document an MCP server publishes — whose transport is the page itself.
+So the page and the server describe themselves in one format, and one parser
+reads both.
+
+Since 0.10.0 the block is found by its media type. Since 0.11.0 a page can also
+name the global that holds its handlers. Both are below.
 
 ```html
 <script type="application/mcp-static-primitives+json">
-{ "_meta": { "io.modelcontextprotocol/static-primitives": {
+{
+  "name": "org.example/your-page",
+  "remotes": [ { "type": "page-global", "global": "mcp" } ],
+  "_meta": { "io.modelcontextprotocol/static-primitives": {
     "tools":     [ { "name": "set_text", "description": "…", "inputSchema": { } } ],
     "prompts":   [ { "name": "annotate", "description": "Annotate this page" } ],
     "resources": [ { "uri": "page:text", "name": "Text", "description": "the text to annotate",
                      "volatility": "volatile" } ]
-} } }
+  } }
+}
 </script>
 ```
 
-The card says what exists. Three global objects say what it does, and each one is
-keyed by the identifier that the matching MCP operation takes:
+`name` identifies the card, as it does for a server. `remotes` says where the
+handlers live — see "Say where your handlers live" below. Only the `_meta`
+block is required by this widget; the rest is what makes the card readable by
+anything else.
+
+The card says what exists. Three maps say what it does, and each one is keyed by
+the identifier that the matching MCP operation takes:
 
 | declared in the card | implemented in | keyed by |
 |---|---|---|
-| `tools` | `window.aiActions` | tool `name`, as `tools/call` takes |
-| `prompts` | `window.aiPrompts` | prompt `name`, as `prompts/get` takes |
-| `resources` | `window.aiResources` | resource `uri`, as `resources/read` takes |
+| `tools` | `tools` under your declared global, else `window.aiActions` | tool `name`, as `tools/call` takes |
+| `prompts` | `prompts` under it, else `window.aiPrompts` | prompt `name`, as `prompts/get` takes |
+| `resources` | `resources` under it, else `window.aiResources` | resource `uri`, as `resources/read` takes |
 
 ```js
-window.aiActions   = { set_text: (args) => { /* change the page */ } }
-window.aiPrompts   = { annotate: (args) => "Annotate this: " + args.text }
-window.aiResources = { "page:text": () => document.querySelector("#text").value }
+window.mcp = {
+  tools:     { set_text: (args) => { /* change the page */ } },
+  prompts:   { annotate: (args) => "Annotate this: " + args.text },
+  resources: { "page:text": () => document.querySelector("#text").value }
+}
 ```
 
 A prompt handler may return a plain string or the full `messages` array that
@@ -466,6 +561,37 @@ fetch from the web by itself — which page resources are not. The form is
 `page:<name>` with no path, because a page has only one namespace. Expect this to
 change.
 
+**Say where your handlers live.** A card can declare the global that holds
+them, the way a Server Card declares its endpoint. Then a consumer that has
+never heard of this widget can read your card, find your handlers and call
+them:
+
+```html
+<script type="application/mcp-static-primitives+json">
+{ "name": "org.example/your-page",
+  "remotes": [ { "type": "page-global", "global": "mcp" } ],
+  "_meta": { "io.modelcontextprotocol/static-primitives": { "tools": [ ... ] } } }
+</script>
+<script>
+  window.mcp = {
+    tools:     { set_text: function (args) { } },
+    prompts:   { annotate: function (args) { return "..." } },
+    resources: { "page:text": function () { return "..." } }
+  };
+</script>
+```
+
+The name is yours to choose, and it is declared rather than assumed: this code
+runs on your page, where a short fixed name such as `mcp` could collide with
+something of your own.
+
+Without that declaration the widget reads `window.aiActions`,
+`window.aiPrompts` and `window.aiResources`, as before. Those names are known
+only to this widget, and they can be renamed per page with the options below,
+so no other consumer can rely on them. Each kind falls back on its own, so you
+can move tools into the declared global and leave prompts and resources where
+they are.
+
 **The card is found by its media type.** A client matches
 `script[type="application/mcp-static-primitives+json"]`, so the element needs no
 `id`. This is how a client that was never told about your page can still read
@@ -491,15 +617,15 @@ loses the conversation. The transcript, the record of which tools ran, and the
 model's own context are kept in `sessionStorage`: per tab, gone when the tab
 closes, never sent anywhere.
 
-The key is the page's **path**, not its full URL, so a form submit that returns
-to the same page with a new query string keeps the thread, while moving to a
-different page starts a fresh one. Nothing to configure.
+The key is the page's **path**, not its full URL. A form submit that returns to
+the same page with a new query string therefore keeps the same conversation.
+Moving to a different page starts a new one. There is nothing to configure.
 
 Two consequences worth knowing. An action of yours that navigates is now safe
 to declare — before this, offering one meant offering to wipe the visitor's
-chat. And if the navigation lands on an error page that does not render the
-widget, the conversation is still in storage but there is no panel to show it
-until the visitor returns to a page that has one.
+chat. And if the navigation lands on an error page that renders no widget, the
+conversation is still in storage. There is no panel to show it until the visitor
+returns to a page that has one.
 
 ## Choosing what answers the chat, and whose tools to offer
 
@@ -510,10 +636,10 @@ does is what its call site says.
 ```erb
 <%# a hub answers the chat; its registered tools are offered too %>
 <% hub = "https://your-meta-server.example" %>
-<%= llm_meta_widget(llm_url: hub, tool_hub_url: hub, model: "qwen3-6-35b-fast") %>
+<%= llm_meta_widget(llm_url: hub, tool_hub_url: hub, model: "gpt-oss-120b") %>
 
 <%# a hub answers the chat; no hub-registered tools %>
-<%= llm_meta_widget(llm_url: hub, model: "qwen3-6-35b-fast") %>
+<%= llm_meta_widget(llm_url: hub, model: "gpt-oss-120b") %>
 
 <%# the visitor's own Ollama answers; a hub still supplies its tools %>
 <%= llm_meta_widget(llm_url: "http://localhost:11434", llm_provider: :ollama,
@@ -524,12 +650,14 @@ does is what its call site says.
                     model: "qwen3.8:27b") %>
 ```
 
-**The Ollama path.** The widget POSTs to `{llm_url}/api/chat` and reads
-Ollama's NDJSON stream; tool schemas go over as OpenAI-shaped functions and
-`tool_calls` come back, so Class 2 and Class 3 tools work exactly as they do
-against a hub. The model picker lists `{llm_url}/api/tags`. Ollama must be
-told to accept your page's origin — `OLLAMA_ORIGINS=https://your-site.example`
-— which is the same CORS story as the hub, configured elsewhere.
+**The Ollama path.** The widget POSTs to `{llm_url}/api/chat` and reads Ollama's
+NDJSON stream. Tool schemas are sent in OpenAI's shape, and `tool_calls` come
+back the same way, so Class 2 and Class 3 tools work exactly as they do against
+a hub. The model picker lists `{llm_url}/api/tags`.
+
+Ollama must be told to accept your page's origin:
+`OLLAMA_ORIGINS=https://your-site.example`. This is the same CORS requirement
+as the hub has, set in a different place.
 
 What you give up without a `tool_hub_url` is Class 1 only: tools registered on
 somebody's hub. That is not "no tools" — page actions and your own
@@ -543,9 +671,9 @@ no retention policy to write.
 ## Declaring resources and prompts (static-primitives extension)
 
 If you operate the MCP endpoint behind your `.well-known/mcp.json`, you can
-also offer **prompts** (one-click starting points, shown as buttons above the
-input) and **resources** (reference data the widget can put in the model's
-context). The widget reads two optional fields the
+offer two more things. **Prompts** are one-click starting points, shown as
+buttons above the input. **Resources** are reference data the widget can put in
+the model's context. The widget reads two optional fields the
 `io.modelcontextprotocol/static-primitives` extension defines on a
 `resources/list` entry:
 
@@ -554,9 +682,9 @@ context). The widget reads two optional fields the
   "uri": "yourhost://catalog",
   "name": "Catalog",
   "mimeType": "application/json",
+  "size": 1298,
   "_meta": {
     "io.modelcontextprotocol/static-primitives": {
-      "sizeBytes": 1298,
       "volatility": "stable",
       "autoAttach": true
     }
@@ -564,10 +692,14 @@ context). The widget reads two optional fields the
 }
 ```
 
-- **`sizeBytes`** — the byte length of the payload `resources/read` returns.
-  The widget decides whether it can afford the resource *before* fetching it;
-  over its budget (8 KB), the bytes never cross the wire and the LLM is left
-  to ask for what it needs through your tools instead.
+- **`size`** — the byte length of the payload `resources/read` returns. It is the
+  base MCP `Resource` field, not an extension field, so it sits at the top level
+  of the entry. Earlier versions of the extension carried `sizeBytes` inside
+  `_meta`; the widget still reads that when `size` is absent, but it will be
+  removed, so emit `size`.
+  The widget decides whether it can afford the resource *before* fetching it. If
+  the resource is over its budget of 8 KB, the bytes never cross the wire, and
+  the LLM asks for what it needs through your tools instead.
 - **`volatility`** — `"stable"` (read once, re-used) or `"volatile"` (re-read
   on every turn that uses it).
 - **`autoAttach`** — may the widget put this in the model's context without
@@ -578,9 +710,9 @@ that predates the extension: the resource is fetched, trimmed to budget and
 carried in the model's context.
 
 A prompt is offered as a button labelled by its `title`. Declare its arguments
-as **optional** and fill them from page state where you can: an argument the
-visitor must supply by hand makes the button useless to the visitor who needed
-it most, since they must already know your form to press it.
+as **optional**, and fill them from page state where you can. An argument the
+visitor must type in makes the button useless to the visitor who needed it most:
+to press it, they would already have to know your form.
 
 ## Further reading
 
@@ -590,8 +722,9 @@ it most, since they must already know your form to press it.
   current draft shape.
 - **MCP itself** — <https://modelcontextprotocol.io>
 - **A worked adopter** — PubDictionaries' annotation page
-  (<https://pubdictionaries.org/text_annotation>) runs this widget with all
-  three tool classes plus prompts and resources. Its
+  (<https://pubdictionaries.org/text_annotation>) runs this widget with all three
+  tool classes, and declares its own tools, prompts and resources in one page
+  card. Its
   `app/views/annotation/text_annotation.html.erb` and `app/controllers/mcp_controller.rb`
   are the fullest example available.
 - **Shipping the element** — `docs/custom-element-distribution.md` is the design note

package/app/assets/javascripts/llm_meta_widget/llm-meta-widget.js

@@ -561,8 +561,50 @@ function parseSseFrame(raw) {
 }
 var STATIC_PRIMITIVES_META = "io.modelcontextprotocol/static-primitives";
 var PAGE_CARD_MEDIA_TYPE = "application/mcp-static-primitives+json";
+var PAGE_GLOBAL_TRANSPORT = "page-global";
+function declaredPageGlobal(card) {
+  for (const remote of card && card.remotes || []) {
+    if (!remote || remote.type !== PAGE_GLOBAL_TRANSPORT) continue;
+    if (typeof remote.global === "string" && remote.global.trim() !== "") return remote.global.trim();
+  }
+  return null;
+}
+function pageHandlers({ card, scope = {}, legacy = {}, warn = console.warn } = {}) {
+  const name = declaredPageGlobal(card);
+  const declared = name ? scope[name] : null;
+  if (name && !declared) {
+    warn(`[llm-meta-widget] the page card declares global "${name}", but window.${name} is not defined \u2014 is the script that defines it loaded, and did it run?`);
+  }
+  const isMap = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+  const pick = (kind, legacyName) => {
+    const fromGlobal = declared ? declared[kind] : void 0;
+    if (isMap(fromGlobal)) return fromGlobal;
+    if (declared && fromGlobal !== void 0 && !isMap(fromGlobal)) {
+      warn(`[llm-meta-widget] window.${name}.${kind} is ${Array.isArray(fromGlobal) ? "an array" : typeof fromGlobal}; it must be an object keyed by ${kind === "resources" ? "uri" : "name"}`);
+    }
+    return legacyName && scope[legacyName] || {};
+  };
+  return {
+    global: name,
+    tools: pick("tools", legacy.tools),
+    prompts: pick("prompts", legacy.prompts),
+    resources: pick("resources", legacy.resources)
+  };
+}
 function mergeStaticPrimitivesCards(cards, warn = console.warn) {
-  const merged = { tools: [], prompts: [], resources: [] };
+  const merged = { remotes: [], tools: [], prompts: [], resources: [] };
+  for (const card of cards || []) {
+    for (const remote of card && card.remotes || []) {
+      const clash = merged.remotes.find((r) => r.type === remote.type && r.global !== remote.global);
+      if (clash) {
+        warn(`[llm-meta-widget] two blocks declare different ${remote.type} globals ("${clash.global}" and "${remote.global}"); using "${clash.global}"`);
+        continue;
+      }
+      if (!merged.remotes.some((r) => r.type === remote.type && r.global === remote.global)) {
+        merged.remotes.push(remote);
+      }
+    }
+  }
   const keyOf = { tools: "name", prompts: "name", resources: "uri" };
   for (const kind of ["tools", "prompts", "resources"]) {
     const key = keyOf[kind];
@@ -580,7 +622,7 @@ function mergeStaticPrimitivesCards(cards, warn = console.warn) {
   return merged;
 }
 function readStaticPrimitivesCard(text, warn = console.warn) {
-  const empty = { tools: [], prompts: [], resources: [] };
+  const empty = { remotes: [], tools: [], prompts: [], resources: [] };
   if (typeof text !== "string" || text.trim() === "") return empty;
   let doc;
   try {
@@ -600,6 +642,8 @@ function readStaticPrimitivesCard(text, warn = console.warn) {
     return ok;
   });
   return {
+    // The whole card's transport, so what it declares survives the parse.
+    remotes: Array.isArray(doc.remotes) ? doc.remotes : [],
     tools: named(ext.tools, "tool"),
     prompts: named(ext.prompts, "prompt"),
     // Resources are addressed by uri, not name — resources/read takes the uri.
@@ -3919,6 +3963,12 @@ function boot(cfg) {
       model: MODEL
     });
   }
+  var lastPersist = 0;
+  function persistSoon() {
+    if (Date.now() - lastPersist < 400) return;
+    lastPersist = Date.now();
+    persistConversation();
+  }
   var typedCards = document.querySelectorAll('script[type="' + PAGE_CARD_MEDIA_TYPE + '"]');
   var pageCard;
   if (typedCards.length) {
@@ -3931,6 +3981,11 @@ function boot(cfg) {
     var pageCardEl = document.getElementById(PAGE_CARD_ID);
     pageCard = readStaticPrimitivesCard(pageCardEl ? pageCardEl.textContent : null);
   }
+  var handlers = pageHandlers({
+    card: pageCard,
+    scope: window,
+    legacy: { tools: ACTIONS_GLOBAL, prompts: PROMPTS_GLOBAL, resources: RESOURCES_GLOBAL }
+  });
   var actionsSchemaEl = document.getElementById(ACTIONS_SCHEMA_ID);
   var localTools = pageCard.tools.length ? pageCard.tools : actionsSchemaEl ? JSON.parse(actionsSchemaEl.textContent) : [];
   var remoteToolsEl = document.getElementById(REMOTE_TOOLS_SCHEMA_ID);
@@ -4207,7 +4262,7 @@ function boot(cfg) {
   function argState() {
     return promptArgState({
       entries: pageCard.resources,
-      resources: window[RESOURCES_GLOBAL] || {},
+      resources: handlers.resources,
       state: window[STATE_GLOBAL] || {}
     });
   }
@@ -4307,7 +4362,7 @@ function boot(cfg) {
     }
     button.disabled = true;
     try {
-      var result = prompt.source === "page" ? await getPagePrompt({ name: prompt.name, args, prompts: window[PROMPTS_GLOBAL] }) : await getMcpPrompt({ endpoint: prompt.endpoint, name: prompt.name, args });
+      var result = prompt.source === "page" ? await getPagePrompt({ name: prompt.name, args, prompts: handlers.prompts }) : await getMcpPrompt({ endpoint: prompt.endpoint, name: prompt.name, args });
       var text = promptMessagesToText(result);
       if (!text) {
         appendTurn("error", "The server returned an empty prompt.");
@@ -4523,7 +4578,7 @@ function boot(cfg) {
     resourceContext = turn.cached;
     var page = await pageResourceLinesForTurn({
       plans: pageResourcePlans,
-      resources: window[RESOURCES_GLOBAL],
+      resources: handlers.resources,
       budgetBytes: RESOURCE_BUDGET_BYTES,
       cache: pageResourceCache
     });
@@ -4576,6 +4631,10 @@ function boot(cfg) {
       var messages = [{ role: "system", content: currentSystemPrompt(resourceLines) }].concat(conversation.map(function(t) {
         return { role: t.role, content: t.content };
       })).concat([{ role: "user", content: userText }]);
+      conversation.push({ role: "user", content: userText });
+      var liveTurn = { role: "assistant", content: "", tools: [] };
+      conversation.push(liveTurn);
+      persistConversation();
       var result = await runChatLoop({
         baseUrl: LLM_BASE,
         toolHubUrl: TOOL_HUB_BASE,
@@ -4585,15 +4644,18 @@ function boot(cfg) {
         localTools,
         remoteTools,
         hostWideTools,
-        aiActions: window[ACTIONS_GLOBAL] || {},
+        aiActions: handlers.tools,
         maxRounds: MAX_ROUNDS,
         provider: LLM_PROVIDER === "ollama" ? "ollama" : "hub",
         signal: currentAbort.signal,
         onToolCall: function(toolCall) {
           announceToolCall(toolCall);
+          persistConversation();
         },
         onToolDispatched: function(outcome) {
           resolveToolCall(outcome);
+          liveTurn.tools = liveTurn.tools.concat([outcome.error ? { name: outcome.toolCall.name, error: true } : { name: outcome.toolCall.name }]);
+          persistConversation();
         },
         onPhase: function(name) {
           if (name === "responding") markDone(assistantBody.roleLabel);
@@ -4614,18 +4676,14 @@ function boot(cfg) {
           collapseThinkingBlock();
           assistantMarkdown += delta;
           renderMarkdownInto(assistantBody, assistantMarkdown);
+          liveTurn.content = assistantMarkdown;
+          persistSoon();
           historyEl.scrollTop = historyEl.scrollHeight;
         }
       });
-      conversation.push({ role: "user", content: userText });
-      conversation.push({
-        role: "assistant",
-        content: result.content,
-        // Kept so a restored transcript still shows what ran — losing
-        // that record is what made a navigating action unbearable.
-        tools: result.dispatched.map(function(d) {
-          return d.error ? { name: d.toolCall.name, error: true } : { name: d.toolCall.name };
-        })
+      liveTurn.content = result.content;
+      liveTurn.tools = result.dispatched.map(function(d) {
+        return d.error ? { name: d.toolCall.name, error: true } : { name: d.toolCall.name };
       });
       persistConversation();
       result.dispatched.forEach(function(d) {

package/app/assets/javascripts/llm_meta_widget/orchestrator.js

@@ -884,6 +884,62 @@ export const STATIC_PRIMITIVES_META = "io.modelcontextprotocol/static-primitives
 // look cannot discover anything. SEP-0000, "HTML-delivery mode".
 export const PAGE_CARD_MEDIA_TYPE = "application/mcp-static-primitives+json"
 
+// The transport an HTML-delivered Server Card declares: a JavaScript global
+// under which the handler maps live. A Server Card always states its endpoint
+// rather than relying on a convention, and a page card states its global the
+// same way — so a consumer that has never heard of this widget can parse the
+// card, find the handlers and dispatch. The three legacy globals
+// (aiActions/aiPrompts/aiResources) are names only this widget knows, and are
+// configurable per page, so nothing outside could rely on them.
+export const PAGE_GLOBAL_TRANSPORT = "page-global"
+
+export function declaredPageGlobal(card) {
+  for (const remote of (card && card.remotes) || []) {
+    if (!remote || remote.type !== PAGE_GLOBAL_TRANSPORT) continue
+    if (typeof remote.global === "string" && remote.global.trim() !== "") return remote.global.trim()
+  }
+  return null
+}
+
+// Resolves the three handler maps. A declared global wins; each map falls back
+// to its legacy global independently, so a page part-way through moving over
+// keeps working instead of losing the primitives it has not moved yet.
+export function pageHandlers({ card, scope = {}, legacy = {}, warn = console.warn } = {}) {
+  const name = declaredPageGlobal(card)
+  const declared = name ? scope[name] : null
+
+  // A card that names a global the page never defines is almost always a load
+  // order problem, or a script that threw before it got there. Falling back in
+  // silence hides that: the page then behaves as if it had declared nothing,
+  // and the first symptom is a prompt or tool that "has no handler".
+  if (name && !declared) {
+    warn(`[llm-meta-widget] the page card declares global "${name}", but window.${name} ` +
+         "is not defined — is the script that defines it loaded, and did it run?")
+  }
+
+  const isMap = (v) => !!v && typeof v === "object" && !Array.isArray(v)
+  const pick = (kind, legacyName) => {
+    // `declared ? … : undefined`, not `declared && …`: the second yields null
+    // when nothing is declared, and `typeof null === "object"`, so the check
+    // below then warned about "window.null.tools" on every page with no card.
+    const fromGlobal = declared ? declared[kind] : undefined
+    if (isMap(fromGlobal)) return fromGlobal
+    // An array is the mistake worth naming: it passes a typeof check, so it
+    // would be used as a map and answer every lookup with undefined.
+    if (declared && fromGlobal !== undefined && !isMap(fromGlobal)) {
+      warn(`[llm-meta-widget] window.${name}.${kind} is ${Array.isArray(fromGlobal) ? "an array" : typeof fromGlobal}; ` +
+           `it must be an object keyed by ${kind === "resources" ? "uri" : "name"}`)
+    }
+    return (legacyName && scope[legacyName]) || {}
+  }
+  return {
+    global: name,
+    tools: pick("tools", legacy.tools),
+    prompts: pick("prompts", legacy.prompts),
+    resources: pick("resources", legacy.resources)
+  }
+}
+
 // Several blocks may appear in one document, so that a page assembled from
 // components can let each component declare its own primitives. The arrays
 // concatenate by primitive type.
@@ -894,7 +950,23 @@ export const PAGE_CARD_MEDIA_TYPE = "application/mcp-static-primitives+json"
 // Picking the first would make which component wins depend on DOM order, which
 // is not something a page author controls when the components are partials.
 export function mergeStaticPrimitivesCards(cards, warn = console.warn) {
-  const merged = { tools: [], prompts: [], resources: [] }
+  const merged = { remotes: [], tools: [], prompts: [], resources: [] }
+  // Each block is a full Server Card and may declare a transport. The first
+  // one wins; a second block naming a DIFFERENT global is an authoring error,
+  // because only one of them can be dispatched to.
+  for (const card of cards || []) {
+    for (const remote of (card && card.remotes) || []) {
+      const clash = merged.remotes.find((r) => r.type === remote.type && r.global !== remote.global)
+      if (clash) {
+        warn(`[llm-meta-widget] two blocks declare different ${remote.type} globals ` +
+             `("${clash.global}" and "${remote.global}"); using "${clash.global}"`)
+        continue
+      }
+      if (!merged.remotes.some((r) => r.type === remote.type && r.global === remote.global)) {
+        merged.remotes.push(remote)
+      }
+    }
+  }
   const keyOf = { tools: "name", prompts: "name", resources: "uri" }
 
   for (const kind of [ "tools", "prompts", "resources" ]) {
@@ -917,7 +989,7 @@ export function mergeStaticPrimitivesCards(cards, warn = console.warn) {
 }
 
 export function readStaticPrimitivesCard(text, warn = console.warn) {
-  const empty = { tools: [], prompts: [], resources: [] }
+  const empty = { remotes: [], tools: [], prompts: [], resources: [] }
   if (typeof text !== "string" || text.trim() === "") return empty
 
   let doc
@@ -941,6 +1013,8 @@ export function readStaticPrimitivesCard(text, warn = console.warn) {
   })
 
   return {
+    // The whole card's transport, so what it declares survives the parse.
+    remotes: Array.isArray(doc.remotes) ? doc.remotes : [],
     tools: named(ext.tools, "tool"),
     prompts: named(ext.prompts, "prompt"),
     // Resources are addressed by uri, not name — resources/read takes the uri.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aibranch/llm-meta-widget",
-  "version": "0.10.1",
+  "version": "0.11.1",
   "//version": "Must stay in step with lib/llm_meta_widget/version.rb. Two independently versioned copies of the same client is the drift docs/custom-element-distribution.md warns about: bump both, release both.",
   "description": "Embeddable browser chat widget: a custom element that discovers tools at page, origin and hub scope and dispatches each tool call to the right one. Two lines of HTML on any host, Rails or not.",
   "keywords": [