wiki-formant 0.12.0 → 0.15.0

package/README.md

@@ -123,11 +123,16 @@ What it gets right:
 - **Batches are capped** (default 20) with a teaching error, because the rate limiter charges one token per HTTP request before the body is parsed. Under 2025-06-18 they are refused outright, because the revision removed them.
 - **The protocol version is negotiated, not asserted.** `initialize` echoes what the client asked for when it is one of `2025-06-18`, `2025-03-26` or `2024-11-05`, and offers the newest otherwise; every response carries the negotiated version back in `MCP-Protocol-Version`. Answering a constant is legal and still costs the caller structured output, tool titles and `_meta` without ever saying so.
 - **`Access-Control-Expose-Headers` is set.** Allow-Headers governs what a browser may send, Expose-Headers what it may read — without the second a browser client cannot see `Retry-After` on a 429, and a rate limit presents as a hang.
+- **The rate limit is declared, not wired.** Put `rateLimit: {capacity, refillPerSec}` on the config and `mcpResponse` enforces it before parsing the body, refuses with a JSON-RPC envelope, and states `RateLimit-Limit`/`-Remaining`/`-Reset` on every answer. Four routes had each transcribed that by hand through three differently-named local helpers, which is how a headroom header gets added to one surface and forgotten on the next.
 - **`mcpRateLimited(retryAfterSec)` is a JSON-RPC envelope.** A 429 whose body is `{"error": "..."}` is a string where the client's parser expects `{code, message}`, on the one response an agent meets exactly when it is working hard.
 
 ### Structured output, `_meta`, and the envelope gate
 
