rapier-markdown-kit 1.1.101 → 1.1.104

package/dist/layout/paragraph-fit.mjs

@@ -0,0 +1,191 @@
+// SPDX-License-Identifier: MIT
+// Original paragraph-wide optimization over immutable Pretext geometry. Four spacing
+// classes and the discretionary run length are the actual transition policy, not
+// buckets approximating a continuous history. The numerical solver requests exact
+// missing edges; the preparation scope observes them before declaring a plan current.
+// Normal spaces retain 60–180% of their natural advance. At most two consecutive
+// discretionary endings are allowed, and the final line starts whole.
+export function createParagraphFitter() {
+  const indexes = new WeakMap();
+  function prepare(input) {
+    if (!input?.segments || typeof input.text !== 'string') return null;
+    const segments = input.segments.map(segment => {
+      const prefix = [0], gaps = [0], minimum = [0];
+      const points = [{word: 0, cut: null, cutIndex: -1, end: segment.start, next: segment.start, kind: 'start'}];
+      segment.words.forEach((word, index) => {
+        prefix.push(prefix.at(-1) + word.width + (word.gap?.width || 0));
+        gaps.push(gaps.at(-1) + (word.gap?.width || 0));
+        // Conservative bound for interior whole words; no substring-width subtraction.
+        minimum.push(minimum.at(-1) + Math.max(0, word.width - word.endTrim) + Math.max(0, (word.gap?.width || 0) * .6));
+        word.breaks.forEach((cut, cutIndex) => points.push({word: index, cut, cutIndex, end: cut.offset, next: cut.offset, kind: cut.kind}));
+        points.push({word: index + 1, cut: null, cutIndex: -1, end: word.end, next: word.gap?.end ?? word.end,
+          kind: index === segment.words.length - 1 ? 'end' : 'space'});
+      });
+      if (segment.words.length) points[0].end = points[0].next = segment.words[0].start;
+      return {...segment, prefix, gaps, minimum, points};
+    });
+    // Numeric indexes are private and never written after this point. Their opaque
+    // handle keeps hot numeric arrays out of public custody without freezing them
+    // into a different element representation on each engine.
+    const handle = Object.freeze({});
+    indexes.set(handle, {text: input.text, segments});
+    return handle;
+  }
+
+  function* solveSteps(handle, width, {indent = 0, left = 0, right = 0} = {}, known) {
+    const prepared = indexes.get(handle);
+    if (!prepared || ![width, indent, left, right].every(Number.isFinite) || width <= 0) return null;
+    const lines = []; let work = 0, visited = 0, totalCost = 0;
+    for (let segmentIndex = 0; segmentIndex < prepared.segments.length; segmentIndex++) {
+      const {words, points, prefix, gaps, minimum} = prepared.segments[segmentIndex];
+      if (!words.length) continue;
+      const ceiling = width + Math.max(0, left) + Math.max(0, right) + Math.max(0, -indent);
+      const lastIndex = points.length - 1;
+      let smallest = Infinity;
+      for (let index = 0; index < words.length - 1; index++) smallest = Math.min(smallest, words[index].gap?.width || 0);
+      let natural = prefix[words.length] - prefix[0];
+      natural -= (words.at(-1).gap?.width || 0) + words.at(-1).endTrim;
+      natural += words[0].startExtra;
+      const opening = Math.min(Math.max(0, left), words[0].opening);
+      const closing = Math.min(Math.max(0, right), words.at(-1).closing);
+      const target = width - (segmentIndex === 0 ? indent : 0) + opening + closing;
+      const count = words.length - 1;
+      const delta = !count ? 0 : Math.max(-smallest * .4, Math.min(0, (target - natural) / count));
+      const overflow = natural + delta * count - target;
+      const cost = 1 + 100 * Math.max(0, overflow / target) ** 2;
+      // Every edge costs at least one and every transition penalty is nonnegative.
+      // This is the original start-to-final arithmetic, so a valid single edge below
+      // two is the exact global optimum. Keep legal cuts for the overflow exception.
+      if (Number.isFinite(natural) && target > 0 && cost < 2 && minimum[words.length - 1] - minimum[Math.min(words.length - 1, 1)] <= ceiling + .02 &&
+          !(overflow > .02 && (count || words.at(-1).breaks.length))) {
+        lines.push({start: points[0].next, end: points[lastIndex].end, next: points[lastIndex].next, kind: 'end', glyph: '',
+          wordSpacing: delta, opening, closing, firstWord: 0, lastWord: words.length - 1, segment: segmentIndex});
+        totalCost += cost; work++; continue;
+      }
+
+      // A point's predecessors are final before that point is visited. Store its
+      // winning cost and backpointer directly; later points cannot observe an old
+      // replaced state. Build source line records only for the final chosen path.
+      const costs = new Float64Array(points.length * 12);
+      const previous = new Float64Array(costs.length), spacing = new Float64Array(costs.length);
+      const prefixes = [], suffixes = [], reachable = new Uint16Array(points.length);
+      reachable[0] = 1 << 3;
+      // The final line rejects a discretionary start. In its last word, automatic
+      // points cannot lead to any later cut either. Authored soft points need a later
+      // ordinary cut to reset that state. Retain breaks.length for overflow policy.
+      let lastPlain = lastIndex - 1;
+      while (lastPlain > 0 && (points[lastPlain].kind === 'soft' || points[lastPlain].kind === 'auto')) lastPlain--;
+      for (let endIndex = 1; endIndex < points.length; endIndex++) {
+        const end = points[endIndex], final = end.kind === 'end', lastWord = end.cut ? end.word : end.word - 1;
+        const discretionary = end.kind === 'soft' || end.kind === 'auto';
+        if (end.cut && end.word === words.length - 1 && (end.kind === 'auto' || endIndex > lastPlain)) continue;
+        let smallest = Infinity, minWord = lastWord;
+        for (let startIndex = endIndex - 1; startIndex >= 0; startIndex--) {
+          if (++visited % 1024 === 0) yield null;
+          const start = points[startIndex];
+          if (start.word > lastWord) continue;
+          if (minimum[lastWord] - minimum[Math.min(lastWord, start.word + 1)] > ceiling + .02) break;
+          while (minWord > start.word) smallest = Math.min(smallest, words[--minWord].gap?.width || 0);
+          if (final && (start.kind === 'soft' || start.kind === 'auto')) continue;
+          if (start.cut && end.cut && start.word === end.word && (start.kind === 'auto' || end.kind === 'auto')) continue;
+          // Metric work is useful only if a prior state can actually reach this edge.
+          const available = reachable[startIndex] & (discretionary ? 0x6db : 0xfff);
+          if (!available) continue;
+          let natural;
+          if (start.cut && end.cut && start.word === end.word) {
+            natural = yield {segment: segmentIndex, word: start.word, from: start.cutIndex, to: end.cutIndex};
+          } else {
+            natural = prefix[end.word] - prefix[start.word];
+            if (end.cut) {
+              if (prefixes[endIndex] === undefined) {
+                const query = {segment: segmentIndex, word: end.word, from: -1, to: end.cutIndex};
+                prefixes[endIndex] = known?.(query);
+                if (prefixes[endIndex] === undefined) prefixes[endIndex] = yield query;
+              }
+              natural += prefixes[endIndex];
+            } else natural -= (words[lastWord].gap?.width || 0) + words[lastWord].endTrim;
+            if (start.cut) {
+              if (suffixes[startIndex] === undefined) {
+                const query = {segment: segmentIndex, word: start.word, from: start.cutIndex, to: -1};
+                suffixes[startIndex] = known?.(query);
+                if (suffixes[startIndex] === undefined) suffixes[startIndex] = yield query;
+              }
+              natural -= words[start.word].width - suffixes[startIndex];
+            } else natural += words[start.word].startExtra;
+          }
+          if (!Number.isFinite(natural)) continue;
+          const count = lastWord - start.word, gapWidth = gaps[lastWord] - gaps[start.word];
+          const opening = start.cut ? 0 : Math.min(Math.max(0, left), words[start.word].opening);
+          const closing = end.cut ? 0 : Math.min(Math.max(0, right), words[lastWord].closing);
+          const target = width - (segmentIndex === 0 && startIndex === 0 ? indent : 0) + opening + closing;
+          if (target <= 0) continue;
+          const remaining = target - natural;
+          const delta = !count ? 0 : Math.max(-smallest * .4, Math.min(final ? 0 : smallest * .8, remaining / count));
+          const overflow = natural + delta * count - target;
+          // A truly unbreakable word/atom can stand alone at its natural width. Never
+          // fabricate an emergency source cut or eject the surrounding paragraph.
+          if (overflow > .02 && (count || start.cut || end.cut || words[lastWord].breaks.length)) continue;
+          const residual = Math.max(0, remaining - delta * count);
+          const ratio = gapWidth > 0 ? delta * count / gapWidth : 0;
+          const fitness = final ? 1 : ratio < -.075 ? 0 : ratio <= .2 ? 1 : ratio <= .5 ? 2 : 3;
+          let local = 1 + 100 * Math.max(0, overflow / target) ** 2;
+          if (final && startIndex) local += 100 * Math.max(0, .45 - natural / target) ** 2 + (count === 0 ? 25 : 0);
+          else if (!final) local += (ratio < 0 ? 100 : 12.5) * ratio ** 2 + 2400 * (residual / target) ** 2;
+          const priorDiscretionary = start.kind === 'soft' || start.kind === 'auto';
+          if (discretionary) local += 12 + (priorDiscretionary ? 12 : 0);
+          if (final && priorDiscretionary) continue;
+          // The mask visits exactly the occupied slots, in the original ascending
+          // slot order, retaining both the objective and its deterministic ties.
+          for (let active = available; active; active &= active - 1) {
+            const slot = 31 - Math.clz32(active & -active), priorIndex = startIndex * 12 + slot;
+            const hyphens = discretionary ? slot % 3 + 1 : 0;
+            if (hyphens > 2) continue;
+            work++;
+            const cost = costs[priorIndex] + local + (!final && startIndex ? .6 * (fitness - Math.floor(slot / 3)) ** 2 : 0);
+            const stateIndex = fitness * 3 + hyphens;
+            const index = endIndex * 12 + stateIndex;
+            if (reachable[endIndex] & 1 << stateIndex && costs[index] <= cost) continue;
+            costs[index] = cost; previous[index] = priorIndex; spacing[index] = delta;
+            reachable[endIndex] |= 1 << stateIndex;
+          }
+        }
+      }
+      let best = -1;
+      for (let slot = 0; slot < 12; slot++) if (reachable[lastIndex] & 1 << slot) {
+        const index = lastIndex * 12 + slot;
+        if (best < 0 || costs[index] < costs[best]) best = index;
+      }
+      if (best < 0) return null;
+      totalCost += costs[best];
+      const chosen = [];
+      for (let endIndex = lastIndex; endIndex;) {
+        const priorIndex = previous[best], startIndex = Math.floor(priorIndex / 12);
+        const start = points[startIndex], end = points[endIndex], lastWord = end.cut ? end.word : end.word - 1;
+        chosen.push({start: start.next, end: end.end, next: end.next, kind: end.kind, glyph: end.cut?.glyph || '',
+          wordSpacing: spacing[best], opening: start.cut ? 0 : Math.min(Math.max(0, left), words[start.word].opening),
+          closing: end.cut ? 0 : Math.min(Math.max(0, right), words[lastWord].closing),
+          firstWord: start.word, lastWord, segment: segmentIndex});
+        best = priorIndex; endIndex = startIndex;
+      }
+      lines.push(...chosen.reverse());
+    }
+    return {lines, work, cost: totalCost, approximate: false};
+  }
+
+  function solve(prepared, width, options, observe) {
+    const work = solveSteps(prepared, width, options);
+    try {
+      let step = work.next();
+      while (!step.done) {
+        if (step.value && !observe) return null;
+        step = work.next(step.value ? observe(step.value) : undefined);
+      }
+      return step.value;
+    } finally { work.return(); }
+  }
+  return {prepare, solve, solveSteps};
+}
+
+const fitter = createParagraphFitter();
+export const prepareParagraph = fitter.prepare;
+export const fitParagraph = fitter.solve;

