llm_meta_widget 0.13.1 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b72c0af2bf75bb5a7d1b83b0048aac15dc0485d86448ca4ea99403737c7a95ec
-  data.tar.gz: 1c5dfb8782859c09727fde1f996a39055c0cbe8e75b6116258b9d547a4a7b7a4
+  metadata.gz: 8797cb824bc5421990348a5de7fabd7eb95a0ec0c10f8e2d579d29d3483e7b29
+  data.tar.gz: 8151a9ab5e27e0e1bd1f46d62750e2a41137660d65c501713e9a10e94269858f
 SHA512:
-  metadata.gz: cf20127dce92b482a6c6a88a42e3a31fc2b80e127274c9cbae5e7d6f75d3043c9334e38459a7feddf90f0c985984f1a3cdced6550091953952ab44a9282fcf25
-  data.tar.gz: 5554707eda6744fdf8188c1c7d81765c27c068cb078a672d894825cb70f8f5c2c2e6ed4f3593f5a5432b7255bd7d0f01718c14804b1dcba9af661c0df7667a3c
+  metadata.gz: 12d33498cb17917ebc7f6a5950185b003267c52eab06f50e9632d36e5fd7e9c1bfe54d18134be7bc5e9082ff4c5e087769b0235983ff72aa6ec3dbd8461641af
+  data.tar.gz: 0f2975b8f85714bb11e64b43192755e26b61f90a9a80e6f20871895a76e292bfbb3f245c7e7f679e81331f1ab9be7d0362e91b8ce4e32b96d16ac10ce9eb8ded

data/CHANGELOG.md

@@ -3,6 +3,64 @@
 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.15.0
+
+### The declared global is resolved when a handler is needed, not at startup
+
+A page card is parsed from the DOM before the page's own scripts have
+necessarily run, and a consumer may be injected before them. Until now the
+widget looked up the global named by the card's `page-global` transport once, at
+startup, and kept the result: a page whose handler script ran later — with
+`defer`, as an ES module, or from a `<script>` near the end of the document —
+got no handlers at all for the rest of its life, with only a console warning to
+explain it.
+
+The lookup now happens each time a handler is wanted, so script order no longer
+matters. A global defined after the card was read is found; a global that
+disappears falls back to the older globals again instead of serving a stale map.
+
+The "declares a global the page never defines" message moved with it. At startup
+it was a false alarm, because the defining script may simply not have run yet;
+it is now said when a handler is actually wanted, and said once rather than on
+every lookup.
+
+This is what SEP-0000 asks of a consumer: handler availability is a runtime
+binding, and the burden sits on the consumer, which is the side that can know
+its own injection timing.
+
+### Two smaller fixes from the same conformance audit
+
+- A transport type declared twice was reported as "two blocks declare different
+  globals" even when a single block declared it twice. The message now covers
+  both cases.
+- A card addressed by `page_card_id:` — the escape hatch for a host that cannot
+  set the media type — was read without the merge step, which is where a
+  duplicated transport is caught. It was therefore the one path where that
+  authoring error went unreported. It now goes through the same check.
+
+Nothing a conformant page declares behaves differently, and no card needs
+changing.
+
+## 0.14.0
+
+### Breaking: a transport declared in top-level `remotes` is no longer read
+
+0.13.0 moved the declaration into
+`_meta["io.modelcontextprotocol/static-primitives"].transports` and kept reading
+the old top-level `remotes` list, with a warning, so that a page and a widget
+could be updated in either order. That transition is over.
+
+**If your page card still declares its transport in `remotes`, move it to
+`transports` before taking this release.** A card that still carries the old
+spelling gets no handlers from the card: the widget falls back to
+`window.aiActions`, `window.aiPrompts` and `window.aiResources`, which is
+nothing at all for a page that does not define them. The widget reports the
+situation in the browser console rather than leaving you to find it, but it
+cannot dispatch.
+
+Nothing else changed. If your card already declares `transports`, this release
+behaves exactly like 0.13.1.
+
 ## 0.13.1
 
 ### Documentation: the README caught up with 0.12.x and 0.13.0

