rapier-markdown-kit 1.1.102 → 1.2.3

package/LICENSE

@@ -21,8 +21,11 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
 Files under this licence carry `SPDX-License-Identifier: MIT` in their first lines: the standard's
-grammar, marks and reference style (`spec/md-layout.mjs`, `spec/md-marks.mjs`, `spec/flowchart.mjs`, `spec/markdown-style.css`), the layout model and line planner
-(`layout/model.mjs`, `layout/line-plan.mjs`, `layout/typography.mjs`),
+grammar, marks and reference style (`spec/md-layout.mjs`, `spec/md-marks.mjs`, `spec/md-source.mjs`, `spec/flowchart.mjs`, `spec/markdown-style.css`), ink geometry
+(`spec/ink.mjs`),
+the layout model and line planner (`layout/model.mjs`, `layout/line-plan.mjs`, `layout/typography.mjs`, `layout/preparation.mjs`,
+`layout/prepared-paragraph.mjs`, `layout/hyphenation.mjs`, `layout/paragraph-fit.mjs`), the animated-picture reader and playback
+the HTML blocks use (`images/gif.mjs`, `images/playback.mjs`),
 the portable HTML and document metadata helpers (`spec/html-blocks.mjs`, `spec/frontmatter.mjs`,
 `spec/document-settings.mjs`, `spec/document-fonts.mjs`), the Will grammar (`agent/will.mjs`), the picture appendix reader and writer
 (`spec/md-assets.mjs`), the two shared-page reference readers (`tools/read-shared-page.mjs`,

package/README.md

@@ -1,11 +1,11 @@
 # rapier-markdown-kit
 
 Read, render and write Self-contained Markdown in browsers and Node: one `.md` file with pictures, editable SVG
-drawings, layout and colour. Build portable documents for people and agents. Will/1 regions mark what an agent
+drawings, layout and precise inline typography. Build portable documents for people and agents. Will/1 regions mark what an agent
 may edit, append to or preserve. MIT, no dependencies.
 
-- Everything past CommonMark and GFM is an HTML comment other readers ignore or an ordinary reference
-  definition, so every Markdown app still reads the file.
+- Typography uses ordinary inline HTML spans with validated size, colour and family. Comments and references
+  carry other optional facts; each reader chooses its HTML, style, extension and resource support.
 - One stylesheet renders the document as the editor and its exported page do.
 - The line planner flows text around a picture's real shape; a conformance suite of thirteen documents runs
   any implementation against it.
@@ -26,7 +26,7 @@ npm install rapier-markdown-kit
 
 ```js
 import {parseLayout} from 'rapier-markdown-kit/layout';   // the md-layout comment a picture carries
-import {scanColorMarkers, formatPageBreak} from 'rapier-markdown-kit/marks';   // colour runs and page breaks
+import {typography, formatPageBreak} from 'rapier-markdown-kit/marks';   // inline typography and page breaks
 import {flowLines} from 'rapier-markdown-kit/model';      // the line planner: text around pictures
 import {parseWill} from 'rapier-markdown-kit/will';       // Will/1 markers: keep, append, edit
 import {parseAssets} from 'rapier-markdown-kit/assets';   // the picture appendix
@@ -37,7 +37,7 @@ import {parseAssets} from 'rapier-markdown-kit/assets';   // the picture appendi
 Rapier is a phone-first Markdown editor for notes, diagrams, drawing and watercolor painting. It runs offline
 as one HTML file on Android, Web and Windows.
 
-1. **Work together live.** Connect to `https://mcp.rapier.website/mcp`, then call `open` to share one document with the person.
+1. **Work together live.** Connect to `https://mcp.rapier.website/door/mcp`, then call `open` to share one document with the person.
 2. **Deliver an offline editor.** Run `npx rapier-html notes.md` to put the document and editor in one HTML file ([rapier-html](https://github.com/jackskip22/rapier-plugins/tree/main/npm/rapier-html)).
 3. **Embed in your app.** Install [rapier-embed](https://github.com/jackskip22/rapier-plugins/tree/main/npm/rapier-embed); mount the editor or reader, with your app's agent over WebMCP in the editor.
 4. **Keep portable Markdown.** Use [rapier-markdown-kit](https://github.com/jackskip22/rapier-plugins/tree/main/npm/rapier-markdown-kit) for pictures, editable SVG drawings and layout in one `.md` file. Respect [Will/1](https://github.com/jackskip22/will) `keep`, `append` and `edit` regions.
@@ -64,6 +64,27 @@ const {html, filename} = await writer.render(source, {filename: 'report.md'});
 ```
 
 `createMarkdownRenderer(host).render(source, metadata)` returns the semantic HTML.
+`createMarkdownRenderer(host).renderWithMathML(source, metadata)` returns
+`{html, equations}` using the ready host math provider's `renderWithMathML` operation.
+The provider must also support the existing `renderToString` operation.
+Each equation is parsed once for its SVG and MathML. The HTML stays identical to
+ordinary SVG rendering; `equations` follows render order and carries `source`
+(the admitted token spelling, including its delimiters), `tex`, `displayMode`, `semantics`, and SVG
+`errors`. Pass `{docKind: 'markdown'}` as metadata for Markdown documents.
+The existing Markdown grammar may normalize display-block indentation; the original
+document remains the source of untouched document bytes.
+Inspect both `errors` and `semantics.status`: a rendered SVG can have refused or
+partial semantic output. The method throws if the combined provider is unavailable
+or fails, rather than returning an empty semantic success. It does not return an AST.
+
+This explicit method makes structured output available to consuming applications;
+Rapier's live editor and ordinary HTML/DOCX/print exports still use the current
+engine's Latin Modern SVG path. They do not insert hidden MathML, synthesize speech,
+or claim screen-reader qualification. A consumer that inserts MathML must preserve
+its namespace and semantics/annotation elements, name enclosing links meaningfully,
+and qualify its own accessibility presentation. The current ordinary document
+sanitizer is not a MathML composition API.
+
 The page writer's `render` returns `{html, filename}` asynchronously and preserves the
 original source, including BOM and line endings, in the SHA-256-verified source carrier.
 Every existing lower-level method is also returned for hosts that compose the stages.
@@ -119,17 +140,138 @@ family name share the host's font namespace. Print retains its existing factory
 | Import | What it is |
 | --- | --- |
 | `rapier-markdown-kit/layout` | The `md-layout:v1` comment a picture carries: parse it, validate it, write it back. |
-| `rapier-markdown-kit/marks` | Text colour and page-break markers. |
+| `rapier-markdown-kit/marks` | Unified typography values, span writer and parser installer; preserved colour/font comments, ink and page breaks. |
 | `rapier-markdown-kit/model` | Occupancy profiles and the line planner: the wrapping itself. |
+| `rapier-markdown-kit/typography` | Source-preserving paragraph refinement through `createTypography()`. |
 | `rapier-markdown-kit/will` | The Will/1 grammar (a separate, optional standard): the markers around an agent's intent regions. |
 | `rapier-markdown-kit/assets` | The picture appendix: the reference definitions a document's pictures live in. It never decodes a picture. |
 | `rapier-markdown-kit/style.css` | The reference style: type, lists, tables, tasks, pictures and the document's other markup, scoped to `.md-render`. |
 | `rapier-markdown-kit/rapier-ledger` | The MIT edit-ledger format, replay, authorship projection and offline merge. |
 | `rapier-markdown-kit/ledger/carried` | Checked optional parts for pages and saved Markdown. |
-| `rapier-markdown-kit` | Named exports from the layout, marks, model, Will, assets and render modules, plus the `ledger` namespace. |
+| `rapier-markdown-kit` | Named exports from the layout, marks, model, typography, Will, assets and render modules, plus the `ledger` namespace. |
+
+The canonical inline form is ordinary HTML inside Markdown. CSS support varies; the host's font metrics still
+determine line layout (below).
+
+## Refined paragraphs
+
+The existing comment expresses the paragraph's intent without storing font-dependent line breaks:
+
+```md
+Words stay in their original source. <!--md-layout:v1 align=justify hyphens=auto hanging=on-->
+```
+
+`align=justify` alone keeps native justification. With `hyphens=auto`, the browser adapter chooses a paragraph-wide
+plan using the same pinned Pretext analysis, shaping and actual-font authority as picture wrapping. It prefers
+whole words, bounds ordinary spaces to 60–180% of their natural advance, permits at most two consecutive
+discretionary endings, and starts the final line with a whole word. A short final line costs more; the final line
+is never stretched. Authored compound hyphens are ordinary break opportunities, distinct from discretionary ones.
+In very narrow measures, bounded spaces can leave some ragged edges. There is no paragraph-length switch.
+
+Automatic cuts keep at least three graphemes on each side, with at most one automatic split per word. ASCII words
+under `en` and `en-US` use the included Kuiken/Plain TeX pattern data and exceptions. Other English regions,
+non-ASCII words and other admitted languages ask the browser's offline hyphenator for legal positions. That path
+requires native `hyphenate-limit-chars` support; otherwise the paragraph stays native. Available dictionaries and
+their divisions depend on the host. The included American patterns are a deliberate alternative to native data,
+not a promise of identical opportunities in every browser. No language or font data is downloaded.
+
+The projection displays a hyphen-minus from the affected text face, measured by Pretext as part of the whole
+prefix. It never adds a source hyphen. Explicit authored `hyphenate-character` stays native. With `hanging=on`,
+measured punctuation extends only into available unclipped margins, by at most half an em. Refinement adds no
+letter tracking; authored supported letter spacing remains part of its shaping contract.
+
+```js
+import {createTypography} from 'rapier-markdown-kit/typography';
+
+const refinement = createTypography();
+await document.fonts.ready;
+function update() {
+  if (refinement.apply(root).pending) requestAnimationFrame(update);
+}
+update();
+for (const event of ['copy', 'cut']) document.addEventListener(event, () => {
+  if (refinement.clearSelection(root)) requestAnimationFrame(update);
+}, true);
+// On a width change, call update() again. Source/style/font changes are revalidated.
+// Before native editing or consuming this disposable DOM projection:
+refinement.clear(root);
+// When retiring the root:
+refinement.retire(root);
+```
+
+`apply()` works on visible paragraphs and yields at completed preparation phases or word batches after an 8 ms
+allowance. A single native shaping call can exceed that allowance; it is not a hard execution deadline. Pending
+paragraphs remain native and readable. Each continuation revalidates source, style and font authority, and chooses
+lines at the current width only after all required metrics finish. `{all:true}` performs the same complete work
+synchronously for explicit capture or a print host with an established content width. Width changes reuse current measured geometry, and unchanged break
+topology reuses projection nodes. Bind font loading, completion and failure to `invalidateFonts(document)` and
+schedule `apply()`; a changed font generation removes stale projections before new preparation.
+
+The adapter retains original text, semantic elements and listeners, backward selections, hard breaks, protected
+code/nowrap atoms, NBSP, SHY and Unicode source coordinates. `clearSelection()` restores selected inline trees
+before native clipboard capture; schedule refinement afterward as above. The editor and complete exported pages
+bind this lifecycle themselves. Active editing/composition stays native. Unsupported
+scripts, direction, shaping controls, initials and picture-flow paragraphs also stay native. The current adapter
+admits horizontal LTR Latin, Greek, Cyrillic and common/inherited characters on Chrome/Chromium; native font
+coverage and language support still apply. A font-family name is never a substitute for a loaded actual face.
 
-Every convention is plain Markdown or an HTML comment other readers ignore. Laying lines out as Rapier does takes
-the host's font metrics (below).
+Complete exported pages carry the same single module graph, CSP nonce, offline language data and font lifecycle.
+Their readiness promise completes after the visible refinement queue; scrolling refines newly visible paragraphs.
+Before print, an authored paper size supplies the fixed content width and all paragraphs finish synchronously.
+Automatic-paper browser printing clears the projection and uses native CSS: `beforeprint` may still report the
+screen viewport rather than the selected paper. Scoped fragments and `scripts:false` output also retain native CSS. The American data's separate permissive notice and exact provenance accompany the kit;
+Pretext retains its own complete notices. These vendor notices are not replaced by the kit's MIT grant.
+
+## One inline typography form
+
+```md
+Plain prose needs no typography markup.
+
+A <span style="font-size:13.5pt;color:#175dc4">precise **phrase**</span>.
+
+## <span style="font-size:9.25pt;font-family:serif">Still a semantic H2</span>
+
+<span style="font-size:18px;color:#175dc4;font-family:&quot;Coastal Text&quot;">An offline custom run</span>
+
+[font:Coastal Text]: data:font/woff2;base64,<font-bytes> '{"family":"Coastal Text","sourceId":"f0123456789abcdef01234567"}'
+```
+
+The font bytes and identity in that last example are placeholders; a host derives identity from admitted bytes.
+A family name alone is not a portable font. Default prose needs no font reference. Custom faces keep the existing
+font-data authority, including a name that collides with a factory face.
+
+`typography.normalize({size, color, family})` validates a style. `typography.wrap(style, inlineMarkdown)` writes one
+inline span; split block selections and keep their `#`, list markers and separators outside. `typography.parseStyle`
+returns only admitted facts. `typography.install(md)` installs that interpretation on the caller's markdown-it
+parser, and `typographySourceRanges(source, md)` reports original UTF-16 wrapper ranges through that parser.
+These calls neither mutate the source nor load resources. The installer also reads already-authored colour and
+font comments into the same facts; an ordinary open/save must preserve their bytes, not rewrite them as spans.
+
+Sizes accept positive decimal `pt`/`px`, at most 12 fractional digits, up to 1638pt/2184px; 96px = 72pt. New values
+use lowercase units and omit insignificant zeros. Colours become lowercase six-digit RGB hex; opaque integer
+RGB CSSOM values are also read. Families are one validated name, an unquoted CSS generic, or an existing preset
+stack. `sans`, `serif`, `mono`, `system`, `hand` are reserved choice aliases, not quoted custom identities. Styles
+are bounded to 4096 characters, 32 declarations and 64 paired levels. Invalid declarations and unknown properties
+are ignored; invalid/unclosed style strings admit no facts. Inner spans override individual properties. An editor
+clearing a selection removes that property's overrides and preserves the surrounding words' styles.
+
+Keep each opener with its first words and each closer with its last words. Soft/hard breaks may stay inside one paragraph; blank lines cannot. An opener alone on a line can become a raw HTML block.
+With inline HTML enabled, the new form preserves words, emphasis,
+links and heading rank; GitHub strips the styles, and HTML-disabled readers may show the tags. Rapier's **Copy
+markdown without typography** removes recognized wrappers while retaining semantic Markdown and literal code.
+Its separate Pandoc/Quarto copy option writes bracketed spans deliberately; Pandoc HTML carries the CSS, but
+ordinary LaTeX and native DOCX styling do not follow automatically.
+
+Rapier's own Word adapter writes native run properties, rounding to the nearest half-point with positive ties up
+and refusing results outside 1–3276 half-points. The unchanged DOCX source carrier keeps original decimals and units;
+native import reports represented direct-run/character-style sizes without repeating document or paragraph defaults
+as inline marks. It does not reproduce an arbitrary Word style sheet. HTML and print/PDF retain the same admitted facts at the default reference
+unit, independent of editor zoom. No mapping claims identical glyphs or line breaks across applications.
+
+See the original [typography guidance](https://github.com/jackskip22/rapier/blob/main/docs/markdown-standard.md#inline-typography),
+[CommonMark raw HTML](https://spec.commonmark.org/0.31.2/#raw-html), [CSS absolute units](https://www.w3.org/TR/css-values-4/#absolute-lengths),
+[Pandoc spans](https://pandoc.org/MANUAL.html#extension-bracketed_spans) and [Quarto spans](https://quarto.org/docs/authoring/markdown-basics.html#divs-and-spans).
+Those specifications retain their own licences.
 
 ## Render with the reference style
 
@@ -142,19 +284,19 @@ are named font families with system fallbacks; no font or external asset is fetc
 The example below renders trusted Markdown with `markdown-it` and the kit's readers: run
 `npm install rapier-markdown-kit markdown-it@15`, save it as `render.mjs`, run `node render.mjs` and open
 `styled.html`, which uses only `style.css`. It shows core Markdown, GFM tables, an aligned paragraph, a sized
-picture, a named colour and a page break; tasks, footnotes and diagrams are the caller's plugins. The full markup
+picture, a precise combined run, a semantic heading and a page break; tasks, footnotes and diagrams are the caller's plugins. The full markup
 contract is [Reference style](https://github.com/jackskip22/rapier/blob/main/docs/markdown-standard.md#reference-style).
 
 <!-- reference-style-example -->
 ```js
 import MarkdownIt from 'markdown-it';
 import {parseLayout, formatLayout, imageStyle} from 'rapier-markdown-kit/layout';
-import {TEXT_COLOR_NAMES, formatColorRun, formatPageBreak, parseColorOpen, isColorClose, isPageBreakBlock} from 'rapier-markdown-kit/marks';
+import {TEXT_COLOR_NAMES, typography, formatColorRun, formatPageBreak, isPageBreakBlock} from 'rapier-markdown-kit/marks';
 import {installMarkdownImages} from 'rapier-markdown-kit/assets';
 import {readFile, writeFile} from 'node:fs/promises';
 import {pathToFileURL} from 'node:url';
 
-const md = installMarkdownImages(new MarkdownIt({html: true, linkify: true}));
+const md = typography.install(installMarkdownImages(new MarkdownIt({html: true, linkify: true})));
 md.renderer.rules.table_open = (tokens, index, options, env, renderer) =>
   '<div class="table-scroll-wrap">\n' + renderer.renderToken(tokens, index, options);
 md.renderer.rules.table_close = (tokens, index, options, env, renderer) =>
@@ -175,29 +317,6 @@ md.core.ruler.after('inline', 'reference-layout', state => {
     }
   }
 });
-md.core.ruler.after('inline', 'reference-colour', state => {
-  for (const inline of state.tokens) {
-    if (inline.type !== 'inline') continue;
-    let open = null, depth = 0;
-    for (const token of inline.children) {
-      if (token.type !== 'html_inline') {
-        depth += token.nesting;
-        if (open && depth < open.depth) open = null;
-        continue;
-      }
-      if (isColorClose(token.content) && open && depth === open.depth) {
-        Object.assign(open.token, {type: 'reference_colour_open', tag: 'span', nesting: 1, content: ''});
-        open.token.attrSet('data-md-color', open.hex);
-        open.token.attrSet('style', '--md-color:' + open.hex);
-        Object.assign(token, {type: 'reference_colour_close', tag: 'span', nesting: -1, content: ''});
-        open = null;
-      } else {
-        const hex = parseColorOpen(token.content);
-        if (hex && !open) open = {token, hex, depth};
-      }
-    }
-  }
-});
 const htmlBlock = md.renderer.rules.html_block;
 md.renderer.rules.html_block = (tokens, index, options, env, renderer) =>
   isPageBreakBlock(tokens[index].content)
@@ -213,7 +332,7 @@ export const exampleSource = [
   '',
   'One paragraph with **weight**, *emphasis*, `inline code` and a [link](https://example.com).',
   '',
-  '## Lists and tables',
+  '## ' + typography.wrap({size: '21.5pt', family: 'serif'}, 'Lists and tables'),
   '',
   '1. First numbered item',
   '2. Second numbered item',
@@ -234,7 +353,9 @@ export const exampleSource = [
   '',
   'A centred paragraph.' + formatLayout({align: 'center'}),
   '',
-  'A ' + formatColorRun(TEXT_COLOR_NAMES.blue, 'blue phrase') + ' keeps its named colour.',
+  'A ' + formatColorRun(TEXT_COLOR_NAMES.blue, 'blue phrase') + ' keeps its colour.',
+  '',
+  'And ' + typography.wrap({size: '13.5pt', color: '#175dc4', family: 'serif'}, '**precise words**') + ' keep their emphasis.',
   '',
   '![A square](data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aDAkAAAAASUVORK5CYII=)' + formatLayout({width: 45, align: 'center'}),
   '',
@@ -257,12 +378,12 @@ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
 
 ## Example
 
-Save this as `example.mjs` in the folder you installed into and run `node example.mjs`. It prints
-`lines: 4 height: 80`.
+Save this as `example.mjs` in the folder you installed into and run `node example.mjs`. It validates
+the fragments' source custody and prints the resulting line count and height for its supplied measurements.
 
 ```js
 import {parseLayout} from 'rapier-markdown-kit/layout';
-import {parseProfile, pictureSlices, prepareRun, flowLines, prepareRichInline} from 'rapier-markdown-kit/model';
+import {parseProfile, pictureSlices, createPreparationScope, flowLines, mapFragment} from 'rapier-markdown-kit/model';
 const {loadDocuments, installMeasurer} = await import(new URL(
   './dist/kit/conformance/measurer.mjs', import.meta.resolve('rapier-markdown-kit/package.json')));
 
@@ -281,27 +402,82 @@ const obstacles = pictureSlices(profile, /* x */ 0, /* y */ 0, /* width */ 120,
 
 // 3. Plan the lines of a paragraph around those obstacles.
 const text = 'This anchor paragraph carries enough ordinary prose', font = 'normal 400 17.6px Geist, system-ui, sans-serif';
-const run = prepareRun(text, font);
-const flow = prepareRichInline([{text: run.raw, font, letterSpacing: 0}]);
+const preparation = createPreparationScope(), paragraph = {};
+const flow = preparation.prepare(paragraph, [{text, font, letterSpacing: 0}], {language: 'en'});
+if (!flow) throw new Error('The host could not prepare this paragraph');
 const plan = flowLines(flow, /* column width */ 300, /* top */ 0, obstacles, /* line height */ 20, /* min slot */ 40);
 // Each line carries its own x, y and width, and the text fragments laid into it.
-console.log('lines:', plan.lines.length, 'height:', plan.height); // lines: 4 height: 80
+if (!plan || !preparation.current(flow)) throw new Error('No current plan');
+let end = 0;
+for (const line of plan.lines) for (const fragment of line.fragments) {
+  const mapped = mapFragment(text, fragment);
+  if (!mapped || mapped.start < end || text.slice(end, mapped.start).trim()) throw new Error('Unmapped source');
+  end = mapped.end;
+}
+if (text.slice(end).trim()) throw new Error('Unmapped source tail');
+console.log('lines:', plan.lines.length, 'height:', plan.height);
 ```
 
-A heading, which the style pack balances, takes its font size as an eighth argument
-(`flowLines(flow, width, top, obstacles, lineHeight, minSlot, direction, fontSize)`): its lines come out as
-Chromium lays `text-wrap: balance`, and greedy wherever an obstacle narrows a line. The block's `text-align` is the ninth
-argument (`'start'` by default). A picture moves a block's words only where its outline meets them: when no line of the
+The block's `text-align` is the ninth argument (`'start'` by default). Native balanced headings retain native
+wrapping: the current rich line-range API does not identify every legal balancing candidate. A picture moves a
+block's words only where its outline meets them: when no line of the
 block, laid and aligned in the whole column as with no picture, meets an obstacle, the plan is that layout (`x` 0, the
 column's width); otherwise every line flows around the obstacles.
 
 ## What the host supplies
 
-`prepareRun` and `prepareRichInline` measure text the way a browser does: they need a global
+Rich preparation measures text through one pinned Pretext graph. It needs a global
 `OffscreenCanvas` (or a DOM `document`) whose `getContext('2d')` has a settable `font` and a
 `measureText(text)` returning `{width}`. A browser has one already; in Node, put those two members
-in front of whatever shaper you have. The example replays recorded measurements instead, and a
-query they never recorded falls back to summing single characters, without kerning or shaping.
+in front of the host's actual shaper and admit its fonts before preparation. The example replays historical
+measurements instead; an unrecorded query falls back to summing single characters. That fallback demonstrates API
+execution only and does not qualify kerning, ligatures, complex scripts or actual browser line selection.
+
+Create one `createPreparationScope(document)` for a host document in the same measurement realm. Call
+`scope.prepare(owner, items, {whiteSpace, wordBreak, language})` with a stable paragraph owner and original rich
+items; omitted document support is available for declared Node measurement hosts. Text items accept
+`{text, font, letterSpacing?, break?: 'normal' | 'never', extraWidth?}`; box items accept `{width}`. Paragraph
+`whiteSpace` is `normal` or `pre-wrap`, and `wordBreak` is `normal` or `keep-all`. `language` is the content language,
+not the interface locale. Mixed run languages require native fallback. The scope retains owners weakly and reuses
+preparation across widths. Changes to exact text, item shaping settings or language require a new preparation.
+
+The returned handle is opaque. Pass it to `flowLines`, or retain the original ranges from
+`layoutNextRichInlineLineRange` for `materializeRichInlineLineRange`. Materialized fragments give `itemIndex`,
+`sourceStart` and `sourceEnd` in UTF-16 offsets of that item's **original** text; `mapFragment(originalText, fragment)`
+provides the shared display-to-source mapping. `gapItemIndex` names the source style for a collapsed gap. Never decode
+range cursors as old segment/grapheme fields, resegment text to interpret them, JSON-serialize or deep-freeze the
+handle. Storage segments and emergency overflow advances are not a list of legal breaks.
+
+`scope.current(handle)` checks the shared actual-font authority before projection. Bind font loading, completion and
+failure to `scope.invalidateFonts()` and schedule reflow. Actual face identity, descriptors and status detect
+same-name replacement and invalidate the vendor's metric cache as well as prepared handles. Width changes do
+neither. Call `scope.forget(owner)` when a block stops participating. One imported graph owns the realm's vendor
+metrics; another bundle or copied vendor tree cannot share that authority. Call `scope.retire()` when replacing or
+retiring a projection scope, so both its handles and the shared vendor metrics are retired. This retains the
+document's known custom-family history, allowing a missing previously declared face to be refused instead of
+silently measured through a fallback. Only the owner replacing the whole document calls
+`scope.retire({documentChanged: true})`, which also resets that document's expected-family history.
+
+The browser adapter calls `supportsRichStyle(style, language)` and refuses settings the pinned API cannot represent.
+The API has no independent controls for kerning, OpenType features, variation settings, optical sizing, word spacing
+or mixed item language; a matching font-family string alone is not proof of matching actual font data. Unsupported
+settings, unavailable or failed faces, complex objects, authored `br`, preserved-whitespace DOM paragraphs and
+balanced headings keep selectable native DOM. Direct prepared-text hosts can use `pre-wrap` with original CRLF and
+hard breaks. The reference combines browser-derived break tables and Canvas metrics with JavaScript flow. The DOM
+adapter admits Chrome/Chromium profiles; Firefox, WebKit and Chrome on iOS retain native DOM. It does not invoke live
+DOM line selection or promise identical pixels in other engines.
+Editor soft-break source tokens and generated-content shells stay native. The semantic export resolves verified
+soft-break tokens to ordinary rendered spaces through its existing owner before wrapping; its source carrier keeps
+the original Markdown unchanged.
+Ordinary picture flow keeps its greedy policy instead of the reference sheet's generic `pretty` preference;
+explicit authored inline `text-wrap:pretty` retains native wrapping. No native pretty optimization is claimed.
+A lone Latin, Greek or Cyrillic word prefix, including an authored no-break-space group, may defer to a later
+wider picture-side slot on the same row when the public engine output fits the entire group there. Decorated
+atoms, mixed-item words, punctuation, discretionary breaks and next-row placement retain the engine policy.
+
+`md-layout:v1` remains semantic and engine-independent. No plan or font-dependent pixel carrier is saved. Offline
+complete pages load their admitted embedded faces before enhanced wrapping; fragments and `scripts:false` pages
+retain native wrapping. Fonts and codecs remain explicit host capabilities as described above.
 
 `alphaProfile(image)` samples a decoded `<img>` through a canvas, so it needs a browser. Without
 one, read the saved descriptor with `parseProfile`, or sample the picture with your own image
@@ -317,15 +493,19 @@ node node_modules/rapier-markdown-kit/dist/kit/conformance/run.mjs
 ```
 
 Thirteen small documents, each with the line boxes Rapier's own export produced for it. **Preservation**: every
-layout comment round-trips exactly (12 of 12 that carry one). **Presentation**: how closely the planned lines match
-(3 agree within 2px, 10 are close with a named cause, none differ; `dist/kit/conformance/README.md`).
+layout comment round-trips exactly (12 of 12 that carry one). **Presentation** compares the plan with historical
+measurements and reports real-trace hits separately from character-sum misses (`dist/kit/conformance/README.md`).
+Its historical line counts are not a current-engine or font-shaping acceptance gate.
 `--impl path/to/module.mjs` runs another implementation against the same documents; `--tolerance 2` sets the pixel
 tolerance.
 
 ## Licence
 
-MIT, the full text in `LICENSE`; Rapier-owned modules and the stylesheet keep their MIT line. Pretext's licence, notice and
-pinned source inventory are in `dist/agent/vendor/pretext/`. The history projection uses the MIT diff core;
+MIT, the full text in `LICENSE`; Rapier-owned modules and the stylesheet keep their MIT line. Pretext's complete licence,
+notice and pinned source inventory are in `dist/agent/vendor/pretext/`. The selected upstream is unreleased main
+`bac1774c0f8b7a92e44b9da43b6d5443d55d0d9b`, despite its package version `0.0.9`. Its upstream licence includes
+Chromium/WebKit BSD, Unicode and ICU notices for derived code and generated data; those notices travel with the kit
+and the exported wrapping runtime. The history projection uses the MIT diff core;
 its full grant is in `dist/packages/rapier-diff/LICENSE`. The Rapier editor is AGPL-3.0-only and
 none of it is in this package. The kit carries Rapier's release number, written from the one
 value the editor's release reads.
@@ -403,6 +583,8 @@ no accessors, sparse arrays, cycles, undefined, negative zero or unpaired surrog
 Readers reject unknown envelope/start/head fields, bad checksums, invalid records,
 invalid source boundaries, a replay/root mismatch, or a head different from the
 actual document. `historyEnvelope` additionally proves the editor's Undo/Redo branch.
+Its optional third and fourth arguments are the expected text and metadata, as in
+`readLedger`; installing history can prove both source and navigation in one pass.
 
 **Roots are path-dependent.** `textRoot(text)` mints the existing
 `chars:fnv-base36:adler-base36` initial root. Each splice advances it with
@@ -468,6 +650,15 @@ The comparison page's `#rapier-base` is independent: `text/markdown`, with
 display reference. It is not reconstructed from the optional ledger and never
 replaces current source. `rapier-html --compare original.md revised.md` packages both texts.
 
+A comparison may also carry `data-fonts`, an HTML-attribute-escaped JSON string of
+canonical embedded `[font:]` reference definitions. The admitted base record exposes
+this as `fonts`. These resources belong to the exact comparison, outside its text,
+digest and revision; they never become a source edit or ledger record. Font preparation
+validates their actual bytes and reads font usage only from the original comparison.
+Existing source-owned assets remain authoritative. A missing personal-library font is
+embedded here when available, otherwise export refuses. Reopening and resaving need
+no library or network, and never substitute the current device's default font.
+
 ## Merging copies without a server
 
 `merge(first, second)` locates a common checkpoint with the same root **and exact

package/dist/agent/vendor/hyphen-en-us/LICENSE

@@ -0,0 +1,14 @@
+American English hyphenation patterns (hyph-en-us)
+Copyright (C) 1990, 2004, 2005 Gerard D.C. Kuiken
+
+Copying and distribution of this file, with or without modification,
+are permitted in any medium without royalty provided the copyright
+notice and this notice are preserved.
+
+Source: hyphenation/tex-hyphen, commit 5684c0f51c0b81133db2efbe60a408b4155a3ff5
+hyph-utf8/tex/generic/hyph-utf8/patterns/tex/hyph-en-us.tex
+The accompanying .pat.txt and .hyp.txt inputs are unchanged. patterns.js is a
+mechanical numeric representation generated by tools/compile-hyphens.mjs.
+These data include the original Plain TeX patterns and the additional patterns
+and exceptions described in the upstream file. No hyphenation implementation
+from that repository or Justice is included.

package/dist/agent/vendor/hyphen-en-us/SOURCE.json

@@ -0,0 +1,33 @@
+{
+  "repository": "https://github.com/hyphenation/tex-hyphen",
+  "commit": "5684c0f51c0b81133db2efbe60a408b4155a3ff5",
+  "upstreamDirectory": "hyph-utf8/tex/generic/hyph-utf8/patterns/txt/",
+  "licenseSource": "hyph-utf8/tex/generic/hyph-utf8/patterns/tex/hyph-en-us.tex",
+  "licenseSourceGitBlob": "bd9b757d89074e3e11b590311ce13ba6667544aa",
+  "license": "LicenseRef-Kuiken",
+  "licenseSha256": "0cf036759a4fb63a3d0bdb919f0dacbe137e225cb6f8f268d2928e368a8c1731",
+  "inputs": [
+    {
+      "path": "hyph-en-us.pat.txt",
+      "sourceGitBlob": "f69e835d9dacea688fdc51956ea9243b9d042e51",
+      "bytes": 31489,
+      "sha256": "0f57318b878b132547ae92db39a6e1d1cf2a05d9008874955d6ecb910007a463"
+    },
+    {
+      "path": "hyph-en-us.hyp.txt",
+      "sourceGitBlob": "b87163d4425b7b5b7e2d9f170e486131988706c4",
+      "bytes": 169,
+      "sha256": "5e785c27e151f878c312991d937b5582615b77737ab30bac413d5967d6aa21da"
+    }
+  ],
+  "generator": "tools/compile-hyphens.mjs",
+  "generatorSha256": "b5758c3ceac76ac39a8ba0bf2f45bc88854e4779d4f443a9c0957694305571dd",
+  "policy": "Complete pinned data in a static prefix trie, with original MIT Rapier traversal and matcher; en and en-US ASCII words. Other regional English, non-ASCII words and other languages use the native offline hyphenator.",
+  "files": [
+    {
+      "output": "patterns.js",
+      "outputBytes": 46360,
+      "outputSha256": "e0360f1552704657d79a670f1e2e0b263f6eea42e209866b521cd8ec2aff387d"
+    }
+  ]
+}

package/dist/agent/vendor/hyphen-en-us/hyph-en-us.hyp.txt

@@ -0,0 +1,14 @@
+as-so-ciate
+as-so-ciates
+dec-li-na-tion
+oblig-a-tory
+phil-an-thropic
+present
+presents
+project
+projects
+reci-procity
+re-cog-ni-zance
+ref-or-ma-tion
+ret-ri-bu-tion
+ta-ble