-Declare an `outputSchema` and the result carries `structuredContent` beside the text block, so a client reads the answer rather than scraping prose for it. A handler's second argument is its context:
+**Every object a handler returns comes back as `structuredContent` beside the text block**, so a client reads the answer rather than scraping prose for it. This used to be gated on declaring an `outputSchema`, and the result was that across four live servers and thirty-two tools — every one of them answering in JSON — not a single response ever carried it. `outputSchema` remains the stronger contract, because a client validates against it; it is no longer the price of admission. A handler returning a string is left alone.
+
+`inputSchema.requireOneOf` names a set of which at least one must be present. `required` cannot express "query or popular", so the one tool needing it checked in its handler and the caller learned at execution time — the single class of argument mistake this module was otherwise catching before dispatch.
+
+A handler's second argument is its context:
 
 ```ts
 handler: async (args, ctx) => {
@@ -139,6 +144,20 @@ handler: async (args, ctx) => {
 
 `config.gate` is envelope-level middleware: it may withhold entries before dispatch and merge its own responses back afterwards. A payment gate has to sit there rather than in a handler, because the demand *replaces* the call and the receipt rides on the envelope.
 
+## Conformance
+
+`wiki-formant/conformance` is the half of an MCP conformance run that is not about any one server's tools: a JSON-RPC client that backs off on a 429, the transport assertions (CORS preflight, `GET`→405, a notification answering 202 with no body, `-32700`, the batch cap, honest `capabilities`, version negotiation), version coherence across every descriptor a surface publishes, A2A card parity, conditional-GET and `robots` checks, and a pass/fail table with an exit code.
+
+```ts
+const t = createTester({ base: 'https://example.com', clientName: 'my-mcp-test' });
+await transportChecks(t, 'my-mcp-test');
+await annotationChecks(t, { writes: ['create_page'] });
+await payloadBudget(t, [{ name: 'search', args: { query: 'x' } }]);
+process.exit(t.summary());
+```
+
+What stays in your repo is fixtures: which tools you expect, what a good answer from each looks like, and which text surfaces you publish. `payloadBudget` weighs every listed call **and** every read-only tool that takes no required arguments, because the one tool nobody thought to list is the one that answers with 3.3 MB; pass a per-call `maxBytes` for a bulk-export tool that is deliberately large. It also asserts that a JSON answer arrived with `structuredContent`.
+
 ## Markdown twins
 
 Pass an `etag` and answer `notModified` before rendering: a twin is the single most recrawled URL a page has, so a twin with no validator is a full render on every pass, forever — the same arithmetic that justifies the corpus ETag, applied per page.
@@ -245,7 +264,9 @@ are unit-tested without a DOM.
 
 `FacetBar` renders the rows `createTaxonomy` already produces. This is why the taxonomy exports a rows model rather than markup: the rows could always cross the boundary and, until this subpath existed, the markup could not, so all three wikis hand-rendered it and two put `aria-pressed` on an `<a>`. `Breadcrumbs` renders the trail and its `BreadcrumbList` JSON-LD together, because a trail whose structured data is written somewhere else is a trail that will one day disagree with its own markup — which is the case Google penalises. It takes a `base` origin: structured-data URLs must be absolute and a package cannot know the site.
 
-`WikiRail` stays in `wiki-formant/react`, because it calls `useSidebar` and genuinely is a client component. It renders the whole `wiki-rail__*` tree — scroll wrapper, both labelled `<nav>`s, the table of contents between them — where three wikis had drifted on which of those they had.
+`PageNav` is the previous/next pair at the foot of an article — the sequential read the infobox rail's lateral links do not cover. Ordering is the caller's, because it is the one part that is never portable: a wiki's sequence is its section's configured sort, a knowledge base's is a taxonomy walk. Pair it with `adjacentPages` from `wiki-formant/pagination` over a list you already hold — neither wiki needs a query for it, and the two indexed lookups the neighbours used to cost were the reason one of them dropped the control.
+
+`RailShell` stays in `wiki-formant/react`, because it calls `useSidebar` and genuinely is a client component. It renders the rail's landmark, its scroll wrapper and the three collapse states — including the `--instant` class that keeps a remembered-closed rail from animating shut on first paint, and the close-on-tap that a mobile rail needs. Compose your own rail inside it and mark the active link with `isRailLinkActive`; all three wikis do, and the pre-composed component that used to sit here had one consumer and had already lost both of those behaviours.
 
 All three take the router's link component as a prop:
 
@@ -400,30 +421,15 @@ they name a gap in the corpus in the reader's own words.
 
 ## API
 
-| Export | From |
-|---|---|
-| `createTaxonomy`, `defaultHref`, `firstLetter`, `toggleFilter` | `wiki-formant/taxonomy` |
-| `injectHeadingIds`, `headingsFrom`, `slugifyHeading` | `wiki-formant/headings` |
-| `mcpResponse`, `mcpGet`, `mcpOptions`, `handleMcp`, `withMcpCors`, `McpToolError`, `MCP_CORS`, `MCP_PROTOCOL_VERSION` | `wiki-formant/mcp` |
-| `htmlToMarkdown`, `inlineToMarkdown`, `tableToMarkdown`, `frontmatter`, `markdownDocument`, `decodeEntities` | `wiki-formant/markdown` |
-| `corpusEtag`, `notModified`, `textHeaders`, `markdownHeaders`, `descriptorHeaders`, `descriptorResponse`, `cleanSnippet`, `pageLine` | `wiki-formant/http` |
-| `parsePagination`, `paginatedResponse`, `toOffset` | `wiki-formant/pagination` |
-| `mapBlockTree`, `mapBlockTreeAsync`, `someBlock`, `renderBlockTree` | `wiki-formant/blocks` |
-| `parseVersion`, `formatVersion`, `incrementVersion`, `bump`, `compareVersions` | `wiki-formant/versioning` |
-| `plausibleEvent`, `mcpCallProps`, `searchQueryProps`, `plausibleDomain` | `wiki-formant/analytics` |
-| `comboboxAria`, `listId`, `optionId` | `wiki-formant/combobox` |
-| `computeRevisionDiff`, `diffBlocks`, `extractBlocks`, `classifyChanges`, `changeSummary` | `wiki-formant/revisions` |
-| `renderFeed`, `renderItem`, `escXml`, `cdata`, `clampWords`, `absolutise`, `FEED_HEADERS` | `wiki-formant/feed` |
-| `ccBy40`, `licenseBlock`, `licenseLines`, `licenseNote` | `wiki-formant/license` |
-| `AI_CRAWLERS`, `detectAiBot`, `aiCrawlerTokens`, `aiCrawlerRules` | `wiki-formant/crawlers` |
-| `useCollapsibleSidebar`, `SidebarProvider`, `useSidebar`, `TableOfContents`, `useTypeahead`, `useLinkPreview`, `useClickOutside`, `useTableSort`, `useCopy`, `ErrorBoundary`, `WikiRail` | `wiki-formant/react` |
-| `FacetBar`, `Breadcrumbs` | `wiki-formant/react-server` |
-| `gatePaidCalls` | `wiki-formant/x402` |
-| `resolveSidebarOpen`, `sidebarBootScript`, `SIDEBAR_ATTRIBUTE` | `wiki-formant/sidebar` |
-| `addCopyButtons`, `activateTabGroups`, `tweetEmbedSrc`, `onTweetResize`, `hydrateTweetEmbeds`, `sizeTweetEmbeds`, `TWITTER_ORIGIN` | `wiki-formant/dom` |
-| `Iframe`, `YouTube`, `TwitterEmbed`, `createMapEmbed`, `createCodeBlock`, `createTabs` | `wiki-formant/tiptap` |
-
-Everything above `wiki-formant/react` is also re-exported from the package root. The React, sidebar, DOM, tiptap, react-server and x402 subpaths are not: they carry `'use client'`, reach for a browser global, or need a peer the root must not assume, and the root has to stay importable from a route handler.
+Every module has a subpath — `wiki-formant/taxonomy`, `wiki-formant/mcp`, and so on.
+The emitted `.d.ts` files are the reference. There is no hand-maintained symbol list
+here, because the one that used to be here drifted from them.
+
+The package root re-exports the runtime modules that need no peer dependency and no
+client boundary, so `import … from 'wiki-formant'` stays importable from a route
+handler with nothing else installed. Everything that reaches for React, a browser
+global, tiptap or a wallet — and the tooling modules, which no route imports — is
+subpath-only.
 
 ## A bin
 

package/bin/check-classes.mjs

@@ -113,7 +113,6 @@ for (const [tok, at] of [...dead].sort((a, b) => b[1].length - a[1].length)) {
   console.error(`  ${tok.padEnd(24)} ${String(at.length).padStart(3)}x  ${at.slice(0, 4).join(', ')}${at.length > 4 ? ', …' : ''}`);
 }
 // Derived, not hardcoded: this runs in every sibling project and their
-// globals.css does not sit at the same path.
-const globals = walk(SRC_DIR, '.css').find(f => f.endsWith('globals.css')) ?? 'your globals.css';
-console.error(`\nEither define it in ${globals} or delete the usage.`);
+// globals.css does not sit at the same path. Found once, above.
+console.error(`\nEither define it in ${globalsFile ?? 'your globals.css'} or delete the usage.`);
 process.exit(WARN_ONLY ? 0 : 1);

package/dist/analytics.d.ts

@@ -62,4 +62,3 @@ export interface SearchQueryInput {
 export declare function searchQueryProps({ query, results, surface, }: SearchQueryInput): Record<string, string> | null;
 /** The hostname of a site URL, for the `domain` a Plausible property is filed under. */
 export declare function plausibleDomain(siteUrl: string | undefined, fallback: string): string;
-//# sourceMappingURL=analytics.d.ts.map

package/dist/analytics.js

@@ -88,4 +88,3 @@ export function plausibleDomain(siteUrl, fallback) {
         return fallback.replace(/^https?:\/\//, '').replace(/\/.*$/, '');
     }
 }
-//# sourceMappingURL=analytics.js.map

package/dist/block-views.d.ts

@@ -0,0 +1,97 @@
+import { type ReactNode } from 'react';
+import type { CodeTab, LinkGridGroup, ReferenceItem, StatItem } from './blocks.js';
+import type { WikiLinkComponent } from './react-server.js';
+/**
+ * Tabbed code samples. Every tab's body stays mounted and the inactive ones are
+ * hidden rather than unmounted: the panels carry pre-highlighted markup, and
+ * remounting one would re-run whatever the consumer's highlighter attached to
+ * it on every tab press.
+ */
+export declare function CodeTabsView({ tabs }: {
+    tabs: readonly CodeTab[];
+}): import("react").JSX.Element | null;
+export interface ColumnsViewProps<B extends {
+    id: string;
+}> {
+    columns: ReadonlyArray<{
+        id: string;
+        blocks?: readonly B[];
+    }>;
+    gap?: 'sm' | 'md' | 'lg';
+    align?: 'start' | 'center' | 'end' | 'stretch';
+    /** The caller's own dispatch, because the block union is the caller's. */
+    render: (block: B) => ReactNode;
+}
+/**
+ * A row of columns, each holding blocks the caller renders.
+ *
+ * Children are wrapped in a `Fragment`, not a `<div>`. One repo used a div and
+ * it was a layout bug rather than a style: `.column-view` is the flow context
+ * its stylesheet spaces children in, and an extra element between them means
+ * every gap rule inside a column silently matches nothing.
+ */
+export declare function ColumnsView<B extends {
+    id: string;
+}>({ columns, gap, align, render, }: ColumnsViewProps<B>): import("react").JSX.Element;
+/**
+ * Banded groups of link pills.
+ *
+ * A link whose href fails `safeLinkHref` is DROPPED, not rendered inert. These
+ * hrefs are author-supplied, and a `javascript:` URL fails the http test above
+ * — so without the guard it falls through to the router's link component, which
+ * renders it looking like an ordinary pill and executes it on click.
+ */
+export declare function LinkGridView({ groups, intro, link: Link, }: {
+    groups?: readonly (LinkGridGroup & {
+        id?: string;
+    })[];
+    intro?: string;
+    link?: WikiLinkComponent;
+}): import("react").JSX.Element;
+/**
+ * The numbered citation list, with the `#cite-n` back-links the inline markers
+ * point at. `processHtml` is a prop because only one wiki runs reference text
+ * through its HTML pipeline, and running it in the other would rewrite anchors
+ * that were minted under different rules.
+ */
+export declare function ReferencesView({ items, title, processHtml, }: {
+    items?: readonly (ReferenceItem & {
+        id?: string;
+    })[];
+    title?: string;
+    processHtml?: (html: string) => string;
+}): import("react").JSX.Element | null;
+/**
+ * A row of measured figures.
+ *
+ * The column count is a class (`stat-grid-4`), never an inline
+ * `gridTemplateColumns`. One repo did it inline, which put a layout decision
+ * outside the stylesheet that owns every other one — invisible to the dead-class
+ * check, unreachable from a media query, and so a four-up row that could not
+ * become a two-up row on a phone.
+ */
+export declare function StatsView({ items, columns, }: {
+    items?: readonly (StatItem & {
+        id?: string;
+    })[];
+    columns?: number;
+}): import("react").JSX.Element | null;
+/**
+ * A maintenance notice.
+ *
+ * The label and the fallback message arrive as `meta` because they are this
+ * wiki's editorial voice — "You can help RADIX Wiki by expanding it" has a name
+ * in it. The markup, the `role="note"` and the variant class are shared, and
+ * were identical in both repos. `icon` is optional: one wiki sets one, and a
+ * component library that hardcoded an icon set would make its consumers install
+ * that icon set.
+ */
+export declare function BannerView({ variant, text, meta, icon, }: {
+    variant: string;
+    text?: string | null;
+    meta: {
+        label: string;
+        message: string;
+    };
+    icon?: ReactNode;
+}): import("react").JSX.Element;

