llm_meta_widget 0.12.2 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d3172a4471dd7326d3455cbb4d39ed5f19092df52e81828b98d71a0c541da57
-  data.tar.gz: 1ec235057d668445bcb40cdb6b584cc73c1c579ee54c2cf36b7bcef699efb5b9
+  metadata.gz: 98514af704b8e59db0091c55a0d42f60cc3d9da77ed8debbf8aa2b94e514576d
+  data.tar.gz: e0b25d087956a31ad5bc21ce232b25abe1aa0ca78a917abdaf6f0e97c7ba7237
 SHA512:
-  metadata.gz: 1dcda012841f3a4c1f253c837d1149292f0c19cdc6a5396cb7ab7064bfb0ac0dbae5414bc0e33529fb925a4d5b15de28a78cda13bba26bf4856fca84f13a94e2
-  data.tar.gz: 338955619e9f6712e6889bbe62a295de75b7cf9cb6571d7cd9aab0ac227b52caf5d6c891b14ef136bcc115e6da0f721f441b4a9a7bd3be96248d55cde441870e
+  metadata.gz: 15101bd9cbac468ccc0c2f5e7e5206e153a459335954779f80694e7431713aa5835849b4b9278511df408bd237adc37cfc16ef658b7a85b279b23d6871eb46d8
+  data.tar.gz: e81e6404165550d0521eb1fba9aa18d4e10ebc0cac400f50e6ff9453084f84e082baba1f7b386155d0b0d567c2a0e51e6de93d16a6a80fba0260f949ad1460d7

data/CHANGELOG.md

@@ -3,6 +3,56 @@
 This file starts at 0.8.0, the first release with a breaking change worth
 calling out. Earlier releases are in the git history (`git log --oneline v0.7.6`).
 
+## 0.13.0
+
+### Changed: a page card declares its transport in `transports`, not `remotes`
+
+The declaration that says how to reach a page's handlers has moved, following
+SEP revision d44bd25a. It is now an array inside the extension data:
+
+```json
+{
+  "_meta": {
+    "io.modelcontextprotocol/static-primitives": {
+      "transports": [ { "type": "page-global", "global": "mcp" } ],
+      "tools": [], "prompts": [], "resources": []
+    }
+  }
+}
+```
+
+The reason is that the Server Card's `Remote.type` can only be
+`streamable-http` or `sse`, so `page-global` was never a valid value at the top
+level. It is an array because a page may come to offer more than one page-local
+transport, and the order is the author's preference.
+
+The widget reads the array in order and uses the first type it supports. It
+will not skip a supported entry for a later one. Only `page-global` is
+supported today; a card offering only `page-postmessage`, `page-jsonrpc` or
+`page-worker` gets no handlers rather than the wrong ones, and says so.
+
+**Top-level `remotes` still works in this release**, with a warning, so a page
+and a widget can be updated in either order without the page losing its tools
+in between. Move to `transports`; a later release will drop the fallback. If a
+page declares both, `transports` decides and nothing is reported.
+
+
+### Added: the panel says when reference data did not fit
+
+A resource refused by the budget used to disappear with nothing but a line in
+the browser console: the model answered from less than the page offered, and
+nobody was told. The panel now reports it, naming the resource, its size and
+what the model allows — once per budget, on the first turn it affects, and
+again if a different model changes the figures.
+
+The model is deliberately NOT told. It cannot fetch a resource — only the
+client reads those — so telling it would spend context on something it can do
+nothing about. The reader can act: choose a model with a larger window, or ask
+the page author for a smaller reference.
+
+A resource the page withholds on purpose (`autoAttach: false`) is not reported,
+since that is the author's choice rather than an omission.
+
 ## 0.12.2
 
 ### Changed: one oversized tool result is shortened, not paid for by the others

data/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

data/app/assets/javascripts/llm_meta_widget/element.js