data/README.md

@@ -61,7 +61,7 @@ Option 3 if it does not.
 
 ```ruby
 # Gemfile
-gem "llm_meta_widget", "~> 0.13.1"
+gem "llm_meta_widget", "~> 0.15.0"
 ```
 
 ```bash
@@ -152,26 +152,25 @@ 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.13"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@aibranch/llm-meta-widget@0.15"></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.13` is a version range, and it stops at 0.13.x on purpose.** You receive
+**`@0.15` is a version range, and it stops at 0.15.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.14 is therefore a change you make yourself. Read
+Moving to 0.16 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.
+0.13.0 moved where a page declares its transport, and 0.14.0 stopped reading
+the old spelling. Move your card to `transports` before taking 0.14.x.
 
 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
@@ -312,10 +311,10 @@ 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.
+Widgets from 0.11.1 to 0.12.2 read this declaration from a `remotes` list at the
+top level of the card, and 0.13.x read either spelling. From 0.14.0 the old one
+is not read at all: a card that still carries it gets no handlers, and the
+widget reports that in the browser console. Write `transports`.
 
 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
@@ -603,6 +602,18 @@ so no other consumer can rely on them. Each kind falls back on its own, so you
 can move tools into the declared global and leave prompts and resources where
 they are.
 
+**Script order does not matter.** The widget looks up your global at the moment
+it needs a handler, not when it reads the card. The script that defines
+`window.mcp` may therefore run before or after the widget loads: a `defer`
+attribute, an ES module, or a `<script>` near the end of the page are all fine.
+If a handler is wanted while the global is still undefined, the widget says so
+in the browser console once, and falls back to the older globals for that call.
+
+Before 0.15.0 the lookup happened once at startup, so a page whose handler
+script ran later got no handlers at all for the rest of its life, with only a
+console warning to say why. If you are pinned below 0.15.0, define your global
+before the widget's own script tag.
+
 **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

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

@@ -387,7 +387,11 @@ function boot(cfg) {
   			}));
   	} else {
   		var pageCardEl = document.getElementById(PAGE_CARD_ID);
-  		pageCard = readStaticPrimitivesCard(pageCardEl ? pageCardEl.textContent : null);
+  		// Through the merge as well, with one card: that is where a transport
+  		// declared twice is caught, and the escape hatch should not be the one
+  		// path where an authoring error goes unreported.
+  		pageCard = mergeStaticPrimitivesCards(
+  			[ readStaticPrimitivesCard(pageCardEl ? pageCardEl.textContent : null) ]);
   	}
   	// Where the page's handlers live. The card may declare a global, which is
 	// the only form an outside consumer can discover; the three legacy globals

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

