@aibranch/llm-meta-widget 0.14.0 → 0.15.0

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

package/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,

package/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)) {

package/package.json

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