llm_meta_widget 0.9.1 → 0.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6dba4c1cd88e26bde9f0179009ae2f47cdd07a30aae6035e619f0ca5b83d32e
-  data.tar.gz: 95cca5b804adab95a89dfbdf23b7624cb43304462d4cf6c72a605a7ebef170de
+  metadata.gz: 451052ef64f425f3944991ffb56c4c3990beb5703832d13dcda11eb27d91511e
+  data.tar.gz: 3d408043ea3d236ba7ac0c6a96d28a944d775866a6dc025940eb0bb51a87fafc
 SHA512:
-  metadata.gz: d2c499f1d83a689e52fff3fabb0cc08f359c4d34571295085718f3fa5b8c13ccf565f6f47c9ae73b210f1bea350581e7e1c4ae47ac27a759116364518fce2bd2
-  data.tar.gz: bb45042dcae5849cf88750d8d6235416fda8e531f0852ed454405c59c4358ff3c31137b78349b6b87be8fc490c3235de62b5b9bebd4f0a61cea790c0cf0925ba
+  metadata.gz: a0de8fbfee7c44435077225f675aebc77558a707494a763215e82185ad4b73ba1f8eff65df9f2f6d820f5f0c66b6ff9934bc72bf601285adcf2b1968081f10b2
+  data.tar.gz: b325fed836e89c214b497575e1eead985d0548299938ad32a5a00751b4fc1d3846162c0e0b798e8668beda7bb77945457d50a5fe10080940b177879c4c3134c6

data/CHANGELOG.md

@@ -3,6 +3,92 @@
 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.10.1
+
+Documentation only. The 0.10.0 release notes and the README section on the page
+card were written after that release was published, so the copies on RubyGems
+and npm still described 0.9.1. There is no code change: a page running 0.10.0
+behaves exactly as one running 0.10.1.
+
+## 0.10.0
+
+### Changed: a page card is found by its media type
+
+A card inside a page is now located by the `type` attribute of its `<script>`
+element, not by an `id`:
+
+```html
+<script type="application/mcp-static-primitives+json"> … </script>
+```
+
+A client matches `script[type="application/mcp-static-primitives+json"]`, so the
+element needs no `id`. This follows SEP-0000's "HTML-delivery mode". The reason
+for the change: an `id` that each page chooses cannot be found by a client that
+was not told the id, so an `id` cannot serve as a locator.
+
+**Existing pages keep working.** When no block carries the media type, the widget
+reads `page_card_id:` (still `"ai-page"` by default) exactly as before. That
+option is now only an escape hatch for a host that cannot set the type. Pages
+using it should move to the media type, because the fallback may be removed in a
+later release.
+
+### Added: a document may hold several cards
+
+A page built from components can give each component its own card block. The
+widget reads every block and joins the arrays by primitive type.
+
+Declaring the same tool or prompt `name`, or the same resource `uri`, in two
+blocks is an error: every copy is dropped and a message naming it is written to
+the console. The first block does not win, because which block comes first
+depends on the order the page's parts are rendered in, and the page author did
+not choose that order.
+
+A block whose JSON cannot be read costs only that block. The other blocks still
+load.
+
+## 0.9.1
+
+### Fixed: prompt arguments were empty on a page that declares resources
+
+A prompt's arguments are looked up by plain name (`text`), while page resources
+are addressed by URI (`page:text`). A page that kept its state in resources and
+had no `window.aiState` therefore had every prompt argument arrive empty, and
+the person was asked to type in something the page could already see.
+
+Page resources now fill prompt arguments of the matching name. An explicit
+`window.aiState` entry still wins, so a page running both channels keeps the
+behaviour it declared.
+
+## 0.9.0
+
+### Added: the page card
+
+A page can declare its tools, prompts and resources in one block of JSON, using
+the same envelope an MCP server puts in its Server Card. Three globals hold the
+handlers, each keyed by the identifier its own MCP operation takes:
+
+| declared in the card | implemented in | keyed by |
+|---|---|---|
+| `tools` | `window.aiActions` | tool `name` |
+| `prompts` | `window.aiPrompts` | prompt `name` |
+| `resources` | `window.aiResources` | resource `uri` |
+
+See "The page card" in the README. Nothing is required: a page that declares no
+card behaves as before, and a page that declares no `tools` still uses its
+`ai-actions` block.
+
+Page resources are addressed `page:<name>`. That scheme is experimental and
+unregistered.
+
+## 0.8.6
+
+### Changed: a resource's size is declared in the base `size` field
+
+`size` on the resource entry replaces `_meta…sizeBytes`, following the change to
+the base MCP `Resource` interface. `sizeBytes` is still read if `size` is absent,
+and is still reported for now; both will be removed in a later release. Servers
+should emit `size`.
+
 ## 0.8.0
 
 ### Breaking: state readers must declare a description

