llm_meta_widget 0.12.2 → 0.13.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d3172a4471dd7326d3455cbb4d39ed5f19092df52e81828b98d71a0c541da57
-  data.tar.gz: 1ec235057d668445bcb40cdb6b584cc73c1c579ee54c2cf36b7bcef699efb5b9
+  metadata.gz: b72c0af2bf75bb5a7d1b83b0048aac15dc0485d86448ca4ea99403737c7a95ec
+  data.tar.gz: 1c5dfb8782859c09727fde1f996a39055c0cbe8e75b6116258b9d547a4a7b7a4
 SHA512:
-  metadata.gz: 1dcda012841f3a4c1f253c837d1149292f0c19cdc6a5396cb7ab7064bfb0ac0dbae5414bc0e33529fb925a4d5b15de28a78cda13bba26bf4856fca84f13a94e2
-  data.tar.gz: 338955619e9f6712e6889bbe62a295de75b7cf9cb6571d7cd9aab0ac227b52caf5d6c891b14ef136bcc115e6da0f721f441b4a9a7bd3be96248d55cde441870e
+  metadata.gz: cf20127dce92b482a6c6a88a42e3a31fc2b80e127274c9cbae5e7d6f75d3043c9334e38459a7feddf90f0c985984f1a3cdced6550091953952ab44a9282fcf25
+  data.tar.gz: 5554707eda6744fdf8188c1c7d81765c27c068cb078a672d894825cb70f8f5c2c2e6ed4f3593f5a5432b7255bd7d0f01718c14804b1dcba9af661c0df7667a3c

data/CHANGELOG.md

@@ -3,6 +3,75 @@
 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.1
+
+### Documentation: the README caught up with 0.12.x and 0.13.0
+
+Three examples and two explanations still told a page author to declare the
+transport in a top-level `remotes` list. Following the README would have
+produced a card this version warns about and a later version will stop reading.
+They now use `transports` inside the extension data, and say that the list is
+read in order and that the first supported type wins.
+
+The README also said nothing about what the widget does when a turn does not fit
+the model's context, although every part of that behaviour shipped in 0.12.x and
+puts messages in the panel that a page's visitors will read. There is now a
+section describing the three cases — one oversized tool result shortened, older
+results given up, a reference resource refused for its size — with the wording
+the reader actually sees.
+
+No code changed in this release.
+
+## 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.1"
 ```
 
 ```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
@@ -268,8 +272,8 @@ primitive type:
 <script type="application/mcp-static-primitives+json">
 {
   "name": "org.example/your-page",
-  "remotes": [ { "type": "page-global", "global": "mcp" } ],
   "_meta": { "io.modelcontextprotocol/static-primitives": {
+    "transports": [ { "type": "page-global", "global": "mcp" } ],
     "tools": [
       { "name": "add_dictionaries",
         "description": "Add the named dictionaries to the current selection.",
@@ -301,11 +305,18 @@ primitive type:
 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
+`transports` is how a consumer other than this widget finds your handlers, so
+the global is declared rather than assumed. It is a list, and the consumer uses
+the first entry whose `type` it supports; `page-global` is the only type this
+widget supports today. Leave `transports` out and the widget reads
 `window.aiActions`, `window.aiPrompts` and `window.aiResources` instead — see
 "Say where your handlers live".
 
+Widgets up to 0.12.2 read this declaration from a `remotes` list at the top
+level of the card instead. Version 0.13.0 still reads that, and warns, so a page
+and a widget can be updated in either order. Write `transports`; a page may
+declare both while a deployment is still catching up, and `transports` decides.
+
 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.
@@ -511,8 +522,8 @@ name the global that holds its handlers. Both are below.
 <script type="application/mcp-static-primitives+json">
 {
   "name": "org.example/your-page",
-  "remotes": [ { "type": "page-global", "global": "mcp" } ],
   "_meta": { "io.modelcontextprotocol/static-primitives": {
+    "transports": [ { "type": "page-global", "global": "mcp" } ],
     "tools":     [ { "name": "set_text", "description": "…", "inputSchema": { } } ],
     "prompts":   [ { "name": "annotate", "description": "Annotate this page" } ],
     "resources": [ { "uri": "page:text", "name": "Text", "description": "the text to annotate",
@@ -522,8 +533,8 @@ name the global that holds its handlers. Both are below.
 </script>
 ```
 
-`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`
+`name` identifies the card, as it does for a server. `transports` 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.
 
@@ -569,8 +580,8 @@ 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": [ ... ] } } }
+  "_meta": { "io.modelcontextprotocol/static-primitives": {
+    "transports": [ { "type": "page-global", "global": "mcp" } ], "tools": [ ... ] } } }
 </script>
 <script>
   window.mcp = {
@@ -718,6 +729,47 @@ 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.
 
+## When a turn does not fit the model's context
+
+A model holds a fixed number of tokens. A long conversation, a large reference
+resource and a few big tool results can exceed it, and the provider then refuses
+the whole turn. The widget tries to keep a turn inside the limit instead, and
+tells the reader whenever it has to change something. You do not configure any
+of this, but your page's visitors will see the messages, so it is worth knowing
+what they mean.
+
+The widget learns each model's context window from the server's model list. If
+the server does not report one, none of the behaviour below applies and the turn
+is sent as it is.
+
+**One oversized tool result is shortened.** A single result may use at most 40%
+of the window. A larger one is cut to that size, and the model is told in the
+result itself how much was shown and that it can call the tool again with a
+narrower query. The panel says, for example:
+
+> Shortened an oversized togovar_search_variant result to fit the context:
+> 121,000 tokens, where one result may use at most 51,000. Ask again with a
+> narrower question for the complete result.
+
+**Older tool results are given up when the whole turn is too long.** This is for
+a conversation that has grown over many turns, not for one large result. The
+oldest results go first, one at a time, until the turn fits. The questions, the
+answers and the model's own summaries of what it read are never touched, and a
+dropped result leaves a note in its place so the model knows to ask again.
+
+**A reference resource that does not fit is not attached.** Each turn may carry
+about 6% of the window as reference data — roughly 8 KB for a 32,000-token model
+and 32 KB for a 128,000-token one. A resource larger than that is not fetched at
+all, and the panel says so, naming the resource and both figures. The model is
+not told, because it cannot fetch a resource itself; the reader can act, by
+choosing a model with a larger window or asking you for a smaller resource.
+
+If you publish a large document through MCP, consider offering it in sections
+behind one tool that takes a section name, rather than as a single tool result.
+The list of section names in the tool's own schema costs a few hundred tokens
+and is visible to every client, while a document of tens of kilobytes crowds out
+the conversation it is supposed to support.
+
 ## Further reading
 
 - **The static-primitives extension** — `io.modelcontextprotocol/static-primitives`,

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.1"
 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.1
 platform: ruby
 authors:
 - jdkim