package/dist/block-views.js

@@ -0,0 +1,119 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+// block-views.tsx — the block renderers both wikis had written twice.
+//
+// Behind its own subpath for the reason `react.tsx` is: React is an OPTIONAL
+// peer, so a consumer that only wants the taxonomy or the MCP transport still
+// installs a package with no runtime dependencies.
+//
+// WHY THESE FIVE AND NOT THE SWITCH. The block union is per-repo and staying
+// that way (see the Block Model note in the workspace CLAUDE.md) — a closed
+// union is what makes `switch (block.type)` exhaustive, so a new block type is
+// a compile error rather than a silent blank. What is NOT per-repo is what a
+// codeTabs or a linkGrid LOOKS like once you have dispatched to it: those were
+// byte-identical in both repos, down to the class names. So the dispatch stays
+// with the caller and the leaves move here.
+//
+// The class names are NOT props. Like the rail's `wiki-rail__*` tree they are
+// the shared convention both stylesheets already implement, and making them
+// configurable would only let that convention fork again. Everything that
+// genuinely differs — the prose of a banner, whether references run through an
+// HTML processor, the router's link — arrives as a prop.
+import { Fragment, useState } from 'react';
+import { Anchor } from './react-server.js';
+import { safeLinkHref } from './validation.js';
+import { cx } from './html.js';
+// ---- codeTabs ---------------------------------------------------------------
+/**
+ * Tabbed code samples. Every tab's body stays mounted and the inactive ones are
+ * hidden rather than unmounted: the panels carry pre-highlighted markup, and
+ * remounting one would re-run whatever the consumer's highlighter attached to
+ * it on every tab press.
+ */
+export function CodeTabsView({ tabs }) {
+    const [activeTab, setActiveTab] = useState(0);
+    if (!tabs.length)
+        return null;
+    return (_jsxs("div", { className: "code-tabs", children: [_jsx("div", { className: "code-tabs-list", children: tabs.map((tab, i) => (_jsx("button", { type: "button", className: cx('code-tabs-btn', i === activeTab && 'code-tabs-btn-active'), onClick: () => setActiveTab(i), children: tab.label }, i))) }), tabs.map((tab, i) => (_jsx("div", { className: i === activeTab ? 'block' : 'hidden', dangerouslySetInnerHTML: { __html: tab.code } }, i)))] }));
+}
+/**
+ * A row of columns, each holding blocks the caller renders.
+ *
+ * Children are wrapped in a `Fragment`, not a `<div>`. One repo used a div and
+ * it was a layout bug rather than a style: `.column-view` is the flow context
+ * its stylesheet spaces children in, and an extra element between them means
+ * every gap rule inside a column silently matches nothing.
+ */
+export function ColumnsView({ columns, gap = 'md', align = 'start', render, }) {
+    const gapClass = { sm: 'gap-2', md: 'gap-4', lg: 'gap-6' }[gap];
+    const alignClass = {
+        start: 'items-start',
+        center: 'items-center',
+        end: 'items-end',
+        stretch: 'items-stretch',
+    }[align];
+    return (_jsx("div", { className: cx('columns-layout', gapClass, alignClass), children: columns.map(col => (_jsx("div", { className: "column-view", children: (col.blocks ?? []).map(bl => (_jsx(Fragment, { children: render(bl) }, bl.id))) }, col.id))) }));
+}
+// ---- linkGrid ---------------------------------------------------------------
+/**
+ * Banded groups of link pills.
+ *
+ * A link whose href fails `safeLinkHref` is DROPPED, not rendered inert. These
+ * hrefs are author-supplied, and a `javascript:` URL fails the http test above
+ * — so without the guard it falls through to the router's link component, which
+ * renders it looking like an ordinary pill and executes it on click.
+ */
+export function LinkGridView({ groups, intro, link: Link = Anchor, }) {
+    return (_jsxs("div", { className: "link-grid", children: [intro && _jsx("p", { children: intro }), (groups ?? []).map((group, gi) => (_jsxs("section", { className: "link-grid-group", children: [_jsx("h3", { children: group.heading }), group.description && (_jsx("div", { className: "link-grid-group-description", dangerouslySetInnerHTML: { __html: group.description } })), _jsx("div", { className: "link-grid-pills", children: (group.links ?? []).map((item, i) => {
+                            const href = safeLinkHref(item.href);
+                            if (!href)
+                                return null;
+                            return /^https?:\/\//.test(href) ? (_jsx("a", { href: href, target: "_blank", rel: "noopener", children: item.label }, i)) : (_jsx(Link, { href: href, children: item.label }, i));
+                        }) })] }, group.id ?? gi)))] }));
+}
+// ---- references -------------------------------------------------------------
+/**
+ * The numbered citation list, with the `#cite-n` back-links the inline markers
+ * point at. `processHtml` is a prop because only one wiki runs reference text
+ * through its HTML pipeline, and running it in the other would rewrite anchors
+ * that were minted under different rules.
+ */
+export function ReferencesView({ items, title = 'References', processHtml = (html) => html, }) {
+    const rows = items ?? [];
+    if (!rows.length)
+        return null;
+    return (_jsxs("section", { className: "references-block", "aria-labelledby": "references-heading", children: [_jsx("h2", { id: "references-heading", children: title }), _jsx("ol", { className: "references-list", children: rows.map((item, i) => {
+                    const url = safeLinkHref(item.url);
+                    return (_jsxs("li", { id: `ref-${i + 1}`, className: "reference-item", children: [_jsx("a", { href: `#cite-${i + 1}`, className: "ref-backlink", "aria-label": "Back to citation", children: "\u2191" }), ' ', _jsx("span", { dangerouslySetInnerHTML: { __html: processHtml(item.text) } }), url && (_jsxs(_Fragment, { children: [' ', _jsx("a", { href: url, target: "_blank", rel: "noopener", className: "reference-link", "aria-label": "Open source", children: "\u2197" })] }))] }, item.id ?? i));
+                }) })] }));
+}
+// ---- stats ------------------------------------------------------------------
+/**
+ * A row of measured figures.
+ *
+ * The column count is a class (`stat-grid-4`), never an inline
+ * `gridTemplateColumns`. One repo did it inline, which put a layout decision
+ * outside the stylesheet that owns every other one — invisible to the dead-class
+ * check, unreachable from a media query, and so a four-up row that could not
+ * become a two-up row on a phone.
+ */
+export function StatsView({ items, columns = 4, }) {
+    const rows = items ?? [];
+    if (!rows.length)
+        return null;
+    return (_jsx("div", { className: cx('stat-grid', `stat-grid-${columns}`), children: rows.map((item, i) => (_jsxs("div", { className: "stat-card", children: [_jsxs("span", { className: "stat-value", children: [item.value, item.suffix && _jsx("span", { className: "stat-suffix", children: item.suffix })] }), _jsx("span", { className: "stat-label", children: item.label })] }, item.id ?? i))) }));
+}
+// ---- banner -----------------------------------------------------------------
+/**
+ * A maintenance notice.
+ *
+ * The label and the fallback message arrive as `meta` because they are this
+ * wiki's editorial voice — "You can help RADIX Wiki by expanding it" has a name
+ * in it. The markup, the `role="note"` and the variant class are shared, and
+ * were identical in both repos. `icon` is optional: one wiki sets one, and a
+ * component library that hardcoded an icon set would make its consumers install
+ * that icon set.
+ */
+export function BannerView({ variant, text, meta, icon, }) {
+    return (_jsxs("div", { className: cx('editorial-banner', `editorial-banner-${variant}`), role: "note", children: [icon, _jsxs("p", { className: "editorial-banner-body", children: [_jsxs("strong", { children: [meta.label, "."] }), " ", text?.trim() || meta.message] })] }));
+}

