wiki-formant 0.2.1 → 0.3.0

package/README.md

@@ -47,6 +47,24 @@ Four behaviours worth knowing, because each replaces a plausible wrong answer:
 
 One `href` builder is passed in and used by every chip, letter and sort button. A sort button that drops the active filters is the tell that a project grew a second one.
 
+## Headings
+
+Heading ids, permalink anchors, and the list an "on this page" rail renders — one pass over the HTML you already have.
+
+```ts
+import { injectHeadingIds, headingsFrom } from 'wiki-formant/headings';
+
+const html = injectHeadingIds(page.body);   // ids + anchors, idempotent
+const toc  = headingsFrom(html);            // [{ id, text, level }]
+```
+
+Two behaviours worth knowing:
+
+- **The slug rule is a parameter.** A heading id is a live URL — readers link to `#the-shape-of-a-code`, and so does the page's own permalink anchor. The two wikis this was lifted from had drifted onto different rules, and unifying them would have silently moved every published anchor on whichever one lost. Pass `slug` to keep the rule you already ship.
+- **Deduping is not a parameter.** Two headings with the same text otherwise mint the same id twice, and every link to the second lands on the first. The copy that lacked it had that bug.
+
+`headingsFrom` reads the string, not the rendered DOM — possible only where the body IS a string at render time. A wiki whose content streams in as blocks after mount has to query the DOM, and uses only the injector.
+
 ## MCP
 
 A minimal [Model Context Protocol](https://modelcontextprotocol.io) server over Streamable HTTP, with the transport edges most implementations get wrong.
@@ -135,6 +153,7 @@ export async function GET(request: Request) {
 | 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`, `cleanSnippet`, `pageLine` | `wiki-formant/http` |

package/dist/headings.d.ts

@@ -0,0 +1,42 @@
+/** A heading found in a page's HTML, in document order. */
+export interface Heading {
+    id: string;
+    text: string;
+    /** 1 for `<h1>`, 2 for `<h2>`, and so on. */
+    level: number;
+}
+/** The default slug rule: lowercase words joined by hyphens. */
+export declare function slugifyHeading(text: string): string;
+export interface HeadingIdOptions {
+    /**
+     * How heading text becomes an id. Defaults to `slugifyHeading`. Pass the rule
+     * your wiki has already published ids under — see the note at the top of this
+     * file about why this is not standardised.
+     */
+    slug?: (text: string) => string;
+    /**
+     * Emitted after the heading text so a reader can link to the section. Return
+     * `''` for no anchor. The default is deliberately empty of text — its glyph
+     * comes from CSS, so it never leaks into a heading's `textContent` and out
+     * into a TOC label.
+     */
+    anchor?: (id: string) => string;
+}
+/**
+ * Give every heading in `html` an id and a permalink anchor. Headings that
+ * already carry an id keep it, and a heading already carrying an anchor is left
+ * alone, so this is safe to run twice over the same string.
+ */
+export declare function injectHeadingIds(html: string, options?: HeadingIdOptions): string;
+/**
+ * The headings in `html` that carry an id, in document order — the list an "on
+ * this page" rail renders. Run it over the output of `injectHeadingIds` and
+ * every heading is in it.
+ *
+ * Reading the string rather than the rendered DOM is only possible where the
+ * body IS a string at render time. A wiki whose content streams in as blocks
+ * after mount has to query the DOM instead, which is why two of the three
+ * consumers use only the injector above.
+ */
+export declare function headingsFrom(html: string): Heading[];
+//# sourceMappingURL=headings.d.ts.map

package/dist/headings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headings.d.ts","sourceRoot":"","sources":["../src/headings.ts"],"names":[],"mappings":"AAoBA,2DAA2D;AAC3D,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAC;CACf;AAED,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOnD;AAUD,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAChC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;CACjC;AAKD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,MAAM,CAkBrF;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CAQpD"}

package/dist/headings.js

@@ -0,0 +1,81 @@
+// 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
+// existing anchor on whichever wiki lost, so the rule each has shipped is the
+// rule it keeps, stated at its call site instead of buried in a helper.
+//
+// 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 default slug rule: lowercase words joined by hyphens. */
+export function slugifyHeading(text) {
+    return text
+        .toLowerCase()
+        .trim()
+        .replace(/[^\w\s-]/g, '')
+        .replace(/[\s_-]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+const HEADING = /<(h[1-6])([^>]*)>([\s\S]*?)<\/\1>/gi;
+const stripTags = (s) => s.replace(/<[^>]*>/g, '').replace(/&nbsp;/g, ' ').replace(/&amp;/g, '&').trim();
+const getAttr = (attrs, name) => attrs.match(new RegExp(`\\s${name}\\s*=\\s*"([^"]*)"`, 'i'))?.[1] ?? null;
+const defaultAnchor = (id) => `<a class="heading-anchor" href="#${id}" aria-label="Permalink to this section" tabindex="-1"></a>`;
+/**
+ * Give every heading in `html` an id and a permalink anchor. Headings that
+ * already carry an id keep it, and a heading already carrying an anchor is left
+ * alone, so this is safe to run twice over the same string.
+ */
+export function injectHeadingIds(html, options = {}) {
+    if (!html.trim())
+        return html;
+    const slug = options.slug ?? slugifyHeading;
+    const anchor = options.anchor ?? defaultAnchor;
+    const used = new Set();
+    return html.replace(HEADING, (match, tag, attrs, content) => {
+        if (content.includes('heading-anchor'))
+            return match;
+        const existing = getAttr(attrs, 'id');
+        let id = existing || slug(stripTags(content));
+        if (!id)
+            return match;
+        if (!existing) {
+            const base = id;
+            let n = 2;
+            while (used.has(id))
+                id = `${base}-${n++}`;
+        }
+        used.add(id);
+        return `<${tag}${existing ? attrs : `${attrs} id="${id}"`}>${content}${anchor(id)}</${tag}>`;
+    });
+}
+/**
+ * The headings in `html` that carry an id, in document order — the list an "on
+ * this page" rail renders. Run it over the output of `injectHeadingIds` and
+ * every heading is in it.
+ *
+ * Reading the string rather than the rendered DOM is only possible where the
+ * body IS a string at render time. A wiki whose content streams in as blocks
+ * after mount has to query the DOM instead, which is why two of the three
+ * consumers use only the injector above.
+ */
+export function headingsFrom(html) {
+    const out = [];
+    for (const [, tag, attrs, content] of html.matchAll(HEADING)) {
+        const id = getAttr(attrs ?? '', 'id');
+        const text = stripTags(content ?? '');
+        if (id && text)
+            out.push({ id, text, level: Number(tag[1]) });
+    }
+    return out;
+}
+//# sourceMappingURL=headings.js.map

