wiki-formant 0.17.1 → 0.19.0

package/README.md

@@ -120,8 +120,9 @@ What it gets right:
 - **Malformed JSON is `-32700` with a `400`**, never a 500.
 - **`GET` is an explicit 405 with CORS headers.** A framework's automatic 405 carries none, so a browser client cannot even read the refusal.
 - **The preflight allow-list includes `Accept` and `Mcp-Protocol-Version`.** One missing entry fails the preflight rather than the POST, which presents as "the server is down".
-- **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.
+- **Batches are capped** (default 20) with a teaching error, because the rate limiter charges one token per HTTP request before the body is parsed. From 2025-06-18 on they are refused outright, because that revision removed them.
+- **Both protocol eras, one endpoint.** A request carrying `io.modelcontextprotocol/protocolVersion` in `params._meta` is served as `2026-07-28`: `server/discover`, per-request version and header validation (`-32022` naming every version spoken, `-32020` on a routing header that disagrees with the body), `resultType` and cache hints on results, and 404 for the methods that revision removed. Everything else is the legacy era, where `initialize` echoes the client's version when it is one of `2025-11-25`, `2025-06-18`, `2025-03-26` or `2024-11-05` and offers the newest otherwise. The spec permits a dual-era server, and it is the only way to adopt the new revision without failing the handshake of every client already in the field.
+- **The version is negotiated, not asserted.** Every response carries it 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.

package/bin/check-classes.mjs

@@ -18,11 +18,20 @@
 // are utilities is derived, not listed — anything the build emits that globals.css
 // does not define is Tailwind's.
 //
+// And the reverse: a selector globals.css defines that nothing the build ships
+// references. The shared blocks and chrome render their markup inside
+// wiki-formant while each app styles it, so references are read from the build
+// output, which holds this repo's code, the package's components and bundled
+// libraries alike. A class renamed in the package surfaces here as its old
+// selector going unreferenced. HTML stored in a database is not in the build,
+// so a selector only stored content uses is reported too.
+//
 //   npx check-classes                # exit 1 on any dead token
 //   npx check-classes --warn         # report and exit 0
 //   npx check-classes --compositions # also fail on 3+ inline utilities
+//   npx check-classes --unused       # also fail on unreferenced selectors
 //
-// Run it from the repo root: `.next/static` and `src` are resolved against cwd.
+// Run it from the repo root: `.next` and `src` are resolved against cwd.
 //
 // Needs a build first (npm run build): without one there is nothing to check
 // against, and the script says so and exits 0 rather than failing blind.
