fewrd 0.1.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Egildo Tagliareni
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -8,9 +8,12 @@
 **Finds what recurs in a string, cuts it loose, and gets you the gist in a
 few words.**
 
+[![npm](https://img.shields.io/npm/v/fewrd?style=flat-square&color=78C4B6)](https://www.npmjs.com/package/fewrd)
 ![dependencies: 0](https://img.shields.io/badge/dependencies-0-78C4B6?style=flat-square)
+![core: 4 kB gzip](https://img.shields.io/badge/core-4%20kB%20gzip-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)
+![tests: 59 passing](https://img.shields.io/badge/tests-59%20passing-78C4B6?style=flat-square)
+[![license: MIT](https://img.shields.io/badge/license-MIT-78C4B6?style=flat-square)](LICENSE)
 
 </div>
 
@@ -29,9 +32,56 @@ normalise → anchors → expand → merge → segment  ⇒  Cuts      (depends
                                     render(Cuts, fold)  ⇒  gist | tagged html   (always dynamic)
 ```
 
+## Install
+
+```bash
+npm install fewrd
+```
+
+```bash
+pnpm add fewrd
+```
+
+ESM only, zero dependencies, types included. Runs in Node 18+ and any current
+browser or bundler.
+
+## Quick start
+
+Describe what recurs as a **book** of recipes, in JSON:
+
+```json
+{
+  "$schema": "./node_modules/fewrd/book.schema.json",
+  "version": "shop@1",
+  "defs": { "SKU": "[A-Z]{3}-\\d{4}" },
+  "recipes": [
+    {
+      "entity": "sku",
+      "anchor": "/%{SKU}/iu",
+      "left": [{ "part": "label", "rx": "/(?:sku|code)\\s*:?\\s*/iu" }],
+      "resolve": "upper"
+    }
+  ]
+}
+```
+
+Compile it once, then read any text with it:
+
+```ts
+import { compile, gist, html, read } from 'fewrd';
+import data from './shop.json' with { type: 'json' };
+
+const { book, errors } = compile(data, { resolvers: { upper: (p) => p.value.toUpperCase() } });
+
+const cuts = read('Refund approved - SKU: abc-1234 - customer notified', book);
+cuts.mentions[0].value;                 // 'ABC-1234'
+gist(cuts, (m) => m.entity === 'sku');  // 'Refund approved - customer notified'
+html(cuts, (m) => m.entity === 'sku');  // both views in one markup, see Rendering
+```
+
 ## See it fold
 
-A real case, unfolded:
+A real Italian public-administration subject, 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
 
@@ -44,16 +94,26 @@ 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.
 
+Or an inbox line, with the `Re:`/`Fwd:` chain and the ticket key folded:
+
+> Re: Fwd: Invoice INV-2026-0042 for $1,250.00 due 2026-10-15
+>
+> Invoice for $1,250.00 due 2026-10-15
+
+…while the money still reads as `1250.00 USD` and the date as `2026-10-15`.
+
 ## 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` |
+| `BookData` | a book as plain JSON: patterns as `"/source/flags"`, shared `defs` spliced in as `%{NAME}`, `resolve` by name |
+| `compile` | `BookData` + your named resolvers → a `Book`, plus a list of errors. Never throws |
+| `Recipe` | one pattern: a strict `anchor` (the value), closed lists of `left`/`right` neighbours (label, channel, date…), `requires`, `resolve`, `weak`, `rest`, `glued` |
 | `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 |
+| `Fold` | your policy: which mentions a condensed view drops |
 
 ## The rules
 
@@ -74,35 +134,149 @@ from the same `Cuts`; nothing gets re-parsed to produce the second one.
   condensed view drops with `data-fold`. The whole switch is
   `.condensed [data-fold] { display: none }`.
 
-## Use
+## Books as data
+
+A book is JSON, so it diffs, reviews and validates like any config. Point its
+`$schema` at `./node_modules/fewrd/book.schema.json` (relative to the file)
+and your editor flags typos, wrong types and missing fields as you type.
+
+| key | what it holds |
+|---|---|
+| `version` | required; change it whenever a recipe change can change output |
+| `defs` | named pattern fragments, source only: `{ "DATE": "\\d{4}-\\d{2}-\\d{2}" }` |
+| `recipes` | required; in priority order |
+| `recipes[].entity` | required; what the recipe recognises |
+| `recipes[].anchor` | required; a pattern, the value itself |
+| `recipes[].left` / `right` | neighbours: `{ "part": "label", "rx": "/…/iu" }` |
+| `recipes[].requires` | parts that must attach, e.g. `["currency"]` |
+| `recipes[].resolve` | the name of a resolver you pass to `compile` |
+| `recipes[].weak` / `rest` / `glued` | flags, see The rules |
+
+**Patterns** are regex literals in a string: `"/source/flags"` — JSON doubles
+the backslashes. `%{NAME}` splices in a fragment from `defs` as one unit (an
+`a|b` inside never leaks out) and fragments may use other fragments. `%\{` is
+a literal `%{`. Fragments inside a `[…]` character class aren't supported.
+
+**Resolvers** are the only code in a book: functions from the attached parts'
+text to a canonical value, or `null` for "not this entity after all". Nothing
+in the JSON is ever evaluated.
 
 ```ts
-import { read, gist, html } from 'fewrd';
-import { itPa } from 'fewrd/recipes/it-pa';
+const resolvers = {
+  upper: (p) => p.value.toUpperCase(),
+  // a bare 1.2.3 is too often something else: a version needs its v or a label
+  version: (p) => (p.label || p.value.startsWith('v') ? p.value.replace(/^v/, '') : null),
+};
+```
+
+**Errors** come back as `{ path, recipe, entity, message }` — a bad regex or
+flag, an unknown or circular fragment, an unknown resolver, a wrong type, a
+typo'd key. A recipe with any error is left out; every other recipe keeps
+working, in order.
 
-const cuts = read(subject, itPa);
-const fold = (m) => ['protocol', 'cup'].includes(m.entity);
-gist(cuts, fold);  // plain text
-html(cuts, fold);  // tagged, both views
+```ts
+compile({ version: 'x@1', recipes: [{ entity: 'sku', anchor: '/%{SKU/iu', resolve: 'uper' }] });
+// errors:
+//   recipes[0].anchor  (sku)  Invalid regular expression: /%{SKU/iu: Incomplete quantifier
+//   recipes[0].resolve (sku)  unknown resolver "uper"
+```
+
+A `Book` can also be written directly in TypeScript, with `RegExp`s and
+functions in place of strings and names; `read` doesn't care which.
+
+## Rendering
+
+```ts
+import { gist, html, shown, type Fold } from 'fewrd';
+
+const fold: Fold = (m) => ['protocol', 'cup'].includes(m.entity);
+gist(cuts, fold);   // the condensed view as plain text
+html(cuts, fold);   // every leaf, tagged; what the condensed view drops carries data-fold
+shown(cuts, fold);  // one boolean per leaf, for your own renderer
 ```
 
-## Try it
+Mentions come out as `<span data-entity data-mention>`, parts as
+`<span data-part>`, separators as `<span data-sep>`, nested as the mentions
+nest. Toggle between the full and condensed view with one class:
+
+```css
+.condensed [data-fold] { display: none; }
+```
+
+## Playground
+
+Keep a book in a folder next to your code, and open it in the playground with
+one command. `fewrd-play` is a separate dev-only package, so none of it ends up
+in the library your code ships:
 
 ```bash
-pnpm dev   # playground on 5577 — every case in playground/cases.ts, folded and whole
+npm install -D fewrd-play
+```
+```bash
+npx fewrd-play path/to/book --open
 ```
 
-## Recipes
+```
+path/to/book/
+  book.json          the recipes; the playground's save button writes it back
+  cases.json         sample texts: [{ "name": "refund", "text": "Refund approved - SKU: abc-1234" }]
+  cases.local.json   more texts, e.g. real ones you keep out of git (optional)
+  resolvers.ts       export const resolvers = { upper: (p) => p.value.toUpperCase() } (optional)
+```
+
+`resolvers.ts` is served with its types stripped (Node 22.13+), so it may
+import types, `fewrd` itself and other files in the folder, but no other
+packages. A `resolvers.js` is served as is. The server listens on localhost
+only; `--port` picks the port (default 4747).
+
+Or mount the playground in a page of your own:
+
+```ts
+import { mount } from 'fewrd/playground';
+import data from './shop.json' with { type: 'json' };
+
+mount(document.getElementById('app')!, {
+  data,                                  // edit the JSON live; errors show inline
+  resolvers,                             // your named resolvers
+  cases: [{ name: 'refund', text: 'Refund approved - SKU: abc-1234 - customer notified' }],
+  fold: (m) => m.entity === 'sku',       // optional: which entities start folded
+  save: (json) => fetch('/book', { method: 'POST', body: json }),  // optional: a save button
+});
+```
 
-`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.
+Every edit recompiles the book and re-reads every case; invalid JSON keeps the
+last good result on screen, and reset brings back the last saved book. Pass
+`book` instead of `data`/`resolvers` for a read-only view of a compiled
+`Book`. The playground injects its own scoped styles, so it needs no
+stylesheet.
 
-## Work
+## Demo books
+
+Two books live in this repo as working examples and starting points. They are
+not part of the package — copy what you need.
+
+- [`recipes/common`](recipes/common.json) — what recurs in any inbox, chat or
+  ticket: URLs, emails, phones, IPv4, ISO dates and times, money in three
+  formats, percentages, versions, ticket keys, @handles, #hashtags, `Re:`/`Fwd:`
+  chains and quoted replies. Its [resolvers](recipes/common.ts) mostly say
+  no: a bare `1.2.3`, an octet over 255, month 13, a phone too short.
+- [`recipes/it-pa`](recipes/it-pa.json) — Italian public administration
+  codes: protocol, CIG, CUP, chapter, amount, date, capitals tags,
+  «con oggetto».
+
+Their cases are in [`playground/cases.ts`](playground/cases.ts); the tests read
+those same cases.
+
+## Develop
 
 ```bash
+pnpm install
+pnpm dev         # playground on 5577, both demo books, JSON editable live
 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)
+pnpm build       # minified dist/ + types, what npm gets (runs on publish)
 ```
+
+## License
+
+[MIT](LICENSE) © 2026 Egildo Tagliareni

package/book.schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "fewrd book",
+  "description": "A fewrd recipe book written as data. Compile it with compile(data, { resolvers }) from 'fewrd'.",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Where this schema is, e.g. ./node_modules/fewrd/book.schema.json. Ignored by compile."
+    },
+    "version": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Keys a cached reading. Change it whenever a change to the recipes can change output."
+    },
+    "defs": {
+      "type": "object",
+      "description": "Named pattern fragments: source only, no slashes, no flags. Reference one from any pattern or fragment as %{NAME}; it splices in as one unit.",
+      "propertyNames": { "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+      "additionalProperties": { "type": "string" }
+    },
+    "recipes": {
+      "type": "array",
+      "description": "Recipes in priority order.",
+      "items": { "$ref": "#/$defs/recipe" }
+    }
+  },
+  "required": ["version", "recipes"],
+  "additionalProperties": false,
+  "$defs": {
+    "pattern": {
+      "type": "string",
+      "pattern": "^/.*/[dgimsuvy]*$",
+      "description": "A regex as /source/flags, e.g. \"/C\\\\.?U\\\\.?P/iu\". %{NAME} splices in a fragment from defs."
+    },
+    "neighbour": {
+      "type": "object",
+      "properties": {
+        "part": { "type": "string", "minLength": 1, "description": "The part name this neighbour attaches as, e.g. label, date, unit." },
+        "rx": { "$ref": "#/$defs/pattern", "description": "Written plainly: the engine pins it to the anchor's edge." }
+      },
+      "required": ["part", "rx"],
+      "additionalProperties": false
+    },
+    "recipe": {
+      "type": "object",
+      "properties": {
+        "entity": { "type": "string", "minLength": 1, "description": "What this recipe recognises; mentions carry it." },
+        "anchor": { "$ref": "#/$defs/pattern", "description": "The value, strict. Its part is value (lead on a rest recipe)." },
+        "left": { "type": "array", "items": { "$ref": "#/$defs/neighbour" }, "description": "Neighbours tried leftward from the anchor, in priority order." },
+        "right": { "type": "array", "items": { "$ref": "#/$defs/neighbour" }, "description": "Neighbours tried rightward from the anchor, in priority order." },
+        "requires": { "type": "array", "items": { "type": "string" }, "description": "Parts that must attach, or the candidate is dropped." },
+        "resolve": { "type": "string", "minLength": 1, "description": "Name of a resolver passed to compile: canonical value from the parts, or null (not this entity after all)." },
+        "weak": { "type": "boolean", "description": "Fills only the gaps the strong recipes leave." },
+        "rest": { "type": "boolean", "description": "The mention runs from its anchor to the end of its level, and what follows is read again inside it. Neighbours are ignored." },
+        "glued": { "type": "boolean", "description": "The anchor may start or end inside a word." }
+      },
+      "required": ["entity", "anchor"],
+      "additionalProperties": false
+    }
+  }
+}

package/dist/index.js

@@ -0,0 +1 @@
+const G=/[‐-―−]/g,H=/[‘-‟]/g,P=e=>"\u201C\u201D\u201E\u201F".includes(e)?'"':"'";function Q(e){let s="";const o=[];let r=!1,n=0;for(const p of e){if(/\s/.test(p))r||(o.push(n),s+=" "),r=!0;else{const c=p.normalize("NFKC").replace(G,"-").replace(H,P);for(const i of c)o.push(n),s+=i;r=!1}n+=p.length}return o.push(e.length),{text:s,at:o}}const U=/[\p{L}\p{N}]/u,y=e=>e!==void 0&&U.test(e),$=(e,s)=>y(e[s])&&y(e[s-1]),b=(e,s)=>y(e[s-1])&&y(e[s]),w=e=>e.replace(/[gy]/g,""),M=new WeakMap;function k(e,s){let o=M.get(e);return o||M.set(e,o={}),o[s]??=s==="left"?new RegExp(`(?:${e.source})$`,w(e.flags)):s==="right"?new RegExp(e.source,`${w(e.flags)}y`):new RegExp(e.source,`${w(e.flags).replace("d","")}gd`)}function Y(e,s,o,r,n){const p=[{part:"value",span:o}],c=new Set;let i=o[0];for(let u=!0;u;){u=!1;for(const t of s.left??[]){if(c.has(t.part))continue;const l=k(t.rx,"left").exec(e.slice(r,i));if(!l||l[0].length===0)continue;const f=r+l.index;if(!$(e,f)){p.unshift({part:t.part,span:[f,i]}),c.add(t.part),i=f,u=!0;break}}}i=o[1];const a=e.slice(0,n);for(let u=!0;u;){u=!1;for(const t of s.right??[]){if(c.has(t.part))continue;const l=k(t.rx,"right");l.lastIndex=i;const f=l.exec(a);if(!f||f[0].length===0)continue;const d=i+f[0].length;if(!b(e,d)){p.push({part:t.part,span:[i,d]}),c.add(t.part),i=d,u=!0;break}}}return p}function z(e,s,o,r,n){const p=[],c=e.slice(0,r);return s.forEach((i,a)=>{if(i.rest||!!i.weak!==n)return;const u=k(i.anchor,"scan");u.lastIndex=o;for(let t=u.exec(c);t;t=u.exec(c)){const l=[t.index,t.index+t[0].length];if(l[0]===l[1]){u.lastIndex=t.index+1;continue}if(!i.glued&&($(e,l[0])||b(e,l[1]))){u.lastIndex=t.index+1;continue}const f=Y(e,i,l,o,r),d=Object.fromEntries(f.map(h=>[h.part,e.slice(h.span[0],h.span[1])])),g=(i.requires??[]).every(h=>h in d)?i.resolve?i.resolve(d):d.value:null;if(g===null){u.lastIndex=t.index+1;continue}p.push({recipe:a,entity:i.entity,extent:[f[0].span[0],f.at(-1).span[1]],parts:f,value:g})}}),p}const B=(e,s)=>e[0]<s[1]&&s[0]<e[1],R=e=>e.extent[1]-e.extent[0];function _(e,s){const o=[...s];for(const r of[...e].sort((n,p)=>R(p)-R(n)||n.recipe-p.recipe))o.some(n=>B(n.extent,r.extent))||o.push(r);return o.sort((r,n)=>r.extent[0]-n.extent[0])}const E=/(?<sep>(?:\s|[,;:](?=\s|$)|(?<=^|\s)-(?=\s|$))+)|(?<open>[(\[])|(?<close>[)\]])/gu;function N(e,s,o,r,n){const p=(i,a,u)=>{a>i&&n.push({start:i,end:a,kind:u,...r!==void 0?{mention:r}:{}})};E.lastIndex=s;let c=s;for(let i=E.exec(e);i&&i.index<o;i=E.exec(e)){p(c,i.index,"text");const a=Math.min(i.index+i[0].length,o);p(i.index,a,i.groups.sep?"sep":i.groups.open?"open":"close"),c=a}p(c,o,"text")}function W(e,s,o,r,n,p,c){let i;s.forEach((l,f)=>{if(!l.rest)return;const d=k(l.anchor,"scan");d.lastIndex=o;for(let g=d.exec(e);g&&g.index<r;g=d.exec(e)){const h=[g.index,Math.min(g.index+g[0].length,r)];if(!(!l.glued&&($(e,h[0])||b(e,h[1])))){(!i||h[0]<i.at[0])&&(i={recipe:f,at:h});break}}});const a=i?i.at[0]:r,u=_(z(e,s,o,a,!0),_(z(e,s,o,a,!1),[]));let t=o;for(const l of u){N(e,t,l.extent[0],n,c);const f=p.push({entity:l.entity,recipe:l.recipe,extent:l.extent,parts:l.parts,value:l.value,...n!==void 0?{parent:n}:{}})-1;for(const d of l.parts)c.push({start:d.span[0],end:d.span[1],kind:"part",part:d.part,mention:f});t=l.extent[1]}if(N(e,t,a,n,c),i){const l=p.push({entity:s[i.recipe].entity,recipe:i.recipe,extent:[i.at[0],r],parts:[{part:"lead",span:i.at}],value:e.slice(i.at[1],r),...n!==void 0?{parent:n}:{}})-1;c.push({start:i.at[0],end:i.at[1],kind:"part",part:"lead",mention:l}),W(e,s,i.at[1],r,l,p,c)}}function J(e,s){const o=Q(e),r=[],n=[];W(o.text,s.recipes,0,o.text.length,void 0,r,n);const p=([a,u])=>({start:o.at[a],end:o.at[u]}),c=r.map(a=>({...a,extent:p(a.extent),parts:a.parts.map(u=>({part:u.part,span:p(u.span)}))})),i=n.map(a=>({...a,start:o.at[a.start],end:o.at[a.end]})).filter(a=>a.end>a.start);for(const a of c){const u=s.recipes[a.recipe];if(u.rest)a.value=e.slice(a.parts[0].span.end,a.extent.end);else if(!u.resolve){const t=a.parts.find(l=>l.part==="value").span;a.value=e.slice(t.start,t.end)}}return{text:e,book:s.version,mentions:c,leaves:i}}const Z=e=>e.includes("-")?4:e.includes(";")?3:e.includes(":")?2:e.includes(",")?1:0,V=/^[.,;:!?)\]]/;function C(e,s){return K(e,s).keep}function K(e,s){const{text:o,mentions:r,leaves:n}=e,p=r.map(()=>!1);r.forEach((t,l)=>p[l]=s(t,l)||t.parent!==void 0&&p[t.parent]);const c=n.map(t=>t.kind!=="sep"&&!(t.mention!==void 0&&p[t.mention])),i=t=>t.kind==="text"||t.kind==="part",a=[];n.forEach((t,l)=>{if(t.kind==="open")a.push(l);else if(t.kind==="close"&&a.length){const f=a.pop();n.slice(f+1,l).some((d,g)=>i(d)&&c[f+1+g])||(c[f]=c[l]=!1)}});let u=-1;for(let t=0;t<=n.length;t++){if(t<n.length&&(n[t].kind==="sep"||!c[t]))continue;const l=[...Array(t-u-1).keys()].map(g=>u+1+g),f=l.filter(g=>n[g].kind==="sep");if(!(l.length!==f.length))f.forEach(g=>c[g]=!0);else{const g=v=>o.slice(v.start,v.end),h=u<0||t===n.length,m=u>=0&&n[u].kind==="open"||t<n.length&&(n[t].kind==="close"||V.test(g(n[t])));if(!h&&!m&&f.length){const v=f.reduce((O,S)=>Z(g(n[S]))>Z(g(n[O]))?S:O);c[v]=!0}}u=t}return{keep:c,folded:p}}function X(e,s){const o=C(e,s);return e.leaves.map((r,n)=>o[n]?e.text.slice(r.start,r.end):"").join("")}const A=e=>e.replace(/[&<>"]/g,s=>({"&":"&amp;","<":"&lt;",">":"&gt;",'"':"&quot;"})[s]);function ee(e,s){const{keep:o,folded:r}=K(e,s),{mentions:n}=e,p=t=>t===void 0?[]:[...p(n[t].parent),t],c=t=>r[t]&&!(n[t].parent!==void 0&&r[n[t].parent]),i=t=>t?" data-fold":"";let a="";const u=[];return e.leaves.forEach((t,l)=>{const f=p(t.mention);let d=0;for(;d<u.length&&u[d]===f[d];)d++;for(;u.length>d;u.pop())a+="</span>";for(const m of f.slice(d))a+=`<span data-entity="${A(n[m].entity)}" data-mention="${m}"${i(c(m))}>`,u.push(m);const g=A(e.text.slice(t.start,t.end)),h=!o[l]&&!(t.mention!==void 0&&r[t.mention]);t.kind==="part"?a+=`<span data-part="${A(t.part)}">${g}</span>`:t.kind==="text"&&!h?a+=g:a+=`<span data-${t.kind}${i(h)}>${g}</span>`}),a+"</span>".repeat(u.length)}const q={book:{all:["$schema","version","defs","recipes"]},recipe:{all:["entity","anchor","left","right","requires","resolve","weak","rest","glued"]},neighbour:{all:["part","rx"]}},te=/^[A-Za-z_][A-Za-z0-9_]*$/,ne=/%\{([A-Za-z_][A-Za-z0-9_]*)\}/g,x=e=>typeof e=="object"&&e!==null&&!Array.isArray(e),L=e=>typeof e=="string"&&e!=="",se=(e,s)=>e?`${e}.${s}`:s;function j(e,s,o,r){for(const n of Object.keys(e))s.includes(n)||r.push({path:se(o,n),message:`unknown key "${n}"`})}function T(e,s,o=[]){return e.replace(ne,(r,n)=>{const p=[...o,n];if(o.includes(n))throw new Error(`circular fragment ${p.join(" \u2192 ")}`);const c=s.get(n);if(c===void 0)throw new Error(`unknown fragment %{${n}}`);return`(?:${T(c,s,p)})`})}function D(e,s,o,r){if(e===void 0)return void r.push({path:s,message:"is required"});const n=typeof e=="string"&&e[0]==="/"?e.lastIndexOf("/"):-1;if(typeof e!="string"||n<1)return void r.push({path:s,message:"must be a pattern string like /source/flags"});try{return new RegExp(T(e.slice(1,n),o),e.slice(n+1))}catch(p){r.push({path:s,message:p instanceof Error?p.message:String(p)})}}function I(e,s,o){return e===void 0?void o.push({path:s,message:"is required"}):L(e)?e:void o.push({path:s,message:"must be a non-empty string"})}function F(e,s,o,r){if(e!==void 0)return Array.isArray(e)?e.flatMap((n,p)=>{const c=`${s}[${p}]`;if(!x(n))return r.push({path:c,message:"must be an object (a neighbour)"}),[];j(n,q.neighbour.all,c,r);const i=I(n.part,`${c}.part`,r),a=D(n.rx,`${c}.rx`,o,r);return i!==void 0&&a?[{part:i,rx:a}]:[]}):void r.push({path:s,message:"must be an array of neighbours"})}function oe(e,s,o,r,n){if(!x(e))return void n.push({path:s,message:"must be an object (a recipe)"});j(e,q.recipe.all,s,n);const p=I(e.entity,`${s}.entity`,n),c=D(e.anchor,`${s}.anchor`,o,n),i=F(e.left,`${s}.left`,o,n),a=F(e.right,`${s}.right`,o,n);e.requires!==void 0&&!(Array.isArray(e.requires)&&e.requires.every(t=>typeof t=="string"))&&n.push({path:`${s}.requires`,message:"must be an array of strings"});let u;e.resolve!==void 0&&(typeof e.resolve!="string"?n.push({path:`${s}.resolve`,message:"must be a string (a resolver name)"}):Object.hasOwn(r,e.resolve)?u=r[e.resolve]:n.push({path:`${s}.resolve`,message:`unknown resolver "${e.resolve}"`}));for(const t of["weak","rest","glued"])e[t]!==void 0&&typeof e[t]!="boolean"&&n.push({path:`${s}.${t}`,message:"must be a boolean"});if(!(p===void 0||!c))return{entity:p,anchor:c,...i&&{left:i},...a&&{right:a},...Array.isArray(e.requires)&&{requires:e.requires.filter(t=>typeof t=="string")},...u&&{resolve:u},...e.weak===!0&&{weak:!0},...e.rest===!0&&{rest:!0},...e.glued===!0&&{glued:!0}}}function ie(e,s={}){if(!x(e))return{book:{version:"",recipes:[]},errors:[{path:"",message:"must be an object (a book)"}]};const o=[];j(e,q.book.all,"",o);const r=I(e.version,"version",o)??"",n=new Map;if(e.defs!==void 0&&!x(e.defs))o.push({path:"defs",message:"must be an object of name \u2192 pattern source"});else if(e.defs)for(const[c,i]of Object.entries(e.defs))te.test(c)?typeof i!="string"?o.push({path:`defs.${c}`,message:"must be a string (pattern source)"}):n.set(c,i):o.push({path:`defs.${c}`,message:"a fragment name is letters, digits and _, not starting with a digit"});if(!Array.isArray(e.recipes))return o.push({path:"recipes",message:e.recipes===void 0?"is required":"must be an array of recipes"}),{book:{version:r,recipes:[]},errors:o};const p=[];return e.recipes.forEach((c,i)=>{const a=[],u=oe(c,`recipes[${i}]`,n,s.resolvers??{},a),t=x(c)&&L(c.entity)?c.entity:void 0;for(const l of a)o.push({...l,recipe:i,...t!==void 0&&{entity:t}});!a.length&&u&&p.push(u)}),{book:{version:r,recipes:p},errors:o}}export{ie as compile,X as gist,ee as html,J as read,C as shown};

package/dist/playground.js

@@ -0,0 +1,39 @@
+import{read as A,compile as C,html as H,gist as F}from"./index.js";function h(e){const t=new Set;for(const r of e.recipes)t.add(r.entity);return[...t]}function J(e,t,r){if(!r)return[];const i=new Set;for(const c of t)A(c.text,e).mentions.forEach((o,u)=>{r(o,u)&&i.add(o.entity)});return h(e).filter(c=>i.has(c))}const l=e=>e.replace(/[&<>"]/g,t=>({"&":"&amp;","<":"&lt;",">":"&gt;",'"':"&quot;"})[t]),b=e=>e instanceof Error?e.message:String(e);function B(e){let t=0;for(let r=0;r<e.length;r++)t=t*31+e.charCodeAt(r)|0;return Math.abs(t)}function D(e){return`<table><thead><tr><th>span</th><th>leaf</th><th>mention</th><th>text</th></tr></thead><tbody>${e.leaves.map(r=>{const i=r.mention===void 0?"":`${r.mention} ${e.mentions[r.mention].entity}`;return`<tr><td>${r.start}\u2013${r.end}</td><td>${r.kind}${r.part?`:${r.part}`:""}</td><td>${i}</td><td><code>${l(JSON.stringify(e.text.slice(r.start,r.end)))}</code></td></tr>`}).join("")}</tbody></table>`}function x(e,t,r,i){try{const c=performance.now(),d=A(t,r),o=(performance.now()-c).toFixed(2);e.innerHTML=`
+      <p class="fewrd-tagged">${H(d,i)}</p>
+      <p class="fewrd-gist"><span class="fewrd-k">gist</span> ${l(F(d,i))}</p>
+      <details><summary>${d.mentions.length} mentions \xB7 ${d.leaves.length} leaves \xB7 ${o} ms</summary>
+        <pre>${l(JSON.stringify(d.mentions,null,1))}</pre>
+        ${D(d)}
+      </details>`}catch(c){e.innerHTML=`<p class="fewrd-error">${l(b(c))}</p>`}}function I(e,t){const{cases:r}=t,i="data"in t?t.resolvers:void 0,c="data"in t?t.save:void 0;let d="data"in t?JSON.stringify(t.data,null,2):"",o,u=[];"book"in t?o=t.book:{book:o,errors:u}=C(t.data,{resolvers:i});const p=new Set(J(o,r,t.fold)),w=n=>p.has(n.entity),a=`fewrd-pg-${Math.random().toString(36).slice(2)}`;e.classList.add(a,"condensed");const S=document.createElement("style");document.head.appendChild(S);function k(){S.textContent=`
+      .${a}.condensed [data-fold] { display: none; }
+      .${a}:not(.condensed) [data-fold] { text-decoration: line-through; text-decoration-color: rgba(0,0,0,.35); }
+      .${a} [data-entity] { background: var(--h); border-radius: 3px; padding: 0 1px; }
+      .${a} .fewrd-tagged [data-entity] [data-entity] { box-shadow: inset 0 -2px 0 rgba(0,0,0,.12); }
+      .${a} [data-part="value"] { font-weight: 600; }
+      .${a} [data-part="label"], .${a} [data-part="channel"], .${a} [data-part="lead"] { opacity: .7; }
+      .${a} [data-part="date"] { font-style: italic; }
+      .${a} [data-sep] { white-space: pre-wrap; }
+      .${a} .fewrd-controls { display: flex; flex-wrap: wrap; gap: 12px; align-items: center; margin-bottom: 12px; }
+      .${a} .fewrd-folds { min-width: 160px; }
+      .${a} .fewrd-editor { margin-bottom: 12px; }
+      .${a} .fewrd-book { display: block; width: 100%; box-sizing: border-box; min-height: 18em; resize: vertical; font: 12px/1.45 ui-monospace, SFMono-Regular, Menlo, monospace; tab-size: 2; }
+      .${a} .fewrd-errors { margin: 6px 0; padding-left: 18px; font-size: 12px; }
+      .${a} .fewrd-errors:empty { display: none; }
+      .${a} .fewrd-errors, .${a} .fewrd-error { color: #b3261e; }
+      .${a} .fewrd-status { font-size: 12px; opacity: .7; }
+      ${h(o).map(n=>`.${a} [data-entity=${JSON.stringify(n)}] { --h: hsl(${B(n)%360}, 70%, 88%); }`).join(`
+`)}
+    `}const T="data"in t?`<details class="fewrd-editor" open><summary>recipes <button type="button" class="fewrd-reset">reset</button>${c?' <button type="button" class="fewrd-save">save</button> <span class="fewrd-status"></span>':""}</summary>
+        <textarea class="fewrd-book" spellcheck="false"></textarea>
+        <ul class="fewrd-errors"></ul>
+      </details>`:"";e.innerHTML=`
+    <div class="fewrd-controls">
+      <label><input type="checkbox" class="fewrd-condensed" checked /> condensed</label>
+      <select class="fewrd-folds" multiple></select>
+    </div>
+    ${T}
+    <section class="fewrd-trial">
+      <textarea class="fewrd-custom" rows="3" spellcheck="false"></textarea>
+      <div class="fewrd-trial-out"></div>
+    </section>
+    <div class="fewrd-cases"></div>`;const L=e.querySelector(".fewrd-condensed"),m=e.querySelector(".fewrd-folds"),$=e.querySelector(".fewrd-custom"),q=e.querySelector(".fewrd-trial-out"),E=e.querySelector(".fewrd-cases");E.innerHTML=r.map((n,s)=>`<section class="fewrd-case"><h2>${l(r[s].name)}</h2><div class="fewrd-out" data-i="${s}"></div></section>`).join("");const j=Array.from(E.querySelectorAll(".fewrd-out"));function M(){const n=h(o);for(const s of Array.from(p))n.includes(s)||p.delete(s);m.size=Math.max(n.length,1),m.innerHTML=n.map(s=>`<option value="${l(s)}"${p.has(s)?" selected":""}>${l(s)}</option>`).join("")}function y(){j.forEach(n=>x(n,r[Number(n.getAttribute("data-i"))].text,o,w)),x(q,$.value,o,w)}m.addEventListener("change",()=>{p.clear();for(const n of Array.from(m.selectedOptions))p.add(n.value);y()}),L.addEventListener("change",()=>e.classList.toggle("condensed",L.checked)),$.addEventListener("input",()=>x(q,$.value,o,w));const f=e.querySelector(".fewrd-book"),O=e.querySelector(".fewrd-errors");function g(n){O&&(O.innerHTML=n.map(s=>`<li>${l([s.path,s.entity&&`(${s.entity})`].filter(Boolean).join(" "))}${s.path?": ":""}${l(s.message)}</li>`).join(""))}function N(){if(!f)return;let n;try{n=JSON.parse(f.value)}catch(s){return g([{path:"",message:`invalid JSON, still showing the last good book: ${b(s)}`}])}({book:o,errors:u}=C(n,{resolvers:i})),g(u),k(),M(),y()}if(f){f.value=d,f.addEventListener("input",N),e.querySelector(".fewrd-reset").addEventListener("click",s=>{s.preventDefault(),f.value=d,N()});const n=e.querySelector(".fewrd-status");e.querySelector(".fewrd-save")?.addEventListener("click",async s=>{s.preventDefault();const v=f.value;try{JSON.parse(v),await c(v),d=v,n.textContent="saved"}catch(z){n.textContent=`not saved: ${b(z)}`}}),f.addEventListener("input",()=>n&&(n.textContent=""))}g(u),k(),M(),y()}export{h as entities,J as initialSelection,I as mount};

package/dist/types/compile.d.ts

@@ -0,0 +1,26 @@
+import type { Book, CompileError, CompileOptions } from './types.ts';
+/** The keys each object accepts and requires. `book.schema.json` must agree (tested). */
+export declare const KEYS: {
+    book: {
+        all: string[];
+        required: string[];
+    };
+    recipe: {
+        all: string[];
+        required: string[];
+    };
+    neighbour: {
+        all: string[];
+        required: string[];
+    };
+};
+/**
+ * Compile a book written as data (typically `JSON.parse` output) into a Book.
+ * `resolve` names are looked up in `options.resolvers`; nothing in `data` is
+ * ever evaluated as code. A recipe with any error is left out; the others
+ * keep their order.
+ */
+export declare function compile(data: unknown, options?: CompileOptions): {
+    book: Book;
+    errors: CompileError[];
+};

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+export type { Book, BookData, CompileError, CompileOptions, Cuts, Leaf, LeafKind, Mention, Neighbour, NeighbourData, Recipe, RecipeData, Resolver, Span, } from './types.ts';
+export { read } from './read.ts';
+export { gist, html, shown, type Fold } from './render.ts';
+export { compile } from './compile.ts';

package/dist/types/playground.d.ts

@@ -0,0 +1,34 @@
+import { type Fold } from './index.ts';
+import type { Book, Resolver } from './types.ts';
+export interface PlaygroundCase {
+    name: string;
+    text: string;
+}
+interface CommonOptions {
+    cases: PlaygroundCase[];
+    /** Evaluated once at mount, against `cases`, to seed the fold control's initial selection. Never called again. */
+    fold?: Fold;
+}
+export type MountOptions = (CommonOptions & {
+    book: Book;
+})
+/** Book data (e.g. parsed JSON) and its resolvers: the playground shows an editor and recompiles on every edit. */
+ | (CommonOptions & {
+    data: unknown;
+    resolvers?: Readonly<Record<string, Resolver>>;
+    /** Shows a save button: called with the editor's text once it parses as JSON. Reset then returns to what was saved. */
+    save?: (json: string) => unknown;
+});
+/** Distinct entities across a book's recipes, in first-appearance order. */
+export declare function entities(book: Book): string[];
+/** Which entities a supplied fold would fold across the given cases, or none if no fold was supplied. */
+export declare function initialSelection(book: Book, cases: PlaygroundCase[], fold?: Fold): string[];
+/**
+ * Mount fewrd's playground UI into `el`, rendering `options.cases` against
+ * `options.book` — or against `options.data` compiled with
+ * `options.resolvers`, editable live. Self-contained: injects the CSS it
+ * needs, scoped to this mount so multiple mounts on one page never collide
+ * and unrelated page content is never touched.
+ */
+export declare function mount(el: Element, options: MountOptions): void;
+export {};

package/dist/{src → types}/types.d.ts

@@ -41,6 +41,48 @@ export interface Book {
     version: string;
     recipes: readonly Recipe[];
 }
+/** A recipe's `resolve`, supplied by name at compile time. */
+export type Resolver = NonNullable<Recipe['resolve']>;
+/** A `Neighbour` as data. `rx` is a pattern: `"/source/flags"`. */
+export interface NeighbourData {
+    part: string;
+    rx: string;
+}
+/**
+ * A `Recipe` as data. Patterns are `"/source/flags"` strings, where
+ * `%{NAME}` splices in `BookData.defs.NAME` as one unit; `resolve` names a
+ * function from `CompileOptions.resolvers`.
+ */
+export interface RecipeData {
+    entity: string;
+    anchor: string;
+    left?: NeighbourData[];
+    right?: NeighbourData[];
+    requires?: string[];
+    resolve?: string;
+    weak?: boolean;
+    rest?: boolean;
+    glued?: boolean;
+}
+/** A `Book` as data: the JSON a book is written in. */
+export interface BookData {
+    $schema?: string;
+    version: string;
+    /** Name → pattern source (no slashes, no flags), referenced as `%{NAME}`. */
+    defs?: Record<string, string>;
+    recipes: RecipeData[];
+}
+/** One problem found by `compile`. `recipe` indexes `BookData.recipes`. */
+export interface CompileError {
+    /** Where in the data, e.g. `recipes[2].left[0].rx`; `""` is the root. */
+    path: string;
+    recipe?: number;
+    entity?: string;
+    message: string;
+}
+export interface CompileOptions {
+    resolvers?: Readonly<Record<string, Resolver>>;
+}
 export interface Mention {
     entity: string;
     /** Index into the book's recipes. */

package/package.json

@@ -1,25 +1,43 @@
 {
   "name": "fewrd",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
-  "description": "Read a string with recipes: anchors, greedy expansion, a cuts index, and a fold-aware render.",
+  "license": "MIT",
+  "description": "Finds what recurs in a string, cuts it loose, and gets you the gist in a few words.",
+  "keywords": [
+    "text",
+    "segmentation",
+    "entity-extraction",
+    "regex",
+    "recipes",
+    "gist",
+    "fold"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/egildo/fewrd.git"
+  },
+  "homepage": "https://github.com/egildo/fewrd#readme",
+  "bugs": "https://github.com/egildo/fewrd/issues",
   "files": [
-    "dist"
+    "dist",
+    "book.schema.json"
   ],
   "exports": {
     ".": {
-      "types": "./dist/src/index.d.ts",
-      "default": "./dist/src/index.js"
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./playground": {
+      "types": "./dist/types/playground.d.ts",
+      "default": "./dist/playground.js"
     },
-    "./recipes/*": {
-      "types": "./dist/recipes/*.d.ts",
-      "default": "./dist/recipes/*.js"
-    }
+    "./book.schema.json": "./book.schema.json"
   },
   "scripts": {
     "test": "node --test \"test/*.test.ts\"",
     "typecheck": "tsc",
-    "build": "tsc -p tsconfig.build.json",
+    "build": "vite build --config vite.lib.ts && tsc -p tsconfig.build.json",
     "prepublishOnly": "npm run build",
     "dev": "vite playground --port 5577 --strictPort"
   },

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

@@ -1,11 +0,0 @@
-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

@@ -1,77 +0,0 @@
-// 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

@@ -1,3 +0,0 @@
-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

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

package/dist/src/normalise.js

@@ -1,33 +0,0 @@
-// 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.js

@@ -1,211 +0,0 @@
-// 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.js

@@ -1,101 +0,0 @@
-// 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.js

@@ -1,3 +0,0 @@
-// 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 {};