package/dist/headings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"headings.js","sourceRoot":"","sources":["../src/headings.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from './taxonomy.js';
 export * from './mcp.js';
+export * from './headings.js';
 export * from './markdown.js';
 export * from './entities.js';
 export * from './http.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC"}

package/dist/index.js

@@ -5,6 +5,7 @@
 // then lets drift.
 export * from './taxonomy.js';
 export * from './mcp.js';
+export * from './headings.js';
 export * from './markdown.js';
 export * from './entities.js';
 export * from './http.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,EAAE;AACF,6EAA6E;AAC7E,6EAA6E;AAC7E,mBAAmB;AAEnB,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,EAAE;AACF,6EAA6E;AAC7E,6EAA6E;AAC7E,mBAAmB;AAEnB,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "The portable half of a wiki: derived taxonomy, a spec-correct MCP transport, markdown twins, block rendering, rate limiting, and the conditional-GET plumbing agent surfaces need. Zero runtime dependencies.",
   "type": "module",
   "license": "MIT",
@@ -34,6 +34,10 @@
       "types": "./dist/mcp.d.ts",
       "import": "./dist/mcp.js"
     },
+    "./headings": {
+      "types": "./dist/headings.d.ts",
+      "import": "./dist/headings.js"
+    },
     "./markdown": {
       "types": "./dist/markdown.d.ts",
       "import": "./dist/markdown.js"