fewrd 0.1.0

package/README.md

@@ -0,0 +1,108 @@
+<div align="center">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset=".github/fewrd-logo.svg">
+  <img src=".github/fewrd-logo-neg.svg" alt="fewrd" width="380">
+</picture>
+
+**Finds what recurs in a string, cuts it loose, and gets you the gist in a
+few words.**
+
+![dependencies: 0](https://img.shields.io/badge/dependencies-0-78C4B6?style=flat-square)
+![types: strict](https://img.shields.io/badge/types-strict-78C4B6?style=flat-square)
+![tests: 18 passing](https://img.shields.io/badge/tests-18%20passing-78C4B6?style=flat-square)
+
+</div>
+
+---
+
+## Why
+
+Your text is hiding treasure: protocol numbers under five different aliases,
+dates wedged between dashes, amounts that only count with a `€` stapled on.
+fewrd digs it all out in one pass, remembers exactly where each piece lives,
+then folds away whatever a reader doesn't need — no regex spaghetti, no
+stray commas left behind.
+
+```
+normalise → anchors → expand → merge → segment  ⇒  Cuts      (depends on text + book only: cacheable)
+                                    render(Cuts, fold)  ⇒  gist | tagged html   (always dynamic)
+```
+
+## See it fold
+
+A real case, unfolded:
+
+> Pec - Prot. n. 0023993 del 23/09/2026 - Misura 1.7.2 della missione 1, componente 1 del PNRR "Rete dei servizi di facilitazione digitale" - Comune di Ghilarza - CUP F84D26000210006 - Trasmissione cronoprogramma procedurale
+
+The same reading, with `protocol` and `cup` folded away:
+
+> Misura 1.7.2 della missione 1, componente 1 del PNRR "Rete dei servizi di facilitazione digitale" - Comune di Ghilarza - Trasmissione cronoprogramma procedurale
+
+No dangling dash where the protocol number used to sit, no orphaned separator
+before "Trasmissione" — fewrd decides which separator survives a fold and
+which bracket empties out along with what was inside it. Both strings come
+from the same `Cuts`; nothing gets re-parsed to produce the second one.
+
+## The pieces
+
+| name | what it is |
+|---|---|
+| `Recipe` | one pattern: a strict `anchor` (the value), closed lists of `left`/`right` neighbours (label, channel, date…), `requires`, `resolve`, `weak`, `rest` |
+| `Book` | recipes in priority order, plus a `version` that keys a cached reading |
+| `Mention` | one recognised thing: its `extent`, its `parts` in text order, a canonical `value`, and its `parent` when nested |
+| `Leaf` | one piece of the partition: `text`, `sep`, `open`, `close`, or a mention's `part` |
+| `Cuts` | the reading: `text`, `mentions`, `leaves`. The leaves cover the text in order, with no gap and no overlap. Survives a JSON round-trip |
+| `Fold` | the caller's policy: which mentions a condensed view drops |
+
+## The rules
+
+- **Anchors are strict and neighbours are generous.** A neighbour's regex is
+  pinned to the edge it grows from. Each neighbour attaches at most once, and
+  after each attachment the list is tried again from the top.
+- **Nothing cuts a word.** An anchor or a neighbour may not start or end
+  inside a run of letters or digits (opt out with `glued`).
+- **Longest extent wins, then priority.** `weak` recipes only fill gaps.
+- **A `rest` recipe runs to the end of its level**, and what follows its
+  anchor is read again inside it. Folding it folds everything it holds.
+- **Separator fate.** Separators between two surviving leaves stay untouched
+  when no fold fell among them. Otherwise only the strongest survives
+  (`-` > `;` > `:` > `,` > space), and none survives at an edge, after an
+  opening bracket or before closing punctuation. Brackets a fold empties go
+  with it.
+- **One HTML, both views.** `html()` emits every leaf and marks what the
+  condensed view drops with `data-fold`. The whole switch is
+  `.condensed [data-fold] { display: none }`.
+
+## Use
+
+```ts
+import { read, gist, html } from 'fewrd';
+import { itPa } from 'fewrd/recipes/it-pa';
+
+const cuts = read(subject, itPa);
+const fold = (m) => ['protocol', 'cup'].includes(m.entity);
+gist(cuts, fold);  // plain text
+html(cuts, fold);  // tagged, both views
+```
+
+## Try it
+
+```bash
+pnpm dev   # playground on 5577 — every case in playground/cases.ts, folded and whole
+```
+
+## Recipes
+
+`recipes/it-pa.ts` is the first book: Italian public administration codes
+(protocol, CIG, CUP, chapter, amount, date, capitals tags, «con oggetto»).
+`playground/cases.ts` holds the cases. The tests read those same cases.
+
+## Work
+
+```bash
+pnpm test        # node --test, type stripping, no build
+pnpm typecheck
+pnpm dev         # playground on 5577
+pnpm build       # dist/ for package consumers (runs automatically on publish)
+```

package/dist/recipes/it-pa.d.ts

@@ -0,0 +1,11 @@
+import type { Book, Recipe } from '../src/index.ts';
+export declare const protocol: Recipe;
+export declare const cig: Recipe;
+export declare const cup: Recipe;
+export declare const chapter: Recipe;
+export declare const amount: Recipe;
+export declare const date: Recipe;
+export declare const caps: Recipe;
+/** From «con oggetto» to the end of its level, read again inside. */
+export declare const quotation: Recipe;
+export declare const itPa: Book;

package/dist/recipes/it-pa.js

@@ -0,0 +1,77 @@
+// Italian public administration: the codes users stuff into a document's
+// «oggetto». Labels vary wildly, values never do — so every anchor is strict
+// and every label generous. Ported from sibardoc-prototype's subject fold.
+const DATE = String.raw `\d{1,2}[\/.\-]\d{1,2}[\/.\-]\d{4}`;
+function isoDate(d) {
+    const m = d.match(/^(\d{1,2})[/.-](\d{1,2})[/.-](\d{4})$/);
+    if (!m)
+        return null;
+    const [day, month] = [Number(m[1]), Number(m[2])];
+    if (day < 1 || day > 31 || month < 1 || month > 12)
+        return null;
+    return `${m[3]}-${m[2].padStart(2, '0')}-${m[1].padStart(2, '0')}`;
+}
+const mixed = (v) => /\p{L}/u.test(v) && /\d/.test(v);
+/** Words that label another entity — never part of a capitals tag. */
+const LABEL_WORDS = String.raw `(?:C\.?I\.?G|C\.?U\.?P|P\.?C\.?F|C\.?D\.?R|PROT|PEC|CAP|CAPITOL[OI]|COD|CODICE|FORN|FORNITORE|IVA|EURO|ID|RIF|DEL)\.?(?![\p{L}])`;
+const CAPS_WORD = String.raw `(?!${LABEL_WORDS})\p{Lu}(?:[.'&]?\p{Lu}){2,}\.?`;
+export const protocol = {
+    entity: 'protocol',
+    anchor: /\d{7}(?:\/\d{4})?/u,
+    left: [
+        { part: 'label', rx: /(?:Numero\s+Protocollo|Protocollo(?:\s+n[r°]?\.?)?|Prot\.?\s*(?:n[r°]?\.?)?|Rif\.?)\s*:?\s*/iu },
+        { part: 'channel', rx: /(?:PEC|Posta\s+certificata|Riscontro\s+a)\s*[:\-]\s*/iu },
+    ],
+    right: [{ part: 'date', rx: new RegExp(String.raw `\s*,?\s*del\s+${DATE}`, 'iu') }],
+    requires: ['label'],
+    resolve: (p) => p.value.slice(0, 7),
+};
+export const cig = {
+    entity: 'cig',
+    anchor: /[A-Z0-9]{10}/u,
+    left: [{ part: 'label', rx: /C\.?I\.?G\.?(?:\s+(?:derivato|originario|master))?(?:\s*n\.)?\s*[:\-]?\s*/iu }],
+    // Unlabelled, one letter and nine digits is a Co.Ge. account, not a CIG.
+    resolve: (p) => (mixed(p.value) && (p.label || !/^[A-Z]\d{9}$/.test(p.value)) ? p.value : null),
+};
+export const cup = {
+    entity: 'cup',
+    anchor: /[A-Z]\d{2}[A-Z0-9]{12}/u,
+    left: [{ part: 'label', rx: /C\.?\s?U\.?\s?P\.?(?:\s+(?:derivato|master))?(?:\s*n\.)?\s*[:\-]?\s*/iu }],
+};
+export const chapter = {
+    entity: 'chapter',
+    anchor: /[A-Z]{2}\d{2,3}\.\d{3,4}/u,
+    left: [{ part: 'label', rx: /(?:Capitol[oi]|Cap\.?)(?:\s+di\s+(?:spesa|entrata))?\s*:?\s*/iu }],
+};
+export const amount = {
+    entity: 'amount',
+    anchor: /\d+(?:\.\d{3})*(?:,\d{1,2})?/u,
+    left: [{ part: 'label', rx: /(?:€|euro)\s*/iu }],
+    right: [{ part: 'unit', rx: /\s*€/u }],
+    resolve: (p) => {
+        if (!p.label && !p.unit)
+            return null;
+        const [int, dec = ''] = p.value.split(',');
+        return `${int.replace(/\./g, '')}.${dec.padEnd(2, '0')}`;
+    },
+};
+export const date = {
+    entity: 'date',
+    anchor: new RegExp(DATE, 'u'),
+    resolve: (p) => isoDate(p.value),
+};
+export const caps = {
+    entity: 'caps',
+    anchor: new RegExp(String.raw `${CAPS_WORD}(?: ${CAPS_WORD})+`, 'u'),
+    weak: true,
+};
+/** From «con oggetto» to the end of its level, read again inside. */
+export const quotation = {
+    entity: 'quotation',
+    anchor: /con oggetto\s*:?\s*/iu,
+    rest: true,
+};
+export const itPa = {
+    version: 'it-pa@1',
+    recipes: [protocol, cig, cup, chapter, amount, date, caps, quotation],
+};

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+export type { Book, Cuts, Leaf, LeafKind, Mention, Neighbour, Recipe, Span } from './types.ts';
+export { read } from './read.ts';
+export { gist, html, shown, type Fold } from './render.ts';

package/dist/src/index.js

@@ -0,0 +1,2 @@
+export { read } from "./read.js";
+export { gist, html, shown } from "./render.js";

package/dist/src/normalise.d.ts

@@ -0,0 +1,6 @@
+export interface Normal {
+    text: string;
+    /** Original boundary of each copy boundary, `text.length + 1` entries. */
+    at: number[];
+}
+export declare function normalise(original: string): Normal;

package/dist/src/normalise.js

@@ -0,0 +1,33 @@
+// Matching runs on a normalised copy; nothing outside the engine sees it.
+// NFKC, dash variants → `-`, curly quotes → straight, every whitespace run →
+// one space. `at(i)` maps a copy boundary back to an original one.
+const DASHES = /[‐-―−]/g;
+const QUOTES = /[‘-‟]/g;
+const straight = (q) => ('“”„‟'.includes(q) ? '"' : "'");
+export function normalise(original) {
+    let text = '';
+    const at = [];
+    let inSpace = false;
+    let i = 0;
+    for (const cp of original) {
+        if (/\s/.test(cp)) {
+            if (!inSpace) {
+                at.push(i);
+                text += ' ';
+            }
+            inSpace = true;
+        }
+        else {
+            const piece = cp.normalize('NFKC').replace(DASHES, '-').replace(QUOTES, straight);
+            // An expanded code point maps every copy boundary inside it to its start.
+            for (const ch of piece) {
+                at.push(i);
+                text += ch;
+            }
+            inSpace = false;
+        }
+        i += cp.length;
+    }
+    at.push(original.length);
+    return { text, at };
+}

package/dist/src/read.d.ts

@@ -0,0 +1,3 @@
+import type { Book, Cuts } from './types.ts';
+/** Read `text` with `book`: every mention, and the partition of the text into leaves. */
+export declare function read(text: string, book: Book): Cuts;

package/dist/src/read.js

@@ -0,0 +1,211 @@
+// The reading: anchors → greedy expansion → merge → segmentation ⇒ Cuts.
+//
+// Everything here works in the normalised copy's coordinates and maps back to
+// the original once, at the end. Nothing depends on anything but the text and
+// the book, so a Cuts is cacheable by (text, book.version).
+import { normalise } from "./normalise.js";
+const WORD = /[\p{L}\p{N}]/u;
+const isWord = (ch) => ch !== undefined && WORD.test(ch);
+/** A match may not start inside a word: its first char is a word char and so is the one before. */
+const cutsWordAtStart = (s, start) => isWord(s[start]) && isWord(s[start - 1]);
+/** …nor end inside one. */
+const cutsWordAtEnd = (s, end) => isWord(s[end - 1]) && isWord(s[end]);
+const bare = (flags) => flags.replace(/[gy]/g, '');
+const cache = new WeakMap();
+function pinned(rx, side) {
+    let c = cache.get(rx);
+    if (!c)
+        cache.set(rx, (c = {}));
+    return (c[side] ??=
+        side === 'left'
+            ? new RegExp(`(?:${rx.source})$`, bare(rx.flags))
+            : side === 'right'
+                ? new RegExp(rx.source, `${bare(rx.flags)}y`)
+                : new RegExp(rx.source, `${bare(rx.flags).replace('d', '')}gd`));
+}
+/**
+ * Grow a candidate outward from its anchor, greedily, inside [from, to).
+ * ponytail: a `$`-pinned regex rescans the prefix, O(n²) worst case per
+ * neighbour; fine for subjects of a few thousand chars, reverse-match if not.
+ */
+function expand(s, r, anchor, from, to) {
+    const parts = [{ part: 'value', span: anchor }];
+    const attached = new Set();
+    let cursor = anchor[0];
+    for (let grew = true; grew;) {
+        grew = false;
+        for (const nb of r.left ?? []) {
+            if (attached.has(nb.part))
+                continue;
+            const m = pinned(nb.rx, 'left').exec(s.slice(from, cursor));
+            if (!m || m[0].length === 0)
+                continue;
+            const start = from + m.index;
+            if (cutsWordAtStart(s, start))
+                continue;
+            parts.unshift({ part: nb.part, span: [start, cursor] });
+            attached.add(nb.part);
+            cursor = start;
+            grew = true;
+            break;
+        }
+    }
+    cursor = anchor[1];
+    const head = s.slice(0, to);
+    for (let grew = true; grew;) {
+        grew = false;
+        for (const nb of r.right ?? []) {
+            if (attached.has(nb.part))
+                continue;
+            const re = pinned(nb.rx, 'right');
+            re.lastIndex = cursor;
+            const m = re.exec(head);
+            if (!m || m[0].length === 0)
+                continue;
+            const end = cursor + m[0].length;
+            if (cutsWordAtEnd(s, end))
+                continue;
+            parts.push({ part: nb.part, span: [cursor, end] });
+            attached.add(nb.part);
+            cursor = end;
+            grew = true;
+            break;
+        }
+    }
+    return parts;
+}
+function candidates(s, recipes, from, to, weak) {
+    const out = [];
+    const head = s.slice(0, to);
+    recipes.forEach((r, index) => {
+        if (r.rest || !!r.weak !== weak)
+            return;
+        const re = pinned(r.anchor, 'scan');
+        re.lastIndex = from;
+        for (let m = re.exec(head); m; m = re.exec(head)) {
+            const anchor = [m.index, m.index + m[0].length];
+            if (anchor[0] === anchor[1]) {
+                re.lastIndex = m.index + 1;
+                continue;
+            }
+            if (!r.glued && (cutsWordAtStart(s, anchor[0]) || cutsWordAtEnd(s, anchor[1]))) {
+                re.lastIndex = m.index + 1; // a rejected match must not hide a later one
+                continue;
+            }
+            const parts = expand(s, r, anchor, from, to);
+            const text = Object.fromEntries(parts.map((p) => [p.part, s.slice(p.span[0], p.span[1])]));
+            const value = (r.requires ?? []).every((p) => p in text) ? (r.resolve ? r.resolve(text) : text.value) : null;
+            if (value === null) {
+                re.lastIndex = m.index + 1;
+                continue;
+            }
+            out.push({
+                recipe: index,
+                entity: r.entity,
+                extent: [parts[0].span[0], parts.at(-1).span[1]],
+                parts,
+                value,
+            });
+        }
+    });
+    return out;
+}
+const overlaps = (a, b) => a[0] < b[1] && b[0] < a[1];
+const size = (c) => c.extent[1] - c.extent[0];
+/** Longest extent first, then priority; a loser never overlaps a winner. */
+function merge(pool, taken) {
+    const kept = [...taken];
+    for (const c of [...pool].sort((a, b) => size(b) - size(a) || a.recipe - b.recipe))
+        if (!kept.some((k) => overlaps(k.extent, c.extent)))
+            kept.push(c);
+    return kept.sort((a, b) => a.extent[0] - b.extent[0]);
+}
+/**
+ * The separator grammar: whitespace, `,;:` followed by space or end, and a
+ * dash standing free. A hyphen inside a word is text. Brackets are their own
+ * leaves so a fold can empty them.
+ */
+const PIECE = /(?<sep>(?:\s|[,;:](?=\s|$)|(?<=^|\s)-(?=\s|$))+)|(?<open>[(\[])|(?<close>[)\]])/gu;
+function segment(s, from, to, mention, out) {
+    const push = (start, end, kind) => {
+        if (end > start)
+            out.push({ start, end, kind, ...(mention !== undefined ? { mention } : {}) });
+    };
+    PIECE.lastIndex = from;
+    let at = from;
+    for (let m = PIECE.exec(s); m && m.index < to; m = PIECE.exec(s)) {
+        push(at, m.index, 'text');
+        const end = Math.min(m.index + m[0].length, to);
+        push(m.index, end, m.groups.sep ? 'sep' : m.groups.open ? 'open' : 'close');
+        at = end;
+    }
+    push(at, to, 'text');
+}
+function level(s, recipes, from, to, parent, mentions, leaves) {
+    // The earliest `rest` anchor closes this level's head.
+    let rest;
+    recipes.forEach((r, index) => {
+        if (!r.rest)
+            return;
+        const re = pinned(r.anchor, 'scan');
+        re.lastIndex = from;
+        for (let m = re.exec(s); m && m.index < to; m = re.exec(s)) {
+            const at = [m.index, Math.min(m.index + m[0].length, to)];
+            if (!r.glued && (cutsWordAtStart(s, at[0]) || cutsWordAtEnd(s, at[1])))
+                continue;
+            if (!rest || at[0] < rest.at[0])
+                rest = { recipe: index, at };
+            break;
+        }
+    });
+    const limit = rest ? rest.at[0] : to;
+    const kept = merge(candidates(s, recipes, from, limit, true), merge(candidates(s, recipes, from, limit, false), []));
+    let at = from;
+    for (const c of kept) {
+        segment(s, at, c.extent[0], parent, leaves);
+        const index = mentions.push({ entity: c.entity, recipe: c.recipe, extent: c.extent, parts: c.parts, value: c.value, ...(parent !== undefined ? { parent } : {}) }) - 1;
+        for (const p of c.parts)
+            leaves.push({ start: p.span[0], end: p.span[1], kind: 'part', part: p.part, mention: index });
+        at = c.extent[1];
+    }
+    segment(s, at, limit, parent, leaves);
+    if (rest) {
+        const index = mentions.push({
+            entity: recipes[rest.recipe].entity,
+            recipe: rest.recipe,
+            extent: [rest.at[0], to],
+            parts: [{ part: 'lead', span: rest.at }],
+            value: s.slice(rest.at[1], to),
+            ...(parent !== undefined ? { parent } : {}),
+        }) - 1;
+        leaves.push({ start: rest.at[0], end: rest.at[1], kind: 'part', part: 'lead', mention: index });
+        level(s, recipes, rest.at[1], to, index, mentions, leaves);
+    }
+}
+/** Read `text` with `book`: every mention, and the partition of the text into leaves. */
+export function read(text, book) {
+    const n = normalise(text);
+    const raw = [];
+    const rawLeaves = [];
+    level(n.text, book.recipes, 0, n.text.length, undefined, raw, rawLeaves);
+    const span = ([s, e]) => ({ start: n.at[s], end: n.at[e] });
+    const mentions = raw.map((m) => ({
+        ...m,
+        extent: span(m.extent),
+        parts: m.parts.map((p) => ({ part: p.part, span: span(p.span) })),
+    }));
+    const leaves = rawLeaves
+        .map((l) => ({ ...l, start: n.at[l.start], end: n.at[l.end] }))
+        .filter((l) => l.end > l.start);
+    // A value comes from the copy; hand back the original's own characters.
+    for (const m of mentions) {
+        const r = book.recipes[m.recipe];
+        if (r.rest)
+            m.value = text.slice(m.parts[0].span.end, m.extent.end);
+        else if (!r.resolve) {
+            const v = m.parts.find((p) => p.part === 'value').span;
+            m.value = text.slice(v.start, v.end);
+        }
+    }
+    return { text, book: book.version, mentions, leaves };
+}

package/dist/src/render.d.ts

@@ -0,0 +1,21 @@
+import type { Cuts, Mention } from './types.ts';
+export type Fold = (mention: Mention, index: number) => boolean;
+/**
+ * Which leaves the condensed view shows. With nothing folded, every leaf.
+ *
+ * - A mention folds when the policy says so, or when the mention holding it folds.
+ * - A bracket pair folds when nothing between them survives.
+ * - The separators between two surviving leaves survive untouched when no
+ *   fold fell among them; otherwise only the strongest one survives, and none
+ *   at an edge, after an opening bracket or before closing punctuation.
+ */
+export declare function shown(cuts: Cuts, fold: Fold): boolean[];
+/** The condensed view as plain text. */
+export declare function gist(cuts: Cuts, fold: Fold): string;
+/**
+ * Tagged HTML holding both views: every leaf is there, and what the condensed
+ * view drops carries `data-fold` — so `.condensed [data-fold] { display: none }`
+ * is the whole switch. Mentions are `<span data-entity data-mention>`, parts
+ * `<span data-part>`, separators `<span data-sep>`, nested as the mentions nest.
+ */
+export declare function html(cuts: Cuts, fold: Fold): string;

package/dist/src/render.js

@@ -0,0 +1,101 @@
+// The last pass, always dynamic: a fold policy decides which mentions go, the
+// separator fate decides which separators go with them, and the same leaves
+// render as a gist or as tagged HTML carrying both views at once.
+/** A separator's weight when a fold makes several meet: the strongest stays. */
+const strength = (s) => (s.includes('-') ? 4 : s.includes(';') ? 3 : s.includes(':') ? 2 : s.includes(',') ? 1 : 0);
+const CLOSING = /^[.,;:!?)\]]/;
+/**
+ * Which leaves the condensed view shows. With nothing folded, every leaf.
+ *
+ * - A mention folds when the policy says so, or when the mention holding it folds.
+ * - A bracket pair folds when nothing between them survives.
+ * - The separators between two surviving leaves survive untouched when no
+ *   fold fell among them; otherwise only the strongest one survives, and none
+ *   at an edge, after an opening bracket or before closing punctuation.
+ */
+export function shown(cuts, fold) {
+    return fate(cuts, fold).keep;
+}
+function fate(cuts, fold) {
+    const { text, mentions, leaves } = cuts;
+    const folded = mentions.map(() => false);
+    mentions.forEach((m, i) => (folded[i] = fold(m, i) || (m.parent !== undefined && folded[m.parent])));
+    const keep = leaves.map((l) => l.kind !== 'sep' && !(l.mention !== undefined && folded[l.mention]));
+    const content = (l) => l.kind === 'text' || l.kind === 'part';
+    // Brackets: pair by stack; a pair with no surviving content inside folds.
+    const stack = [];
+    leaves.forEach((l, i) => {
+        if (l.kind === 'open')
+            stack.push(i);
+        else if (l.kind === 'close' && stack.length) {
+            const o = stack.pop();
+            if (!leaves.slice(o + 1, i).some((x, k) => content(x) && keep[o + 1 + k]))
+                keep[o] = keep[i] = false;
+        }
+    });
+    // Separators: each run between two surviving non-separator leaves.
+    let prev = -1;
+    for (let i = 0; i <= leaves.length; i++) {
+        if (i < leaves.length && (leaves[i].kind === 'sep' || !keep[i]))
+            continue;
+        const between = [...Array(i - prev - 1).keys()].map((k) => prev + 1 + k);
+        const seps = between.filter((k) => leaves[k].kind === 'sep');
+        const cut = between.length !== seps.length;
+        if (!cut)
+            seps.forEach((k) => (keep[k] = true));
+        else {
+            const slice = (l) => text.slice(l.start, l.end);
+            const edge = prev < 0 || i === leaves.length;
+            const hugs = (prev >= 0 && leaves[prev].kind === 'open') || (i < leaves.length && (leaves[i].kind === 'close' || CLOSING.test(slice(leaves[i]))));
+            if (!edge && !hugs && seps.length) {
+                const best = seps.reduce((a, b) => (strength(slice(leaves[b])) > strength(slice(leaves[a])) ? b : a));
+                keep[best] = true;
+            }
+        }
+        prev = i;
+    }
+    return { keep, folded };
+}
+/** The condensed view as plain text. */
+export function gist(cuts, fold) {
+    const keep = shown(cuts, fold);
+    return cuts.leaves.map((l, i) => (keep[i] ? cuts.text.slice(l.start, l.end) : '')).join('');
+}
+const escape = (s) => s.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
+/**
+ * Tagged HTML holding both views: every leaf is there, and what the condensed
+ * view drops carries `data-fold` — so `.condensed [data-fold] { display: none }`
+ * is the whole switch. Mentions are `<span data-entity data-mention>`, parts
+ * `<span data-part>`, separators `<span data-sep>`, nested as the mentions nest.
+ */
+export function html(cuts, fold) {
+    const { keep, folded } = fate(cuts, fold);
+    const { mentions } = cuts;
+    const chain = (m) => (m === undefined ? [] : [...chain(mentions[m].parent), m]);
+    // Marked only where the hiding starts; whatever sits inside inherits it.
+    const marked = (m) => folded[m] && !(mentions[m].parent !== undefined && folded[mentions[m].parent]);
+    const tag = (on) => (on ? ' data-fold' : '');
+    let out = '';
+    const open = [];
+    cuts.leaves.forEach((l, i) => {
+        const want = chain(l.mention);
+        let common = 0;
+        while (common < open.length && open[common] === want[common])
+            common++;
+        for (; open.length > common; open.pop())
+            out += '</span>';
+        for (const m of want.slice(common)) {
+            out += `<span data-entity="${escape(mentions[m].entity)}" data-mention="${m}"${tag(marked(m))}>`;
+            open.push(m);
+        }
+        const t = escape(cuts.text.slice(l.start, l.end));
+        const hide = !keep[i] && !(l.mention !== undefined && folded[l.mention]);
+        if (l.kind === 'part')
+            out += `<span data-part="${escape(l.part)}">${t}</span>`;
+        else if (l.kind === 'text' && !hide)
+            out += t;
+        else
+            out += `<span data-${l.kind}${tag(hide)}>${t}</span>`;
+    });
+    return out + '</span>'.repeat(open.length);
+}

package/dist/src/types.d.ts

@@ -0,0 +1,81 @@
+/** Half-open, indices into the ORIGINAL string. */
+export interface Span {
+    start: number;
+    end: number;
+}
+/**
+ * A neighbour a recipe may attach beside its anchor. Write `rx` plainly: the
+ * engine pins it to the anchor's edge (`$` on the left, sticky on the right).
+ */
+export interface Neighbour {
+    part: string;
+    rx: RegExp;
+}
+/**
+ * One pattern: a strict anchor, then a closed list of neighbours tried outward.
+ * Each neighbour attaches at most once; after every attachment the list is
+ * tried again from the top, so declaration order is priority at each step.
+ */
+export interface Recipe {
+    entity: string;
+    /** The value, strict. Its part is `value` (`lead` on a `rest` recipe). */
+    anchor: RegExp;
+    left?: readonly Neighbour[];
+    right?: readonly Neighbour[];
+    /** Parts that must attach, or the candidate is dropped. */
+    requires?: readonly string[];
+    /** Canonical value from the attached parts' text, or null: not this entity after all. */
+    resolve?: (parts: Readonly<Record<string, string>>) => string | null;
+    /** Fills only the gaps the strong recipes leave. */
+    weak?: boolean;
+    /**
+     * The mention runs from its anchor to the end of its level, and what follows
+     * the anchor is read again inside it. Neighbours are ignored.
+     */
+    rest?: boolean;
+    /** The anchor may start or end inside a word. Default: it may not. */
+    glued?: boolean;
+}
+/** Recipes in priority order, and the version that keys a cached reading. */
+export interface Book {
+    version: string;
+    recipes: readonly Recipe[];
+}
+export interface Mention {
+    entity: string;
+    /** Index into the book's recipes. */
+    recipe: number;
+    /** Every part, contiguous: what folding removes. */
+    extent: Span;
+    /** In text order. */
+    parts: {
+        part: string;
+        span: Span;
+    }[];
+    /** `resolve`'s answer, or the anchor's text. */
+    value: string;
+    /** The `rest` mention this one sits inside. */
+    parent?: number;
+}
+export type LeafKind = 'text' | 'sep' | 'open' | 'close' | 'part';
+/**
+ * One piece of the partition. `mention` is the innermost mention holding it
+ * (a `text` or `sep` leaf may sit inside a `rest` mention).
+ */
+export interface Leaf {
+    start: number;
+    end: number;
+    kind: LeafKind;
+    part?: string;
+    mention?: number;
+}
+/**
+ * The cuts index: leaves partition `text` in order, no gap, no overlap —
+ * concatenating their slices gives `text` back, character for character.
+ */
+export interface Cuts {
+    text: string;
+    book: string;
+    mentions: Mention[];
+    leaves: Leaf[];
+}

package/dist/src/types.js

@@ -0,0 +1,3 @@
+// The vocabulary. A reading is plain data: no RegExp, no functions, nothing a
+// JSON round-trip loses — so it can be cached by (text, book version).
+export {};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "fewrd",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Read a string with recipes: anchors, greedy expansion, a cuts index, and a fold-aware render.",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./recipes/*": {
+      "types": "./dist/recipes/*.d.ts",
+      "default": "./dist/recipes/*.js"
+    }
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.ts\"",
+    "typecheck": "tsc",
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "dev": "vite playground --port 5577 --strictPort"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.3",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.6"
+  }
+}