@aibranch/llm-meta-widget 0.9.0 → 0.10.0

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,74 @@ 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/mcp-static-primitives+json">
+{ "_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 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
+it, and it follows SEP-0000's "HTML-delivery mode". The `page_card_id:` option
+is kept only for a host that cannot set the type; it is read when no block with
+the media type is present.
+
+**A document may hold several blocks.** A page built from components can let
+each component declare its own primitives, and the arrays join by primitive
+type. Declaring the same tool or prompt `name`, or the same resource `uri`,
+twice is an error: every copy is dropped and a message is written to the
+console. The first one does not win, because which block comes first depends on
+the order the page's parts are rendered in, and that is not something the author
+chose.
+
+**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

@@ -560,6 +560,25 @@ function parseSseFrame(raw) {
   return { name, data };
 }
 var STATIC_PRIMITIVES_META = "io.modelcontextprotocol/static-primitives";
+var PAGE_CARD_MEDIA_TYPE = "application/mcp-static-primitives+json";
+function mergeStaticPrimitivesCards(cards, warn = console.warn) {
+  const merged = { tools: [], prompts: [], resources: [] };
+  const keyOf = { tools: "name", prompts: "name", resources: "uri" };
+  for (const kind of ["tools", "prompts", "resources"]) {
+    const key = keyOf[kind];
+    const all = [];
+    for (const card of cards || []) all.push(...card && card[kind] || []);
+    const counts = /* @__PURE__ */ new Map();
+    for (const entry of all) counts.set(entry[key], (counts.get(entry[key]) || 0) + 1);
+    for (const [id, n] of counts) {
+      if (n > 1) {
+        warn(`[llm-meta-widget] the page declares ${kind} "${id}" ${n} times; dropping every copy \u2014 remove the duplicate to say which one you mean`);
+      }
+    }
+    merged[kind] = all.filter((entry) => counts.get(entry[key]) === 1);
+  }
+  return merged;
+}
 function readStaticPrimitivesCard(text, warn = console.warn) {
   const empty = { tools: [], prompts: [], resources: [] };
   if (typeof text !== "string" || text.trim() === "") return empty;
@@ -737,7 +756,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;
@@ -3887,8 +3919,18 @@ function boot(cfg) {
       model: MODEL
     });
   }
-  var pageCardEl = document.getElementById(PAGE_CARD_ID);
-  var pageCard = readStaticPrimitivesCard(pageCardEl ? pageCardEl.textContent : null);
+  var typedCards = document.querySelectorAll('script[type="' + PAGE_CARD_MEDIA_TYPE + '"]');
+  var pageCard;
+  if (typedCards.length) {
+    pageCard = mergeStaticPrimitivesCards(
+      Array.prototype.map.call(typedCards, function(el) {
+        return readStaticPrimitivesCard(el.textContent);
+      })
+    );
+  } else {
+    var pageCardEl = document.getElementById(PAGE_CARD_ID);
+    pageCard = readStaticPrimitivesCard(pageCardEl ? pageCardEl.textContent : null);
+  }
   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);
@@ -4162,6 +4204,13 @@ function boot(cfg) {
     renderPromptButtons();
     renderWelcome();
   })();
+  function argState() {
+    return promptArgState({
+      entries: pageCard.resources,
+      resources: window[RESOURCES_GLOBAL] || {},
+      state: window[STATE_GLOBAL] || {}
+    });
+  }
   function renderPromptButtons() {
     if (!promptsEl) return;
     promptsEl.textContent = "";
@@ -4213,7 +4262,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");
@@ -4249,7 +4298,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) {

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

@@ -879,6 +879,43 @@ export const STATIC_PRIMITIVES_META = "io.modelcontextprotocol/static-primitives
 // 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.
+// The media type that locates a card inside an HTML document. It is the
+// locator, so it is NOT configurable: a client that has to be told where to
+// look cannot discover anything. SEP-0000, "HTML-delivery mode".
+export const PAGE_CARD_MEDIA_TYPE = "application/mcp-static-primitives+json"
+
+// 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.
+//
+// A duplicate identifier across blocks is an ERROR, not a precedence puzzle:
+// the spec says a client should report it and should not silently pick one. So
+// every copy of a duplicated identifier is dropped and the author is told.
+// 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 keyOf = { tools: "name", prompts: "name", resources: "uri" }
+
+  for (const kind of [ "tools", "prompts", "resources" ]) {
+    const key = keyOf[kind]
+    const all = []
+    for (const card of cards || []) all.push(...((card && card[kind]) || []))
+
+    const counts = new Map()
+    for (const entry of all) counts.set(entry[key], (counts.get(entry[key]) || 0) + 1)
+
+    for (const [ id, n ] of counts) {
+      if (n > 1) {
+        warn(`[llm-meta-widget] the page declares ${kind} "${id}" ${n} times; ` +
+             "dropping every copy — remove the duplicate to say which one you mean")
+      }
+    }
+    merged[kind] = all.filter((entry) => counts.get(entry[key]) === 1)
+  }
+  return merged
+}
+
 export function readStaticPrimitivesCard(text, warn = console.warn) {
   const empty = { tools: [], prompts: [], resources: [] }
   if (typeof text !== "string" || text.trim() === "") return empty
@@ -1129,8 +1166,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.9.0",
+  "version": "0.10.0",
   "//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": [