rapier-markdown-kit 1.2.6 → 1.2.8

package/README.md

@@ -24,6 +24,28 @@ deliberately show a diff. The kit supplies the portable source and history those
 npm install rapier-markdown-kit
 ```
 
+Render a document with [markdown-it](https://github.com/markdown-it/markdown-it), then style it with
+`rapier-markdown-kit/style.css` inside `<main class="md-render">`:
+
+```js
+import MarkdownIt from 'markdown-it';
+import {rapierMarkdown} from 'rapier-markdown-kit/markdown-it';
+
+const html = new MarkdownIt({html: true}).use(rapierMarkdown).render('# Plan\n\nShips **Friday**.\n');
+```
+
+Keep a document's history with authorship, and merge two offline copies:
+
+```js
+import {openLedger, replaceLedgerText, merge, authorship} from 'rapier-markdown-kit/rapier-ledger';
+
+const base = openLedger('Draft\n');
+const edited = replaceLedgerText(base, 'Draft, revised\n', {actor: {kind: 'human', id: 'ana'}});
+console.log(merge(edited, base).text, authorship(edited).runs);
+```
+
+TypeScript declarations ship for `markdown-it`, `will`, `rapier-ledger`, `ledger/carried` and `pdf`.
+
 ```js
 import {parseLayout} from 'rapier-markdown-kit/layout';   // the md-layout comment a picture carries
 import {typography, formatPageBreak} from 'rapier-markdown-kit/marks';   // inline typography and page breaks
@@ -46,6 +68,9 @@ as one HTML file on Android, Web and Windows.
 
 ## The shared renderer
 
+To render Markdown in your own app, use `rapier-markdown-kit/markdown-it` (above). The render factories below are the
+editor's own seam: each needs a `host` that supplies its DOM, Markdown, picture, style and font ports.
+
 `rapier-markdown-kit/render` exports `createRenderer`, `createMarkdownRenderer`,
 `createRenderStyles`, `createRenderSanitizer` and `createPrintRenderer`, plus the explicit font helpers
 `exportFontCss`, `requireDocumentFonts`, `fontRequests`, `waitForFonts` and `waitForFontRequests`. These are the
@@ -139,6 +164,7 @@ family name share the host's font namespace. Print retains its existing factory
 
 | Import | What it is |
 | --- | --- |
+| `rapier-markdown-kit/markdown-it` | `md.use(rapierMarkdown)`: the reference style's markup in markdown-it, in one line. |
 | `rapier-markdown-kit/layout` | The `md-layout:v1` comment a picture carries: parse it, validate it, write it back. |
 | `rapier-markdown-kit/marks` | Unified typography values, span writer and parser installer; preserved color/font comments, ink and page breaks. |
 | `rapier-markdown-kit/model` | Occupancy profiles and the line planner: the wrapping itself. |
@@ -146,7 +172,8 @@ family name share the host's font namespace. Print retains its existing factory
 | `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/rapier-ledger` | The MIT edit ledger: `openLedger`, replay, authorship, selective Undo, offline `merge`, three-way `mergeText`, and the carried parts. |
+| `rapier-markdown-kit/pdf` | `attachPdfSource`: attach the exact source to a PDF without rewriting its pages; `readPdfPageCount`. |
 | `rapier-markdown-kit/ledger/carried` | Checked optional parts for pages and saved Markdown. |
 | `rapier-markdown-kit` | Named exports from the layout, marks, model, typography, Will, assets and render modules, plus the `ledger` namespace. |
 