package/dist/blocks.d.ts

@@ -94,4 +94,3 @@ export declare function statsToMarkdown(items: readonly StatItem[]): string;
 export declare function linkGridToMarkdown(groups: readonly LinkGridGroup[], intro?: string | null): string;
 /** A flat bullet list of links — resolved page lists, feed items, link rails. */
 export declare function linkList(items: readonly LinkGridLink[]): string;
-//# sourceMappingURL=blocks.d.ts.map

package/dist/blocks.js

@@ -10,7 +10,7 @@
 // new block type is a compile error until it is handled) and the bodies come
 // from here. Each renderer takes the block's DATA rather than the block, which
 // keeps this file free of any one repo's type union.
-import { decodeEntities } from './entities.js';
+import { decodeEntities } from './markdown.js';
 import { htmlToMarkdown, inlineToMarkdown } from './markdown.js';
 /**
  * The whole tree as markdown. Containers flatten in document order, because a
@@ -121,4 +121,3 @@ export function linkGridToMarkdown(groups, intro) {
 export function linkList(items) {
     return items.map(l => `- [${l.label}](${l.href})`).join('\n');
 }
-//# sourceMappingURL=blocks.js.map

package/dist/combobox.d.ts

@@ -57,4 +57,3 @@ export declare function listId(baseId: string, listKey?: string): string;
  * have an active option.
  */
 export declare function comboboxAria({ baseId, listKey, count, highlight, open }: ComboboxInput): ComboboxAria;
