llm_meta_widget 0.14.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e67bd92aa30299ffd0f7d6e3a9291dc5c398800cf9276b04768101077e212880
-  data.tar.gz: 487c187c3d20631b38f72cc4b6b9241db285ae5a7e2e5e5ef50f814bcb8cee42
+  metadata.gz: 8797cb824bc5421990348a5de7fabd7eb95a0ec0c10f8e2d579d29d3483e7b29
+  data.tar.gz: 8151a9ab5e27e0e1bd1f46d62750e2a41137660d65c501713e9a10e94269858f
 SHA512:
-  metadata.gz: 39e08820f2551e2eccd15b71b7bba68e2342911cb7ec57de0b1f9ee8d26a720b8e36283f2c033a019fe206de3dc1d10b4337c5fedaee94a39c72ba9482c36bcc
-  data.tar.gz: e373ab9a30c2274817d7fae2da1bdea107d024c92f6204af3ae404debcbc22011b6de131bfaf6d25205d420f8f1b98ce8e9328220dcff81ae8142822dbec2a6e
+  metadata.gz: 12d33498cb17917ebc7f6a5950185b003267c52eab06f50e9632d36e5fd7e9c1bfe54d18134be7bc5e9082ff4c5e087769b0235983ff72aa6ec3dbd8461641af
+  data.tar.gz: 0f2975b8f85714bb11e64b43192755e26b61f90a9a80e6f20871895a76e292bfbb3f245c7e7f679e81331f1ab9be7d0362e91b8ce4e32b96d16ac10ce9eb8ded

data/CHANGELOG.md

@@ -3,6 +3,44 @@
 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

data/README.md

@@ -61,7 +61,7 @@ Option 3 if it does not.
 
 ```ruby
 # Gemfile
-gem "llm_meta_widget", "~> 0.14.0"
+gem "llm_meta_widget", "~> 0.15.0"
 ```
 
 ```bash
@@ -152,17 +152,17 @@ 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.14"></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.14` is a version range, and it stops at 0.14.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.15 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
@@ -602,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

@@ -708,24 +708,42 @@ function declaredPageGlobal(card, warn = console.warn) {
 }
 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) {
@@ -736,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)) {
@@ -4163,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

@@ -1165,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.
@@ -1186,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) }
   }
 }
 
@@ -1224,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.14.0"
+  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.14.0
+  version: 0.15.0
 platform: ruby
 authors:
 - jdkim