@aibranch/llm-meta-widget 0.8.6 → 0.9.1

package/README.md

@@ -216,6 +216,7 @@ easy to get wrong:
 | `llm-provider` | `llm_meta_server` (default) or `ollama` |
 | `api-key-uuid`, `greeting`, `max-rounds` | as the helper options |
 | `actions-schema-id`, `state-global`, `actions-global`, `remote-tools-schema-id` | as the helper options |
+| `page-card-id`, `prompts-global`, `resources-global` | as the helper options |
 | `models`, `hub-tools` | comma-separated. Omitted **or empty** means no allowlist — an allowlist permitting nothing is never what anyone meant |
 | `enable-model-picker`, `enable-tool-picker` | **value attributes, not boolean attributes.** They default to true, so presence cannot mean true. Disable with `enable-tool-picker="false"`; any other value is true |
 | `well-known-urls` | **Three different states**, because an attribute cannot tell "not set" from "set to empty": omitted = auto-discover same-origin `/.well-known/mcp.json`; `""` = discovery off; `"a,b"` = fetch those |
@@ -401,6 +402,9 @@ translate directly.
 | `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 |
+| `page_card_id:` | `"ai-page"` | DOM id of the page card (see "The page card"). 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) |
 | `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 |
@@ -412,6 +416,59 @@ translate directly.
 | `models:` | `nil` | Model-name allowlist; `nil` = all anon-available |
 | `hub_tools:` | `nil` | MCP-server-name allowlist; `nil` = all anon-public |
 
+## 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.
+
+```html
+<script type="application/json" id="ai-page">
+{ "_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:
+
+| 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 |
+
+```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 }
+```
+
+A prompt handler may return a plain string or the full `messages` array that
+`prompts/get` returns. A resource reader may return a string or any value that
+can be turned into JSON.
+
+**Resources carry two optional hints.** `volatility` is `"volatile"` when the
+value changes between turns, so the widget reads it again every turn; the default
+is `"stable"`, which is read once and reused. `autoAttach: false` keeps a resource
+out of the turn unless something asks for it. A `size` in bytes lets the widget
+decide whether the value fits its budget before reading it.
+
+**The `page:` scheme is experimental.** It is not a registered URI scheme, and
+nothing outside this widget gives it meaning. It is used because the protocol
+asks for a URI, and because `https://` is reserved for resources a client can
+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.
+
+**The card is optional.** A page that declares nothing keeps working exactly as
+before, and a page that declares no `tools` still uses its `ai-actions` block.
+
 ## Surviving navigation
 
 A page action that navigates — submitting a form, following a link — no longer

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

@@ -483,6 +483,17 @@ async function readMcpResource({ endpoint, uri, signal }) {
     label: `readMcpResource(${uri})`
   });
 }