@@ -30,7 +39,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 const WARN_ONLY = process.argv.includes('--warn');
-const CSS_DIR = '.next/static';
+const STATIC_DIR = '.next/static';
 const SRC_DIR = 'src';
 
 const walk = (dir, ext, out = []) => {
@@ -43,7 +52,7 @@ const walk = (dir, ext, out = []) => {
   return out;
 };
 
-const cssFiles = walk(CSS_DIR, '.css');
+const cssFiles = walk(STATIC_DIR, '.css');
 if (!cssFiles.length) {
   console.log('check-classes: no built CSS under .next/static — run `npm run build` first. Skipping.');
   process.exit(0);
@@ -59,12 +68,18 @@ for (const f of cssFiles) {
 
 // Classes this project defines itself. Everything else the build emitted is a
 // Tailwind utility, which is what makes the composition count derivable rather
-// than a maintained prefix list.
+// than a maintained prefix list. Read from rule preludes only, so a decimal in a
+// value or a class named in a comment is not taken for a selector.
 const globalsFile = walk(SRC_DIR, '.css').find(f => f.endsWith('globals.css'));
 const named = new Set();
 if (globalsFile) {
-  for (const m of fs.readFileSync(globalsFile, 'utf8').matchAll(/\.((?:\\.|[-\w])+)/g)) {
-    named.add(m[1].replace(/\\/g, ''));
+  const css = fs.readFileSync(globalsFile, 'utf8').replace(/\/\*[\s\S]*?\*\//g, '');
+  for (const [, prelude] of css.matchAll(/([^{};]*)\{/g)) {
+    if (prelude.trim().startsWith('@')) continue;
+    for (const m of prelude.matchAll(/\.((?:\\.|[-\w])+)/g)) {
+      const name = m[1].replace(/\\/g, '');
+      if (/^[A-Za-z_-]/.test(name)) named.add(name);
+    }
   }
 }
 
@@ -92,6 +107,7 @@ for (const f of walk(SRC_DIR, '.tsx')) {
 }
 
 const CHECK_COMPOSITIONS = process.argv.includes('--compositions');
+const CHECK_UNUSED = process.argv.includes('--unused');
 
 if (compositions.length) {
   const verb = CHECK_COMPOSITIONS ? 'must be named' : 'should be named (advisory)';
@@ -103,9 +119,30 @@ if (compositions.length) {
   console.error('');
 }
 
+// Every token in the JavaScript the build ships, server and client. A selector
+// is referenced when its name appears whole, or when a prefix of it ending in `-`
+// or `_` does, which is how `editorial-banner-${variant}` is written.
+const shipped = new Set();
+for (const f of [...walk(STATIC_DIR, '.js'), ...walk('.next/server', '.js')]) {
+  for (const [tok] of fs.readFileSync(f, 'utf8').matchAll(/[\w-]+/g)) shipped.add(tok);
+}
+const referenced = name =>
+  shipped.has(name) ||
+  [...name].some((c, i) => i >= 3 && (c === '-' || c === '_') && shipped.has(name.slice(0, i + 1)));
+const unused = [...named].filter(n => !referenced(n)).sort();
+
+if (unused.length) {
+  const verb = CHECK_UNUSED ? 'must be deleted' : 'advisory';
+  console.error(`check-classes: ${unused.length} selector(s) in ${globalsFile} referenced by nothing the build ships (${verb}):\n`);
+  console.error(`  ${unused.join(', ')}\n`);
+  console.error('  Class names inside HTML stored in a database do not count, so check stored content before deleting one.\n');
+}
+
+const advisoryFailed = (CHECK_COMPOSITIONS && compositions.length > 0) || (CHECK_UNUSED && unused.length > 0);
+
 if (!dead.size) {
   console.log(`check-classes: clean — every className token resolves against ${emitted.size} emitted selectors.`);
-  process.exit(CHECK_COMPOSITIONS && compositions.length && !WARN_ONLY ? 1 : 0);
+  process.exit(advisoryFailed && !WARN_ONLY ? 1 : 0);
 }
 
 console.error(`check-classes: ${dead.size} className token(s) style nothing:\n`);

package/dist/block-views.js

@@ -1,6 +1,6 @@
 '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.
+// block-views.tsx — the block leaves the wikis share.
 //
 // 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
@@ -10,13 +10,12 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 // 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.
+// codeTabs or a linkGrid LOOKS like once you have dispatched to it, down to the
+// class names. So the dispatch stays with the caller and the leaves live 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
+// The class names are NOT props. They are the shared convention every
+// stylesheet implements, and making them configurable would let that convention
+// fork. 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';

package/dist/combobox.js

@@ -4,21 +4,12 @@
 // pure, so it can be tested without a DOM, and `react.tsx` is left holding only
 // the hook that calls it.
 //
-// `useTypeahead` already shared the state machine across five surfaces in three
-// wikis. The ARIA did not travel with it, and all five had drifted into
-// different wrongness:
-//
-//   - one put `aria-selected` on a plain `<button>`, which is not a role that
-//     takes it, and gave the container no `role="listbox"` at all;
-//   - one gave the rows `role="option"` but still no listbox, so the options
-//     had no owner;
-//   - two had no roles whatsoever;
-//   - one used a `data-highlighted` attribute, which no assistive technology
-//     reads.
-//
-// None of the five set `aria-activedescendant`, which is the attribute that
-// actually announces the highlighted row as the reader arrows through it. A
-// combobox without it is a text field that silently changes what Enter does.
+// `useTypeahead` shares the state machine; this is the ARIA that goes with it:
+// a `role="listbox"` container that owns `role="option"` rows, `aria-selected`
+// on the option rather than on a plain `<button>`, and `aria-activedescendant`,
+// the attribute that announces the highlighted row as the reader arrows
+// through it. A combobox without it is a text field that silently changes what
+// Enter does.
 /** The id of one option row. Exported because a caller that scrolls the
  *  highlighted row into view has to find it by the same id the input points at. */
 export function optionId(baseId, listKey, index) {

package/dist/conformance.d.ts

@@ -34,12 +34,19 @@ export interface Rpc {
         protocolVersion?: string;
         capabilities?: Record<string, unknown>;
         instructions?: string;
+        resultType?: string;
+        supportedVersions?: string[];
+        ttlMs?: number;
+        cacheScope?: string;
+        _meta?: Record<string, unknown>;
     };
     error?: {
         code: number;
         message: string;
         data?: {
             availableTools?: string[];
+            supported?: string[];
+            requested?: string;
         };
     };
 }

package/dist/conformance.js

@@ -15,12 +15,11 @@
 // 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';
+import { DEFAULT_MAX_BATCH, MCP_CORS, MCP_LEGACY_PROTOCOL_VERSION, MCP_META, MCP_MODERN_VERSIONS, MCP_PROTOCOL_VERSIONS, } 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.
+ * Derived rather than listed, so a header added to `MCP_CORS` is tested too.
  */
 const corsCovers = (res, header) => {
     const live = res.headers.get(header) ?? '';
@@ -112,11 +111,11 @@ expectedCapabilities = ['tools']) {
     // 2025-03-26 — forfeiting structured output, tool titles and `_meta` — while
     // every suite reported green.
     const echoed = await t.rpc('initialize', {
-        protocolVersion: MCP_PROTOCOL_VERSION,
+        protocolVersion: MCP_LEGACY_PROTOCOL_VERSION,
         capabilities: {},
         clientInfo: { name: clientName, version: '1' },
     });
-    t.check('protocol negotiated', echoed.result?.protocolVersion === MCP_PROTOCOL_VERSION, `asked ${MCP_PROTOCOL_VERSION}, got ${echoed.result?.protocolVersion}`);
+    t.check('protocol negotiated', echoed.result?.protocolVersion === MCP_LEGACY_PROTOCOL_VERSION, `asked ${MCP_LEGACY_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' });
@@ -157,19 +156,67 @@ expectedCapabilities = ['tools']) {
         t.check('resources/templates/list', Array.isArray(templates.result?.resourceTemplates), templates.error ? `-${templates.error.code}` : `${templates.result?.resourceTemplates?.length} templates`);
     }
     const versioned = await rawPost(t.endpoint, { jsonrpc: '2.0', id: 1, method: 'ping' }, {
-        'MCP-Protocol-Version': MCP_PROTOCOL_VERSION,
+        'MCP-Protocol-Version': MCP_LEGACY_PROTOCOL_VERSION,
     });
     t.recordCall();
-    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')}`);
+    t.check('MCP-Protocol-Version echoed', versioned.headers.get('mcp-protocol-version') === MCP_LEGACY_PROTOCOL_VERSION, `sent ${MCP_LEGACY_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 rawPost(t.endpoint, [{ jsonrpc: '2.0', id: 1, method: 'ping' }], {
-        'MCP-Protocol-Version': MCP_PROTOCOL_VERSION,
+        'MCP-Protocol-Version': MCP_LEGACY_PROTOCOL_VERSION,
     });
     t.recordCall();
-    t.check('batch refused at 2025-06-18', batched.status === 400, `${batched.status}`);
+    t.check(`batch refused at ${MCP_LEGACY_PROTOCOL_VERSION}`, batched.status === 400, `${batched.status}`);
+    await modernChecks(t, caps);
     return init;
 }
+/**
+ * A modern request exactly as a `2026-07-28` client sends it: version and
+ * capabilities in `_meta`, echoed by the headers a gateway routes on.
+ */
+const modernPost = async (t, method, opts = {}) => {
+    const version = opts.version ?? MCP_MODERN_VERSIONS[0];
+    const res = await rawPost(t.endpoint, {
+        jsonrpc: '2.0',
+        id: method,
+        method,
+        params: { _meta: { [MCP_META.protocolVersion]: version, [MCP_META.clientCapabilities]: {} } },
+    }, { 'MCP-Protocol-Version': version, 'Mcp-Method': method, ...opts.headers });
+    t.recordCall();
+    return { status: res.status, json: (await res.json()) };
+};
+/**
+ * The modern era, served beside the legacy one. Every probe that graded these
+ * servers on `server/discover` saw a -32601 for a month while every legacy check
+ * here stayed green, because nothing asked the modern question.
+ */
+async function modernChecks(t, legacyCapabilities) {
+    console.log(`\n=== modern era (${MCP_MODERN_VERSIONS[0]}) ===`);
+    const discover = await modernPost(t, 'server/discover');
+    const d = discover.json.result;
+    t.check('server/discover', discover.status === 200 &&
+        d?.resultType === 'complete' &&
+        MCP_PROTOCOL_VERSIONS.every(v => d.supportedVersions?.includes(v)) &&
+        !!d.instructions &&
+        typeof d.ttlMs === 'number' &&
+        !!d.cacheScope &&
+        !!d._meta?.[MCP_META.serverInfo], `${discover.status} ${JSON.stringify(d?.supportedVersions ?? discover.json.error)}`);
+    // One server, two ways to ask what it can do. They must give one answer.
+    t.check('discover agrees with initialize', JSON.stringify(d?.capabilities) === JSON.stringify(legacyCapabilities), `discover=${JSON.stringify(d?.capabilities)} initialize=${JSON.stringify(legacyCapabilities)}`);
+    const list = await modernPost(t, 'tools/list');
+    t.check('modern tools/list', list.status === 200 &&
+        list.json.result?.resultType === 'complete' &&
+        (list.json.result?.tools?.length ?? 0) > 0 &&
+        typeof list.json.result?.ttlMs === 'number', `${list.status} tools=${list.json.result?.tools?.length ?? JSON.stringify(list.json.error)} ttlMs=${list.json.result?.ttlMs}`);
+    const unsupported = await modernPost(t, 'tools/list', { version: '1999-01-01' });
+    t.check('unsupported version→-32022', unsupported.status === 400 &&
+        unsupported.json.error?.code === -32022 &&
+        JSON.stringify(unsupported.json.error?.data?.supported) === JSON.stringify(MCP_PROTOCOL_VERSIONS), `${unsupported.status} code=${unsupported.json.error?.code} supported=${JSON.stringify(unsupported.json.error?.data?.supported)}`);
+    const ping = await modernPost(t, 'ping');
+    t.check('removed method→404', ping.status === 404 && ping.json.error?.code === -32601, `ping: ${ping.status} code=${ping.json.error?.code}`);
+    const mismatch = await modernPost(t, 'tools/list', { headers: { 'Mcp-Method': 'prompts/list' } });
+    t.check('header mismatch→-32020', mismatch.status === 400 && mismatch.json.error?.code === -32020, `${mismatch.status} code=${mismatch.json.error?.code}`);
+}
 /**
  * One service, many descriptors — server.json, the two agent-card paths, the
  * OpenAPI document, the MCP server card, and `initialize` — should never
@@ -306,10 +353,9 @@ export async function annotationChecks(t, opts = {}) {
  */
 export async function payloadBudget(t, calls, maxBytes = 120_000) {
     // 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
+    // or not the suite thought to name it, so a no-argument tool answering with
+    // megabytes cannot pass by going unlisted. 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 ?? [])

package/dist/crawlers.js

@@ -1,22 +1,16 @@
 // crawlers.ts — one roster of AI crawler tokens, for both surfaces that need it.
 //
-// Every wiki in the workspace kept this list twice: once in the proxy, keyed by
-// user-agent substring, to count an "AI Bot Visit"; and once in `robots.ts`, as
-// the set of agents that get their own group. The two copies were each
-// byte-identical across all three repos — and they were different lists.
+// The proxy counts an "AI Bot Visit" by user-agent substring, and `robots.ts`
+// gives each agent its own group. Both read this one roster.
 //
-// Only one direction of that difference was deliberate. `Applebot-Extended`
+// One difference between the two uses is deliberate. `Applebot-Extended`
 // never fetches a page: it is a robots.txt-only token that Applebot consults
 // before using already-crawled data for AI, so counting it would count nothing.
 // That belongs in robots and not in the matcher, and it is declared here.
 //
-// The other direction was not deliberate. Bytespider, CCBot, cohere-ai,
-// Claude-Web and Meta-ExternalFetcher were matched by every proxy and named by
-// no robots.txt — and a crawler obeys only its most-specific matching group, so
-// an agent with no group of its own falls through to `*` and is granted
-// whatever that grants. The wikis were measuring five crawlers they had never
-// addressed. One roster makes that a property of the data rather than of which
-// file you happened to edit.
+// Every other token appears in both, because a crawler obeys only its
+// most-specific matching group: an agent with no group of its own falls through
+// to `*` and is granted whatever that grants.
 /**
  * Order is significant: `detectAiBot` returns the first token the user agent
  * contains, so a token that is a substring of another must come after it.

package/dist/dom.d.ts

@@ -19,8 +19,7 @@ export interface CopyButtonOptions {
 export declare function addCopyButtons(root: ParentNode, options?: CopyButtonOptions): number;
 /**
  * The one place this origin is written down. It is both the embed host and the
- * allow-list the resize listener checks, and it was previously spelled out at
- * four call sites across the two wikis.
+ * allow-list the resize listener checks.
  */
 export declare const TWITTER_ORIGIN = "https://platform.twitter.com";
 /** The embed iframe's src. `dnt=true` opts the embed out of Twitter's tracking. */

package/dist/dom.js

@@ -55,8 +55,7 @@ export function addCopyButtons(root, options = {}) {
 // ---- twitter embeds ---------------------------------------------------------
 /**
  * The one place this origin is written down. It is both the embed host and the
- * allow-list the resize listener checks, and it was previously spelled out at
- * four call sites across the two wikis.
+ * allow-list the resize listener checks.
  */
 export const TWITTER_ORIGIN = 'https://platform.twitter.com';
 /** The embed iframe's src. `dnt=true` opts the embed out of Twitter's tracking. */

package/dist/editor.d.ts

@@ -5,8 +5,7 @@ import { type ChangeEvent, type RefObject } from 'react';
  *
  * Each of these packages ships a `declare module '@tiptap/core'` block that adds
  * its commands to `ChainedCommands` — `toggleBold`, `insertTable`, `setLink`,
- * `setImage`. A consumer that imported the extensions itself picked those up as
- * a side effect of the import; now that this module owns them, it has to carry
+ * `setImage`. Because this module owns the extensions, it has to carry
  * the augmentation across the package boundary, and a re-exported type is what
  * makes the emitted `.d.ts` load the module that declares it. Without these
  * four lines every `editor.chain().focus().toggleBold()` in every consumer
@@ -16,19 +15,6 @@ export type { StarterKitOptions } from '@tiptap/starter-kit';
 export type { LinkOptions } from '@tiptap/extension-link';
 export type { ImageOptions } from '@tiptap/extension-image';
 export type { TableOptions } from '@tiptap/extension-table';
-/**
- * Reduce pasted HTML to structure plus the three attributes that carry meaning.
- *
- * A paste from a word processor or a web page arrives carrying its whole
- * stylesheet inline. Keeping any of it means the wiki's own typography loses to
- * whatever the author copied from, per paragraph, invisibly — and `style` on a
- * pasted node is also the cheapest way to smuggle a full-bleed overlay into a
- * page body.
- *
- * Browser-only: it parses with `DOMParser`. Called from `transformPastedHTML`,
- * which only ever runs in response to a paste.
- */
-export declare function cleanPastedHtml(html: string): string;
 export interface WikiEditorExtensionOptions {
     /** Empty-document prompt. */
     placeholder?: string;
@@ -42,15 +28,6 @@ export interface WikiEditorExtensionOptions {
      */
     nodes?: readonly AnyExtension[];
 }
-/**
- * The editor's extension set.
- *
- * `codeBlock: false` on StarterKit is load-bearing: the consumer registers its
- * own via `createCodeBlock`, and leaving StarterKit's in place would give the
- * schema two nodes claiming the same name. Headings stop at h2 — the page title
- * is the only h1 a wiki page has.
- */
-export declare function wikiEditorExtensions({ placeholder, nodes, }?: WikiEditorExtensionOptions): AnyExtension[];
 /**
  * Turn a pasted URL into the richest node that fits it, falling back to a bare
  * iframe. Order matters: a YouTube URL is also a valid iframe source, so the

package/dist/editor.js

@@ -4,25 +4,16 @@
 // `tiptap.tsx` holds the custom NODES both wikis needed (iframe, tweet, map,
 // code block, tabs). This holds what sits around them: which extensions are
 // configured how, what a paste is scrubbed down to, how a pasted URL becomes
-// the right embed, and the state a toolbar reads. Those were byte-identical in
-// both repos — the same twelve-entry extension array, the same paste scrubber,
-// the same embed dispatch including the shortened-map async swap.
+// the right embed, and the state a toolbar reads.
 //
-// TWO BUGS ARE FIXED HERE RATHER THAN PROPAGATED, and the reason this file
-// exists at all is that each repo had exactly one of them:
+// TWO GUARDS HERE ARE LOAD-BEARING:
 //
-//   1. `onChangeRef.current = onChange` was written DURING render in one copy.
-//      A ref mutated mid-render can tear under concurrent rendering. It is
-//      written in an effect here, and only read from events and timeouts, which
-//      run later.
-//   2. The other copy had no `onBlur`. The change is debounced 150ms, and
-//      clicking Save blurs the editor before the click lands — so the final
-//      keystroke of every edit that ended in a click was dropped. Blur flushes
-//      the pending debounce.
-//
-// Neither repo was "behind": each had shipped the fix the other lacked, which
-// is the drift that costs the most, because neither file looks like the one to
-// fix.
+//   1. `onChangeRef.current = onChange` is written in an effect, never during
+//      render: a ref mutated mid-render can tear under concurrent rendering.
+//      It is only read from events and timeouts, which run later.
+//   2. Blur flushes the pending debounce. The change is debounced 150ms, and
+//      clicking Save blurs the editor before the click lands, so without the
+//      flush the final keystroke of an edit that ends in a click is dropped.
 //
 // Every @tiptap package here is an OPTIONAL PEER. A consumer that only wants
 // the taxonomy or the MCP transport installs none of them.
@@ -50,7 +41,7 @@ import { toMapEmbedUrl } from './maps.js';
  * Browser-only: it parses with `DOMParser`. Called from `transformPastedHTML`,
  * which only ever runs in response to a paste.
  */
-export function cleanPastedHtml(html) {
+function cleanPastedHtml(html) {
     const doc = new DOMParser().parseFromString(html, 'text/html');
     doc.querySelectorAll('style, script, meta, link, svg, canvas, noscript').forEach(el => el.remove());
     doc.querySelectorAll('*').forEach(el => {
@@ -72,7 +63,7 @@ export function cleanPastedHtml(html) {
  * schema two nodes claiming the same name. Headings stop at h2 — the page title
  * is the only h1 a wiki page has.
  */
-export function wikiEditorExtensions({ placeholder = '', nodes = [], } = {}) {
+function wikiEditorExtensions({ placeholder = '', nodes = [], } = {}) {
     return [
         StarterKit.configure({ heading: { levels: [2, 3, 4] }, codeBlock: false }),
         TiptapLink.configure({ openOnClick: false, HTMLAttributes: { class: 'link' } }),

package/dist/headings.js

@@ -1,12 +1,6 @@
 // headings.ts — stable ids on a wiki page's headings, and the list a table of
 // contents is built from.
 //
-// Two of the three wikis had already written this out (caper's `injectHeadingIds`,
-// radix-wiki's heading branch in `processHtml`), down to byte-identical
-// `stripTags` and `getAttr` helpers — caper's file says "ported in spirit from
-// radix-wiki" at the top, which is the drift admitting itself. What they had
-// drifted on is below.
-//
 // The slug rule is a parameter, not a decision this module makes. A heading id
 // is a live URL: readers link to `#the-shape-of-a-code`, and so does the page's
 // own permalink anchor. Unifying two slug rules would silently move every
@@ -15,8 +9,7 @@
 //
 // Deduping, by contrast, is not a choice: two headings with the same text
 // otherwise mint the same id twice and every link to the second one lands on
-// the first. That was already a bug in the copy that lacked it, so this always
-// dedupes.
+// the first, so this always dedupes.
 import { getAttr, stripTags } from './html.js';
 /** The default slug rule: lowercase words joined by hyphens. */
 export function slugifyHeading(text) {

package/dist/link-check.js

@@ -1,18 +1,15 @@
-// link-check.ts — the dead-link probe both wikis' sweep scripts had written.
+// link-check.ts — the dead-link probe wiki sweep scripts share.
 //
 // Node-only (fetch, AbortSignal, URL). No framework, no database: what a
 // checker does with the verdicts — which pages to walk, what counts as an
 // internal path, how to report — stays with the caller, because that is the
 // half that is genuinely per-wiki.
 //
-// EVERY GUARD BELOW WAS PAID FOR BY A FALSE POSITIVE, and the two copies had
-// each learned a different half of the lesson. One knew that npmjs.com 403s
-// scripted requests, that an expired certificate is not a dead host, and that a
-// YouTube /embed/ URL answers 200 for a deleted video. The other knew that a
-// connect refusal is usually concurrency rather than death, and that
-// serialising per hostname is what fixes it. Neither copy was behind. A sweep
-// running either one alone strips good citations for reasons the other repo had
-// already written down — which is the entire argument for this file.
+// EVERY GUARD BELOW WAS PAID FOR BY A FALSE POSITIVE. npmjs.com 403s scripted
+// requests, an expired certificate is not a dead host, a YouTube /embed/ URL
+// answers 200 for a deleted video, and a connect refusal is usually concurrency
+// rather than death, which serialising per hostname fixes. A sweep missing any
+// one of these strips good citations.
 import { stripTags } from './html.js';
 const DEFAULTS = { timeoutMs: 12_000, slowTimeoutMs: 40_000 };
 /**

package/dist/maps.d.ts

@@ -3,8 +3,6 @@ export interface MapCoords {
     lon: number;
     zoom?: number | undefined;
 }
-/** A plain embed URL for a coordinate pair. */
-export declare function mapsEmbedUrl(lat: number, lon: number, zoom?: number): string;
 /**
  * Dig a coordinate pair out of a maps URL. Four shapes in descending
  * specificity: the `@lat,lon,zoom` path segment, a `/search/lat,lon`, the

package/dist/maps.js

@@ -4,7 +4,7 @@
 // pure string work over Google and Apple Maps URL shapes, with no framework or
 // database in it, which is why neither copy had a reason to diverge.
 /** A plain embed URL for a coordinate pair. */
-export function mapsEmbedUrl(lat, lon, zoom = 15) {
+function mapsEmbedUrl(lat, lon, zoom = 15) {
     return `https://maps.google.com/maps?q=${lat},${lon}&z=${zoom}&output=embed`;
 }
 /**

package/dist/mcp.d.ts

@@ -1,20 +1,38 @@
 /**
- * The versions this transport speaks, newest first.
+ * The modern era: every request carries its own version and client
+ * capabilities in `params._meta`. No handshake, no session, no `ping`, no batch.
+ */
+export declare const MCP_MODERN_VERSIONS: readonly ["2026-07-28"];
+/**
+ * The legacy era, negotiated by an `initialize` handshake.
  *
- * This was a constant answered unconditionally, which is legal and still wrong:
- * a client asking for 2025-06-18 was told 2025-03-26 and silently gave up tool
- * titles, structured output and `_meta`. The last one is where a payment
- * receipt rides, so the one surface that needed it rebuilt this module's HTTP
- * shell by hand to reach it.
+ * Served beside the modern era rather than replaced by it. The spec lets one
+ * endpoint speak both, and a legacy client meeting a dual-era server works;
+ * going modern-only would fail the handshake of every client in the field.
  */
-export declare const MCP_PROTOCOL_VERSIONS: readonly ["2025-06-18", "2025-03-26", "2024-11-05"];
+export declare const MCP_LEGACY_VERSIONS: readonly ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
+/**
+ * Every version this transport speaks, newest first. It is the `supported` list
+ * a `-32022` names and the `supportedVersions` of `server/discover`, so a modern
+ * client that cannot use the newest still learns a legacy fallback exists.
+ */
+export declare const MCP_PROTOCOL_VERSIONS: readonly ["2026-07-28", "2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
 export type McpProtocolVersion = (typeof MCP_PROTOCOL_VERSIONS)[number];
-/** The newest version spoken here, and what an unrecognised ask falls back to. */
+type LegacyVersion = (typeof MCP_LEGACY_VERSIONS)[number];
+/** The newest version spoken here. */
 export declare const MCP_PROTOCOL_VERSION: McpProtocolVersion;
-/** Echo the client's version when it is one we speak, else offer the newest. */
-export declare function negotiateProtocol(requested: unknown): McpProtocolVersion;
-/** The version a post-initialize request is operating under. */
-export declare function requestProtocol(request: Request): McpProtocolVersion;
+/**
+ * The newest version `initialize` can negotiate, and what an unrecognised ask is
+ * offered. A handshake cannot land on a modern version — the modern era has no
+ * handshake — so this, not `MCP_PROTOCOL_VERSION`, is what a legacy client gets.
+ */
+export declare const MCP_LEGACY_PROTOCOL_VERSION: LegacyVersion;
+/** The reserved `_meta` keys the modern era is spelled in. */
+export declare const MCP_META: {
+    readonly protocolVersion: "io.modelcontextprotocol/protocolVersion";
+    readonly clientCapabilities: "io.modelcontextprotocol/clientCapabilities";
+    readonly serverInfo: "io.modelcontextprotocol/serverInfo";
+};
 import { type RateLimitOptions } from './rate-limit.js';
 export type ToolParam = {
     type: 'string' | 'number' | 'boolean' | 'array' | 'object';
@@ -126,6 +144,12 @@ export interface McpServerConfig {
     prompts?: McpPrompt[];
     /** Appended to the GET refusal so a browser that lands here learns where to go. */
     docsUrl?: string;
+    /**
+     * How long, in ms, a modern client may reuse `server/discover`, a list or a
+     * read. The modern era requires the hint on each of those. Defaults to five
+     * minutes: tool and prompt lists only change on deploy.
+     */
+    cacheTtlMs?: number;
     /**
      * Cap on JSON-RPC batch size. The rate limiter charges one token per HTTP
      * request, before the body is parsed — an unbounded batch would let a single
@@ -203,9 +227,16 @@ export declare const toolText: (id: RpcRequest["id"], text: string, isError?: bo
         }[];
     };
 };
+/** The methods one era has and the other does not. Everything else is shared. */
+declare const ERA_METHODS: {
+    readonly legacy: readonly ["initialize", "ping"];
+    readonly modern: readonly ["server/discover"];
+};
+type Era = keyof typeof ERA_METHODS;
 /** Everything the dispatcher needs that is not in the JSON-RPC entry itself. */
 interface Dispatch {
     protocolVersion: McpProtocolVersion;
+    era: Era;
     request?: Request;
 }
 /** Dispatch a parsed body. `null` means notification-only — answer 202, not 200. */