-//# sourceMappingURL=combobox.d.ts.map

package/dist/combobox.js

@@ -56,4 +56,3 @@ export function comboboxAria({ baseId, listKey, count, highlight, open }) {
         }),
     };
 }
-//# sourceMappingURL=combobox.js.map

package/dist/conformance.d.ts

@@ -7,12 +7,21 @@ export interface Rpc {
         isError?: boolean;
         tools?: Array<{
             name: string;
+            title?: string;
             description?: string;
+            inputSchema?: {
+                required?: string[];
+                requireOneOf?: string[];
+            };
             annotations?: Record<string, unknown>;
         }>;
         resources?: Array<{
             uri: string;
         }>;
+        prompts?: Array<{
+            name: string;
+            description?: string;
+        }>;
         resourceTemplates?: Array<{
             uriTemplate?: string;
         }>;
@@ -82,8 +91,6 @@ export declare function transportChecks(t: Tester, clientName: string,
  * business, so it is a parameter rather than one surface's set hardcoded here.
  */
 expectedCapabilities?: readonly string[]): Promise<Rpc>;
-/** The newest protocol revision `wiki-formant/mcp` speaks. */
-export declare const CURRENT_PROTOCOL = "2025-06-18";
 /**
  * One service, many descriptors — server.json, the two agent-card paths, the
  * OpenAPI document, the MCP server card, and `initialize` — should never
@@ -142,6 +149,7 @@ export declare function annotationChecks(t: Tester, opts?: {
 export declare function payloadBudget(t: Tester, calls: ReadonlyArray<{
     name: string;
     args?: Record<string, unknown>;
+    maxBytes?: number;
 }>, maxBytes?: number): Promise<void>;
 /**
  * The default `User-agent: *` group may reach everything the descriptors
@@ -151,4 +159,3 @@ export declare function payloadBudget(t: Tester, calls: ReadonlyArray<{
  * every unnamed crawler is telling two different stories to the same caller.
  */
 export declare function robotsChecks(t: Tester, paths: readonly string[]): Promise<void>;
-//# sourceMappingURL=conformance.d.ts.map

package/dist/conformance.js

@@ -11,6 +11,31 @@
 // same package — so the suite that checks it belongs next to it. What each app
 // keeps is its own fixtures: which tools it expects, what a good answer from each
 // looks like, and which text surfaces it publishes.
+//
+// Every value the transport assertions compare against is imported from `mcp.ts`,
+// not restated here. A suite that carries its own copy of the contract stops
+// testing the boundary the moment the contract moves and says nothing about it.
+import { DEFAULT_MAX_BATCH, MCP_CORS, MCP_PROTOCOL_VERSION } from './mcp.js';
+/**
+ * Does the live preflight carry every token `MCP_CORS` declares for this header?
+ *
+ * Derived rather than listed: the assertion used to name three headers by hand,
+ * so a fourth added to `MCP_CORS` was tested by nobody.
+ */
+const corsCovers = (res, header) => {
+    const live = res.headers.get(header) ?? '';
+    return (MCP_CORS[header] ?? '').split(',').every(tok => live.includes(tok.trim()));
+};
+/**
+ * A POST that `Tester.rpc` cannot make: one whose raw status and headers are the
+ * thing under test, and which must not take `rpc`'s 429 retry. A string body is
+ * sent as-is, so the malformed-JSON case uses the same door as the rest.
+ */
+const rawPost = (endpoint, body, headers = {}) => fetch(endpoint, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', ...headers },
+    body: typeof body === 'string' ? body : JSON.stringify(body),
+});
 export function createTester(opts) {
     const base = opts.base.replace(/\/$/, '');
     const endpoint = opts.endpoint ?? `${base}/api/mcp`;
@@ -87,42 +112,42 @@ expectedCapabilities = ['tools']) {
     // 2025-03-26 — forfeiting structured output, tool titles and `_meta` — while
     // every suite reported green.
     const echoed = await t.rpc('initialize', {
-        protocolVersion: CURRENT_PROTOCOL,
+        protocolVersion: MCP_PROTOCOL_VERSION,
         capabilities: {},
         clientInfo: { name: clientName, version: '1' },
     });
-    t.check('protocol negotiated', echoed.result?.protocolVersion === CURRENT_PROTOCOL, `asked ${CURRENT_PROTOCOL}, got ${echoed.result?.protocolVersion}`);
+    t.check('protocol negotiated', echoed.result?.protocolVersion === MCP_PROTOCOL_VERSION, `asked ${MCP_PROTOCOL_VERSION}, got ${echoed.result?.protocolVersion}`);
     t.check('downgrades gracefully', (init.result?.protocolVersion ?? '').length > 0, `asked 2024-11-05, got ${init.result?.protocolVersion}`);
     console.log(`\n=== transport ===`);
     const opt = await fetch(t.endpoint, { method: 'OPTIONS' });
     t.check('OPTIONS preflight', opt.status === 204 &&
         opt.headers.get('access-control-allow-origin') === '*' &&
-        (opt.headers.get('access-control-allow-headers') ?? '').includes('Mcp-Protocol-Version'), `${opt.status} ACAO=${opt.headers.get('access-control-allow-origin')}`);
+        corsCovers(opt, 'Access-Control-Allow-Headers'), `${opt.status} ACAO=${opt.headers.get('access-control-allow-origin')}`);
     // Allow-Headers governs what a browser may send; Expose-Headers what it may
     // read. Without the second, a browser client cannot see `Retry-After` on a
     // 429 and a rate limit reads to it as a hang.
