@aibranch/llm-meta-widget 0.12.2 → 0.13.0

package/README.md

@@ -61,7 +61,7 @@ Option 3 if it does not.
 
 ```ruby
 # Gemfile
-gem "llm_meta_widget", "~> 0.12.2"
+gem "llm_meta_widget", "~> 0.13.0"
 ```
 
 ```bash
@@ -152,23 +152,27 @@ 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.12"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@aibranch/llm-meta-widget@0.13"></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.12` is a version range, and it stops at 0.12.x on purpose.** You receive
+**`@0.13` is a version range, and it stops at 0.13.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.13 is therefore a change you make yourself. Read
+Moving to 0.14 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.
 
+0.13.0 moves where a page declares its transport. That one is safe to take
+first, because 0.13.x still reads the old spelling and warns; the page can move
+afterwards.
+
 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

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

@@ -689,15 +689,29 @@ function modelWindowFrom(payload, modelId) {
   return null;
 }
 var PAGE_GLOBAL_TRANSPORT = "page-global";
-function declaredPageGlobal(card) {
+function declaredPageGlobal(card, warn = console.warn) {
+  const declared = card && card.transports || [];
+  for (const transport of declared) {
+    if (!transport || transport.type !== PAGE_GLOBAL_TRANSPORT) continue;
+    if (typeof transport.global === "string" && transport.global.trim() !== "") {
+      return transport.global.trim();
+    }
+  }
+  if (declared.length) {
+    warn("[llm-meta-widget] page card declares transports " + JSON.stringify(declared.map((t) => t && t.type)) + ", none of which this widget supports; not dispatching to the page");
+    return null;
+  }
   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();
+    if (typeof remote.global === "string" && remote.global.trim() !== "") {
+      warn(`[llm-meta-widget] page card declares its transport in top-level "remotes", which is deprecated; move it to _meta["${STATIC_PRIMITIVES_META}"].transports`);
+      return remote.global.trim();
+    }
   }
   return null;
 }
 function pageHandlers({ card, scope = {}, legacy = {}, warn = console.warn } = {}) {
-  const name = declaredPageGlobal(card);
+  const name = declaredPageGlobal(card, warn);
   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?`);
@@ -719,16 +733,19 @@ function pageHandlers({ card, scope = {}, legacy = {}, warn = console.warn } = {
   };
 }
 function mergeStaticPrimitivesCards(cards, warn = console.warn) {
-  const merged = { remotes: [], tools: [], prompts: [], resources: [] };
+  const merged = { transports: [], 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);
+    for (const kind of ["transports", "remotes"]) {
+      for (const entry of card && card[kind] || []) {
+        if (!entry || typeof entry.type !== "string") continue;
+        const clash = merged[kind].find((r) => r.type === entry.type && r.global !== entry.global);
+        if (clash) {
+          warn(`[llm-meta-widget] two blocks declare different ${entry.type} globals ("${clash.global}" and "${entry.global}"); using "${clash.global}"`);
+          continue;
+        }
+        if (!merged[kind].some((r) => r.type === entry.type && r.global === entry.global)) {
+          merged[kind].push(entry);
+        }
       }
     }
   }
@@ -749,7 +766,7 @@ function mergeStaticPrimitivesCards(cards, warn = console.warn) {
   return merged;
 }
 function readStaticPrimitivesCard(text, warn = console.warn) {
-  const empty = { remotes: [], tools: [], prompts: [], resources: [] };
+  const empty = { transports: [], remotes: [], tools: [], prompts: [], resources: [] };
   if (typeof text !== "string" || text.trim() === "") return empty;
   let doc;
   try {
@@ -769,7 +786,12 @@ function readStaticPrimitivesCard(text, warn = console.warn) {
     return ok;
   });
   return {
-    // The whole card's transport, so what it declares survives the parse.
+    // Where a page says how to reach its handlers. Since SEP d44bd25a this is
+    // `transports` inside the extension data, because the Server Card's
+    // `Remote.type` enum is streamable-http|sse and `page-global` was never a
+    // valid value there. Top-level `remotes` is what 0.11.1-0.12.2 read, and is
+    // still accepted for one release — see declaredPageGlobal.
+    transports: Array.isArray(ext.transports) ? ext.transports : [],
     remotes: Array.isArray(doc.remotes) ? doc.remotes : [],
     tools: named(ext.tools, "tool"),
     prompts: named(ext.prompts, "prompt"),
@@ -3988,6 +4010,19 @@ function boot(cfg) {
   var toggleBtn = document.getElementById("llm-meta-widget-toggle");
   var historyEl = root.querySelector(".lmw-messages");
   var SCROLL_PIN_SLACK = 40;
+  var skippedResources = [];
+  var announcedSkips = false;
+  function kb(bytes) {
+    return Math.round((bytes || 0) / 1024) + " KB";
+  }
+  function noteSkippedResource(plan, budget, origin) {
+    if (plan.reason !== "over-budget") return;
+    var name = plan.name || plan.uri;
+    skippedResources = skippedResources.filter(function(s) {
+      return s.name !== name;
+    });
+    skippedResources.push({ name, size: plan.size, budget, origin });
+  }
   function thousands(n) {
     return (Math.round(n / 1e3) * 1e3).toLocaleString("en-US");
   }
@@ -4382,11 +4417,16 @@ function boot(cfg) {
     var budget = resourceBudget();
     if (pageResourcePlans === null || budget !== pageResourcePlansBudget) {
       pageResourcePlansBudget = budget;
+      skippedResources = skippedResources.filter(function(s) {
+        return s.origin !== "page";
+      });
+      announcedSkips = false;
       pageResourcePlans = planPageResources({
         entries: pageCard.resources,
         budgetBytes: budget,
         onSkip: function(plan) {
           console.info("[llm_meta_widget] not attaching " + plan.uri + " (" + plan.reason + ", size=" + plan.size + ")");
+          noteSkippedResource(plan, resourceBudget(), "page");
         }
       });
     }
@@ -4417,6 +4457,7 @@ function boot(cfg) {
           read: readMcpResource,
           onSkip: function(plan) {
             console.info("[llm_meta_widget] not attaching " + plan.uri + " (" + plan.reason + ", size=" + plan.size + ")");
+            noteSkippedResource(plan, resourceBudget(), "host");
           }
         });
         if (loaded && loaded.plan && loaded.plan.fetch) {
@@ -4807,6 +4848,14 @@ function boot(cfg) {
     if (!userText) return;
     inputEl.value = "";
     appendTurn("user", userText, pendingTurnLabel);
+    pageResourcePlansNow();
+    if (skippedResources.length && !announcedSkips) {
+      announcedSkips = true;
+      var skipped = skippedResources[0];
+      var others = skippedResources.length - 1;
+      var alsoText = others > 0 ? " and " + others + " other reference" + (others > 1 ? "s" : "") : "";
+      appendTurn("system", "Did not attach the " + skipped.name + " reference" + alsoText + " (" + kb(skipped.size) + ", and a " + MODEL + " turn allows " + kb(skipped.budget) + " for reference data), so the answer may be less precise. A model with a larger context window would make room.");
+    }
     pendingTurnLabel = null;
     if (currentAbort) {
       try {

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

@@ -1122,10 +1122,41 @@ export function modelWindowFrom(payload, modelId) {
 
 export const PAGE_GLOBAL_TRANSPORT = "page-global"
 
-export function declaredPageGlobal(card) {
+// Which JS global holds the handlers, from the card's declared transports.
+//
+// The array is processed IN ORDER and the first entry whose type we support
+// wins: the page author's order is their preference, so a supported entry is
+// never skipped for a later one. Only `page-global` is supported today;
+// `page-postmessage`, `page-jsonrpc` and `page-worker` are reserved, and a card
+// declaring only those gets no handlers rather than the wrong ones.
+//
+// Top-level `remotes` is the pre-d44bd25a shape that 0.11.1 and 0.12.2 read. It
+// is accepted for one release so a page and a widget can be updated in either
+// order without the page going dark in between, and it warns so the author
+// knows to move.
+export function declaredPageGlobal(card, warn = console.warn) {
+  const declared = (card && card.transports) || []
+  for (const transport of declared) {
+    if (!transport || transport.type !== PAGE_GLOBAL_TRANSPORT) continue
+    if (typeof transport.global === "string" && transport.global.trim() !== "") {
+      return transport.global.trim()
+    }
+  }
+  if (declared.length) {
+    warn("[llm-meta-widget] page card declares transports " +
+         JSON.stringify(declared.map((t) => t && t.type)) +
+         ", none of which this widget supports; not dispatching to the page")
+    return null
+  }
+
   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()
+    if (typeof remote.global === "string" && remote.global.trim() !== "") {
+      warn('[llm-meta-widget] page card declares its transport in top-level ' +
+           '"remotes", which is deprecated; move it to ' +
+           `_meta["${STATIC_PRIMITIVES_META}"].transports`)
+      return remote.global.trim()
+    }
   }
   return null
 }
@@ -1134,7 +1165,7 @@ export function declaredPageGlobal(card) {
 // 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 name = declaredPageGlobal(card, warn)
   const declared = name ? scope[name] : null
 
   // A card that names a global the page never defines is almost always a load
@@ -1179,20 +1210,28 @@ export function pageHandlers({ card, scope = {}, legacy = {}, warn = console.war
 // 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 = { 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.
+  const merged = { transports: [], remotes: [], tools: [], prompts: [], resources: [] }
+  // Each block is a full Server Card and may declare transports. They are
+  // concatenated in document order, because the order is the author's
+  // preference and selection honours it. A second block naming a DIFFERENT
+  // global for the same type is an authoring error — only one of them can be
+  // dispatched to — so the first is kept and the clash is reported.
+  //
+  // `remotes` is merged the same way: it is the deprecated spelling of the same
+  // thing, and a page mid-migration may still carry it.
   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)
+    for (const kind of [ "transports", "remotes" ]) {
+      for (const entry of (card && card[kind]) || []) {
+        if (!entry || typeof entry.type !== "string") continue
+        const clash = merged[kind].find((r) => r.type === entry.type && r.global !== entry.global)
+        if (clash) {
+          warn(`[llm-meta-widget] two blocks declare different ${entry.type} globals ` +
+               `("${clash.global}" and "${entry.global}"); using "${clash.global}"`)
+          continue
+        }
+        if (!merged[kind].some((r) => r.type === entry.type && r.global === entry.global)) {
+          merged[kind].push(entry)
+        }
       }
     }
   }
@@ -1218,7 +1257,7 @@ export function mergeStaticPrimitivesCards(cards, warn = console.warn) {
 }
 
 export function readStaticPrimitivesCard(text, warn = console.warn) {
-  const empty = { remotes: [], tools: [], prompts: [], resources: [] }
+  const empty = { transports: [], remotes: [], tools: [], prompts: [], resources: [] }
   if (typeof text !== "string" || text.trim() === "") return empty
 
   let doc
@@ -1242,7 +1281,12 @@ export function readStaticPrimitivesCard(text, warn = console.warn) {
   })
 
   return {
-    // The whole card's transport, so what it declares survives the parse.
+    // Where a page says how to reach its handlers. Since SEP d44bd25a this is
+    // `transports` inside the extension data, because the Server Card's
+    // `Remote.type` enum is streamable-http|sse and `page-global` was never a
+    // valid value there. Top-level `remotes` is what 0.11.1-0.12.2 read, and is
+    // still accepted for one release — see declaredPageGlobal.
+    transports: Array.isArray(ext.transports) ? ext.transports : [],
     remotes: Array.isArray(doc.remotes) ? doc.remotes : [],
     tools: named(ext.tools, "tool"),
     prompts: named(ext.prompts, "prompt"),

package/package.json

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