@@ -290,38 +317,13 @@ contract is [Reference style](https://github.com/jackskip22/rapier/blob/main/doc
 <!-- reference-style-example -->
 ```js
 import MarkdownIt from 'markdown-it';
-import {parseLayout, formatLayout, imageStyle} from 'rapier-markdown-kit/layout';
-import {TEXT_COLOR_NAMES, typography, formatColorRun, formatPageBreak, isPageBreakBlock} from 'rapier-markdown-kit/marks';
-import {installMarkdownImages} from 'rapier-markdown-kit/assets';
+import {rapierMarkdown} from 'rapier-markdown-kit/markdown-it';
+import {formatLayout} from 'rapier-markdown-kit/layout';
+import {TEXT_COLOR_NAMES, typography, formatColorRun, formatPageBreak} from 'rapier-markdown-kit/marks';
 import {readFile, writeFile} from 'node:fs/promises';
 import {pathToFileURL} from 'node:url';
 
-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) =>
-  renderer.renderToken(tokens, index, options) + '</div>\n';
-md.core.ruler.after('inline', 'reference-layout', state => {
-  for (let i = 1; i < state.tokens.length; i++) {
-    const inline = state.tokens[i], owner = state.tokens[i - 1];
-    if (inline.type !== 'inline' || !['paragraph_open', 'heading_open'].includes(owner.type)) continue;
-    const children = inline.children, marker = children.at(-1);
-    const layout = marker?.type === 'html_inline' ? parseLayout(marker.content) : null;
-    if (!layout) continue;
-    children.pop();
-    if (layout.align) owner.attrSet('data-md-align', layout.align);
-    const visible = children.filter(token => token.type !== 'text' || token.content.trim());
-    if (visible.length === 1 && visible[0].type === 'image' && layout.width) {
-      visible[0].attrSet('style', imageStyle(layout));
-      visible[0].attrSet('data-md-image-width', String(layout.width));
-    }
-  }
-});
-const htmlBlock = md.renderer.rules.html_block;
-md.renderer.rules.html_block = (tokens, index, options, env, renderer) =>
-  isPageBreakBlock(tokens[index].content)
-    ? '<div class="rapier-page-break" data-md-break="page" role="separator" aria-label="Page break"></div>\n'
-    : htmlBlock(tokens, index, options, env, renderer);
+const md = new MarkdownIt({html: true, linkify: true}).use(rapierMarkdown);
 
 export function renderReferenceDocument(source) {
   return md.render(source);

package/dist/agent/will.mjs

@@ -10,7 +10,8 @@ const _RAPIER_WILL_UNSPACED_OPENER = '<!--will/';
 const _RAPIER_WILL_UNSPACED_CLOSER = '<!--/will';
 
 function hasWillMarkers(text) {
-	return /^<!-- ?(?:will\/|\/will)/m.test(String(text == null ? '' : text));
+	// Lines end at \r and \n only, as the parser splits them; /m would also start a line after U+2028 and U+2029.
+	return /(?:^|[\r\n])<!-- ?(?:will\/|\/will)/.test(String(text == null ? '' : text));
 }
 
 function _rapierWillMarkerOf(content) {

package/dist/images/playback.mjs

@@ -73,8 +73,9 @@ export function createMediaPlayback(win, inspectGIF) {
           if (canvas.height !== h) canvas.height = h;
           const ctx = canvas.getContext('2d'); ctx.clearRect(0, 0, w, h); ctx.drawImage(frame, 0, 0);
           if (!state.first && next === 0) state.first = canvas.toDataURL('image/png');
-          // A frame of 10 ms or less shows for 100 ms, as the browser draws an <img> (images/gif.mjs counts the same).
-          const delay = frame.duration > 10000 ? Math.max(20, frame.duration / 1000) : 100;
+          // A GIF frame of 10 ms or less shows for 100 ms, as the browser draws an <img> (images/gif.mjs counts the same).
+          // A JPEG XL frame keeps its own duration: its ticks are exact, and 100 frames a second is a real animation.
+          const delay = type !== 'image/gif' ? Math.max(8, frame.duration / 1000) : frame.duration > 10000 ? Math.max(20, frame.duration / 1000) : 100;
           duration += delay; if (duration > 120000) throw new Error('Animation exceeds the duration budget');
           state.status = 'ready'; state.frame = next; changed(state);
           if (single) {paused = true; closeDecoder(); return;}

package/dist/kit/index.mjs

@@ -6,4 +6,4 @@ export * from './typography.mjs';
 export * from './will.mjs';
 export * from './assets.mjs';
 export * from './render-entry.mjs';
-export * as ledger from './rapier-ledger.mjs';
+export * as ledger from './ledger.mjs';

package/dist/kit/ledger/carried.d.mts

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: MIT
+// The ledger and authorship carried inside the document: an optional HTML comment at the end of the file.
+import type {LedgerEnvelope, AuthorshipEnvelope, Metadata} from '../ledger.mjs';
+export interface DocumentParts { ledger?: LedgerEnvelope | null; authorship?: AuthorshipEnvelope | null; metadata?: Metadata; }
+export interface ReadParts { text: string; ledger: LedgerEnvelope | null; authorship: AuthorshipEnvelope | null; }
+/** The text with its parts appended as one EOF comment; the text alone when there are none. */
+export function writeDocument(text: string, parts?: DocumentParts): string;
+/** Splits a saved file into its exact text and verified parts; throws on a damaged or mismatched comment. */
+export function readDocument(source: string): ReadParts;
+export function writeParts(text: string, parts?: DocumentParts): string;
+export function readParts(text: string, elements: unknown): {ledger: LedgerEnvelope | null; authorship: AuthorshipEnvelope | null};
+export function validateParts(text: string, parts?: DocumentParts): {ledger: LedgerEnvelope | null; authorship: AuthorshipEnvelope | null};
+export function takeParts(html: string, text?: string): {html: string; ledger: LedgerEnvelope | null; authorship: AuthorshipEnvelope | null};
+export function encodeCarried(text: string): string;
+export function decodeCarried(text: string): string;
+export interface ComparisonBase { text: string; sha256: string; revision: string; name: string; by: string; at: string; }
+export function readBase(value: Partial<ComparisonBase>): ComparisonBase;
+export function writeBase(text: string, value: Partial<ComparisonBase>): string;
+export function readBaseElements(elements: unknown): ComparisonBase | null;
+export function takeBase(html: string): {html: string; base: ComparisonBase | null};

package/dist/kit/ledger.d.mts

@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: MIT
+// rapier-markdown-kit/rapier-ledger: a document's edit history with authorship, Undo of any act and offline merge.
+// Offsets count UTF-16 code units; splices run in their recorded order.
+export type ActorKind = 'human' | 'agent' | 'system';
+export interface Actor { kind: ActorKind; id: string; }
+export type DocKind = 'markdown' | 'text' | 'code';
+export interface Metadata { filename: string; docKind: DocKind; }
+export interface Splice { pos: number; removed: string; inserted: string; }
+export interface Transaction {
+  id: string; documentAuthority: string; baseRevision: number; revision: number; actor: Actor;
+  transport: string; operation: string; requestId: string | null; sourceTransactionId: string | null;
+  affectedBlockIds: string[]; parent: string | null; reverts: string | null; reapplies: string | null;
+  createdAt: string | null; turnId?: string; sourceTransactionIds?: string[];
+}
+export interface LedgerRecord { transaction: Transaction; splices: Splice[]; beforeHash: string; afterHash: string; metadata?: Record<string, unknown>; authored?: unknown; }
+/** rapier-ledger/2: plain JSON. */
+export interface LedgerEnvelope {
+  format: 'rapier-ledger/2';
+  documentAuthority: string;
+  start: {text: string; revision: number; root: string; sha256: string; metadata: Metadata};
+  records: LedgerRecord[];
+  head: {revision: number; root: string; sha256: string; metadata: Metadata};
+  complete: boolean;
+  sha256: string;
+}
+/** Runs of [start, end, actor kind, actor id, createdAt] over the current text. */
+export interface AuthorshipEnvelope { format: 'rapier-authorship/1'; sha256: string; runs: [number, number, ActorKind, string, string | number | null][]; }
+export interface ReadLedger { ledger: LedgerEnvelope; text: string; metadata: Metadata; root: string; revision: number; complete: boolean; }
+export interface LedgerInput { text: string; metadata: Metadata; records: LedgerRecord[]; documentAuthority?: string; revision?: number; root?: string; complete?: boolean; }
+
+/** A new ledger with no history. Give every copy that may later merge the same documentAuthority. */
+export function openLedger(text: string, options?: {filename?: string; docKind?: DocKind; documentAuthority?: string}): LedgerEnvelope;
+export function exportLedger(input: LedgerInput): LedgerEnvelope;
+/** Verifies the envelope (and, when given, that it describes this text and metadata); throws when it does not. */
+export function readLedger(input: LedgerEnvelope, expectedText?: string, expectedMetadata?: Metadata): ReadLedger;
+/** Records one replacement of the whole text as an act by `actor`. */
+export function replaceLedgerText(input: LedgerEnvelope, text: string, options?: {actor?: Actor; operation?: string; at?: string}): LedgerEnvelope;
+export function ledgerWithStart(input: LedgerEnvelope, text: string): LedgerEnvelope;
+export function historyEnvelope(input: LedgerEnvelope, segmentIdentity?: unknown[], expectedText?: string, expectedMetadata?: Metadata): Record<string, unknown>;
+/** The actor id an agent writes under, for a door and an agent name. */
+export function agentActorId(door: string, agent: string): string;
+export function textRoot(text: string): string;
+export function rootAfter(root: string, splice: Splice): string;
+export function sha256State(): {update(text: string): unknown; digest(): string};
+
+export function authorship(input: LedgerEnvelope): AuthorshipEnvelope;
+export function readAuthorship(input: AuthorshipEnvelope, text: string): AuthorshipEnvelope;
+export function ledgerFromAuthorship(input: AuthorshipEnvelope, text: string, documentAuthority: string, metadata: Metadata): LedgerEnvelope;
+
+export interface MergeConflict { kind: string; code?: string; actId?: string; [key: string]: unknown; }
+export interface MergeResult {
+  text: string; metadata: Metadata; ledger: LedgerEnvelope;
+  /** False when a person must review: conflicts, or Will keep regions that differ. */
+  clean: boolean;
+  conflicts: MergeConflict[];
+  review: {required: boolean; base: string; proposed: string};
+}
+/** Merges two copies of one document (same documentAuthority) without a server. */
+export function merge(first: LedgerEnvelope, second: LedgerEnvelope): MergeResult;
+export function transportInterval(start: number, end: number, splices: Splice[]): {start: number; end: number} | null;
+export function transportTouchedInterval(start: number, end: number, splices: Splice[]): {start: number; end: number};
+
+export interface HistoryInput { source: string; metadata: Metadata; records: LedgerRecord[]; revision: number; earliestRevision: number; complete: boolean; }
+export interface HistoryFailure { ok?: false; code: string; [key: string]: unknown; }
+/** Reverses chosen acts while later work stays. */
+export function selectiveUndo(input: HistoryInput, actIds: string[], options?: {actor?: Actor; splitSplice?: (...args: unknown[]) => unknown}): Record<string, unknown> | HistoryFailure;
+export function replayHistory(input: HistoryInput): unknown;
+export function sourceBefore(input: HistoryInput, actId: string): unknown;
+export function historyProjection(input: HistoryInput, range?: {from?: number; to?: number; actId?: string}): unknown;
+export function historyProjections(input: HistoryInput, ranges: unknown[]): unknown;
+export function historyPlaces(input: HistoryInput, blocks: unknown[]): unknown;
+export function groupHistoryActs(acts: unknown[]): unknown;
+export function pictureHistorySplices(input: unknown, target: unknown, redo: boolean): Splice[] | null;
+export function transposeSource(base: string, splices: Splice[], client: unknown, log: unknown): unknown;
+export function authoredBasis(...args: unknown[]): unknown;
+export function authoredPlacement(...args: unknown[]): unknown;
+export function authoredHistory(base: string, records: LedgerRecord[], selected?: unknown): unknown;
+export function transposeAuthored(base: string, records: LedgerRecord[], incoming: unknown, submitted: unknown): unknown;
+
+export {writeDocument, readDocument, writeParts, readParts} from './ledger/carried.mjs';
+
+export interface TextConflict { kind: 'text'; id: string; start: number; end: number; block: string; variants: string[]; }
+export interface TextMerge { text: string; clean: boolean; conflicts: (TextConflict | {kind: string; advisory?: boolean})[]; }
+/** Exact three-way text merge; a region both sides changed becomes a marked choice in the text. */
+export function mergeText(base: string | null, ours: string, theirs: string, options?: Record<string, unknown>): TextMerge;
+export function inspectTextConflicts(text: string, options?: {nested?: boolean}): TextConflict[];
+export function resolveTextConflict(text: string, conflict: TextConflict | string, device: unknown): string;
+export function mapTextConflictVariants(text: string, mapper: (variant: string) => string): string;

package/dist/kit/ledger.mjs

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: MIT
+// The public edit ledger (rapier-markdown-kit/rapier-ledger): the history, its carried parts and three-way text merge.
+// The editor binds kit/rapier-ledger.mjs, which also carries its private record helpers.
+import {exportLedger} from './ledger/format.mjs';
+export {exportLedger, replaceLedgerText, readLedger, ledgerWithStart, textRoot, rootAfter, historyEnvelope, agentActorId} from './ledger/format.mjs';
+export {authorship, readAuthorship, ledgerFromAuthorship} from './ledger/authorship.mjs';
+export {merge, transportInterval, transportTouchedInterval} from './ledger/merge.mjs';
+export {replayHistory, sourceBefore, historyProjection, historyProjections, historyPlaces, selectiveUndo, groupHistoryActs, pictureHistorySplices} from './ledger/history.mjs';
+export {sha256State} from './ledger/hash.mjs';
+export {transposeSource, authoredBasis, authoredPlacement, authoredHistory, transposeAuthored} from './ledger/transport.mjs';
+export {writeDocument, readDocument, writeParts, readParts} from './ledger/carried.mjs';
+export {mergeText, resolveTextConflict, inspectTextConflicts, mapTextConflictVariants} from './ledger/text-merge.mjs';
+
+// A new ledger for one text, with no history yet. documentAuthority names the document across its copies:
+// pass the same one to every copy that may later merge.
+export function openLedger(text, {filename = 'document.md', docKind = 'markdown', documentAuthority = globalThis.crypto.randomUUID()} = {}) {
+  return exportLedger({text, metadata: {filename, docKind}, records: [], documentAuthority, complete: true});
+}

package/dist/kit/markdown-it.d.mts

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: MIT
+// md.use(rapierMarkdown): Self-contained Markdown in markdown-it, with the reference style's markup.
+interface MarkdownItLike { use(plugin: (md: any, ...params: any[]) => unknown, ...params: any[]): any; renderer: {rules: Record<string, unknown>}; core: {ruler: {after(after: string, name: string, rule: (state: any) => unknown): void}}; }
+export function rapierMarkdown<T extends MarkdownItLike>(md: T): T;

package/dist/kit/markdown-it.mjs

@@ -0,0 +1,39 @@
+// SPDX-License-Identifier: MIT
+// rapier-markdown-kit/markdown-it: md.use(rapierMarkdown) renders Self-contained Markdown with the reference style's markup
+// (wrap the output in <main class="md-render"> with rapier-markdown-kit/style.css). Create markdown-it with {html: true}.
+import {parseLayout, imageStyle} from './layout.mjs';
+import {typography, isPageBreakBlock} from './marks.mjs';
+import {installMarkdownImages} from './assets.mjs';
+
+const PAGE_BREAK = '<div class="rapier-page-break" data-md-break="page" role="separator" aria-label="Page break"></div>\n';
+
+export function rapierMarkdown(md) {
+  if (md.__rapierMarkdownInstalled) return md;
+  md.__rapierMarkdownInstalled = true;
+  typography.install(installMarkdownImages(md));
+  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) =>
+    renderer.renderToken(tokens, index, options) + '</div>\n';
+  // A paragraph's or heading's closing layout comment: its alignment, and a lone picture's width.
+  md.core.ruler.after('inline', 'rapier-layout', state => {
+    for (let i = 1; i < state.tokens.length; i++) {
+      const inline = state.tokens[i], owner = state.tokens[i - 1];
+      if (inline.type !== 'inline' || !['paragraph_open', 'heading_open'].includes(owner.type)) continue;
+      const children = inline.children, marker = children.at(-1);
+      const layout = marker?.type === 'html_inline' ? parseLayout(marker.content) : null;
+      if (!layout) continue;
+      children.pop();
+      if (layout.align) owner.attrSet('data-md-align', layout.align);
+      const visible = children.filter(token => token.type !== 'text' || token.content.trim());
+      if (visible.length === 1 && visible[0].type === 'image' && layout.width) {
+        visible[0].attrSet('style', imageStyle(layout));
+        visible[0].attrSet('data-md-image-width', String(layout.width));
+      }
+    }
+  });
+  const htmlBlock = md.renderer.rules.html_block || ((tokens, index) => tokens[index].content);
+  md.renderer.rules.html_block = (tokens, index, options, env, renderer) =>
+    isPageBreakBlock(tokens[index].content) ? PAGE_BREAK : htmlBlock(tokens, index, options, env, renderer);
+  return md;
+}

package/dist/kit/pdf-glyphs.mjs

@@ -77,6 +77,14 @@ function shape(value, font, preserve, ligatures) {
   const result = [];
   for (let at = 0; at < value.length;) {
     const code = value.codePointAt(at), character = String.fromCodePoint(code), start = at;
+    if (code === 0x00ad) {
+      at += character.length;
+      const own = font.glyph(code), hyphen = font.glyph(0x2d), glyph = own || hyphen;
+      // A discretionary hyphen with no glyph stays in the page paint. Do not skip the lookup.
+      if (!glyph || glyph >= font.glyphCount) return null;
+      result.push({start, end: at, text: own ? character : '-', glyph, soft: true});
+      continue;
+    }
     if (/[\p{Mark}\p{Format}]/u.test(character) || (/[\p{Letter}]/u.test(character) && !/\p{Script=Latin}/u.test(character)) || code === 0xfb01 || code === 0xfb02) return null;
     at += character.length;
     if (!preserve && /[ \t\r\n\f]/.test(character)) {while (at < value.length && /[ \t\r\n\f]/.test(value[at])) at++;}
@@ -97,7 +105,13 @@ export async function collectPdfGlyphs(main, {width, check, faces = []}) {
   const document = main.ownerDocument, window = document.defaultView, origin = main.getBoundingClientRect();
   const nodes = new Map(), hidden = [], canvas = document.createElement('canvas'); canvas.width = canvas.height = 1;
   const context = canvas.getContext('2d', {willReadFrequently: true});
-  const restore = () => {for (const row of hidden) {if (row.value) row.node.style.setProperty('-webkit-text-fill-color', row.value, row.priority); else row.node.style.removeProperty('-webkit-text-fill-color');} canvas.width = canvas.height = 0;};
+  const restore = () => {
+    for (const row of hidden) {
+      if (row.wrap) {row.wrap.replaceWith(...row.wrap.childNodes); continue;}
+      if (row.value) row.node.style.setProperty('-webkit-text-fill-color', row.value, row.priority); else row.node.style.removeProperty('-webkit-text-fill-color');
+    }
+    canvas.width = canvas.height = 0;
+  };
   if (!context) return {nodes, restore};
   const colorCache = new Map(), styles = new Map(), styleOf = node => {if (!styles.has(node)) styles.set(node, window.getComputedStyle(node)); return styles.get(node);};
   const color = value => {if (!colorCache.has(value)) {context.clearRect(0, 0, 1, 1); context.fillStyle = value; context.fillRect(0, 0, 1, 1); colorCache.set(value, Array.from(context.getImageData(0, 0, 1, 1).data, item => item / 255));} return colorCache.get(value);};
@@ -118,9 +132,10 @@ export async function collectPdfGlyphs(main, {width, check, faces = []}) {
       if (++visited % 128 === 0) {await new Promise(resolve => setTimeout(resolve, 0)); check();}
       // Leaving the existing element in place preserves selectors, counters, line breaking and inline marks.
       // Keep preformatted blocks, their inline struts and syntax paint together.
-      if (element.namespaceURI !== 'http://www.w3.org/1999/xhtml' || element.children.length || element.closest('svg,pre,.rapier-will-carrier') || element.localName === 'li') continue;
-      const textNodes = Array.from(element.childNodes).filter(node => node.nodeType === 3);
-      if (textNodes.length !== 1 || !textNodes[0].data.trim() || !safe(element)) continue;
+      // A paragraph's own words beside a mark, a link or code are drawn too: each text node is placed and hidden on its own.
+      if (element.namespaceURI !== 'http://www.w3.org/1999/xhtml' || element.closest('svg,pre,.rapier-will-carrier')) continue;
+      const textNodes = Array.from(element.childNodes).filter(node => node.nodeType === 3 && node.data.trim());
+      if (!textNodes.length || !safe(element)) continue;
       const language = (element.closest('[lang]')?.getAttribute('lang') || document.documentElement.lang || '').toLowerCase();
       if (language && !/^en(?:-|$)/.test(language)) continue;
       const style = styleOf(element), family = familyName(style.fontFamily.split(',')[0]), weight = Number(style.fontWeight), size = Number.parseFloat(style.fontSize);
@@ -134,25 +149,51 @@ export async function collectPdfGlyphs(main, {width, check, faces = []}) {
       if (generated || altered || !Array.from(document.fonts).some(face => familyName(face.family) === family && face.status === 'loaded')) continue;
       const asset = faces.find(face => face.family === family && face.weight === weight);
       if (!asset) continue;
-      const font = readFont(asset, fontCache), preserve = /pre|break-spaces/.test(style.whiteSpace), node = textNodes[0];
-      const shaped = shape(node.data, font, preserve, style.fontVariantLigatures === 'normal' && !(Number.parseFloat(style.letterSpacing) || 0));
-      if (!shaped) continue;
+      const font = readFont(asset, fontCache), preserve = /pre|break-spaces/.test(style.whiteSpace);
       context.font = [style.fontStyle, style.fontWeight, style.fontSize, style.fontFamily].join(' ');
       const metrics = context.measureText('Hg'), ascent = metrics.fontBoundingBoxAscent;
       if (!Number.isFinite(ascent)) continue;
       const rgba = color(style.webkitTextFillColor || style.color), range = document.createRange();
-      let valid = true;
-      for (const item of shaped) {
-        range.setStart(node, item.start); range.setEnd(node, item.end);
-        const rects = Array.from(range.getClientRects()).filter(rect => rect.height > 0), first = rects[0];
-        if (!first || rects.some(rect => Math.abs(rect.top - first.top) > .25)) {valid = false; break;}
-        const page = Math.max(0, Math.floor((first.left - origin.left + .01) / width));
-        Object.assign(item, {font, size, rgba, x: first.left - origin.left - page * width, baseline: first.top - origin.top + ascent});
+      for (const node of textNodes) {
+        const shaped = shape(node.data, font, preserve, style.fontVariantLigatures === 'normal' && !(Number.parseFloat(style.letterSpacing) || 0));
+        if (!shaped) continue;
+        let valid = true;
+        const placed = [];
+        for (const item of shaped) {
+          range.setStart(node, item.start); range.setEnd(node, item.end);
+          const ink = Array.from(range.getClientRects()).filter(rect => rect.height > 0);
+          // A break after a soft hyphen can leave the next letter with a phantom box on the
+          // hyphen's line. Keep the line that actually holds the ink.
+          const lines = [];
+          for (const rect of ink) {
+            const line = lines.find(row => Math.abs(row[0].top - rect.top) <= .25);
+            if (line) line.push(rect); else lines.push([rect]);
+          }
+          lines.sort((a, b) => b.reduce((sum, rect) => sum + rect.width, 0) - a.reduce((sum, rect) => sum + rect.width, 0));
+          const previous = shaped[shaped.indexOf(item) - 1];
+          if (lines.length > 1 && !item.soft && !previous?.soft) {valid = false; break;}
+          const rects = lines[0] || [];
+          const first = (item.soft ? rects.find(rect => rect.width > 0) : null) || rects[0];
+          // An unbroken soft hyphen has no ink. Leave it out of the vector run.
+          if (item.soft && !(first?.width > 0)) continue;
+          if (!first) {valid = false; break;}
+          const page = Math.max(0, Math.floor((first.left - origin.left + .01) / width));
+          Object.assign(item, {font, size, rgba, x: first.left - origin.left - page * width, baseline: first.top - origin.top + ascent});
+          placed.push(item);
+        }
+        if (!valid || !placed.length) continue;
+        nodes.set(node, placed);
+        if (element.localName === 'li' || element.children.length || textNodes.length > 1) {
+          // A list item's marker and a paragraph's marks are not this node's words: hide only the words.
+          const wrap = document.createElement('span');
+          node.replaceWith(wrap); wrap.append(node);
+          wrap.style.setProperty('-webkit-text-fill-color', 'transparent', 'important');
+          hidden.push({wrap});
+          continue;
+        }
+        hidden.push({node: element, value: element.style.getPropertyValue('-webkit-text-fill-color'), priority: element.style.getPropertyPriority('-webkit-text-fill-color')});
+        element.style.setProperty('-webkit-text-fill-color', 'transparent', 'important');
       }
-      if (!valid) continue;
-      nodes.set(node, shaped);
-      hidden.push({node: element, value: element.style.getPropertyValue('-webkit-text-fill-color'), priority: element.style.getPropertyPriority('-webkit-text-fill-color')});
-      element.style.setProperty('-webkit-text-fill-color', 'transparent', 'important');
     }
     check(); return {nodes, restore};
   } catch (error) {restore(); throw error;}

package/dist/kit/pdf-source.d.mts

@@ -0,0 +1,5 @@
+// SPDX-License-Identifier: MIT
+// Attach the exact source to a PDF Rapier wrote, without rewriting its pages (rapier-markdown-kit/pdf).
+export function readPdfPageCount(input: Uint8Array | ArrayBuffer): number;
+/** The PDF with `source` attached as an associated file; throws `pdf_source_invalid` for a PDF it cannot extend. */
+export function attachPdfSource(input: Uint8Array | ArrayBuffer, options: {source: string; filename: string; maxBytes?: number; check?: () => void}): Promise<Uint8Array>;

package/dist/kit/pdf-source.mjs

@@ -0,0 +1,125 @@
+// SPDX-License-Identifier: MIT
+// Add an associated source file to Rapier's fresh PDF without rewriting its pages.
+function pdfStructure(input) {
+  const bytes = input instanceof Uint8Array ? input : new Uint8Array(input);
+  const fail = () => { throw Object.assign(new Error('The PDF source could not be attached.'), {code: 'pdf_source_invalid'}); };
+  let text = '';
+  for (let at = 0; at < bytes.length; at += 32768) text += String.fromCharCode(...bytes.subarray(at, at + 32768));
+  if (!text.startsWith('%PDF-')) fail();
+  const end = /startxref\s+(\d+)\s+%%EOF\s*$/.exec(text), xref = Number(end?.[1]);
+  if (!end || !Number.isSafeInteger(xref) || text.slice(xref, xref + 4) !== 'xref') fail();
+  const offsets = new Map();
+  let at = xref + 4;
+  const space = () => { while (at < text.length && /[\s\0]/.test(text[at])) at++; };
+  for (;;) {
+    space(); if (text.startsWith('trailer', at)) { at += 7; break; }
+    const section = /^(\d+)\s+(\d+)\s+/.exec(text.slice(at)); if (!section) fail();
+    at += section[0].length;
+    const from = Number(section[1]), count = Number(section[2]);
+    if (!Number.isSafeInteger(from + count) || count > bytes.length / 18) fail();
+    for (let i = 0; i < count; i++) {
+      const entry = /^(\d{10})\s+(\d{5})\s+([nf])\s+/.exec(text.slice(at)); if (!entry) fail();
+      at += entry[0].length;
+      if (entry[3] === 'n') offsets.set(from + i, {at: Number(entry[1]), generation: Number(entry[2])});
+    }
+  }
+  const skip = pos => { for (;;) { while (pos < text.length && /[\s\0]/.test(text[pos])) pos++; if (text[pos] !== '%') return pos; while (pos < text.length && !/[\r\n]/.test(text[pos])) pos++; } };
+  const tokenEnd = pos => { while (pos < text.length && !/[\s\0()[\]<>/%]/.test(text[pos])) pos++; return pos; };
+  const valueEnd = (pos, depth = 0) => {
+    if (depth > 32) fail(); pos = skip(pos);
+    if (text.startsWith('<<', pos)) {
+      pos += 2;
+      for (;;) { pos = skip(pos); if (text.startsWith('>>', pos)) return pos + 2; if (text[pos] !== '/') fail(); pos = valueEnd(tokenEnd(pos + 1), depth + 1); }
+    }
+    if (text[pos] === '[') { pos++; for (;;) { pos = skip(pos); if (text[pos] === ']') return pos + 1; pos = valueEnd(pos, depth + 1); } }
+    if (text[pos] === '(') {
+      let nesting = 1; pos++;
+      while (pos < text.length && nesting) { const c = text[pos++]; if (c === '\\') pos++; else if (c === '(') nesting++; else if (c === ')') nesting--; }
+      if (nesting) fail(); return pos;
+    }
+    if (text[pos] === '<') { const close = text.indexOf('>', pos + 1); if (close < 0) fail(); return close + 1; }
+    if (text[pos] === '/') return tokenEnd(pos + 1);
+    const first = tokenEnd(pos); if (first === pos) fail();
+    const reference = /^\d+\s+\d+\s+R\b/.exec(text.slice(pos)); return reference ? pos + reference[0].length : first;
+  };
+  const dictionary = pos => {
+    pos = skip(pos); if (!text.startsWith('<<', pos)) fail();
+    const start = pos, fields = new Map(); pos += 2;
+    for (;;) {
+      pos = skip(pos); if (text.startsWith('>>', pos)) return {start, end: pos + 2, fields};
+      if (text[pos] !== '/') fail();
+      const keyStart = pos, keyEnd = tokenEnd(pos + 1), name = text.slice(pos + 1, keyEnd);
+      if (fields.has(name)) fail();
+      const from = skip(keyEnd), end = valueEnd(from);
+      fields.set(name, {start: keyStart, from, end, value: text.slice(from, end)}); pos = end;
+    }
+  };
+  const trailer = dictionary(at), rootRef = /^(\d+)\s+(\d+)\s+R$/.exec(trailer.fields.get('Root')?.value || '');
+  const size = Number(trailer.fields.get('Size')?.value), rootId = Number(rootRef?.[1]), generation = Number(rootRef?.[2]);
+  let highest = 0; for (const id of offsets.keys()) highest = Math.max(highest, id);
+  if (!rootRef || !Number.isSafeInteger(size) || size <= highest || trailer.fields.has('Encrypt') || trailer.fields.has('Prev')) fail();
+  const readDictionary = (id, gen) => {
+    const place = offsets.get(id); if (!place || place.generation !== gen) fail();
+    const header = new RegExp('^' + id + '\\s+' + gen + '\\s+obj\\b').exec(text.slice(place.at)); if (!header) fail();
+    return dictionary(place.at + header[0].length);
+  };
+  const root = readDictionary(rootId, generation);
+  return {bytes, text, offsets, root, rootId, generation, trailer, size, xref, readDictionary, dictionary, fail};
+}
+
+export function readPdfPageCount(input) {
+  const {root, readDictionary, fail} = pdfStructure(input);
+  const reference = /^(\d+)\s+(\d+)\s+R$/.exec(root.fields.get('Pages')?.value || '');
+  if (!reference) fail();
+  const pages = readDictionary(Number(reference[1]), Number(reference[2])), count = Number(pages.fields.get('Count')?.value);
+  if (pages.fields.get('Type')?.value !== '/Pages' || !Number.isSafeInteger(count) || count < 1) fail();
+  return count;
+}
+
+export async function attachPdfSource(input, {source, filename, maxBytes = Infinity, check = () => {}}) {
+  const {bytes, text, offsets, root, rootId, generation, trailer, size, readDictionary, dictionary, fail} = pdfStructure(input);
+  if (typeof source !== 'string' || typeof filename !== 'string' || !filename) fail();
+  const ascii = value => Uint8Array.from(value, character => character.charCodeAt(0));
+  const encode = new TextEncoder(), hex = value => Array.from({length: value.length}, (_, i) => value.charCodeAt(i).toString(16).padStart(4, '0')).join('');
+  if (root.fields.get('Type')?.value !== '/Catalog' || root.fields.has('AF')) fail();
+  let names = '<<', remove = root.fields.get('Names');
+  if (remove) {
+    const ref = /^(\d+)\s+(\d+)\s+R$/.exec(remove.value);
+    const held = ref ? readDictionary(Number(ref[1]), Number(ref[2])) : dictionary(remove.from);
+    if (held.fields.has('EmbeddedFiles')) fail();
+    names = text.slice(held.start, held.end - 2);
+  }
+  const original = remove ? text.slice(root.start, remove.start) + text.slice(remove.end, root.end - 2) : text.slice(root.start, root.end - 2);
+  const payload = encode.encode(source); check();
+  const compressed = new Uint8Array(await new Response(new Blob([payload]).stream().pipeThrough(new CompressionStream('deflate'))).arrayBuffer()); check();
+  const fileId = size, streamId = size + 1, infoId = size + 2, totalSize = size + 3;
+  let infoBody = '<< /Producer (Rapier) >>';
+  const existingInfo = trailer.fields.get('Info');
+  if (existingInfo) {
+    const ref = /^(\d+)\s+(\d+)\s+R$/.exec(existingInfo.value);
+    const held = ref ? readDictionary(Number(ref[1]), Number(ref[2])) : dictionary(existingInfo.from);
+    const producer = held.fields.get('Producer');
+    const kept = producer ? text.slice(held.start, producer.start) + text.slice(producer.end, held.end - 2) : text.slice(held.start, held.end - 2);
+    infoBody = kept + ' /Producer (Rapier) >>';
+  }
+  const escaped = '(' + filename.replace(/[^\x20-\x7e]/g, '_').replace(/[\\()]/g, '\\$&') + ')';
+  const parts = [bytes, ascii('\n')], merged = new Map(offsets);
+  let length = bytes.length + 1;
+  const append = (id, gen, chunks) => { merged.set(id, {at: length, generation: gen}); const body = [ascii(id + ' ' + gen + ' obj\n'), ...chunks, ascii('\nendobj\n')]; for (const chunk of body) {parts.push(chunk); length += chunk.length;} };
+  append(rootId, generation, [ascii(original + ' /Names ' + names + ' /EmbeddedFiles << /Names [<feff' + hex(filename) + '> ' + fileId + ' 0 R] >> >> /AF [' + fileId + ' 0 R] >>')]);
+  append(fileId, 0, [ascii('<< /Type /Filespec /F ' + escaped + ' /UF <feff' + hex(filename) + '> /AFRelationship /Source /EF << /F ' + streamId + ' 0 R /UF ' + streamId + ' 0 R >> >>')]);
+  append(streamId, 0, [ascii('<< /Type /EmbeddedFile /Subtype /text#2Fmarkdown /Params << /Size ' + payload.length + ' >> /Filter /FlateDecode /Length ' + compressed.length + ' >>\nstream\n'), compressed, ascii('\nendstream')]);
+  append(infoId, 0, [ascii(infoBody)]);
+  let table = 'xref\n0 ' + totalSize + '\n0000000000 65535 f \n';
+  for (let id = 1; id < totalSize; id++) {
+    const place = merged.get(id);
+    table += place ? String(place.at).padStart(10, '0') + ' ' + String(place.generation).padStart(5, '0') + ' n \n' : '0000000000 00000 f \n';
+  }
+  const identity = trailer.fields.get('ID');
+  table += 'trailer\n<< /Size ' + totalSize + ' /Root ' + rootId + ' ' + generation + ' R /Info ' + infoId + ' 0 R' + (identity ? ' /ID ' + identity.value : '') + ' >>\nstartxref\n' + length + '\n%%EOF\n';
+  parts.push(ascii(table)); length += table.length;
+  if (length > maxBytes) throw Object.assign(new Error('The exported file exceeds the file limit.'), {code: 'export_too_large'});
+  const result = new Uint8Array(length); let at = 0;
+  for (const chunk of parts) { result.set(chunk, at); at += chunk.length; }
+  check(); return result;
+}

package/dist/kit/render-markdown.mjs

@@ -410,7 +410,7 @@ function initMarkdownIt() {
 }
 
 function _rapierRenderSemanticRoot(canonical, metadata, options = {}) {
-	const root = document.createElement('div');
+	const root = document.createElement('template').content.ownerDocument.createElement('div');
 	root.setAttribute('data-rapier-semantic-root', 'true');
 
 	if (metadata.docKind !== 'markdown') {
@@ -469,7 +469,8 @@ async function _rapierRenderSemanticRootAsync(canonical, metadata, options = {})
 	let {tokens, env} = parsed, labels = env.footnotes?.list?.map((item, index) => String(item?.label || ('inline-' + (index + 1))));
 	env = {...env, rapierImagePresentation: options.imagePresentation === true};
 	await pause(work, .3);
-	const root = document.createElement('div'), part = document.createElement('div'), boundary = htmlBoundary();
+	const inert = document.createElement('template').content.ownerDocument;
+	const root = inert.createElement('div'), part = inert.createElement('div'), boundary = htmlBoundary();
 	root.setAttribute('data-rapier-semantic-root', 'true');
 	let html = '', began = performance.now(), complete = false;
 	const append = () => {

package/dist/kit/render-print.mjs

@@ -5,6 +5,8 @@ import {fontRequests, waitForFonts} from './export-fonts.mjs';
 import {apply as applyTypography} from '../layout/typography.mjs';
 import {documentLanguage} from '../spec/document-settings.mjs';
 import {applyPrintCapitals} from './print-capitals.mjs';
+import {stripOneTerminator as _rapierWillStripOneTerminator} from '../agent/will.mjs';
+import {quotedWillSpan} from '../spec/md-marks.mjs';
 const RAPIER_WILL_SENTINEL_MARK = '⁣';
 // SPDX-License-Identifier: MIT
 // The document's renderer. DOM, codecs and host state are explicit inputs.
@@ -27,12 +29,11 @@ function _rapierWillSentinelPlan(canonical, kind) {
 	return { canonical: out + source.slice(cursor), markers, sentinel };
 }
 
-const _rapierWillStripOneTerminator = globalThis.RapierAgentWill.stripOneTerminator;
 
 
 
 function _rapierPrintWillAdmit(canonical, plan) {
-	const quoted = globalThis.RapierMarkdownSpec.quotedWillSpan(canonical, _rapierWillParse(canonical).blocks.map(block => [block.start, block.end]));
+	const quoted = quotedWillSpan(canonical, _rapierWillParse(canonical).blocks.map(block => [block.start, block.end]));
 	if (quoted && quoted.where === 'frontmatter') throw _rapierPrintWillLost('a marker stands in the front matter, which is not on the printed page', 'Take it out of the front matter');
 	if (quoted) throw _rapierPrintWillLost('a marker stands inside other content, where a reader of the PDF\'s text could not tell it from a carried marker', 'Take the quoted marker out');
 	for (const marker of plan.markers) {
@@ -42,8 +43,12 @@ function _rapierPrintWillAdmit(canonical, plan) {
 	if (new Set(plan.markers.flatMap(marker => Array.from(marker))).size > 65000) throw _rapierPrintWillLost('the markers use more distinct characters than a font can hold', 'Shorten them');
 }
 
-function _rapierPrintWillFont(markers) {
-	const { size, advance } = _rapierPrintWillMetrics(markers);
+function _rapierPrintWillFont(markers, advanceOverride) {
+	const metrics = _rapierPrintWillMetrics(markers);
+	const size = metrics.size;
+	// The page's carrier face keeps the short marker advance. Searchable text is
+	// positioned at 500 units, which is also /DW, so this copy can be asked to match it.
+	const advance = advanceOverride ?? metrics.advance;
 	const scalars = Array.from(new Set(markers.flatMap(marker => Array.from(marker, ch => ch.codePointAt(0)))));
 	const order = scalars.filter(code => code < 0x10000).sort((a, b) => a - b)
 		.concat(scalars.filter(code => code >= 0x10000).sort((a, b) => b - a));
@@ -296,7 +301,7 @@ async function _rapierWritePrintPdf({root, css, fontCss = '', canonical, bom = f
 			glyphs.add(character);
 			if (glyphs.size > 65000) refuse('pdf_text_glyph_limit');
 		}
-		const font = _rapierPrintWillFont(text);
+		const font = _rapierPrintWillFont(text, 500);
 		strip.style.width = count * bodyWidth + 'px';
 		strip.style.transform = 'none';
 		// One styled film is reused for every page window. Batches stay inside the capture edge