-    t.check('CORS exposes response headers', ['Mcp-Protocol-Version', 'Retry-After'].every(h => (opt.headers.get('access-control-expose-headers') ?? '').includes(h)), `expose=${opt.headers.get('access-control-expose-headers')}`);
+    t.check('CORS exposes response headers', corsCovers(opt, 'Access-Control-Expose-Headers'), `expose=${opt.headers.get('access-control-expose-headers')}`);
+    // A budget stated only in the 429 can be discovered only by exceeding it —
+    // the one moment an agent is least able to act on it. This suite is the
+    // proof: with no header to read, its own client blind-sleeps five seconds on
+    // a 429 and hopes.
+    const headroom = await rawPost(t.endpoint, { jsonrpc: '2.0', id: 'headroom', method: 'ping' });
+    t.recordCall();
+    const remaining = headroom.headers.get('ratelimit-remaining');
+    t.check('rate limit states headroom', !!headroom.headers.get('ratelimit-limit') && remaining !== null, `RateLimit-Limit=${headroom.headers.get('ratelimit-limit')} Remaining=${remaining} Reset=${headroom.headers.get('ratelimit-reset')}`);
     const get = await fetch(t.endpoint);
     t.check('GET→405', get.status === 405 && get.headers.get('access-control-allow-origin') === '*', `${get.status} Allow=${get.headers.get('allow')} ACAO=${get.headers.get('access-control-allow-origin')}`);
     // A notification has no id, so it must be acknowledged with no body at all —
     // a JSON-RPC response to one is a protocol error.