+async function getPagePrompt({ name, args, prompts }) {
+  const handler = prompts && prompts[name];
+  if (typeof handler !== "function") {
+    throw new Error('the page declares prompt "' + name + '" but no handler answers to that name');
+  }
+  const result = await handler(args || {});
+  if (typeof result === "string") {
+    return { messages: [{ role: "user", content: { type: "text", text: result } }] };
+  }
+  return result || { messages: [] };
+}
 function promptMessagesToText(result) {
   return (result?.messages || []).map((m) => {
     const c = m.content;
@@ -549,8 +560,40 @@ function parseSseFrame(raw) {
   return { name, data };
 }
 var STATIC_PRIMITIVES_META = "io.modelcontextprotocol/static-primitives";
+function readStaticPrimitivesCard(text, warn = console.warn) {
+  const empty = { tools: [], prompts: [], resources: [] };
+  if (typeof text !== "string" || text.trim() === "") return empty;
+  let doc;
+  try {
+    doc = JSON.parse(text);
+  } catch (e) {
+    warn("[llm-meta-widget] page card is not valid JSON; ignoring it:", e.message);
+    return empty;
+  }
+  const ext = doc && doc._meta && doc._meta[STATIC_PRIMITIVES_META] || null;
+  if (!ext) {
+    warn(`[llm-meta-widget] page card has no _meta["${STATIC_PRIMITIVES_META}"]; ignoring it`);
+    return empty;
+  }
+  const named = (arr, kind) => (Array.isArray(arr) ? arr : []).filter((e) => {
+    const ok = e && typeof e.name === "string" && e.name.trim() !== "";
+    if (!ok) warn(`[llm-meta-widget] page card: dropping a ${kind} with no name`);
+    return ok;
+  });
+  return {
+    tools: named(ext.tools, "tool"),
+    prompts: named(ext.prompts, "prompt"),
+    // Resources are addressed by uri, not name — resources/read takes the uri.
+    resources: (Array.isArray(ext.resources) ? ext.resources : []).filter((e) => {
+      const ok = e && typeof e.uri === "string" && e.uri.trim() !== "";
+      if (!ok) warn("[llm-meta-widget] page card: dropping a resource with no uri");
+      return ok;
+    })
+  };
+}
 var VOLATILITIES = ["stable", "volatile"];
 var usableSize = (n) => typeof n === "number" && isFinite(n) ? n : null;
+var pickDeclared = (own, fromMeta) => own === void 0 ? fromMeta : own;
 function resourceHints(entry) {
   const meta = entry && entry._meta && entry._meta[STATIC_PRIMITIVES_META] || {};
   return {
@@ -566,8 +609,13 @@ function resourceHints(entry) {
     get sizeBytes() {
       return this.size;
     },
-    volatility: VOLATILITIES.indexOf(meta.volatility) === -1 ? "stable" : meta.volatility,
-    autoAttach: typeof meta.autoAttach === "boolean" ? meta.autoAttach : true
+    // Same rule as `size`: the entry's own field wins, `_meta` is the fallback.
+    // SEP-0000 defines these ON the Resource object; a server puts them in
+    // `_meta` only because the extension is not merged yet. A PAGE card's
+    // entries already sit inside the extension block, so for them the fields
+    // are simply top-level — reading both is what lets one planner serve both.
+    volatility: VOLATILITIES.indexOf(pickDeclared(entry && entry.volatility, meta.volatility)) === -1 ? "stable" : pickDeclared(entry && entry.volatility, meta.volatility),
+    autoAttach: typeof pickDeclared(entry && entry.autoAttach, meta.autoAttach) === "boolean" ? pickDeclared(entry && entry.autoAttach, meta.autoAttach) : true
   };
 }
 function planResourceAttachment(entry, budgetBytes) {
@@ -611,6 +659,45 @@ async function readResourceContext({ endpoint, uri, name, read, budgetBytes }) {
     return null;
   }
 }
+function planPageResources({ entries, budgetBytes, onSkip }) {
+  return (entries || []).map((entry) => {
+    const plan = planResourceAttachment(entry, budgetBytes);
+    plan.name = entry.name || entry.uri;
+    plan.description = entry.description || "";
+    if (!plan.fetch && onSkip) onSkip(plan);
+    return plan;
+  }).filter((plan) => plan.fetch);
+}
+function pageResourceLine(plan, text) {
+  return "- " + plan.name + (plan.description ? " (" + plan.description + ")" : "") + ": " + text;
+}
+async function pageResourceLinesForTurn({ plans, resources, budgetBytes, cache = {} }) {
+  const lines = [];
+  for (const plan of plans || []) {
+    let text = plan.volatility === "volatile" ? null : cache[plan.uri];
+    if (text === null || text === void 0) {
+      text = await readPageResource({ uri: plan.uri, resources, budgetBytes });
+      if (plan.volatility !== "volatile" && text !== null) cache[plan.uri] = text;
+    }
+    if (text !== null) lines.push(pageResourceLine(plan, text));
+  }
+  return { lines, cache };
+}
+async function readPageResource({ uri, resources, budgetBytes }) {
+  const handler = resources && resources[uri];
+  if (typeof handler !== "function") {
+    console.warn('[llm-meta-widget] the page declares resource "' + uri + '" but no handler answers to that uri');
+    return null;
+  }
+  try {
+    const value = await handler();
+    const text = typeof value === "string" ? value : JSON.stringify(value);
+    return trimResourceText(text === void 0 ? "" : text, budgetBytes);
+  } catch (e) {
+    console.warn('[llm-meta-widget] reading "' + uri + '" failed:', e && e.message);
+    return null;
+  }
+}
 async function loadHostResource({ endpoint, budgetBytes, list: list2, read, onSkip }) {
   const resources = await list2({ endpoint });
   const candidate = (resources || []).filter((r) => (r.mimeType || "") === "application/json")[0];
@@ -650,7 +737,20 @@ async function resourceLinesForTurn({ plan, cached, endpoint, read, budgetBytes
   }
   return { lines: resourceContextLines(cached), cached };
 }
+var PAGE_URI_PREFIX = "page:";
 var PROMPT_ARG_ALIASES = { dictionaries: "selected_dictionaries" };
+function promptArgState({ entries = [], resources = {}, state = {} } = {}) {
+  const merged = Object.assign({}, state);
+  for (const entry of entries) {
+    const uri = entry && entry.uri;
+    if (!uri || uri.indexOf(PAGE_URI_PREFIX) !== 0) continue;
+    const name = uri.slice(PAGE_URI_PREFIX.length);
+    const reader = resources[uri];
+    if (!name || merged[name] || typeof reader !== "function") continue;
+    merged[name] = { description: entry.description || "", read: reader };
+  }
+  return merged;
+}
 function promptArgFromState(argName, state) {
   const entry = state && state[argName] || state && state[PROMPT_ARG_ALIASES[argName]];
   const reader = entry && typeof entry.read === "function" ? entry.read : null;
@@ -2904,8 +3004,11 @@ var lexer = _Lexer.lex;
 var DEFAULTS = Object.freeze({
   API_KEY_UUID: "ollama-local",
   ACTIONS_SCHEMA_ID: "ai-actions",
+  PAGE_CARD_ID: "ai-page",
   STATE_GLOBAL: "aiState",
   ACTIONS_GLOBAL: "aiActions",
+  PROMPTS_GLOBAL: "aiPrompts",
+  RESOURCES_GLOBAL: "aiResources",
   REMOTE_TOOLS_SCHEMA_ID: "remote-mcp-tools",
   LLM_PROVIDER: "llm_meta_server",
   MAX_ROUNDS: 3
@@ -2939,9 +3042,12 @@ function readConfig(el) {
     API_KEY_UUID: str("api-key-uuid", DEFAULTS.API_KEY_UUID),
     MODEL: str("model", null),
     ACTIONS_SCHEMA_ID: str("actions-schema-id", DEFAULTS.ACTIONS_SCHEMA_ID),
+    PAGE_CARD_ID: str("page-card-id", DEFAULTS.PAGE_CARD_ID),
     GREETING: str("greeting", null),
     STATE_GLOBAL: str("state-global", DEFAULTS.STATE_GLOBAL),
     ACTIONS_GLOBAL: str("actions-global", DEFAULTS.ACTIONS_GLOBAL),
+    PROMPTS_GLOBAL: str("prompts-global", DEFAULTS.PROMPTS_GLOBAL),
+    RESOURCES_GLOBAL: str("resources-global", DEFAULTS.RESOURCES_GLOBAL),
     REMOTE_TOOLS_SCHEMA_ID: str("remote-tools-schema-id", DEFAULTS.REMOTE_TOOLS_SCHEMA_ID),
     MAX_ROUNDS: int("max-rounds", DEFAULTS.MAX_ROUNDS),
     WELL_KNOWN_URLS: wellKnown === null ? null : wellKnown.trim() === "" ? [] : splitList(wellKnown),
@@ -3658,9 +3764,12 @@ function boot(cfg) {
   var API_KEY_UUID = cfg.API_KEY_UUID;
   var MODEL = cfg.MODEL;
   var ACTIONS_SCHEMA_ID = cfg.ACTIONS_SCHEMA_ID;
+  var PAGE_CARD_ID = cfg.PAGE_CARD_ID;
   var GREETING = cfg.GREETING;
   var STATE_GLOBAL = cfg.STATE_GLOBAL;
   var ACTIONS_GLOBAL = cfg.ACTIONS_GLOBAL;
+  var PROMPTS_GLOBAL = cfg.PROMPTS_GLOBAL;
+  var RESOURCES_GLOBAL = cfg.RESOURCES_GLOBAL;
   var REMOTE_TOOLS_SCHEMA_ID = cfg.REMOTE_TOOLS_SCHEMA_ID;
   var MAX_ROUNDS = cfg.MAX_ROUNDS;
   var WELL_KNOWN_URLS = cfg.WELL_KNOWN_URLS;
@@ -3791,8 +3900,10 @@ function boot(cfg) {
       model: MODEL
     });
   }
+  var pageCardEl = document.getElementById(PAGE_CARD_ID);
+  var pageCard = readStaticPrimitivesCard(pageCardEl ? pageCardEl.textContent : null);
   var actionsSchemaEl = document.getElementById(ACTIONS_SCHEMA_ID);
-  var localTools = actionsSchemaEl ? JSON.parse(actionsSchemaEl.textContent) : [];
+  var localTools = pageCard.tools.length ? pageCard.tools : actionsSchemaEl ? JSON.parse(actionsSchemaEl.textContent) : [];
   var remoteToolsEl = document.getElementById(REMOTE_TOOLS_SCHEMA_ID);
   var baselineRemoteTools = remoteToolsEl ? JSON.parse(remoteToolsEl.textContent) : [];
   var remoteTools = baselineRemoteTools.slice();
@@ -4015,11 +4126,22 @@ function boot(cfg) {
     }
   }
   var hostWideTools = [];
-  var hostWidePrompts = [];
+  var hostWidePrompts = pageCard.prompts.map(function(p) {
+    return Object.assign({}, p, { source: "page" });
+  });
   var resourceContext = null;
   var resourcePlan = null;
   var RESOURCE_BUDGET_BYTES = 8e3;
+  var pageResourcePlans = planPageResources({
+    entries: pageCard.resources,
+    budgetBytes: RESOURCE_BUDGET_BYTES,
+    onSkip: function(plan) {
+      console.info("[llm_meta_widget] not attaching " + plan.uri + " (" + plan.reason + ", size=" + plan.size + ")");
+    }
+  });
+  var pageResourceCache = {};
   restoreConversation();
+  var promptsEl = root.querySelector(".lmw-prompts");
   var wellKnownReady = (async function() {
     var urls = WELL_KNOWN_URLS === null ? [window.location.origin + "/.well-known/mcp.json"] : WELL_KNOWN_URLS;
     for (var i = 0; i < urls.length; i++) {
@@ -4053,7 +4175,13 @@ function boot(cfg) {
     renderPromptButtons();
     renderWelcome();
   })();
-  var promptsEl = root.querySelector(".lmw-prompts");
+  function argState() {
+    return promptArgState({
+      entries: pageCard.resources,
+      resources: window[RESOURCES_GLOBAL] || {},
+      state: window[STATE_GLOBAL] || {}
+    });
+  }
   function renderPromptButtons() {
     if (!promptsEl) return;
     promptsEl.textContent = "";
@@ -4105,7 +4233,7 @@ function boot(cfg) {
     hello.className = "lmw-welcome-hello";
     hello.textContent = GREETING || "Hi \u2014 I can work this page for you. Tell me what you need in your own words" + (hostWidePrompts.length ? ", or start with one of these:" : ".");
     box.appendChild(hello);
-    var state = window[STATE_GLOBAL] || {};
+    var state = argState();
     hostWidePrompts.forEach(function(prompt) {
       var props = promptButtonProps(prompt);
       var card = document.createElement("div");
@@ -4141,7 +4269,7 @@ function boot(cfg) {
     historyEl.appendChild(box);
   }
   async function runPromptTemplate(prompt, button) {
-    var resolved = resolvePromptArguments(prompt, window[STATE_GLOBAL] || {});
+    var resolved = resolvePromptArguments(prompt, argState());
     var args = resolved.args;
     var missing = resolved.missing;
     if (missing.length) {
@@ -4150,7 +4278,7 @@ function boot(cfg) {
     }
     button.disabled = true;
     try {
-      var result = await getMcpPrompt({ endpoint: prompt.endpoint, name: prompt.name, args });
+      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 text = promptMessagesToText(result);
       if (!text) {
         appendTurn("error", "The server returned an empty prompt.");
@@ -4364,7 +4492,14 @@ function boot(cfg) {
       budgetBytes: RESOURCE_BUDGET_BYTES
     });
     resourceContext = turn.cached;
-    return turn.lines;
+    var page = await pageResourceLinesForTurn({
+      plans: pageResourcePlans,
+      resources: window[RESOURCES_GLOBAL],
+      budgetBytes: RESOURCE_BUDGET_BYTES,
+      cache: pageResourceCache
+    });
+    pageResourceCache = page.cache;
+    return turn.lines.concat(page.lines);
   }
   var currentAbort = null;
   clearBtn.addEventListener("click", function() {

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

@@ -730,6 +730,28 @@ export async function readMcpResource({ endpoint, uri, signal }) {
 // The spec allows `content` to be an object or an array of content blocks;
 // anything non-text is dropped, which is worth knowing — a prompt carrying an
 // image would silently lose it on this path.
+// A prompt the PAGE declared, resolved against its handler map. This is
+// prompts/get for a surface with no transport: the card carries the metadata
+// (name, description, arguments — what prompts/list returns) and the handler
+// returns the filled messages, exactly as a server's prompts/get would.
+//
+// Keyed by `name` because that is what prompts/get takes. Accepts a plain
+// string as well as a messages array: a page prompt is usually one block of
+// text, and making every host write the envelope by hand would be a tax with
+// no benefit — promptMessagesToText flattens both to the same thing.
+export async function getPagePrompt({ name, args, prompts }) {
+  const handler = prompts && prompts[name]
+  if (typeof handler !== "function") {
+    throw new Error('the page declares prompt "' + name + '" but no handler answers to that name')
+  }
+
+  const result = await handler(args || {})
+  if (typeof result === "string") {
+    return { messages: [ { role: "user", content: { type: "text", text: result } } ] }
+  }
+  return result || { messages: [] }
+}
+
 export function promptMessagesToText(result) {
   return (result?.messages || [])
     .map((m) => {
@@ -840,9 +862,63 @@ function parseSseFrame(raw) {
 // the first turn only.
 export const STATIC_PRIMITIVES_META = "io.modelcontextprotocol/static-primitives"
 
+// ---- page card --------------------------------------------------------
+//
+// The same `io.modelcontextprotocol/static-primitives` envelope a server puts
+// in its Server Card, delivered in the DOCUMENT instead: one <script> of JSON
+// declaring the page's own tools, prompts and resources. SEP-2575 already says
+// the Server Card and server/discover are two deliveries of one content; a page
+// is a third, with no transport at all.
+//
+// Parsing only. What a declaration MEANS is resolved elsewhere: tool handlers
+// live in window.aiActions keyed by `name`, and reads will be keyed by the
+// protocol's own identifier — `name` for prompts, `uri` for resources, because
+// that is what prompts/get and resources/read take.
+//
+// Malformed input must never take the page down: a card is host-authored and a
+// typo in it should cost that one entry, not the assistant. Everything
+// unparseable returns empty arrays and says so on the console, which is how
+// aiState already treats a reader missing its description.
+export function readStaticPrimitivesCard(text, warn = console.warn) {
+  const empty = { tools: [], prompts: [], resources: [] }
+  if (typeof text !== "string" || text.trim() === "") return empty
+
+  let doc
+  try {
+    doc = JSON.parse(text)
+  } catch (e) {
+    warn("[llm-meta-widget] page card is not valid JSON; ignoring it:", e.message)
+    return empty
+  }
+
+  const ext = (doc && doc._meta && doc._meta[STATIC_PRIMITIVES_META]) || null
+  if (!ext) {
+    warn(`[llm-meta-widget] page card has no _meta["${STATIC_PRIMITIVES_META}"]; ignoring it`)
+    return empty
+  }
+
+  const named = (arr, kind) => (Array.isArray(arr) ? arr : []).filter((e) => {
+    const ok = e && typeof e.name === "string" && e.name.trim() !== ""
+    if (!ok) warn(`[llm-meta-widget] page card: dropping a ${kind} with no name`)
+    return ok
+  })
+
+  return {
+    tools: named(ext.tools, "tool"),
+    prompts: named(ext.prompts, "prompt"),
+    // Resources are addressed by uri, not name — resources/read takes the uri.
+    resources: (Array.isArray(ext.resources) ? ext.resources : []).filter((e) => {
+      const ok = e && typeof e.uri === "string" && e.uri.trim() !== ""
+      if (!ok) warn("[llm-meta-widget] page card: dropping a resource with no uri")
+      return ok
+    })
+  }
+}
+
 const VOLATILITIES = [ "stable", "volatile" ]
 
 const usableSize = (n) => (typeof n === "number" && isFinite(n) ? n : null)
+const pickDeclared = (own, fromMeta) => (own === undefined ? fromMeta : own)
 
 export function resourceHints(entry) {
   const meta = (entry && entry._meta && entry._meta[STATIC_PRIMITIVES_META]) || {}
@@ -857,8 +933,17 @@ export function resourceHints(entry) {
     // it returns is public API. Dropped at 0.9.0 together with the
     // `_meta.sizeBytes` fallback above — one deprecation, one bump.
     get sizeBytes() { return this.size },
-    volatility: VOLATILITIES.indexOf(meta.volatility) === -1 ? "stable" : meta.volatility,
-    autoAttach: typeof meta.autoAttach === "boolean" ? meta.autoAttach : true
+    // Same rule as `size`: the entry's own field wins, `_meta` is the fallback.
+    // SEP-0000 defines these ON the Resource object; a server puts them in
+    // `_meta` only because the extension is not merged yet. A PAGE card's
+    // entries already sit inside the extension block, so for them the fields
+    // are simply top-level — reading both is what lets one planner serve both.
+    volatility: VOLATILITIES.indexOf(pickDeclared(entry && entry.volatility, meta.volatility)) === -1
+      ? "stable"
+      : pickDeclared(entry && entry.volatility, meta.volatility),
+    autoAttach: typeof pickDeclared(entry && entry.autoAttach, meta.autoAttach) === "boolean"
+      ? pickDeclared(entry && entry.autoAttach, meta.autoAttach)
+      : true
   }
 }
 
@@ -920,6 +1005,65 @@ async function readResourceContext({ endpoint, uri, name, read, budgetBytes }) {
   }
 }
 
+// ---- page resources ----------------------------------------------------
+//
+// resources/read for a surface with no transport. The card lists them, a
+// handler map keyed by URI reads them — URI because that is what
+// resources/read takes, and because the spec defines it as the unique
+// identifier while `name` is only required, never unique.
+//
+// Unlike a server endpoint, a page declares SEVERAL: PubDictionaries has six
+// readers, each with its own description. So these are planned and rendered as
+// a list, not as the single reference resource loadHostResource assumes.
+export function planPageResources({ entries, budgetBytes, onSkip }) {
+  return (entries || []).map((entry) => {
+    const plan = planResourceAttachment(entry, budgetBytes)
+    plan.name = entry.name || entry.uri
+    plan.description = entry.description || ""
+    if (!plan.fetch && onSkip) onSkip(plan)
+    return plan
+  }).filter((plan) => plan.fetch)
+}
+
+// One compact line per resource — the same shape the page-state annex uses,
+// NOT the block form a hub resource gets. Six block-form resources would cost
+// three lines each and repeat a header the model does not need; how to render
+// attached context is the client's decision, which the spec leaves open.
+export function pageResourceLine(plan, text) {
+  return "- " + plan.name + (plan.description ? " (" + plan.description + ")" : "") + ": " + text
+}
+
+export async function pageResourceLinesForTurn({ plans, resources, budgetBytes, cache = {} }) {
+  const lines = []
+  for (const plan of plans || []) {
+    let text = plan.volatility === "volatile" ? null : cache[plan.uri]
+    if (text === null || text === undefined) {
+      text = await readPageResource({ uri: plan.uri, resources, budgetBytes })
+      if (plan.volatility !== "volatile" && text !== null) cache[plan.uri] = text
+    }
+    if (text !== null) lines.push(pageResourceLine(plan, text))
+  }
+  return { lines, cache }
+}
+
+async function readPageResource({ uri, resources, budgetBytes }) {
+  const handler = resources && resources[uri]
+  if (typeof handler !== "function") {
+    console.warn('[llm-meta-widget] the page declares resource "' + uri + '" but no handler answers to that uri')
+    return null
+  }
+  try {
+    const value = await handler()
+    const text = typeof value === "string" ? value : JSON.stringify(value)
+    return trimResourceText(text === undefined ? "" : text, budgetBytes)
+  } catch (e) {
+    // Optional context — one broken reader must not cost the turn, exactly as
+    // a failed hub read does not.
+    console.warn('[llm-meta-widget] reading "' + uri + '" failed:', e && e.message)
+    return null
+  }
+}
+
 // The discovery sequence for one endpoint's reference resource, kept here
 // rather than in the panel so the decision AND the call site are testable
 // together: a gate nothing consults is exactly the bug this shape prevents.
@@ -985,8 +1129,35 @@ export async function resourceLinesForTurn({ plan, cached, endpoint, read, budge
 // (window.aiState) by name. `dictionaries` is read from a
 // `selected_dictionaries` reader: the page selects a LIST, and the prompt
 // declares the CSV shape the text_annotation tool already takes.
+// Page resources are addressed `page:<name>`: a custom scheme because the
+// protocol asks for a URI and `https:` is reserved for what a client can fetch
+// itself, and with no path because a page has one namespace.
+const PAGE_URI_PREFIX = "page:"
+
 const PROMPT_ARG_ALIASES = { dictionaries: "selected_dictionaries" }
 
+// Prompt arguments are declared by plain name (`text`); page resources are
+// addressed by URI (`page:text`). So on a page that declares its state as
+// resources and keeps no `aiState`, the resolver below finds nothing under the
+// names it looks up and every argument arrives empty — the visitor is asked to
+// retype what is already on screen. This presents those resources in the shape
+// the resolver consumes, keyed by the name inside the URI.
+//
+// An explicit `aiState` entry wins: a page running both channels has said what
+// it wants under that name.
+export function promptArgState({ entries = [], resources = {}, state = {} } = {}) {
+  const merged = Object.assign({}, state)
+  for (const entry of entries) {
+    const uri = entry && entry.uri
+    if (!uri || uri.indexOf(PAGE_URI_PREFIX) !== 0) continue
+    const name = uri.slice(PAGE_URI_PREFIX.length)
+    const reader = resources[uri]
+    if (!name || merged[name] || typeof reader !== "function") continue
+    merged[name] = { description: entry.description || "", read: reader }
+  }
+  return merged
+}
+
 export function promptArgFromState(argName, state) {
   // Same object shape the system-prompt annex consumes: { description, read }.
   // The bare-function form was removed in 0.8.0, so an entry without `read` is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aibranch/llm-meta-widget",
-  "version": "0.8.6",
+  "version": "0.9.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": [