package/dist/layout/preparation.mjs

@@ -0,0 +1,373 @@
+// SPDX-License-Identifier: MIT
+import {clearCache, setLocale} from '../agent/vendor/pretext/layout.js';
+import {prepareRichInline} from '../agent/vendor/pretext/rich-inline.js';
+import {prepareParagraphCandidateSteps, createParagraphObserver} from './prepared-paragraph.mjs';
+
+// One metric authority for this loaded vendor graph. Document/face/paragraph identities are
+// weak; a width is never part of source preparation. A separate captured fitting operation
+// completes its requested interval facts before its immutable plan is ready. A font-string
+// cache must be retired when the actual face changes, even if a replacement kept its family
+// and all its CSS descriptors.
+const documents = new WeakMap(), faces = new WeakMap(), paragraphs = new WeakMap();
+let faceId = 0, generation = 0, language;
+const descriptors = ['family', 'style', 'weight', 'stretch', 'unicodeRange', 'status',
+  'featureSettings', 'variationSettings', 'display', 'sizeAdjust', 'ascentOverride',
+  'descentOverride', 'lineGapOverride'];
+const finite = value => typeof value === 'number' && Number.isFinite(value);
+
+function clearMetrics() { clearCache(); return ++generation; }
+
+export function captureFontAuthority(document = globalThis.document) {
+  if (!document || typeof document !== 'object') return generation;
+  const previous = documents.get(document), declared = previous?.declared || new Set();
+  const entries = [];
+  try {
+    for (const face of document.fonts || []) {
+      if (!faces.has(face)) faces.set(face, ++faceId);
+      declared.add(familyName(face.family));
+      entries.push([faces.get(face), ...descriptors.map(name => String(face[name] ?? ''))]);
+    }
+  } catch (_) { entries.push(['unavailable']); }
+  const ratio = document.defaultView?.devicePixelRatio ?? 1;
+  const signature = JSON.stringify([document.fonts?.status ?? '', ratio, entries]);
+  if (previous?.signature !== signature) {
+    documents.set(document, {signature, declared});
+    clearMetrics();
+  }
+  return generation;
+}
+
+// Several hosts can observe the same FontFaceSet event. Its observed identity retires metrics
+// once. A non-DOM host has no observable face set and explicitly announces its own replacement.
+export function invalidateRichMetrics(document = globalThis.document) {
+  return document ? captureFontAuthority(document) : clearMetrics();
+}
+
+function familyName(value) {
+  const name = String(value).trim();
+  return (/^(["']).*\1$/s.test(name) ? name.slice(1, -1) : name)
+    .replace(/\\([\da-f]{1,6})[ \t\r\n\f]?|\\([^\r\n\f])/gi,
+      (_, hex, char) => hex ? String.fromCodePoint(Math.min(0x10ffff, parseInt(hex, 16)) || 0xfffd) : char)
+    .toLowerCase();
+}
+
+// A CSS family with no declared FontFace can intentionally resolve through its fallback list.
+// For declared custom faces, a FontFaceSet.check() alone is insufficient: it can report true
+// after a failed face has fallen back. Keep that failure and same-name replacement observable.
+export function fontReady(document, font, text = ' ') {
+  if (!document) return true;
+  if (!document.fonts || document.fonts.status === 'loading') return false;
+  try {
+    if (document.fonts.check(font, text || ' ') !== true) return false;
+    const family = /(?:\d*\.)?\d+px(?:\s*\/\s*[^\s]+)?\s+(.+)$/.exec(font)?.[1];
+    if (!family) return false;
+    const names = new Set((family.match(/"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|[^,]+/g) || []).map(familyName));
+    const present = new Set();
+    for (const face of document.fonts) {
+      const family = familyName(face.family); present.add(family);
+      if (names.has(family) && face.status !== 'loaded') return false;
+    }
+    // A deleted declared face is unavailable even when check() now succeeds with a fallback.
+    // Its expected name belongs to this document lifetime, not an individual projection root.
+    for (const family of documents.get(document)?.declared || []) if (names.has(family) && !present.has(family)) return false;
+    return true;
+  } catch (_) { return false; }
+}
+
+function validLanguage(value) {
+  if (typeof value !== 'string') return false;
+  if (value === '') return true;
+  try { return Intl.getCanonicalLocales(value).length === 1; } catch (_) { return false; }
+}
+
+function supportedDocument(document) {
+  if (!document) return true; // A declared non-DOM Canvas host owns its chosen fonts/profile.
+  const agent = document.defaultView?.navigator?.userAgent ?? globalThis.navigator?.userAgent ?? '';
+  return /(?:^|\s)(?:HeadlessChrome|Chrome|Chromium)\/\d+/.test(agent) && !/\bCriOS\//.test(agent);
+}
+
+// The pinned API accepts font shorthand, letter spacing, content language and two break modes.
+// Canvas supplies its default shaping. It has no public feature/variation/kerning controls or
+// paragraph-direction input; these styles retain the native selectable paragraph instead.
+// `nowrap` here is for an atomic item; the paragraph itself still needs normal or pre-wrap.
+// The app's inherited `pretty` is its existing greedy picture-flow policy, not an implementation
+// of native pretty optimization. A host's explicit request for that optimization stays native.
+export function supportsRichStyle(style, contentLanguage = '') {
+  if (!style || !validLanguage(contentLanguage)) return false;
+  const oneOf = (key, values) => style[key] == null || style[key] === '' || values.includes(style[key]);
+  if (!oneOf('writingMode', ['horizontal-tb']) || !oneOf('direction', ['ltr']) ||
+      !oneOf('unicodeBidi', ['normal', 'isolate']) || !oneOf('textTransform', ['none']) ||
+      !oneOf('fontKerning', ['auto']) || !oneOf('fontOpticalSizing', ['auto']) ||
+      !oneOf('fontStretch', ['normal', '100%']) || !oneOf('fontSizeAdjust', ['none']) ||
+      !oneOf('textRendering', ['auto']) || !oneOf('verticalAlign', ['baseline']) ||
+      !oneOf('whiteSpace', ['normal', 'pre-wrap', 'nowrap']) || !oneOf('wordBreak', ['normal', 'keep-all']) ||
+      !oneOf('hyphens', ['manual']) || !oneOf('lineBreak', ['auto']) || !oneOf('hangingPunctuation', ['none']) ||
+      !oneOf('tabSize', ['8']) || !oneOf('textWrapStyle', ['auto', 'pretty'])) return false;
+  for (const name of ['fontFeatureSettings', 'fontVariationSettings', 'fontVariant', 'fontVariantLigatures',
+    'fontVariantCaps', 'fontVariantNumeric', 'fontVariantEastAsian', 'fontVariantPosition', 'fontVariantAlternates']) {
+    if (!oneOf(name, ['normal'])) return false;
+  }
+  if (!oneOf('fontSynthesis', ['auto', 'weight style small-caps']) ||
+      !oneOf('fontSynthesisWeight', ['auto']) || !oneOf('fontSynthesisStyle', ['auto']) ||
+      !oneOf('fontSynthesisSmallCaps', ['auto'])) return false;
+  const spacing = value => value == null || value === '' || value === 'normal' || /^[-+]?(?:\d*\.)?\d+px$/.test(value);
+  if (!spacing(style.letterSpacing) || !spacing(style.wordSpacing)) return false;
+  return !(parseFloat(style.wordSpacing) || 0);
+}
+
+function optionsFor(options, document) {
+  const value = {whiteSpace: options?.whiteSpace ?? 'normal', wordBreak: options?.wordBreak ?? 'normal',
+    language: options?.language ?? document?.documentElement?.lang ?? '', policy: options?.policy ?? 'wrap',
+    hanging: options?.hanging === true, paragraphBreaks: options?.paragraphBreaks ? Object.freeze([...options.paragraphBreaks]) : null};
+  if (!['wrap', 'paragraph'].includes(value.policy)) return null;
+  return (value.whiteSpace === 'normal' || value.whiteSpace === 'pre-wrap') &&
+    (value.wordBreak === 'normal' || value.wordBreak === 'keep-all') && validLanguage(value.language) ? value : null;
+}
+
+function copyItems(items) {
+  if (!Array.isArray(items)) return null;
+  const result = [];
+  for (const item of items) {
+    if (!item || typeof item !== 'object') return null;
+    if (item.text === undefined) {
+      if (!finite(item.width) || item.width < 0) return null;
+      result.push(Object.freeze({width: item.width}));
+    } else {
+      if (typeof item.text !== 'string' || typeof item.font !== 'string' || !item.font.trim() ||
+          !finite(item.letterSpacing ?? 0) || !finite(item.extraWidth ?? 0) ||
+          item.break != null && item.break !== 'normal' && item.break !== 'never') return null;
+      result.push(Object.freeze({text: item.text, font: item.font, letterSpacing: item.letterSpacing ?? 0,
+        extraWidth: item.extraWidth ?? 0, break: item.break ?? 'normal', hyphenate: item.hyphenate !== false}));
+    }
+  }
+  return Object.freeze(result);
+}
+
+function sameItems(a, b) {
+  return a.length === b.length && a.every((item, index) => {
+    const other = b[index];
+    return item.text === other.text && item.font === other.font && item.width === other.width &&
+      item.letterSpacing === other.letterSpacing && item.extraWidth === other.extraWidth && item.break === other.break && item.hyphenate === other.hyphenate;
+  });
+}
+
+function finish(work) {
+  let step;
+  do { step = work.next(); } while (!step.done);
+  return step.value;
+}
+
+function* prepareSteps(items, options, document) {
+  // FontFaceSet.check depends on the font and the used character set. Check each shaped
+  // font once across its runs; the scope is the sole font-readiness authority.
+  const usedFonts = new Map();
+  for (const item of items) if (item.text !== undefined) usedFonts.set(item.font, (usedFonts.get(item.font) || '') + item.text);
+  for (const [font, text] of usedFonts) {
+    if (!fontReady(document, font, text)) return null;
+    yield;
+  }
+  try {
+    // Locale selects content language for this preparation only. Existing handles already own
+    // their measured language; switching paragraphs must not invalidate those handles.
+    if (language !== options.language) { setLocale(options.language); language = options.language; }
+    if (options.paragraphBreaks && (options.paragraphBreaks[0] !== 0 || options.paragraphBreaks.at(-1) !== items.length ||
+        options.paragraphBreaks.some((value, index, all) => !Number.isInteger(value) || value < 0 || value > items.length || index > 0 && value < all[index - 1]))) return null;
+    let handle;
+    if (options.policy === 'paragraph') {
+      const work = prepareParagraphCandidateSteps(items, {...options, document});
+      try {
+        for (;;) {
+          // Another consumer may have selected a different content language between
+          // frames. Every resumed step uses this request's original language again.
+          if (language !== options.language) { setLocale(options.language); language = options.language; }
+          const step = work.next();
+          if (step.done) { handle = step.value; break; }
+          yield;
+        }
+      } finally { work.return(); }
+    } else handle = prepareRichInline(items, {whiteSpace: options.whiteSpace, wordBreak: options.wordBreak});
+    if (!handle) return null;
+    paragraphs.set(handle, {items, options, generation});
+    return handle;
+  } catch (_) { return null; }
+}
+
+export function prepareRichParagraph(items, options = {}) {
+  const document = globalThis.document;
+  if (!supportedDocument(document)) return null;
+  captureFontAuthority(document);
+  const source = copyItems(items), settings = optionsFor(options, document);
+  return source && settings ? finish(prepareSteps(source, settings, document)) : null;
+}
+
+// This metadata is Rapier's original input snapshot, never a reconstruction of opaque vendor
+// fields. It exists only while its handle does and is used for exact source containment.
+export function paragraphItems(handle) { return paragraphs.get(handle)?.items ?? null; }
+
+export function createPreparationScope(document = globalThis.document) {
+  let owners = new WeakMap(), tickets = new WeakMap();
+  const handles = new WeakMap();
+  const current = handle => {
+    if (!supportedDocument(document)) return false;
+    captureFontAuthority(document);
+    const owner = handles.get(handle);
+    return !!owner && owners.get(owner) === handle && paragraphs.get(handle)?.generation === generation;
+  };
+  function* steps(owner, items, options = {}) {
+      if (!supportedDocument(document) || !owner || typeof owner !== 'object' && typeof owner !== 'function') return null;
+      captureFontAuthority(document);
+      tickets.delete(owner);
+      const source = copyItems(items), settings = optionsFor(options, document);
+      if (!source || !settings) { owners.delete(owner); return null; }
+      const previous = owners.get(owner), prior = paragraphs.get(previous);
+      if (prior?.generation === generation && prior.options.whiteSpace === settings.whiteSpace &&
+          prior.options.wordBreak === settings.wordBreak && prior.options.language === settings.language &&
+          prior.options.policy === settings.policy && prior.options.hanging === settings.hanging &&
+          JSON.stringify(prior.options.paragraphBreaks) === JSON.stringify(settings.paragraphBreaks) &&
+          sameItems(prior.items, source)) return previous;
+      owners.delete(owner);
+      const ticket = {}, birth = generation, work = prepareSteps(source, settings, document);
+      tickets.set(owner, ticket);
+      try {
+        for (;;) {
+          // A forgotten/replaced source request or changed face cannot publish a result
+          // after suspension. Until completion, no ready handle is installed for its owner.
+          if (tickets.get(owner) !== ticket || captureFontAuthority(document) !== birth) return null;
+          const step = work.next();
+          if (step.done) {
+            if (captureFontAuthority(document) !== birth) return null;
+            const handle = step.value;
+            if (handle) { owners.set(owner, handle); handles.set(handle, owner); }
+            return handle;
+          }
+          yield;
+        }
+      } finally { work.return(); if (tickets.get(owner) === ticket) tickets.delete(owner); }
+  }
+  function* fitSteps(owner, handle, createWork) {
+    let ticket = null, work = null, observe = null, facts = null;
+    let slotFor = null, readKnown = null, staged = false, active = false;
+    try {
+      if (!supportedDocument(document) || !owner || typeof owner !== 'object' && typeof owner !== 'function') return null;
+      // Preparation, fitting and forgetting share one outstanding request for this owner.
+      // Replacing a fit keeps its immutable source geometry, but retires the old plan work.
+      tickets.delete(owner);
+      const birth = captureFontAuthority(document), source = paragraphs.get(handle);
+      if (owners.get(owner) !== handle || !source || source.generation !== birth ||
+          source.options.policy !== 'paragraph' || typeof createWork !== 'function' ||
+          !Number.isInteger(handle.cutCount) || handle.cutCount < 0) return null;
+      ticket = {};
+      tickets.set(owner, ticket);
+      facts = source.edges;
+      active = true;
+      const currentFit = () => tickets.get(owner) === ticket && owners.get(owner) === handle &&
+        source.generation === birth && captureFontAuthority(document) === birth;
+      const selectLanguage = () => {
+        if (language !== source.options.language) { setLocale(source.options.language); language = source.options.language; }
+      };
+      slotFor = (segment, word, from, to) => {
+        if (!Number.isInteger(segment) || segment < 0 || !Number.isInteger(word) || word < 0 ||
+            !Number.isInteger(from) || from < -1 || !Number.isInteger(to) || to < -1) return -2;
+        const cuts = handle.segments[segment]?.words[word]?.breaks;
+        if (!cuts || from >= cuts.length || to >= cuts.length || from < 0 && to < 0 || from >= 0 && to >= 0 && from >= to) return -2;
+        if (from >= 0 && to >= 0) return -1; // Exact interior facts remain transient.
+        const cut = cuts[from < 0 ? to : from];
+        if (!Number.isInteger(cut.slot) || cut.slot < 0 || cut.slot >= handle.cutCount) return -2;
+        // Slots come only from the captured geometry's final legal cuts. A request
+        // can select coordinates, but cannot supply a cache key or a metric buffer.
+        return cut.slot * 2 + (from < 0 ? 0 : 1);
+      };
+      readKnown = request => {
+        // This callback belongs only to active numerical work. A warm edge reads an
+        // exact scalar without a generator crossing, FontFaceSet scan or observation.
+        // Current source/font authority is checked at each actual resume and finish.
+        if (!active || tickets.get(owner) !== ticket || generation !== birth) return undefined;
+        const slot = slotFor(request?.segment, request?.word, request?.from, request?.to);
+        if (slot < 0 || tickets.get(owner) !== ticket || generation !== birth) return undefined;
+        const value = facts?.[slot];
+        return Number.isNaN(value) ? undefined : value;
+      };
+      selectLanguage();
+      work = createWork(readKnown);
+      createWork = null;
+      if (typeof work?.next !== 'function') return null;
+      let answer, requests = 0;
+      for (;;) {
+        if (!currentFit()) return null;
+        selectLanguage();
+        const step = work.next(answer);
+        answer = undefined;
+        if (step.done) {
+          // A host measurement or another synchronous caller may replace this owner too.
+          if (!currentFit()) return null;
+          const plan = step.value;
+          if (!plan || !Array.isArray(plan.lines)) return null;
+          for (const line of plan.lines) Object.freeze(line);
+          Object.freeze(plan.lines);
+          Object.freeze(plan);
+          if (!currentFit()) return null;
+          // The private buffer holds at most two exact numbers per legal cut. It
+          // never escapes and is never written after publication. A later fit must
+          // copy it before staging a miss; cancellation cannot poison this snapshot.
+          if (staged) source.edges = facts;
+          return plan;
+        }
+        if (step.value === null) { yield; continue; }
+        const request = step.value;
+        const segment = request?.segment, word = request?.word, from = request?.from, to = request?.to;
+        const slot = slotFor(segment, word, from, to);
+        if (slot === -2) return null;
+        if (slot >= 0) {
+          answer = facts?.[slot];
+          if (answer !== undefined && !Number.isNaN(answer)) continue;
+        }
+        selectLanguage();
+        // No observer exists for a plan proved from whole-word facts. Its temporary
+        // vendor metric objects are owned only by this operation, never by the handle.
+        observe ??= createParagraphObserver(source.items, handle, source.options.language);
+        answer = observe({segment, word, from, to});
+        if (!finite(answer) || answer < 0) return null;
+        if (slot >= 0) {
+          if (!staged) {
+            facts = facts ? facts.slice() : new Float64Array(handle.cutCount * 2).fill(NaN);
+            staged = true;
+          }
+          facts[slot] = answer;
+        }
+        if (++requests % 8 === 0) yield;
+      }
+    } catch (_) { return null; }
+    finally {
+      active = false;
+      observe = null;
+      facts = null;
+      slotFor = null;
+      readKnown = null;
+      createWork = null;
+      try { work?.return?.(); } catch (_) {}
+      work = null;
+      if (ticket && tickets.get(owner) === ticket) tickets.delete(owner);
+    }
+  }
+  return {
+    prepare: (owner, items, options) => finish(steps(owner, items, options)),
+    prepareSteps: steps,
+    fit: (owner, handle, createWork) => finish(fitSteps(owner, handle, createWork)),
+    fitSteps,
+    current,
+    invalidateFonts: () => invalidateRichMetrics(document),
+    forget: owner => { owners.delete(owner); tickets.delete(owner); },
+    // The existing document/style owner calls this when replacing or retiring its content,
+    // not for width reflow. Upstream caches outlive handles, so dropping a WeakMap is not enough.
+    retire({documentChanged = false} = {}) {
+      owners = new WeakMap();
+      tickets = new WeakMap();
+      // Disposing a projection must not erase a still-live peer's missing custom-family
+      // authority. Only the host's whole-document identity transition resets that history.
+      if (documentChanged && document) documents.delete(document);
+      const before = generation;
+      captureFontAuthority(document);
+      if (generation === before) clearMetrics();
+    },
+  };
+}