-    const notif = await fetch(t.endpoint, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }),
-    });
+    const notif = await rawPost(t.endpoint, { jsonrpc: '2.0', method: 'notifications/initialized' });
     const notifBody = await notif.text();
     t.check('notification→202', notif.status === 202 && notifBody === '', `${notif.status} body="${notifBody}"`);
-    const bad = await fetch(t.endpoint, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: 'not json' });
+    const bad = await rawPost(t.endpoint, 'not json');
     const badJson = (await bad.json());
     t.check('parse error→400', bad.status === 400 && badJson.error?.code === -32700, `${bad.status} code=${badJson.error?.code}`);
-    const over = await fetch(t.endpoint, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(Array.from({ length: 21 }, (_, i) => ({ jsonrpc: '2.0', id: i, method: 'ping' }))),
-    });
+    const over = await rawPost(t.endpoint, Array.from({ length: DEFAULT_MAX_BATCH + 1 }, (_, i) => ({ jsonrpc: '2.0', id: i, method: 'ping' })));
     const overJson = (await over.json());
-    t.check('batch cap (21)', overJson.error?.code === -32600, `code=${overJson.error?.code}: ${(overJson.error?.message ?? '').slice(0, 80)}`);
+    t.check(`batch cap (${DEFAULT_MAX_BATCH + 1})`, overJson.error?.code === -32600, `code=${overJson.error?.code}: ${(overJson.error?.message ?? '').slice(0, 80)}`);
     const caps = init.result?.capabilities ?? {};
     t.check('capabilities honest', expectedCapabilities.every(k => k in caps), `${JSON.stringify(caps)} expected=[${expectedCapabilities.join(', ')}]`);
     // Declaring `resources` makes a client ask for templates. -32601 to a method
@@ -131,26 +156,20 @@ expectedCapabilities = ['tools']) {
         const templates = await t.rpc('resources/templates/list');
         t.check('resources/templates/list', Array.isArray(templates.result?.resourceTemplates), templates.error ? `-${templates.error.code}` : `${templates.result?.resourceTemplates?.length} templates`);
     }
-    const versioned = await fetch(t.endpoint, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json', 'MCP-Protocol-Version': CURRENT_PROTOCOL },
-        body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'ping' }),
+    const versioned = await rawPost(t.endpoint, { jsonrpc: '2.0', id: 1, method: 'ping' }, {
+        'MCP-Protocol-Version': MCP_PROTOCOL_VERSION,
     });
     t.recordCall();
-    t.check('MCP-Protocol-Version echoed', versioned.headers.get('mcp-protocol-version') === CURRENT_PROTOCOL, `sent ${CURRENT_PROTOCOL}, got ${versioned.headers.get('mcp-protocol-version')}`);
+    t.check('MCP-Protocol-Version echoed', versioned.headers.get('mcp-protocol-version') === MCP_PROTOCOL_VERSION, `sent ${MCP_PROTOCOL_VERSION}, got ${versioned.headers.get('mcp-protocol-version')}`);
     // Batching was removed in 2025-06-18. A server that keeps honouring it under
     // a version that forbids it is telling the client something untrue.
-    const batched = await fetch(t.endpoint, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json', 'MCP-Protocol-Version': CURRENT_PROTOCOL },
-        body: JSON.stringify([{ jsonrpc: '2.0', id: 1, method: 'ping' }]),
+    const batched = await rawPost(t.endpoint, [{ jsonrpc: '2.0', id: 1, method: 'ping' }], {
+        'MCP-Protocol-Version': MCP_PROTOCOL_VERSION,
     });
     t.recordCall();
     t.check('batch refused at 2025-06-18', batched.status === 400, `${batched.status}`);
     return init;
 }