@@ -171,7 +171,35 @@ function boot(cfg) {
 
   	// Rounded to the nearest thousand and grouped, so the numbers read as a
   	// scale rather than as a precise count the estimate cannot support.
-  	function thousands(n) {
+  	// Reference data the budget refused, so the panel can say so on the next
+	// turn. NOT announced at boot: appendTurn persists, so a boot-time notice
+	// would be saved into the transcript and repeat on every reload.
+	//
+	// The model is not told, deliberately. It cannot fetch a resource — only the
+	// client reads those — so telling it would spend tokens on something it can
+	// do nothing about. The person CAN act: pick a model with more room, or ask
+	// the page author for a smaller reference.
+	var skippedResources = [];
+	var announcedSkips   = false;
+
+	function kb(bytes) { return Math.round((bytes || 0) / 1024) + " KB"; }
+
+	// `origin` is "page" for a page-card resource and "host" for one from a
+	// host-wide server. It matters when the budget changes: page resources are
+	// planned again, so their refusals are re-recorded, while a host resource is
+	// listed once at boot and never re-planned. Clearing both on a re-plan
+	// erased the host refusal before it could be reported — which silenced the
+	// case that matters most, since PubDictionaries' catalog arrives that way.
+	function noteSkippedResource(plan, budget, origin) {
+		// A resource the page marked autoAttach:false is a deliberate choice, not
+		// an omission — only a budget refusal is worth reporting.
+		if (plan.reason !== "over-budget") return;
+		var name = plan.name || plan.uri;
+		skippedResources = skippedResources.filter(function(s) { return s.name !== name; });
+		skippedResources.push({ name: name, size: plan.size, budget: budget, origin: origin });
+	}
+
+	function thousands(n) {
   		return (Math.round(n / 1000) * 1000).toLocaleString("en-US");
   	}
 
@@ -701,12 +729,19 @@ function boot(cfg) {
   		var budget = resourceBudget();
   		if (pageResourcePlans === null || budget !== pageResourcePlansBudget) {
   			pageResourcePlansBudget = budget;
+			// A different budget is a different decision: say it again. Only the
+			// page's own refusals are dropped — those are about to be re-recorded
+			// by the planning below. A host resource is listed once at boot, so
+			// discarding its refusal here would lose it for good.
+			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");
   				}
   			});
   		}
@@ -759,6 +794,7 @@ function boot(cfg) {
   					onSkip: function(plan) {
   						console.info("[llm_meta_widget] not attaching " + plan.uri +
   						             " (" + plan.reason + ", size=" + plan.size + ")");
+  						             noteSkippedResource(plan, resourceBudget(), "host");
   					}
   				});
   				// A volatile resource comes back with no context — it is read
@@ -1143,7 +1179,10 @@ function boot(cfg) {
   	// pixels — while scrollTop and scrollHeight stay correct. So the reader can
   	// scroll a few pixels and no further, by any input method, while
   	// `scrollTop = 600` set from script still works. Chrome 154 reproduces it
-  	// with no widget code at all; Firefox 158 never does (reported 2026-10-17).
+  	// with no widget code at all; Firefox 158 never does.
+	// https://issues.chromium.org/issues/574960594 — docs/chromium-scroll-bug.md has the
+	// measurements and a self-checking test case. Remove this once the fix
+	// has shipped widely enough.
   	//
   	// Taking the scroller off the inner box BEFORE the close avoids the state.
   	// Two frames, because one is not enough for Chrome to pick up the new
@@ -1307,6 +1346,23 @@ function boot(cfg) {
   		if (!userText) return;
   		inputEl.value = "";
   		appendTurn("user", userText, pendingTurnLabel);
+
+  		// Reference data that did not fit, reported once per budget, at the moment
+  		// it affects an answer rather than at boot.
+  		// Plan the page's resources first: the refusals are recorded while planning,
+  		// which otherwise happens later in the turn — after this check had already
+  		// looked at an empty list and said nothing.
+  		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 { currentAbort.abort(); } catch (e) { /* noop */ } }

data/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 {

data/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"),

data/lib/llm_meta_widget/version.rb

@@ -1,3 +1,3 @@
 module LlmMetaWidget
-  VERSION = "0.12.2"
+  VERSION = "0.13.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm_meta_widget
 version: !ruby/object:Gem::Version
-  version: 0.12.2
+  version: 0.13.0
 platform: ruby
 authors:
 - jdkim