data/README.md

@@ -402,7 +402,7 @@ translate directly.
 | `api_key_uuid:` | `"ollama-local"` | Hub API-key uuid to invoke |
 | `element_path:` | `"/llm_meta_widget_assets/llm-meta-widget.js"` | The bundled element the page loads. Served by the gem's engine; override to load it from elsewhere |
 | `actions_schema_id:` | `"ai-actions"` | DOM id of the Class-3 schema block |
-| `page_card_id:` | `"ai-page"` | DOM id of the page card (see "The page card"). Its tools replace the `actions_schema_id` block |
+| `page_card_id:` | `"ai-page"` | **Fallback only.** A card is normally found by its media type (see "The page card"); this id is read when the page has no block with that type. Its tools replace the `actions_schema_id` block |
 | `prompts_global:` | `"aiPrompts"` | Global object holding page prompt handlers, keyed by prompt name |
 | `resources_global:` | `"aiResources"` | Global object holding page resource readers, keyed by resource URI |
 | `state_global:` | `"aiState"` | Global window object holding Class-3 state readers, each `{ description, read }` (see the breaking change in 0.8.0) |
@@ -424,7 +424,7 @@ an MCP server puts in its Server Card, so the page and the server describe
 themselves the same way.
 
 ```html
-<script type="application/json" id="ai-page">
+<script type="application/mcp-static-primitives+json">
 { "_meta": { "io.modelcontextprotocol/static-primitives": {
     "tools":     [ { "name": "set_text", "description": "…", "inputSchema": { } } ],
     "prompts":   [ { "name": "annotate", "description": "Annotate this page" } ],
@@ -466,6 +466,21 @@ fetch from the web by itself — which page resources are not. The form is
 `page:<name>` with no path, because a page has only one namespace. Expect this to
 change.
 
+**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
+it, and it follows SEP-0000's "HTML-delivery mode". The `page_card_id:` option
+is kept only for a host that cannot set the type; it is read when no block with
+the media type is present.
+
+**A document may hold several blocks.** A page built from components can let
+each component declare its own primitives, and the arrays join by primitive
+type. Declaring the same tool or prompt `name`, or the same resource `uri`,
+twice is an error: every copy is dropped and a message is written to the
+console. The first one does not win, because which block comes first depends on
+the order the page's parts are rendered in, and that is not something the author
+chose.
+
 **The card is optional.** A page that declares nothing keeps working exactly as
 before, and a page that declares no `tools` still uses its `ai-actions` block.
 

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

@@ -25,7 +25,8 @@ import { runChatLoop, fetchMcpManifest, listMcpPrompts, getMcpPrompt,
          createConversationStore, conversationKeyFor,
          readStaticPrimitivesCard, getPagePrompt,
          planPageResources, pageResourceLinesForTurn,
-         promptArgState } from "./orchestrator.js";
+         promptArgState, mergeStaticPrimitivesCards,
+         PAGE_CARD_MEDIA_TYPE } from "./orchestrator.js";
 import { marked } from "./marked.esm.js";
 import { readConfig } from "./config.js";
 import conversationCss from "../../stylesheets/llm_meta_widget/conversation.css";
@@ -306,8 +307,24 @@ function boot(cfg) {
   	// older #ai-actions schema tag rather than merging with it: two sources
   	// for one list means a reader has to work out which the page meant, and a
   	// handler in window.aiActions answers to a name either way.
-  	var pageCardEl = document.getElementById(PAGE_CARD_ID);
-  	var pageCard = readStaticPrimitivesCard(pageCardEl ? pageCardEl.textContent : null);
+  	//
+  	// Discovery is by MEDIA TYPE, which is the locator the spec defines: an id
+  	// the page chooses cannot be found by a client that was not told it.
+  	// Several blocks may appear, so a page built from components can let each
+  	// one declare its own primitives. `page-card-id` survives only as an escape
+  	// hatch for a host that cannot set the type, and is read when no typed
+  	// block is present.
+  	var typedCards = document.querySelectorAll('script[type="' + PAGE_CARD_MEDIA_TYPE + '"]');
+  	var pageCard;
+  	if (typedCards.length) {
+  		pageCard = mergeStaticPrimitivesCards(
+  			Array.prototype.map.call(typedCards, function(el) {
+  				return readStaticPrimitivesCard(el.textContent);
+  			}));
+  	} else {
+  		var pageCardEl = document.getElementById(PAGE_CARD_ID);
+  		pageCard = readStaticPrimitivesCard(pageCardEl ? pageCardEl.textContent : null);
+  	}
   	var actionsSchemaEl = document.getElementById(ACTIONS_SCHEMA_ID);
   	var localTools = pageCard.tools.length
   		? pageCard.tools

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

@@ -560,6 +560,25 @@ function parseSseFrame(raw) {
   return { name, data };
 }
 var STATIC_PRIMITIVES_META = "io.modelcontextprotocol/static-primitives";
+var PAGE_CARD_MEDIA_TYPE = "application/mcp-static-primitives+json";
+function mergeStaticPrimitivesCards(cards, warn = console.warn) {
+  const merged = { tools: [], prompts: [], resources: [] };
+  const keyOf = { tools: "name", prompts: "name", resources: "uri" };
+  for (const kind of ["tools", "prompts", "resources"]) {
+    const key = keyOf[kind];
+    const all = [];
+    for (const card of cards || []) all.push(...card && card[kind] || []);
+    const counts = /* @__PURE__ */ new Map();
+    for (const entry of all) counts.set(entry[key], (counts.get(entry[key]) || 0) + 1);
+    for (const [id, n] of counts) {
+      if (n > 1) {
+        warn(`[llm-meta-widget] the page declares ${kind} "${id}" ${n} times; dropping every copy \u2014 remove the duplicate to say which one you mean`);
+      }
+    }
+    merged[kind] = all.filter((entry) => counts.get(entry[key]) === 1);
+  }
+  return merged;
+}
 function readStaticPrimitivesCard(text, warn = console.warn) {
   const empty = { tools: [], prompts: [], resources: [] };
   if (typeof text !== "string" || text.trim() === "") return empty;
@@ -3900,8 +3919,18 @@ function boot(cfg) {
       model: MODEL
     });
   }
-  var pageCardEl = document.getElementById(PAGE_CARD_ID);
-  var pageCard = readStaticPrimitivesCard(pageCardEl ? pageCardEl.textContent : null);
+  var typedCards = document.querySelectorAll('script[type="' + PAGE_CARD_MEDIA_TYPE + '"]');
+  var pageCard;
+  if (typedCards.length) {
+    pageCard = mergeStaticPrimitivesCards(
+      Array.prototype.map.call(typedCards, function(el) {
+        return readStaticPrimitivesCard(el.textContent);
+      })
+    );
+  } else {
+    var pageCardEl = document.getElementById(PAGE_CARD_ID);
+    pageCard = readStaticPrimitivesCard(pageCardEl ? pageCardEl.textContent : null);
+  }
   var actionsSchemaEl = document.getElementById(ACTIONS_SCHEMA_ID);
   var localTools = pageCard.tools.length ? pageCard.tools : actionsSchemaEl ? JSON.parse(actionsSchemaEl.textContent) : [];
   var remoteToolsEl = document.getElementById(REMOTE_TOOLS_SCHEMA_ID);

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

@@ -879,6 +879,43 @@ export const STATIC_PRIMITIVES_META = "io.modelcontextprotocol/static-primitives
 // typo in it should cost that one entry, not the assistant. Everything
 // unparseable returns empty arrays and says so on the console, which is how
 // aiState already treats a reader missing its description.
+// The media type that locates a card inside an HTML document. It is the
+// locator, so it is NOT configurable: a client that has to be told where to
+// look cannot discover anything. SEP-0000, "HTML-delivery mode".
+export const PAGE_CARD_MEDIA_TYPE = "application/mcp-static-primitives+json"
+
+// Several blocks may appear in one document, so that a page assembled from
+// components can let each component declare its own primitives. The arrays
+// concatenate by primitive type.
+//
+// A duplicate identifier across blocks is an ERROR, not a precedence puzzle:
+// the spec says a client should report it and should not silently pick one. So
+// every copy of a duplicated identifier is dropped and the author is told.
+// 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 = { tools: [], prompts: [], resources: [] }
+  const keyOf = { tools: "name", prompts: "name", resources: "uri" }
+
+  for (const kind of [ "tools", "prompts", "resources" ]) {
+    const key = keyOf[kind]
+    const all = []
+    for (const card of cards || []) all.push(...((card && card[kind]) || []))
+
+    const counts = new Map()
+    for (const entry of all) counts.set(entry[key], (counts.get(entry[key]) || 0) + 1)
+
+    for (const [ id, n ] of counts) {
+      if (n > 1) {
+        warn(`[llm-meta-widget] the page declares ${kind} "${id}" ${n} times; ` +
+             "dropping every copy — remove the duplicate to say which one you mean")
+      }
+    }
+    merged[kind] = all.filter((entry) => counts.get(entry[key]) === 1)
+  }
+  return merged
+}
+
 export function readStaticPrimitivesCard(text, warn = console.warn) {
   const empty = { tools: [], prompts: [], resources: [] }
   if (typeof text !== "string" || text.trim() === "") return empty

data/lib/llm_meta_widget/version.rb

@@ -1,3 +1,3 @@
 module LlmMetaWidget
-  VERSION = "0.9.1"
+  VERSION = "0.10.1"
 end

metadata

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