-/** The newest protocol revision `wiki-formant/mcp` speaks. */
-export const CURRENT_PROTOCOL = '2025-06-18';
 /**
  * One service, many descriptors — server.json, the two agent-card paths, the
  * OpenAPI document, the MCP server card, and `initialize` — should never
@@ -200,11 +219,7 @@ export async function agentCardParity(t) {
     // `url` is where a client sends its first call. Pointed at the homepage it
     // gets HTML back, which is the failure that looks like a broken agent.
     const endpoint = String(a.url ?? '');
-    const probe = await fetch(endpoint, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'ping' }),
-    });
+    const probe = await rawPost(endpoint, { jsonrpc: '2.0', id: 1, method: 'ping' });
     t.recordCall();
     t.check('agent card url is callable', (probe.headers.get('content-type') ?? '').includes('json'), `POST ${endpoint} -> ${probe.status} ${probe.headers.get('content-type')}`);
 }
@@ -290,7 +305,21 @@ export async function annotationChecks(t, opts = {}) {
  * answer, so this weighs it.
  */
 export async function payloadBudget(t, calls, maxBytes = 120_000) {
-    for (const { name, args } of calls) {
+    // Every read-only tool a caller can invoke with no arguments at all, whether
+    // or not the suite thought to name it. This check used to weigh only the
+    // listed calls, which is how a tool taking no parameters and answering with
+    // 3.3 MB — 27× the budget it was exempt from — passed a suite that measured
+    // the four tools beside it. A tool with required arguments still has to be
+    // listed: the suite is the only thing that knows a valid pair.
+    const listed = new Set(calls.map(c => c.name));
+    const bare = ((await t.rpc('tools/list')).result?.tools ?? [])
+        .filter(x => x.annotations?.readOnlyHint === true && !listed.has(x.name))
+        // `requireOneOf` is a required argument too, just one this cannot pick for
+        // the caller — such a tool has to be listed with args like any other.
+        .filter(x => !(x.inputSchema?.required ?? []).length && !(x.inputSchema?.requireOneOf ?? []).length)
+        .map(x => ({ name: x.name, args: undefined, maxBytes: undefined }));
+    for (const { name, args, maxBytes: own } of [...calls, ...bare]) {
+        const budget = own ?? maxBytes;
         const answer = await t.call(name, args ?? {});
         const text = answer.result?.content?.[0]?.text ?? '';
         // An empty answer is not a small one. The first draft compared only the
@@ -299,9 +328,18 @@ export async function payloadBudget(t, calls, maxBytes = 120_000) {
         // measured nothing. A budget that green-lights a call that never returned
         // is the exact failure it exists to catch.
         const answered = text.length > 0 && !answer.error && !answer.result?.isError;
-        t.check(`${name} within budget`, answered && text.length <= maxBytes, answered
-            ? `${text.length.toLocaleString()} chars (max ${maxBytes.toLocaleString()})`
+        t.check(`${name} within budget`, answered && text.length <= budget, answered
+            ? `${text.length.toLocaleString()} chars (max ${budget.toLocaleString()})`
             : `no answer to weigh: ${answer.error ? `-${answer.error.code} ${answer.error.message}` : answer.result?.isError ? `isError: ${text.slice(0, 80)}` : 'empty result'}`);
+        // A JSON answer that arrives only as prose costs every client a parse it
+        // should never have had to write. Measured on the answer already in hand,
+        // so it is free — and it stays quiet for a tool that genuinely returns
+        // prose, which is the only reason a read tool may skip it.
+        if (answered && /^\s*\{/.test(text)) {
+            t.check(`${name} structured`, answer.result?.structuredContent !== undefined, answer.result?.structuredContent !== undefined
+                ? 'structuredContent beside the text'
+                : 'JSON answer with no structuredContent — the client has to parse prose');
+        }
     }
 }
 /**
@@ -337,4 +375,3 @@ export async function robotsChecks(t, paths) {
         t.check(`robots allows ${path}`, !match || match.allow, match ? `${match.allow ? 'Allow' : 'Disallow'}: ${match.path}` : 'no matching rule');
     }
 }
-//# sourceMappingURL=conformance.js.map

package/dist/crawlers.d.ts

@@ -42,4 +42,3 @@ export declare function aiCrawlerRules(opts: {
     disallow: string | string[];
     aiAllow: string | string[];
 }): RobotsGroup[];
-//# sourceMappingURL=crawlers.d.ts.map

package/dist/crawlers.js

@@ -84,4 +84,3 @@ export function aiCrawlerRules(opts) {
         })),
     ];
 }
-//# sourceMappingURL=crawlers.js.map

package/dist/dom.d.ts

@@ -66,4 +66,3 @@ export interface TabGroupClassNames {
  * silently reset it to the first tab.
  */
 export declare function activateTabGroups(root: ParentNode, classNames?: TabGroupClassNames): void;
-//# sourceMappingURL=dom.d.ts.map

package/dist/dom.js

@@ -164,4 +164,3 @@ export function activateTabGroups(root, classNames = {}) {
         group.appendChild(tabPanels);
     }
 }
-//# sourceMappingURL=dom.js.map