@@ -701,35 +701,49 @@ function declaredPageGlobal(card, warn = console.warn) {
     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() !== "") {
-      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();
-    }
+  if ((card && card.remotes || []).some((r) => r && r.type === PAGE_GLOBAL_TRANSPORT)) {
+    warn(`[llm-meta-widget] page card declares its transport in top-level "remotes", which is no longer read. Move it to _meta["${STATIC_PRIMITIVES_META}"].transports`);
   }
   return null;
 }
 function pageHandlers({ card, scope = {}, legacy = {}, warn = console.warn } = {}) {
   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?`);
-  }
   const isMap = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+  const said = /* @__PURE__ */ new Set();
+  const sayOnce = (key, message) => {
+    if (said.has(key)) return;
+    said.add(key);
+    warn(message);
+  };
   const pick = (kind, legacyName) => {
+    const declared = name ? scope[name] : null;
+    if (name && !declared) {
+      sayOnce(
+        "missing",
+        `[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?`
+      );
+    }
     const fromGlobal = declared ? declared[kind] : void 0;
     if (isMap(fromGlobal)) return fromGlobal;
     if (declared && fromGlobal !== void 0 && !isMap(fromGlobal)) {
-      warn(`[llm-meta-widget] window.${name}.${kind} is ${Array.isArray(fromGlobal) ? "an array" : typeof fromGlobal}; it must be an object keyed by ${kind === "resources" ? "uri" : "name"}`);
+      sayOnce(
+        `shape:${kind}`,
+        `[llm-meta-widget] window.${name}.${kind} is ${Array.isArray(fromGlobal) ? "an array" : typeof fromGlobal}; it must be an object keyed by ${kind === "resources" ? "uri" : "name"}`
+      );
     }
     return legacyName && scope[legacyName] || {};
   };
   return {
     global: name,
-    tools: pick("tools", legacy.tools),
-    prompts: pick("prompts", legacy.prompts),
-    resources: pick("resources", legacy.resources)
+    get tools() {
+      return pick("tools", legacy.tools);
+    },
+    get prompts() {
+      return pick("prompts", legacy.prompts);
+    },
+    get resources() {
+      return pick("resources", legacy.resources);
+    }
   };
 }
 function mergeStaticPrimitivesCards(cards, warn = console.warn) {
@@ -740,7 +754,7 @@ function mergeStaticPrimitivesCards(cards, warn = console.warn) {
         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}"`);
+          warn(`[llm-meta-widget] the ${entry.type} transport is declared more than once, with different globals ("${clash.global}" and "${entry.global}"); using "${clash.global}". One block may declare it twice, or two blocks may disagree`);
           continue;
         }
         if (!merged[kind].some((r) => r.type === entry.type && r.global === entry.global)) {
@@ -4167,7 +4181,9 @@ function boot(cfg) {
     );
   } else {
     var pageCardEl = document.getElementById(PAGE_CARD_ID);
-    pageCard = readStaticPrimitivesCard(pageCardEl ? pageCardEl.textContent : null);
+    pageCard = mergeStaticPrimitivesCards(
+      [readStaticPrimitivesCard(pageCardEl ? pageCardEl.textContent : null)]
+    );
   }
   var handlers = pageHandlers({
     card: pageCard,

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

@@ -1130,10 +1130,9 @@ export const PAGE_GLOBAL_TRANSPORT = "page-global"
 // `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.
+// Top-level `remotes` is the pre-d44bd25a shape that 0.11.1 to 0.12.2 read and
+// 0.13.x accepted. It is no longer read, but a card still carrying it is
+// reported, because the alternative is a page that quietly stops working.
 export function declaredPageGlobal(card, warn = console.warn) {
   const declared = (card && card.transports) || []
   for (const transport of declared) {
@@ -1149,14 +1148,14 @@ export function declaredPageGlobal(card, warn = console.warn) {
     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() !== "") {
-      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()
-    }
+  // No longer read. Reporting it is still worth a few lines: without this a
+  // card that declares its transport only in the old place gets no handlers,
+  // falls through to the legacy globals, and a page that deliberately defines
+  // none — as PubDictionaries does — simply stops working with nothing said.
+  if (((card && card.remotes) || []).some((r) => r && r.type === PAGE_GLOBAL_TRANSPORT)) {
+    warn('[llm-meta-widget] page card declares its transport in top-level ' +
+         '"remotes", which is no longer read. Move it to ' +
+         `_meta["${STATIC_PRIMITIVES_META}"].transports`)
   }
   return null
 }
@@ -1166,19 +1165,36 @@ export function declaredPageGlobal(card, warn = console.warn) {
 // 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, warn)
-  const declared = name ? scope[name] : null
-
-  // A card that names a global the page never defines is almost always a load
-  // order problem, or a script that threw before it got there. Falling back in
-  // silence hides that: the page then behaves as if it had declared nothing,
-  // and the first symptom is a prompt or tool that "has no handler".
-  if (name && !declared) {
-    warn(`[llm-meta-widget] the page card declares global "${name}", but window.${name} ` +
-         "is not defined — is the script that defines it loaded, and did it run?")
+  const isMap = (v) => !!v && typeof v === "object" && !Array.isArray(v)
+
+  // Each said at most once. These now fire on dispatch rather than at mount, so
+  // a page that never defines its global would otherwise repeat them every turn.
+  const said = new Set()
+  const sayOnce = (key, message) => {
+    if (said.has(key)) return
+    said.add(key)
+    warn(message)
   }
 
-  const isMap = (v) => !!v && typeof v === "object" && !Array.isArray(v)
   const pick = (kind, legacyName) => {
+    // Resolved HERE, when a handler is wanted, not when the card was read. The
+    // card is parsed from the DOM before the page's own scripts have
+    // necessarily run, and a consumer may be injected before them, so a global
+    // that is missing at discovery may well be defined by the time a tool is
+    // called. Caching that first lookup turned a load-order detail into a page
+    // that silently had no handlers for the rest of its life.
+    const declared = name ? scope[name] : null
+
+    // A card that names a global the page never defines is almost always a load
+    // order problem, or a script that threw before it got there. Falling back in
+    // silence hides that: the page then behaves as if it had declared nothing,
+    // and the first symptom is a prompt or tool that "has no handler".
+    if (name && !declared) {
+      sayOnce("missing",
+              `[llm-meta-widget] the page card declares global "${name}", but window.${name} ` +
+              "is not defined — is the script that defines it loaded, and did it run?")
+    }
+
     // `declared ? … : undefined`, not `declared && …`: the second yields null
     // when nothing is declared, and `typeof null === "object"`, so the check
     // below then warned about "window.null.tools" on every page with no card.
@@ -1187,16 +1203,20 @@ export function pageHandlers({ card, scope = {}, legacy = {}, warn = console.war
     // An array is the mistake worth naming: it passes a typeof check, so it
     // would be used as a map and answer every lookup with undefined.
     if (declared && fromGlobal !== undefined && !isMap(fromGlobal)) {
-      warn(`[llm-meta-widget] window.${name}.${kind} is ${Array.isArray(fromGlobal) ? "an array" : typeof fromGlobal}; ` +
-           `it must be an object keyed by ${kind === "resources" ? "uri" : "name"}`)
+      sayOnce(`shape:${kind}`,
+              `[llm-meta-widget] window.${name}.${kind} is ${Array.isArray(fromGlobal) ? "an array" : typeof fromGlobal}; ` +
+              `it must be an object keyed by ${kind === "resources" ? "uri" : "name"}`)
     }
     return (legacyName && scope[legacyName]) || {}
   }
+
+  // Getters, so each dispatch re-resolves. The call sites read
+  // `handlers.tools` at the moment they need it, which is what makes this work.
   return {
     global: name,
-    tools: pick("tools", legacy.tools),
-    prompts: pick("prompts", legacy.prompts),
-    resources: pick("resources", legacy.resources)
+    get tools() { return pick("tools", legacy.tools) },
+    get prompts() { return pick("prompts", legacy.prompts) },
+    get resources() { return pick("resources", legacy.resources) }
   }
 }
 
@@ -1225,8 +1245,9 @@ export function mergeStaticPrimitivesCards(cards, warn = console.warn) {
         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}"`)
+          warn(`[llm-meta-widget] the ${entry.type} transport is declared more than once, ` +
+               `with different globals ("${clash.global}" and "${entry.global}"); using ` +
+               `"${clash.global}". One block may declare it twice, or two blocks may disagree`)
           continue
         }
         if (!merged[kind].some((r) => r.type === entry.type && r.global === entry.global)) {

data/lib/llm_meta_widget/version.rb

@@ -1,3 +1,3 @@
 module LlmMetaWidget
-  VERSION = "0.13.1"
+  VERSION = "0.15.0"
 end

metadata

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