npm - wiki-formant - Versions diffs - 0.23.0 → 0.25.0 - Mend

wiki-formant 0.23.0 → 0.25.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/README.md CHANGED Viewed

@@ -225,6 +225,17 @@ export async function GET(request: Request) {
 `SidebarProvider` / `useSidebar` hold the rail's collapse state — remembered across loads, defaulted from the viewport only when the reader has never chosen. Pair it with `sidebarBootScript` from `wiki-formant/sidebar` (framework-free, so a server component can stamp it into `<head>`) or a remembered-closed rail paints open and animates shut on every load. `TableOfContents` is the "on this page" list, with scroll-spy, reading either headings you already know or the rendered article.
+The rail's breakpoint is necessarily known twice — `matchMedia` here, a media query in your stylesheet — because a media query cannot read a JS constant and a JS constant cannot read a media query. What the two can be stopped from doing is parting in silence, which is the failure that actually happens: all three wikis matched the numbers by hand, all three were right, and nothing said so. Set `--rail-floating: 1` inside the same media query that lays the rail out, and the hook checks the two agree on every breakpoint crossing, in development, naming both sides and the number to change:
+```css
+@media (max-width: 767px) {          /* the edge of breakpoint={768} */
+  :root { --rail-floating: 1; }
+  .sidebar { position: fixed; /* … however this wiki floats its rail */ }
+}
+```
+Declaring the property is what opts a stylesheet in; without it the check stays quiet, since a package cannot require CSS it does not ship. The mechanism is `railBreakpointMismatch` and `readRailFloating` from `wiki-formant/sidebar`, both exported, the first pure.
 `useTypeahead` is the search field's state machine. Five surfaces across the three wikis had three implementations and no two agreed on what a search field does; this is their union, because each had a piece the others lacked:
 ```ts

package/bin/check-pages.mjs ADDED Viewed

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+// bin/check-pages.mjs — what a crawler reads on a rendered page, checked over a
+// whole site instead of one URL at a time.
+//
+// Four defects were found by hand across the three wikis in one September 2026
+// sweep, and each had been live for months because nothing looked at a rendered
+// page as a document. radix.wiki/contents shipped an h1 and no other heading at
+// all, its category names drawn as bare links. acuiq.com's home page went h1,
+// h2, h4, skipping a level. Twenty-seven radix.wiki titles ran past the point a
+// result truncates them, twenty-six of which no audit had counted because the
+// crawl that found the first one reached a quarter of the site. caper.network
+// served every wiki article with no site name in its title, and one route with
+// the title "Wiki" and nothing else.
+//
+// None of these are visible in source review, and all four are one regex over
+// rendered HTML. The rules themselves live in the package next to the things
+// they are about — `outlineIssues` beside the heading injector, `TITLE_BUDGET`
+// beside `pageMetadata` — so an app can apply them at render time too. This
+// only crawls, and reports.
+//
+//   npx check-pages --site https://radix.wiki        # exit 1 on any fault
+//   npx check-pages --site http://localhost:3000     # against a dev server
+//   npx check-pages --site … --limit 200             # default 100
+//   npx check-pages --site … --warn                  # report and exit 0
+//   npx check-pages --site … --json                  # machine-readable
+//
+// URLs come from /sitemap.xml, so a route the sitemap omits is not checked —
+// which is the right default, since an unlisted route is one nobody asked a
+// crawler to read.
+import { outlineIssues } from '../dist/headings.js';
+import { TITLE_BUDGET, TITLE_LIMIT } from '../dist/metadata.js';
+const arg = name => {
+  const i = process.argv.indexOf(name);
+  return i >= 0 ? process.argv[i + 1] : undefined;
+};
+const has = name => process.argv.includes(name);
+const site = (arg('--site') || '').replace(/\/+$/, '');
+const limit = Number(arg('--limit') || 100);
+const WARN_ONLY = has('--warn');
+const JSON_OUT = has('--json');
+if (!site) {
+  console.error('check-pages: --site <origin> is required, e.g. --site https://radix.wiki');
+  process.exit(2);
+}
+const UA = 'wiki-formant/check-pages';
+const get = async url => {
+  const res = await fetch(url, { headers: { 'user-agent': UA, accept: 'text/html,application/xhtml+xml' } });
+  return { status: res.status, body: res.ok ? await res.text() : '' };
+};
+// The sitemap is the URL list, and a sitemap index is one more fetch deep.
+async function sitemapUrls(origin) {
+  const seen = [];
+  const read = async url => {
+    const { status, body } = await get(url);
+    if (status !== 200) return;
+    const locs = [...body.matchAll(/<loc>\s*([^<\s]+)\s*<\/loc>/g)].map(m => m[1]);
+    if (/<sitemapindex/i.test(body)) {
+      for (const child of locs.slice(0, 20)) await read(child);
+    } else {
+      seen.push(...locs);
+    }
+  };
+  await read(`${origin}/sitemap.xml`);
+  // A sitemap states absolute production URLs by definition, so pointing
+  // --site at a dev server would otherwise crawl production and report the
+  // build you were trying to replace. The path is what the sitemap contributes;
+  // the origin is what you asked for.
+  return seen.map(u => {
+    try {
+      const { pathname, search } = new URL(u);
+      return `${origin}${pathname}${search}`;
+    } catch {
+      return u;
+    }
+  });
+}
+const titleOf = html => {
+  const m = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+  return m ? m[1].replace(/\s+/g, ' ').trim() : '';
+};
+const descriptionOf = html => {
+  const m = html.match(/<meta[^>]+name=["']description["'][^>]*>/i);
+  return m ? (m[0].match(/content=["']([\s\S]*?)["']/i)?.[1] ?? '').trim() : null;
+};
+const decode = s =>
+  s.replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#0?39;|&apos;/g, "'");
+const urls = await sitemapUrls(site);
+if (!urls.length) {
+  console.log(`check-pages: no URLs in ${site}/sitemap.xml — nothing to check. Skipping.`);
+  process.exit(0);
+}
+const checked = urls.slice(0, limit);
+const faults = [];
+const titles = new Map();
+for (const url of checked) {
+  let page;
+  try {
+    page = await get(url);
+  } catch (e) {
+    faults.push({ url, fault: 'unreachable', detail: e.message });
+    continue;
+  }
+  if (page.status !== 200) {
+    // A sitemap is a set of promises about what exists; a broken one is the
+    // loudest fault here, so it is reported even though it is not about markup.
+    faults.push({ url, fault: 'sitemapDead', detail: String(page.status) });
+    continue;
+  }
+  for (const issue of outlineIssues(page.body)) {
+    faults.push({
+      url,
+      fault: issue.fault,
+      detail: issue.fault === 'skippedLevel'
+        ? `h${issue.after} → h${issue.level} at "${issue.text?.slice(0, 40)}"`
+        : issue.text?.slice(0, 40) ?? '',
+    });
+  }
+  const title = decode(titleOf(page.body));
+  if (!title) faults.push({ url, fault: 'noTitle', detail: '' });
+  else {
+    if (title.length > TITLE_LIMIT) faults.push({ url, fault: 'titleTooLong', detail: `${title.length} chars: ${title}` });
+    else if (title.length > TITLE_BUDGET) faults.push({ url, fault: 'titleTight', detail: `${title.length} chars: ${title}` });
+    const sharing = titles.get(title);
+    if (sharing) sharing.push(url);
+    else titles.set(title, [url]);
+  }
+  if (descriptionOf(page.body) === null) faults.push({ url, fault: 'noDescription', detail: '' });
+}
+// Reported once per title rather than once per page, or a shared title on forty
+// routes drowns everything else.
+for (const [title, sharing] of titles) {
+  if (sharing.length > 1) {
+    faults.push({ url: sharing[0], fault: 'duplicateTitle', detail: `${sharing.length} pages share "${title}"` });
+  }
+}
+// Two faults are reported and never set the exit code. `noSubheading`: a page
+// that is one h1 and one table — a leaderboard, a token list — has no second
+// section to name, and inventing an h2 to satisfy a checker is the noise this
+// is supposed to remove; it is still reported, because the same shape on a
+// category index meant 190 words of links with no outline at all.
+// `titleTight`: between TITLE_BUDGET and TITLE_LIMIT what a result drops is
+// usually the site name, which is a judgement rather than a defect.
+const ADVISORY = new Set(['noSubheading', 'titleTight']);
+const failing = faults.filter(f => !ADVISORY.has(f.fault));
+if (JSON_OUT) {
+  console.log(JSON.stringify({ site, checked: checked.length, of: urls.length, failing: failing.length, faults }, null, 2));
+} else {
+  const byFault = new Map();
+  for (const f of faults) byFault.set(f.fault, [...(byFault.get(f.fault) ?? []), f]);
+  console.log(`check-pages: ${checked.length} of ${urls.length} sitemap URLs on ${site}\n`);
+  if (!faults.length) console.log('  clean — one h1 per page, no skipped levels, every title inside the budget.');
+  else if (!failing.length) console.log('  no failures; everything below is advisory.\n');
+  for (const [fault, list] of [...byFault].sort((a, b) => b[1].length - a[1].length)) {
+    console.log(`  ${fault} (${list.length})${ADVISORY.has(fault) ? '  — advisory, does not fail' : ''}`);
+    for (const f of list.slice(0, 12)) console.log(`    ${f.url.replace(site, '') || '/'}${f.detail ? `  ${f.detail}` : ''}`);
+    if (list.length > 12) console.log(`    … and ${list.length - 12} more`);
+    console.log('');
+  }
+}
+process.exit(failing.length && !WARN_ONLY ? 1 : 0);

package/dist/headings.d.ts CHANGED Viewed

@@ -53,3 +53,42 @@ export declare function injectHeadingIds(html: string, options?: HeadingIdOption
  * consumers use only the injector above.
  */
 export declare function headingsFrom(html: string): Heading[];
+/**
+ * Every heading in `html`, in document order, whether or not it carries an id —
+ * the outline a crawler reads. `headingsFrom` above answers a different
+ * question: which headings a rail can link to, which is why it drops the ones
+ * with no id. An audit must not, because a chrome heading with no id still
+ * takes a level in the outline, and the levels are the thing under test.
+ */
+export declare function headingOutline(html: string): Heading[];
+/**
+ * What is wrong with a page's heading outline.
+ *
+ * `noH1` and `multipleH1` are unambiguous. `skippedLevel` means a heading sits
+ * more than one level below the one before it — an h2 followed by an h4, which
+ * is what acuiq.com's home page shipped. `noSubheading` means the page has an
+ * h1 and nothing under it at all, which is what radix.wiki's /contents shipped:
+ * a category index whose section names were rendered as bare links, leaving a
+ * document with no outline for a reader or a parser to move through.
+ *
+ * What none of these catch is a heading at the right level under the wrong
+ * parent. radix.wiki's /ecosystem listed 140 projects as h3 beneath the single
+ * h2 of an unrelated prose section; every level was legal and the nesting was a
+ * lie. That one needs a person.
+ */
+export type OutlineFault = 'noH1' | 'multipleH1' | 'skippedLevel' | 'noSubheading';
+export interface OutlineIssue {
+    fault: OutlineFault;
+    /** The offending heading's level, where the fault names one. */
+    level?: number;
+    /** The level it followed, for `skippedLevel`. */
+    after?: number;
+    /** Its text, trimmed, for `skippedLevel` and `multipleH1`. */
+    text?: string;
+}
+/**
+ * `html` is a whole rendered page, not a content fragment: the outline a
+ * crawler sees includes the chrome. A page with no headings at all returns a
+ * single `noH1` and nothing else, since every later rule would restate it.
+ */
+export declare function outlineIssues(html: string): OutlineIssue[];

package/dist/headings.js CHANGED Viewed

@@ -86,3 +86,46 @@ export function headingsFrom(html) {
     }
     return out;
 }
+/**
+ * Every heading in `html`, in document order, whether or not it carries an id —
+ * the outline a crawler reads. `headingsFrom` above answers a different
+ * question: which headings a rail can link to, which is why it drops the ones
+ * with no id. An audit must not, because a chrome heading with no id still
+ * takes a level in the outline, and the levels are the thing under test.
+ */
+export function headingOutline(html) {
+    const out = [];
+    for (const [, tag, attrs, content] of html.matchAll(HEADING)) {
+        const text = stripTags(content ?? '');
+        if (text)
+            out.push({ id: getAttr(attrs ?? '', 'id') ?? '', text, level: Number(tag[1]) });
+    }
+    return out;
+}
+/**
+ * `html` is a whole rendered page, not a content fragment: the outline a
+ * crawler sees includes the chrome. A page with no headings at all returns a
+ * single `noH1` and nothing else, since every later rule would restate it.
+ */
+export function outlineIssues(html) {
+    const headings = headingOutline(html);
+    const issues = [];
+    const h1s = headings.filter(h => h.level === 1);
+    if (h1s.length === 0)
+        issues.push({ fault: 'noH1' });
+    else
+        for (const extra of h1s.slice(1))
+            issues.push({ fault: 'multipleH1', level: 1, text: extra.text });
+    if (!headings.length)
+        return issues;
+    let previous = 0;
+    for (const h of headings) {
+        if (previous && h.level > previous + 1) {
+            issues.push({ fault: 'skippedLevel', level: h.level, after: previous, text: h.text });
+        }
+        previous = h.level;
+    }
+    if (h1s.length === 1 && headings.length === 1)
+        issues.push({ fault: 'noSubheading', level: 1 });
+    return issues;
+}

package/dist/http.d.ts CHANGED Viewed

@@ -99,7 +99,17 @@ export declare function descriptorResponse(request: Request, body: unknown, opts
     maxAge?: number;
     extra?: Record<string, string>;
 }): Response;
-/** Strip URLs and collapse whitespace so an excerpt stays one readable line. */
+/**
+ * Strip URLs and collapse whitespace so an excerpt stays one readable line.
+ *
+ * A markdown link whose text is kept and whose target is not leaves the target
+ * behind in parentheses, and only the absolute form was being removed: an
+ * excerpt opening "[Decentralized science (DeSci)](/wiki/desci/what-is-desci)
+ * runs into…" reached a meta description as "Decentralized science (DeSci)
+ * (/wiki/desci/what-is-desci) runs into…". Root-relative targets and bare
+ * anchors go the same way as absolute ones. The leading character is what
+ * separates a target from ordinary parenthetical prose, so "(DeSci)" survives.
+ */
 export declare function cleanSnippet(text: string, max?: number): string;
 /** One markdown bullet: linked title, excerpt, and the date an agent diffs on. */
 export declare function pageLine(opts: {

package/dist/http.js CHANGED Viewed

@@ -164,10 +164,21 @@ export function descriptorResponse(request, body, opts = {}) {
     const sent = descriptorHeaders(etag, opts);
     return notModified(request, etag, null, sent) ?? new Response(text, { headers: sent });
 }
-/** Strip URLs and collapse whitespace so an excerpt stays one readable line. */
+/**
+ * Strip URLs and collapse whitespace so an excerpt stays one readable line.
+ *
+ * A markdown link whose text is kept and whose target is not leaves the target
+ * behind in parentheses, and only the absolute form was being removed: an
+ * excerpt opening "[Decentralized science (DeSci)](/wiki/desci/what-is-desci)
+ * runs into…" reached a meta description as "Decentralized science (DeSci)
+ * (/wiki/desci/what-is-desci) runs into…". Root-relative targets and bare
+ * anchors go the same way as absolute ones. The leading character is what
+ * separates a target from ordinary parenthetical prose, so "(DeSci)" survives.
+ */
 export function cleanSnippet(text, max = 160) {
     return text
-        .replace(/\(https?:\/\/[^)]*\)/g, '')
+        .replace(/\((?:https?:\/\/|mailto:)[^)]*\)/g, '')
+        .replace(/\((?:\/|#)[^)\s]*\)/g, '')
         .replace(/https?:\/\/\S+/g, '')
         .replace(/\(\s*\)/g, '')
         .replace(/\s{2,}/g, ' ')

package/dist/metadata.d.ts CHANGED Viewed

@@ -121,3 +121,57 @@ export declare function collectionLd(o: CollectionLdOptions): LdNode;
  * an authored `&amp;` is not what a crawler reads.
  */
 export declare function citationsFromReferences(items: readonly ReferenceItem[], max?: number): LdNode[];
+/**
+ * Characters a document `<title>` has before a search result truncates it.
+ *
+ * Google measures pixels, not characters, so this is the round number that
+ * approximates ~580px of the default result font and is what every audit in
+ * these repos has counted against. The budget covers the WHOLE rendered title,
+ * template included: a wiki spending 13 of it on " | RADIX Wiki" has 47 left,
+ * which is the number that matters to whoever writes the title.
+ */
+export declare const TITLE_BUDGET = 60;
+/**
+ * Past this, a title is not merely trimmed but cut into.
+ *
+ * Between the budget and this limit a title loses its tail, which is often the
+ * site name and no loss at all. Past it, the words carrying what the page is
+ * about are going too: the radix.wiki ideas board spent its first sixteen
+ * characters on a working group and reached 93, and the symptom pages on
+ * acuiq.com reached 88 before naming the symptom. That is the line worth
+ * failing a build over; the band below it is worth reporting and no more.
+ */
+export declare const TITLE_LIMIT = 70;
+/**
+ * The document `<title>` for a page: its short form where the page carries one,
+ * else its own title.
+ *
+ * A wiki title is written for the H1 and the listing card, where a prefix that
+ * groups the page earns its space — "Governance WG · ", "Radix Week in Review: ".
+ * In a search result the same prefix spends the budget before the topic arrives,
+ * so a page may store a short form under `key` and the document title takes it.
+ * Nothing else does: the H1, the listing card, the markdown twin and the social
+ * card all keep the page's own title, and `pageMetadata` above is deliberately
+ * not wired to this, because a social card is not length-constrained the same
+ * way and the full title reads better on one.
+ */
+export declare function documentTitle(title: string, metadata: unknown, key?: string): string;
+/**
+ * The longest of `variants` whose rendered length fits, or the shortest one
+ * when none of them do.
+ *
+ * `documentTitle` above is for a page whose short form someone wrote down. A
+ * generated page has no one to write it: acuiq.com composes a point's title
+ * from its code, its pinyin and its English name, which is 37 characters for
+ * LI04 Hegu and 148 for a point carrying three names and three pinyin
+ * readings. A single template cannot serve both, and truncating mid-word
+ * serves neither. Ordering the forms from fullest to barest and taking the
+ * first that fits keeps the English name on the pages where a result would
+ * show it and drops it only where it would have been cut off anyway.
+ *
+ * `suffix` is the template's, counted but not returned - Next applies it.
+ */
+export declare function fittingTitle(variants: readonly string[], opts?: {
+    suffix?: string;
+    limit?: number;
+}): string;

package/dist/metadata.js CHANGED Viewed

@@ -107,3 +107,63 @@ export function citationsFromReferences(items, max = 50) {
     })
         .slice(0, max);
 }
+/**
+ * Characters a document `<title>` has before a search result truncates it.
+ *
+ * Google measures pixels, not characters, so this is the round number that
+ * approximates ~580px of the default result font and is what every audit in
+ * these repos has counted against. The budget covers the WHOLE rendered title,
+ * template included: a wiki spending 13 of it on " | RADIX Wiki" has 47 left,
+ * which is the number that matters to whoever writes the title.
+ */
+export const TITLE_BUDGET = 60;
+/**
+ * Past this, a title is not merely trimmed but cut into.
+ *
+ * Between the budget and this limit a title loses its tail, which is often the
+ * site name and no loss at all. Past it, the words carrying what the page is
+ * about are going too: the radix.wiki ideas board spent its first sixteen
+ * characters on a working group and reached 93, and the symptom pages on
+ * acuiq.com reached 88 before naming the symptom. That is the line worth
+ * failing a build over; the band below it is worth reporting and no more.
+ */
+export const TITLE_LIMIT = 70;
+/**
+ * The document `<title>` for a page: its short form where the page carries one,
+ * else its own title.
+ *
+ * A wiki title is written for the H1 and the listing card, where a prefix that
+ * groups the page earns its space — "Governance WG · ", "Radix Week in Review: ".
+ * In a search result the same prefix spends the budget before the topic arrives,
+ * so a page may store a short form under `key` and the document title takes it.
+ * Nothing else does: the H1, the listing card, the markdown twin and the social
+ * card all keep the page's own title, and `pageMetadata` above is deliberately
+ * not wired to this, because a social card is not length-constrained the same
+ * way and the full title reads better on one.
+ */
+export function documentTitle(title, metadata, key = 'seoTitle') {
+    const short = metadata?.[key];
+    return typeof short === 'string' && short.trim() ? short : title;
+}
+/**
+ * The longest of `variants` whose rendered length fits, or the shortest one
+ * when none of them do.
+ *
+ * `documentTitle` above is for a page whose short form someone wrote down. A
+ * generated page has no one to write it: acuiq.com composes a point's title
+ * from its code, its pinyin and its English name, which is 37 characters for
+ * LI04 Hegu and 148 for a point carrying three names and three pinyin
+ * readings. A single template cannot serve both, and truncating mid-word
+ * serves neither. Ordering the forms from fullest to barest and taking the
+ * first that fits keeps the English name on the pages where a result would
+ * show it and drops it only where it would have been cut off anyway.
+ *
+ * `suffix` is the template's, counted but not returned - Next applies it.
+ */
+export function fittingTitle(variants, opts = {}) {
+    const { suffix = '', limit = TITLE_LIMIT } = opts;
+    const usable = variants.map(v => v.trim()).filter(Boolean);
+    if (!usable.length)
+        return '';
+    return usable.find(v => v.length + suffix.length <= limit) ?? usable[usable.length - 1];
+}

package/dist/react.d.ts CHANGED Viewed

@@ -423,6 +423,13 @@ export declare function RailShell({ children, prefix, label, className }: RailSh
  * matched on the PATH ONLY, deliberately: `?edit=` and `?history=` are modes a
  * page enters, not destinations a rail selects, and reading them would drag
  * `useSearchParams` into a statically-rendered wiki.
+ *
+ * The path is decoded first. Next serves a catch-all route's prerender with the
+ * joined segments percent-encoded — `/wiki/tech%2Fcore-concepts` for
+ * `/wiki/tech/core-concepts` — so an encoded path matches neither its own href
+ * nor its section's prefix, and React does not patch a className on hydration.
+ * Both wikis were shipping every page below the top level with nothing in the
+ * rail marked, and it only came right if you arrived by client navigation.
  */
 export declare function isRailLinkActive(activePath: string, href: string, tree?: boolean): boolean;
 export type { WikiLinkComponent, WikiLinkProps } from './react-server.js';

package/dist/react.js CHANGED Viewed

@@ -26,7 +26,7 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 //      `sidebarBootScript`, a blocking inline script that stamps the remembered
 //      state on <html> before first paint. The hook keeps that attribute in
 //      sync afterwards, so CSS has one source of truth either side of hydration.
-import { resolveSidebarOpen, SIDEBAR_ATTRIBUTE } from './sidebar.js';
+import { railBreakpointMismatch, readRailFloating, resolveSidebarOpen, SIDEBAR_ATTRIBUTE, } from './sidebar.js';
 import { activateTabGroups, addCopyButtons, hydrateTweetEmbeds, onTweetResize, sizeTweetEmbeds, sortTables } from './dom.js';
 import { comboboxAria } from './combobox.js';
 import { Component, createContext, createElement, useCallback, useContext, useEffect, useId, useMemo, useRef, useState, } from 'react';
@@ -65,6 +65,19 @@ function useCollapsibleSidebar(options = {}) {
             setIsMobile(matches);
             // The breakpoint supplies a default, never an override. This is bug 1.
             setOpenState(current => resolveSidebarOpen({ chosen: chosen.current, current, stored, isMobile: matches }));
+            // The same number lives in the stylesheet, and must. Say so out loud the
+            // moment the two part, rather than leaving it to whoever next opens the
+            // rail on a phone. Development only: this is a wiring mistake, caught
+            // once at the desk, not a condition to watch for in production.
+            if (process.env.NODE_ENV !== 'production') {
+                const complaint = railBreakpointMismatch({
+                    isMobile: matches,
+                    floating: readRailFloating(),
+                    breakpoint,
+                });
+                if (complaint)
+                    console.error(complaint);
+            }
         };
         apply(mql.matches);
         setReady(true);
@@ -137,8 +150,15 @@ export function TableOfContents({ containerSelector, headings: providedHeadings,
             // article per mutation is what makes a rail janky.
             timer = setTimeout(() => {
                 const root = document.querySelector(containerSelector);
-                if (!root)
+                // No container is an answer, not a reason to skip: a rail that bailed
+                // here kept the LAST page's headings, so a section index reached from
+                // one of its own articles listed that article's sections under "on this
+                // page". It only looked right when a loading skeleton happened to render
+                // the container and scan to nothing.
+                if (!root) {
+                    setScanned(prev => (prev.length ? [] : prev));
                     return;
+                }
                 const used = new Set();
                 const next = [];
                 for (const el of Array.from(root.querySelectorAll('h1, h2, h3'))) {
@@ -747,10 +767,29 @@ export function RailShell({ children, prefix, label, className }) {
  * matched on the PATH ONLY, deliberately: `?edit=` and `?history=` are modes a
  * page enters, not destinations a rail selects, and reading them would drag
  * `useSearchParams` into a statically-rendered wiki.
+ *
+ * The path is decoded first. Next serves a catch-all route's prerender with the
+ * joined segments percent-encoded — `/wiki/tech%2Fcore-concepts` for
+ * `/wiki/tech/core-concepts` — so an encoded path matches neither its own href
+ * nor its section's prefix, and React does not patch a className on hydration.
+ * Both wikis were shipping every page below the top level with nothing in the
+ * rail marked, and it only came right if you arrived by client navigation.
  */
 export function isRailLinkActive(activePath, href, tree = false) {
-    return tree ? activePath === href || activePath.startsWith(`${href}/`) : activePath === href;
+    const path = decodePath(activePath);
+    return tree ? path === href || path.startsWith(`${href}/`) : path === href;
 }
+/** `decodeURIComponent` throws on a stray `%`; a path it cannot read is its own answer. */
+const decodePath = (path) => {
+    if (!path.includes('%'))
+        return path;
+    try {
+        return decodeURIComponent(path);
+    }
+    catch {
+        return path;
+    }
+};
 // ---- rendered-article passes --------------------------------------------------
 /**
  * The `wiki-formant/dom` passes over a rendered article: tab groups, copy

package/dist/sidebar.d.ts CHANGED Viewed

@@ -20,6 +20,42 @@ export declare function resolveSidebarOpen({ chosen, current, stored, isMobile,
 }): boolean;
 /** The attribute the boot script and the hook both write to `<html>`. */
 export declare const SIDEBAR_ATTRIBUTE = "data-sidebar";
+/**
+ * The custom property a consumer's stylesheet sets inside its own rail media
+ * query — `1` where the rail stops being a column beside the article, `0`
+ * elsewhere.
+ *
+ * The rail's breakpoint is necessarily known twice: this hook needs it in JS
+ * (to close the rail on navigate, and to default a first-ever visit), and the
+ * stylesheet needs it in CSS (to lay the rail out, before any script runs and
+ * whether or not one ever does). A media query cannot read a JS constant and a
+ * JS constant cannot read a media query, so the two numbers cannot be merged —
+ * but they can be made unable to disagree QUIETLY, which is the actual hazard.
+ *
+ * All three wikis matched by hand and all three happened to be right; nothing
+ * said so. Declaring this property is what opts a stylesheet into the check.
+ */
+export declare const RAIL_FLOATING_PROPERTY = "--rail-floating";
+/**
+ * What the stylesheet currently says about the rail: `true` inside the repo's
+ * rail media query, `false` outside it, `null` when the property is not
+ * declared — a consumer that has not opted in, or a render with no DOM.
+ */
+export declare function readRailFloating(): boolean | null;
+/**
+ * The complaint to make when CSS and JS disagree about where the rail floats,
+ * or `null` when they agree or the stylesheet has not opted in.
+ *
+ * Pure, and separate from the reading, so the rule is testable without a DOM.
+ */
+export declare function railBreakpointMismatch({ isMobile, floating, breakpoint, }: {
+    /** What `matchMedia` told the hook. */
+    isMobile: boolean;
+    /** What the stylesheet says, from `readRailFloating()`. */
+    floating: boolean | null;
+    /** The breakpoint the hook was given, for naming the number in the message. */
+    breakpoint: number;
+}): string | null;
 /**
  * A blocking inline script for the document head, so the rail's first paint
  * already matches what the reader last chose.

package/dist/sidebar.js CHANGED Viewed

@@ -21,6 +21,60 @@ export function resolveSidebarOpen({ chosen, current, stored, isMobile, }) {
 }
 /** The attribute the boot script and the hook both write to `<html>`. */
 export const SIDEBAR_ATTRIBUTE = 'data-sidebar';
+/**
+ * The custom property a consumer's stylesheet sets inside its own rail media
+ * query — `1` where the rail stops being a column beside the article, `0`
+ * elsewhere.
+ *
+ * The rail's breakpoint is necessarily known twice: this hook needs it in JS
+ * (to close the rail on navigate, and to default a first-ever visit), and the
+ * stylesheet needs it in CSS (to lay the rail out, before any script runs and
+ * whether or not one ever does). A media query cannot read a JS constant and a
+ * JS constant cannot read a media query, so the two numbers cannot be merged —
+ * but they can be made unable to disagree QUIETLY, which is the actual hazard.
+ *
+ * All three wikis matched by hand and all three happened to be right; nothing
+ * said so. Declaring this property is what opts a stylesheet into the check.
+ */
+export const RAIL_FLOATING_PROPERTY = '--rail-floating';
+/**
+ * What the stylesheet currently says about the rail: `true` inside the repo's
+ * rail media query, `false` outside it, `null` when the property is not
+ * declared — a consumer that has not opted in, or a render with no DOM.
+ */
+export function readRailFloating() {
+    if (typeof document === 'undefined')
+        return null;
+    try {
+        const value = getComputedStyle(document.documentElement)
+            .getPropertyValue(RAIL_FLOATING_PROPERTY)
+            .trim();
+        return value === '' ? null : value === '1';
+    }
+    catch {
+        // No CSSOM (jsdom without styles, a blocked stylesheet). Not knowing is not
+        // a mismatch, and a diagnostic must never be the thing that breaks a page.
+        return null;
+    }
+}
+/**
+ * The complaint to make when CSS and JS disagree about where the rail floats,
+ * or `null` when they agree or the stylesheet has not opted in.
+ *
+ * Pure, and separate from the reading, so the rule is testable without a DOM.
+ */
+export function railBreakpointMismatch({ isMobile, floating, breakpoint, }) {
+    if (floating === null || floating === isMobile)
+        return null;
+    return (`wiki-formant: the rail's breakpoint disagrees between CSS and JS. ` +
+        `This hook was given breakpoint=${breakpoint}, so it believes the rail ` +
+        `${isMobile ? 'should float' : 'should be a column'} at this width, ` +
+        `while ${RAIL_FLOATING_PROPERTY} says it ` +
+        `${floating ? 'should float' : 'should be a column'}. ` +
+        `Set ${RAIL_FLOATING_PROPERTY}: 1 inside the same media query that lays the ` +
+        `rail out, and give that query the edge of breakpoint=${breakpoint} ` +
+        `(max-width: ${breakpoint - 1}px).`);
+}
 /**
  * A blocking inline script for the document head, so the rail's first paint
  * already matches what the reader last chose.

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "The portable half of a wiki: derived taxonomy and facet controls, a version-negotiating MCP transport, markdown twins, block rendering, a rich-text editor engine, and conditional-GET plumbing.",
   "type": "module",
   "license": "MIT",
@@ -18,7 +18,9 @@
     "markdown",
     "agent"
   ],
-  "sideEffects": ["*.css"],
+  "sideEffects": [
+    "*.css"
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -175,7 +177,8 @@
     }
   },
   "bin": {
-    "check-classes": "./bin/check-classes.mjs"
+    "check-classes": "./bin/check-classes.mjs",
+    "check-pages": "./bin/check-pages.mjs"
   },
   "files": [
     "dist",