('.clause').forEach((card) => {
+ const label = (card.querySelector('.clause-label')?.textContent ?? '').toLowerCase();
+ card.style.display = !q || label.includes(q) ? '' : 'none';
+ });
+ });
+
+ renderClausesPanel();
+}
+
+/**
+ * Values tab: fill the fields that are in the document. Editing a value
+ * debounces ~250ms and fans it to every occurrence of that field's tag
+ * (`selectByTag` + per-occurrence `text.setValue`). Locate/Focus jump to the
+ * first occurrence.
+ */
+function renderValuesPanel(): void {
+ valuesPanelEl.innerHTML = '';
for (const field of FIELDS) {
// A wrapper (not ): a may not contain interactive
// content, so the Locate must be a sibling of the input, with a
@@ -413,9 +874,9 @@ function renderFieldsPanel(): void {
Focus
- ('.locate')?.addEventListener('click', () => {
locateByTag(fieldTag(field.key));
});
@@ -437,97 +898,82 @@ function renderFieldsPanel(): void {
}
}
+/**
+ * Render the clause cards: one card per clause, styled like the in-document
+ * block clause (blue left rail). Like the smart-tag chips, a card is draggable
+ * into the document or click-to-insert at the cursor (insertClause snaps to a
+ * block boundary). A card highlights when its clause is clicked in the document.
+ */
+/** Every control in the document for a given clause (used internally for counts). */
+function clauseControls(clauseId: ClauseId): ContentControlInfo[] {
+ const doc = state.editor?.doc;
+ if (!doc) return [];
+ return doc.contentControls.list({}).items.filter((c) => {
+ const t = parseTag(c.properties?.tag);
+ return t?.kind === 'reusableSection' && t.sectionId === clauseId;
+ });
+}
+
+/** A clause is single-use: it's either in the contract or available to add. */
+function isClauseInDocument(clauseId: ClauseId): boolean {
+ return clauseControls(clauseId).length > 0;
+}
+
+/** Scroll the clause's placement into view and highlight its card. */
+function revealClause(clauseId: ClauseId): void {
+ const ctrl = clauseControls(clauseId)[0];
+ if (!state.ui || !ctrl) return;
+ state.activeClauseId = clauseId;
+ highlightActiveClause();
+ void state.ui.contentControls.scrollIntoView({ id: ctrl.target.nodeId, block: 'center' });
+}
+
+/**
+ * Render the clause library as a single-use inclusion checklist. Each card shows
+ * the clause's category / jurisdiction / version and whether it's "In contract"
+ * or available to "Add clause". A clause is governed and appears once: a card
+ * that's already in the contract can't be inserted again - clicking it reveals
+ * the existing clause instead; an available card inserts (click) or drags in.
+ */
function renderClausesPanel(): void {
- clausesPanelEl.innerHTML = '';
+ const list = clausesListEl;
+ if (!list) return;
+ list.innerHTML = '';
for (const clause of CLAUSE_LIBRARY) {
- const inDoc = state.versions[clause.id] ?? clause.latestVersion;
- const stale = clause.upgrade != null && inDoc !== clause.latestVersion;
- const expanded = stale && state.expandedClause === clause.id;
-
+ const inDoc = isClauseInDocument(clause.id);
const card = document.createElement('article');
- card.className = 'clause' + (stale ? ' stale' : ' current') + (expanded ? ' expanded' : '');
-
- if (stale && clause.upgrade) {
- const upgrade = clause.upgrade;
- const previewHtml = upgrade.preview.map(renderSegment).join('');
- card.innerHTML = `
-
- ${escapeHtml(upgrade.summary)}
- Document ${escapeHtml(inDoc)} \u00b7 Library ${escapeHtml(upgrade.version)}
- ${expanded ? 'Hide' : 'Review'}
- ${
- expanded
- ? `
-
-
Proposed change
-
${previewHtml}
-
Replace with library clause
-
('.clause-review')?.addEventListener('click', () => {
- state.expandedClause = expanded ? null : clause.id;
- renderClausesPanel();
- });
- card.querySelector('.clause-replace')?.addEventListener('click', () => {
- void run(`${clause.label}: replaced with library clause`, async () => {
- await applyClauseVersion(clause.id, upgrade.version, upgrade.body);
- state.expandedClause = null;
- });
- });
- } else {
- card.innerHTML = `
-
- Document ${escapeHtml(inDoc)}
- `;
- }
-
- card.querySelector('.locate')?.addEventListener('click', () => {
- locateByTag(clauseTag(clause.id, inDoc));
- });
- card.querySelector('.focus')?.addEventListener('click', () => {
- focusByTag(clauseTag(clause.id, inDoc));
+ card.className =
+ 'clause ' + (inDoc ? 'is-present' : 'is-available') + (clause.id === state.activeClauseId ? ' is-active' : '');
+ card.dataset.clauseId = clause.id;
+ card.draggable = !inDoc; // single-use: can't drag a clause that's already in
+ card.title = inDoc
+ ? `${clause.label} is in the contract — click to reveal it`
+ : `Drag into the document, or click to add the ${clause.label} clause at the cursor`;
+ card.innerHTML = `
+
+
${escapeHtml(clause.label)}
+ ${inDoc ? 'In contract' : 'Add clause'}
+
+ ${escapeHtml(clause.category)} · ${escapeHtml(clause.jurisdiction)} · ${escapeHtml(clause.version)}
+ `;
+ card.addEventListener('click', () => (isClauseInDocument(clause.id) ? revealClause(clause.id) : insertClauseAtCursor(clause.id)));
+ card.addEventListener('dragstart', (event) => {
+ if (!event.dataTransfer || isClauseInDocument(clause.id)) return;
+ event.dataTransfer.setData(CLAUSE_MIME, clause.id);
+ event.dataTransfer.effectAllowed = 'copy';
});
- clausesPanelEl.appendChild(card);
+ list.appendChild(card);
}
}
function refreshSummary(): void {
- const stale = CLAUSE_LIBRARY.filter(
- (c) => c.upgrade != null && (state.versions[c.id] ?? c.latestVersion) !== c.latestVersion,
- ).length;
- const updateText = stale === 0 ? 'all clauses current' : `${stale} update${stale === 1 ? '' : 's'} available`;
- summaryEl.textContent = `${FIELDS.length} fields \u00b7 ${CLAUSE_LIBRARY.length} clauses \u00b7 ${updateText}`;
+ summaryEl.textContent = `${FIELDS.length} fields \u00b7 ${CLAUSE_LIBRARY.length} clauses`;
}
// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------
-function findClauseControl(clauseId: ClauseId): ContentControlInfo | undefined {
- const doc = getDoc();
- return doc.contentControls.list({}).items.find((ctrl) => {
- const t = parseTag(ctrl.properties?.tag);
- return t?.kind === 'reusableSection' && t.sectionId === clauseId;
- });
-}
-
async function run(status: string, action: () => Promise): Promise {
setBusy(true);
setStatus('Working');
@@ -548,10 +994,18 @@ function getDoc(): DocumentApi {
return state.editor.doc;
}
-function assertMutation(result: MutationResult, message: string, allowNoOp = false): void {
- if (result.success) return;
- if (allowNoOp && result.failure.code === 'NO_OP') return;
- throw new Error(result.failure.message || message);
+/**
+ * Surface a failed mutation instead of swallowing it. Returns whether it
+ * succeeded so callers can branch (e.g. skip the write if the unlock failed).
+ * NO_OP (value already matches) is treated as success. Used on the form-only
+ * write path, where a silent failure would leave a field stale or - worse, on a
+ * failed relock - editable by the user.
+ */
+function reportMutation(result: MutationResult, context: string): boolean {
+ if (result.success || result.failure.code === 'NO_OP') return true;
+ console.error(`[contract-templates] ${context} failed:`, result.failure);
+ setStatus(`${context} failed: ${result.failure.message}`);
+ return false;
}
function setBusy(busy: boolean): void {
@@ -574,13 +1028,6 @@ function escapeHtml(s: string): string {
return s.replace(/[&<>"]/g, (ch) => ({ '&': '&', '<': '<', '>': '>', '"': '"' })[ch]!);
}
-function renderSegment(seg: PreviewSegment): string {
- const text = escapeHtml(seg.text);
- if (seg.kind === 'insert') return `${text} `;
- if (seg.kind === 'delete') return `${text}`;
- return text;
-}
-
function escapeAttr(s: string): string {
return escapeHtml(s).replace(/'/g, ''');
}
@@ -592,16 +1039,21 @@ function escapeAttr(s: string): string {
};
const teardown = () => {
- // Order matters: detach the field chip first (it relies on the UI
- // controller for `getRect`), then destroy the UI controller, then
- // the SuperDoc instance. Each step is best-effort so a late error in
- // one branch doesn't strand the others.
+ // Detach the palette-sync listeners, then destroy the UI controller, then the
+ // SuperDoc instance. Each step is best-effort so a late error in one branch
+ // doesn't strand the others.
+ try {
+ state.smartTagSyncTeardown?.();
+ } catch {
+ /* best-effort teardown */
+ }
+ state.smartTagSyncTeardown = null;
try {
- state.fieldChipTeardown?.();
+ state.dragDropTeardown?.();
} catch {
/* best-effort teardown */
}
- state.fieldChipTeardown = null;
+ state.dragDropTeardown = null;
try {
state.ui?.destroy();
} catch {
diff --git a/demos/contract-templates/src/style.css b/demos/contract-templates/src/style.css
index 9d7213e80b..3348d77676 100644
--- a/demos/contract-templates/src/style.css
+++ b/demos/contract-templates/src/style.css
@@ -34,7 +34,30 @@ button { cursor: pointer; }
.app { display: grid; grid-template-columns: 1fr 360px; height: 100vh; }
.editor-area { display: flex; flex-direction: column; min-width: 0; min-height: 0; }
-.editor-area #editor { flex: 1; overflow: auto; padding: 12px; }
+/* SuperDoc's formatting toolbar, rendered into #superdoc-toolbar. Clip to the
+ editor column so overflowing items can't paint over the sidebar (they collapse
+ into the responsive overflow menu instead; popovers append to ). */
+#superdoc-toolbar {
+ border-bottom: 1px solid var(--demo-border);
+ background: var(--demo-bg);
+ overflow: hidden;
+ min-width: 0;
+}
+/* Center the page horizontally; align to top so multi-page docs scroll. */
+.editor-area #editor {
+ flex: 1;
+ overflow: auto;
+ padding: 12px;
+ display: flex;
+ justify-content: center;
+ align-items: flex-start;
+}
+/* Drop zone: highlight the editor while a field chip is dragged over it. */
+.editor-area #editor.drop-target {
+ outline: 2px dashed var(--demo-accent);
+ outline-offset: -4px;
+ background: var(--demo-accent-soft);
+}
.toolbar {
display: flex;
@@ -136,9 +159,9 @@ input:focus {
}
.btn:disabled { color: var(--demo-text-muted); cursor: not-allowed; opacity: 0.55; }
-/* "Locate" — scroll a control into view (ui.contentControls.scrollIntoView);
- "Focus" — scroll AND place the caret inside it (ui.contentControls.focus). */
-.clause-actions { display: flex; align-items: center; gap: 8px; }
+/* Field rows (Values tab): "Locate" scrolls a control into view
+ (ui.contentControls.scrollIntoView); "Focus" scrolls AND places the caret
+ inside it (ui.contentControls.focus). */
.row-actions { display: flex; align-items: center; gap: 6px; }
.locate,
.focus {
@@ -161,96 +184,71 @@ input:focus {
#fields-panel .btn { width: 100%; margin-top: 12px; }
/* -----------------------------------------------------------------------
- Clauses panel
+ Clause library (Template tab)
+
+ A single-use catalog of governed clauses. Each card echoes the in-document
+ block clause (blue left rail, soft border, faint blue fill) and shows its
+ metadata plus a status: an available clause ("Add clause") drags or clicks in,
+ while one already in the contract ("In contract") is a quieter card that
+ clicks to reveal the existing section. The clauses themselves are locked blocks.
----------------------------------------------------------------------- */
+.clauses-section { margin-top: 16px; }
+
.clause {
- border: 1px solid var(--demo-border);
- border-radius: var(--sd-radius-100, 6px);
- padding: 10px 12px;
- margin-bottom: 8px;
- background: var(--demo-bg);
-}
-.clause.current {
- background: transparent;
- border-color: var(--demo-border);
-}
-.clause.stale {
- background: var(--demo-stale-soft);
- border-color: var(--demo-accent);
-}
-.clause-header {
+ border: 1px solid var(--tag-block-border);
+ border-left: 4px solid var(--tag-color);
+ border-radius: var(--tag-radius);
+ background-color: var(--tag-block-bg);
+ padding: 7px 10px;
+ margin-bottom: 6px;
+}
+.clause:hover { background-color: var(--tag-block-bg-hover); }
+.clause.is-active { box-shadow: 0 0 0 2px var(--tag-color); }
+/* Available clauses drag/click to add; clauses already in the contract are a
+ quieter card you click to reveal the existing section. */
+.clause.is-available { cursor: grab; }
+.clause.is-available:active { cursor: grabbing; }
+.clause.is-present { cursor: pointer; }
+.clause.is-present { background-color: var(--tag-block-bg); }
+.clause-head {
display: flex;
align-items: baseline;
justify-content: space-between;
gap: 8px;
- margin-bottom: 4px;
}
.clause-label {
margin: 0;
+ flex: 1;
+ min-width: 0;
font-size: var(--sd-font-size-300, 13px);
font-weight: 600;
color: var(--demo-text);
+ overflow: hidden;
+ text-overflow: ellipsis;
+ white-space: nowrap;
}
.clause-status {
- font-size: var(--sd-font-size-200, 11px);
+ flex-shrink: 0;
+ font-size: var(--sd-font-size-100, 10px);
font-weight: 600;
text-transform: uppercase;
- letter-spacing: 0.05em;
- color: var(--demo-accent);
-}
-.clause-status.muted { color: var(--demo-text-muted); }
-.clause-summary {
- margin: 0 0 6px;
- font-size: var(--sd-font-size-300, 13px);
- color: var(--demo-text);
- line-height: 1.4;
-}
-.clause-meta {
- margin: 0 0 8px;
- font-size: var(--sd-font-size-200, 12px);
- color: var(--demo-text-muted);
-}
-.clause .btn { width: 100%; }
-.clause-review-panel {
- margin-top: 10px;
- padding-top: 10px;
- border-top: 1px solid var(--demo-accent);
- display: flex;
- flex-direction: column;
- gap: 10px;
+ letter-spacing: 0.04em;
+ padding: 1px 6px;
+ border-radius: 999px;
}
-.review-label {
- font-size: var(--sd-font-size-200, 11px);
- font-weight: 600;
- text-transform: uppercase;
- letter-spacing: 0.05em;
+.clause.is-present .clause-status {
color: var(--demo-text-muted);
+ background: color-mix(in srgb, var(--demo-text-muted) 14%, transparent);
}
-.clause-preview {
- margin: 0;
- padding: 10px 12px;
- background: var(--demo-bg);
- border: 1px solid var(--demo-border);
- border-radius: var(--sd-radius-50, 4px);
- font-size: var(--sd-font-size-300, 13px);
- line-height: 1.5;
- color: var(--demo-text);
-}
-.clause-preview ins {
- background: color-mix(in srgb, #15803d 18%, transparent);
- color: var(--demo-text);
- text-decoration: none;
- padding: 0 2px;
- border-radius: 2px;
+.clause.is-available .clause-status {
+ color: var(--tag-fg);
+ background: var(--tag-bg);
}
-.clause-preview del {
+.clause-meta {
+ margin: 2px 0 0;
+ font-size: var(--sd-font-size-100, 11px);
color: var(--demo-text-muted);
- text-decoration: line-through;
- text-decoration-color: #d92e2e;
- background: color-mix(in srgb, #d92e2e 12%, transparent);
- padding: 0 2px;
- border-radius: 2px;
}
.status {
@@ -265,60 +263,105 @@ input:focus {
/* -----------------------------------------------------------------------
Host-owned SDT styling.
This demo turns off SuperDoc's built-in content-control chrome
- (`modules.contentControls.chrome: 'none'` in main.ts) and paints its
- own. The painter adds `.superdoc-cc-chrome-none` to the mount and resets
- border/padding/radius/background on the SDT wrappers; scoping under that
- class keeps these rules above the reset in specificity and cascade, and
- restores the box properties the reset strips. No painter label element
- exists under chrome-none, so there is nothing to style for it.
+ (`modules.contentControls.chrome: 'none'` in main.ts) and paints its own,
+ driving it entirely through SuperDoc's public --sd-content-controls-custom-*
+ variables. We set those variables per tag (on the data-sdt-tag selector) and
+ the painter applies them across rest, hover, selected, and locked-hover. So
+ there is no !important, and no .ProseMirror-selectednode / .sdt-group-hover
+ state selectors - this is the copy-pasteable pattern for styling custom SDTs.
----------------------------------------------------------------------- */
-/* Inline smart fields: blue pill */
+/* Smart-tag token look, shared by the in-editor inline SDT and the Smart-tags
+ palette chips so a sidebar tag and the field it inserts read as one object. */
+:root {
+ /* Template fields use the SuperDoc brand blue (brand.md: blue-500 / blue-600),
+ via the --sd-color-blue-* tokens. One token set, applied to both the palette
+ chip and the painted in-editor field. Fields read as tinted/outlined pills,
+ so they stay distinct from the solid-blue primary buttons. */
+ --tag-color: var(--sd-color-blue-500, #1355ff);
+ --tag-border: var(--tag-color);
+ --tag-bg: color-mix(in srgb, var(--tag-color) 12%, transparent);
+ --tag-fg: var(--sd-color-blue-600, #0f44cc);
+ --tag-bg-hover: color-mix(in srgb, var(--tag-color) 22%, transparent);
+ /* Block clauses are large regions, so they wear the same blue quietly:
+ a left rail + a faint fill + a soft border, lighter than the inline pill. */
+ --tag-block-border: color-mix(in srgb, var(--tag-color) 30%, var(--demo-border));
+ --tag-block-bg: color-mix(in srgb, var(--tag-color) 4%, var(--demo-bg));
+ --tag-block-bg-hover: color-mix(in srgb, var(--tag-color) 8%, var(--demo-bg));
+ --tag-radius: 6px;
+}
+/* Inline smart fields: token pill, painted by SuperDoc under chrome:'none'. We
+ set the public --sd-content-controls-custom-inline-* variables, and SuperDoc
+ applies them across rest, hover, selected, and locked-hover. No !important, no
+ .ProseMirror-selectednode / .sdt-group-hover state selectors, and the box
+ (border + padding) stays identical in every state, so a field never shifts on
+ hover or click. Only the background changes; the border is constant. */
.superdoc-cc-chrome-none .superdoc-structured-content-inline[data-sdt-tag*='smartField'] {
- padding: 1px 4px;
- border: 1px solid var(--demo-accent);
- border-radius: 4px;
- background-color: var(--demo-accent-soft);
+ --sd-content-controls-custom-inline-border: 1px solid var(--tag-border);
+ --sd-content-controls-custom-inline-radius: var(--tag-radius);
+ --sd-content-controls-custom-inline-padding: 1px 6px;
+ --sd-content-controls-custom-inline-bg: var(--tag-bg);
+ --sd-content-controls-custom-inline-hover-bg: var(--tag-bg-hover);
+ --sd-content-controls-custom-inline-selected-bg: var(--tag-bg-hover);
+ /* Text colour is not part of the custom border/fill layer and chrome:'none'
+ does not reset it, so it can be set directly and stays stable across states. */
+ color: var(--tag-fg);
}
-/* Block clauses: bordered card with soft background */
-.superdoc-cc-chrome-none .superdoc-structured-content-block[data-sdt-tag*='reusableSection'] {
+/* Smart-tags palette (sidebar). Chips reuse the --tag-* token look above, so a
+ palette chip and the field it inserts are visually identical. */
+.smart-tags { margin-bottom: 14px; }
+.smart-tags-hint { margin: 0 0 8px; font-size: var(--sd-font-size-200, 12px); color: var(--demo-text-muted); }
+.smart-tags-search {
+ width: 100%;
+ height: 30px;
+ padding: 0 10px;
+ margin-bottom: 10px;
border: 1px solid var(--demo-border);
- border-radius: 4px;
- background-color: var(--demo-bg);
+ border-radius: var(--sd-radius-50, 4px);
+ background: var(--demo-bg);
+ color: var(--demo-text);
}
-
-/*
- * Contextual smart-field chip (SD-3157 / SD-3232). Floats over the active
- * smart-field SDT showing field label + live value. Wired in field-chip.ts
- * against the public `content-control:active-change` event (what's active)
- * + `ui.contentControls.getRect` (where to draw). With built-in chrome off
- * (SD-3159), the chip is the smart field's active-state affordance: custom
- * UI anchored to the SDT via public events and the geometry API.
- */
-.sd-field-chip {
- display: inline-flex;
- align-items: center;
- padding: 3px 8px;
- border-radius: 999px;
- font-size: 11px;
+.smart-tags-group {
+ font-size: var(--sd-font-size-100, 11px);
+ font-weight: 600;
+ text-transform: uppercase;
+ letter-spacing: 0.05em;
+ color: var(--demo-text-muted);
+ margin-bottom: 6px;
+}
+.smart-tags-list { display: flex; flex-wrap: wrap; gap: 6px; }
+.smart-tag {
+ font: inherit;
+ /* Match the in-editor field pill (which inherits the ~11pt document font) so
+ a chip and the token it inserts read as the same size, not just color. */
+ font-size: 14px;
font-weight: 500;
- background: var(--demo-bg, #ffffff);
- border: 1px solid var(--demo-accent, #2563eb);
- color: var(--demo-accent, #2563eb);
- box-shadow: 0 2px 6px rgba(15, 23, 42, 0.08);
- font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+ line-height: 1.2;
+ cursor: grab;
+ padding: 1px 6px;
+ border: 1px solid var(--tag-border);
+ border-radius: var(--tag-radius);
+ background: var(--tag-bg);
+ color: var(--tag-fg);
white-space: nowrap;
- max-width: 320px;
- overflow: hidden;
- text-overflow: ellipsis;
}
+.smart-tag:hover { background: var(--tag-bg-hover); }
+.smart-tag:active { cursor: grabbing; }
+.smart-tag.is-active { box-shadow: 0 0 0 2px var(--demo-accent); }
+.smart-tag:focus-visible { outline: 1px solid var(--demo-accent); outline-offset: 1px; }
-.sd-field-chip__label {
- font-weight: 600;
-}
-
-.sd-field-chip__value {
- color: var(--demo-text, #18181b);
- font-weight: 400;
+/* Block clauses: a quiet card with a blue left rail, same field language as the
+ inline pills but a region not a token (soft border, faint fill, a 4px blue
+ spine). Set the public --sd-content-controls-custom-block-* variables; SuperDoc
+ applies them across rest, hover, selected, and locked-hover - so, like the
+ inline fields, there's no !important and no .sdt-group-hover /
+ .ProseMirror-selectednode state selectors, and the box stays constant. */
+.superdoc-cc-chrome-none .superdoc-structured-content-block[data-sdt-tag*='reusableSection'] {
+ --sd-content-controls-custom-block-border: 1px solid var(--tag-block-border);
+ --sd-content-controls-custom-block-border-left: 4px solid var(--tag-color);
+ --sd-content-controls-custom-block-radius: var(--tag-radius);
+ --sd-content-controls-custom-block-bg: var(--tag-block-bg);
+ --sd-content-controls-custom-block-hover-bg: var(--tag-block-bg-hover);
+ --sd-content-controls-custom-block-selected-bg: var(--tag-block-bg-hover);
}
diff --git a/docs/architecture/package-boundaries.md b/docs/architecture/package-boundaries.md
index 74e3f52963..d96e061d92 100644
--- a/docs/architecture/package-boundaries.md
+++ b/docs/architecture/package-boundaries.md
@@ -65,7 +65,7 @@ For any entry classified as legacy public:
| `packages/layout-engine/dom-contract` | `@superdoc/dom-contract` | Internal implementation | DOM rendering contracts |
| `packages/layout-engine/painters/dom` | `@superdoc/painter-dom` | Internal implementation | DOM rendering pipeline |
| `packages/layout-engine/measuring/dom` | `@superdoc/measuring-dom` | Internal implementation | Measurement pipeline |
-| `packages/layout-engine/pm-adapter` | `@superdoc/pm-adapter` | Internal implementation | ProseMirror to FlowBlock bridge |
+| `packages/super-editor/src/editors/v1/core/layout-adapter` | (internal to `@superdoc/super-editor`) | Internal implementation | v1 ProseMirror → FlowBlock projection; owned by super-editor, not a standalone package |
| `packages/layout-engine/style-engine` | `@superdoc/style-engine` | Internal implementation | OOXML cascade resolution |
| `packages/layout-engine/layout-bridge` | `@superdoc/layout-bridge` | Internal implementation | Pipeline orchestration |
| `packages/layout-engine/layout-engine` | `@superdoc/layout-engine` | Internal implementation | Pagination algorithms |
@@ -174,7 +174,7 @@ The relocation pattern is what `superdoc` currently uses for several internal-bu
### Decision 3. The layout-engine sub-packages stay separate.
-**Context.** `packages/layout-engine/` contains ten sub-packages (`contracts`, `dom-contract`, `geometry-utils`, `layout-bridge`, `layout-engine`, `layout-resolved`, `pm-adapter`, `style-engine`, `painters/dom`, `measuring/dom`), all private, all internal implementation.
+**Context.** `packages/layout-engine/` contains nine sub-packages (`contracts`, `dom-contract`, `geometry-utils`, `layout-bridge`, `layout-engine`, `layout-resolved`, `style-engine`, `painters/dom`, `measuring/dom`), all private, all internal implementation. (The v1 ProseMirror → FlowBlock adapter is no longer here; it is owned by `@superdoc/super-editor` at `src/editors/v1/core/layout-adapter`.)
**Decision.** Keep as-is. The audit gate (SD-2832) plus the type ownership rules remove the customer-visible cost of the split. Restructuring without a strong forcing function is scope creep. Revisit only if the audit gate proves expensive to maintain because of the package count.
diff --git a/package.json b/package.json
index ac9a86ab93..3243b24b45 100644
--- a/package.json
+++ b/package.json
@@ -25,7 +25,7 @@
"test:behavior:html": "pnpm --filter @superdoc-testing/behavior test:html",
"type-check": "pnpm run check:types",
"type-check:force": "tsc -b --force tsconfig.references.json",
- "rebuild:types": "pnpm --workspace-concurrency=1 run --filter=@superdoc/common --filter=@superdoc/word-layout --filter=@superdoc/contracts --filter=@superdoc/dom-contract --filter=@superdoc/layout-resolved --filter=@superdoc/geometry-utils --filter=@superdoc/style-engine --filter=@superdoc/pm-adapter --filter=@superdoc/measuring-dom --filter=@superdoc/layout-engine --filter=@superdoc/layout-bridge build && pnpm --filter=@superdoc/painter-dom build",
+ "rebuild:types": "pnpm --workspace-concurrency=1 run --filter=@superdoc/common --filter=@superdoc/word-layout --filter=@superdoc/contracts --filter=@superdoc/dom-contract --filter=@superdoc/layout-resolved --filter=@superdoc/geometry-utils --filter=@superdoc/style-engine --filter=@superdoc/measuring-dom --filter=@superdoc/layout-engine --filter=@superdoc/layout-bridge build && pnpm --filter=@superdoc/painter-dom build",
"validate:commands": "node scripts/validate-command-types.mjs",
"unzip": "bash packages/super-editor/src/editors/v1/tests/helpers/unzip.sh",
"dev": "pnpm --prefix packages/superdoc run dev",
diff --git a/packages/docx-evidence-contracts/src/contracts.test.ts b/packages/docx-evidence-contracts/src/contracts.test.ts
index 860251d666..4b1b7613ee 100644
--- a/packages/docx-evidence-contracts/src/contracts.test.ts
+++ b/packages/docx-evidence-contracts/src/contracts.test.ts
@@ -188,7 +188,7 @@ describe('public DOCX evidence contracts', () => {
expect(text).not.toMatch(/from ['"]node:/);
expect(text).not.toMatch(/from ['"].*\.\.\/\.\.\/\.\.\/labs/);
- expect(text).not.toMatch(/from ['"]@superdoc\/(super-editor|painter-dom|layout-engine|pm-adapter)/);
+ expect(text).not.toMatch(/from ['"]@superdoc\/(super-editor|painter-dom|layout-engine)/);
}
});
});
diff --git a/packages/layout-engine/AGENTS.md b/packages/layout-engine/AGENTS.md
index 3d6a3a73de..2f17e5173f 100644
--- a/packages/layout-engine/AGENTS.md
+++ b/packages/layout-engine/AGENTS.md
@@ -5,32 +5,37 @@ Pagination and rendering pipeline for SuperDoc's presentation/viewing mode.
## Pipeline Overview
```
-ProseMirror Doc → pm-adapter → FlowBlock[] → layout-engine → Layout[] → painter-dom → DOM
+ProseMirror Doc → v1 layout-adapter (super-editor) → FlowBlock[] → layout-engine → Layout[] → painter-dom → DOM
```
+The PM → `FlowBlock[]` adapter is owned by `@superdoc/super-editor`
+(`src/editors/v1/core/layout-adapter`), not by this package. The layout-engine
+packages consume `FlowBlock[]` and the shared layout contracts only and must
+never import the concrete adapter or `@superdoc/super-editor`.
+
## Sub-packages
| Package | Purpose | Key Entry |
|---------|---------|-----------|
-| `contracts/` | Shared types (FlowBlock, Layout, etc.) | `src/index.ts` |
-| `pm-adapter/` | PM document → FlowBlocks conversion | `src/internal.ts` |
-| `layout-engine/` | Pagination algorithms | `src/index.ts` |
-| `layout-bridge/` | Layout orchestration & bridge utilities | `src/incrementalLayout.ts` |
-| `painters/dom/` | DOM rendering | `src/renderer.ts` |
-| `style-engine/` | OOXML style resolution | `src/index.ts` |
-| `geometry-utils/` | Math utilities for layout | `src/index.ts` |
+| `contracts/` | Shared types (FlowBlock, Layout, etc.) | `contracts/src/index.ts` |
+| v1 layout-adapter (super-editor) | PM document → FlowBlocks conversion | `../super-editor/src/editors/v1/core/layout-adapter/internal.ts` |
+| `layout-engine/` | Pagination algorithms | `layout-engine/src/index.ts` |
+| `layout-bridge/` | Layout orchestration & bridge utilities | `layout-bridge/src/incrementalLayout.ts` |
+| `painters/dom/` | DOM rendering | `painters/dom/src/renderer.ts` |
+| `style-engine/` | OOXML style resolution | `style-engine/src/index.ts` |
+| `geometry-utils/` | Math utilities for layout | `geometry-utils/src/index.ts` |
## Key Insight: DomPainter Receives Paint-Ready Data
DomPainter receives a single paint-ready input — `ResolvedLayout` — and
-renders it to DOM. It does not do layout logic, measurement, or pm-adapter
+renders it to DOM. It does not do layout logic, measurement, or PM → FlowBlock
conversion. Those decisions happen upstream in `layout-engine/`,
-`layout-resolved/`, and `pm-adapter/`.
+`layout-resolved/`, and the v1 layout-adapter (super-editor).
This is enforced as two hard invariants, not aspirational language:
1. **No upstream package imports.** The painter has zero runtime imports
- from `@superdoc/pm-adapter`, `@superdoc/layout-bridge`, or
+ from the v1 adapter (`@superdoc/super-editor`), `@superdoc/layout-bridge`, or
`@superdoc/layout-resolved`. Guard D in
`tests/src/architecture-boundaries.test.ts` enforces this (SD-2836).
2. **No paint-time DOM measurement.** The painter never reads
@@ -53,11 +58,11 @@ reads.
| Change how OOXML element renders | `painters/dom/src/features/feature-registry.ts` → feature module |
| Change rendering orchestration | `painters/dom/src/renderer.ts` |
| Change pagination/layout | `layout-engine/src/index.ts` |
-| Add new block type | `pm-adapter/src/converters/` + `painters/dom/` |
+| Add new block type | v1 `core/layout-adapter/converters/` + `painters/dom/` |
| Change style resolution | `style-engine/` |
| Change text measurement | `measuring-dom/` |
-AIDEV-NOTE: `pm-adapter` must preserve shared `SdtMetadata` object identity for sibling blocks in one id-less SDT container; see `contracts/src/sdt-container.ts` before changing SDT imports.
+AIDEV-NOTE: the v1 layout-adapter must preserve shared `SdtMetadata` object identity for sibling blocks in one id-less SDT container; see `contracts/src/sdt-container.ts` before changing SDT imports.
## Style Engine (`style-engine/`)
@@ -103,20 +108,20 @@ Rendering logic for specific OOXML features is extracted into **feature modules*
### How to find where an OOXML element renders
-1. **Search `features/feature-registry.ts`** — maps OOXML element names (e.g., `w:pBdr`, `w:shd`) to their feature module
+1. **Search `painters/dom/src/features/feature-registry.ts`** — maps OOXML element names (e.g., `w:pBdr`, `w:shd`) to their feature module
2. Each entry has: `feature` (folder name), `module` (import path), `handles` (OOXML elements), `spec` (ECMA-376 section)
3. Open the feature's `index.ts` for its public API and `@ooxml`/`@spec` annotations
### Adding a new rendering feature
-1. **Add a registry entry** in `features/feature-registry.ts` first — this is the source of truth
-2. **Create the feature folder** at `features//`:
+1. **Add a registry entry** in `painters/dom/src/features/feature-registry.ts` first — this is the source of truth
+2. **Create the feature folder** at `painters/dom/src/features//`:
- `index.ts` — barrel exports with `@ooxml` and `@spec` JSDoc annotations
- Split logic into focused files (e.g., `group-analysis.ts`, `border-layer.ts`)
- `types.ts` — shared types if needed
3. **Import from the feature module** in `renderer.ts` — renderer calls feature functions, features don't import from renderer
4. **Remove extracted code** from `renderer.ts` — don't leave dead copies
-5. **Update imports** in any other files that used the old renderer exports (e.g., `table/renderTableCell.ts`)
+5. **Update imports** in any other files that used the old renderer exports (e.g., `painters/dom/src/table/renderTableCell.ts`)
### Feature module conventions
@@ -130,7 +135,7 @@ Rendering logic for specific OOXML features is extracted into **feature modules*
| Feature | OOXML elements | Folder |
|---------|---------------|--------|
-| Paragraph borders & shading | `w:pBdr`, `w:shd` | `features/paragraph-borders/` |
+| Paragraph borders & shading | `w:pBdr`, `w:shd` | `painters/dom/src/paragraph/borders/` |
## Entry Points
@@ -138,14 +143,14 @@ Rendering logic for specific OOXML features is extracted into **feature modules*
- `painters/dom/src/features/feature-registry.ts` - OOXML element → feature module lookup
- `painters/dom/src/styles.ts` - CSS class definitions
- `layout-bridge/src/incrementalLayout.ts` - Layout orchestration (called by PresentationEditor)
-- `pm-adapter/src/internal.ts` - PM → FlowBlock conversion
+- `../super-editor/src/editors/v1/core/layout-adapter/internal.ts` - PM → FlowBlock conversion (super-editor-owned)
## Layer Ownership
See root `CLAUDE.md` for the full placement map. This package owns the
layout and rendering pipeline.
-- Style-resolved properties flow through `style-engine` → `pm-adapter` →
+- Style-resolved properties flow through `style-engine` → v1 layout-adapter →
DomPainter.
- Static document visuals belong in layout data plus DomPainter rendering, not
ProseMirror decorations.
@@ -154,9 +159,9 @@ layout and rendering pipeline.
- `PresentationEditor` bridges editor state into layout and paint state. It
should not resolve OOXML semantics.
- Direction work keeps OOXML axes separate. `style-engine` resolves cascades,
- `pm-adapter` writes typed direction/table attrs, and DomPainter owns
+ the v1 layout-adapter writes typed direction/table attrs, and DomPainter owns
paint-time visual mirroring. For `w:bidiVisual`, upstream layers keep table
sides in LTR-default form and DomPainter mirrors once.
For the full direction taxonomy, see
-`pm-adapter/src/direction/README.md`.
+`../super-editor/src/editors/v1/core/layout-adapter/direction/README.md`.
diff --git a/packages/layout-engine/contracts/README.md b/packages/layout-engine/contracts/README.md
index 5a7547d01e..db8288e510 100644
--- a/packages/layout-engine/contracts/README.md
+++ b/packages/layout-engine/contracts/README.md
@@ -11,7 +11,7 @@ sync.
`TrackedChangeMeta` types
- `TextRun` now exposes an optional `trackedChange` payload carrying author/date
metadata plus format deltas for track-change marks
-- `AdapterOptions` (in `@superdoc/pm-adapter`) accepts `trackedChangesMode` and
+- `AdapterOptions` (in the v1 SuperEditor layout adapter) accepts `trackedChangesMode` and
`enableTrackedChanges` so callers can opt into the new metadata
- Versioned `FlowRunLink` schema with extended metadata (target, rel, anchor, docLocation, etc.)
diff --git a/packages/layout-engine/contracts/src/author-colors.test.ts b/packages/layout-engine/contracts/src/author-colors.test.ts
new file mode 100644
index 0000000000..e335f0f179
--- /dev/null
+++ b/packages/layout-engine/contracts/src/author-colors.test.ts
@@ -0,0 +1,97 @@
+import { describe, expect, it } from 'vitest';
+import { composeAuthorColorResolver, fallbackAuthorColor, stampTrackedChangeColors } from './author-colors.js';
+import type { FlowBlock, ParagraphBlock, TextRun } from './index.js';
+
+describe('composeAuthorColorResolver', () => {
+ it('returns undefined when config is missing or disabled', () => {
+ expect(composeAuthorColorResolver(undefined)).toBeUndefined();
+ expect(composeAuthorColorResolver(null)).toBeUndefined();
+ expect(composeAuthorColorResolver({ enabled: false, overrides: { a: '#fff' } })).toBeUndefined();
+ });
+
+ it('resolves overrides by email first, then name (exact match)', () => {
+ const resolve = composeAuthorColorResolver({
+ overrides: { 'a@x.test': '#111111', Alice: '#222222' },
+ })!;
+ expect(resolve({ email: 'a@x.test', name: 'Alice' })).toBe('#111111');
+ expect(resolve({ name: 'Alice' })).toBe('#222222');
+ });
+
+ it('falls through to resolve() when no override matches', () => {
+ const resolve = composeAuthorColorResolver({
+ overrides: { Bob: '#000000' },
+ resolve: (author) => (author.name === 'Alice' ? '#abcabc' : undefined),
+ })!;
+ expect(resolve({ name: 'Alice' })).toBe('#abcabc');
+ });
+
+ it('uses a deterministic fallback when overrides and resolve decline', () => {
+ const resolve = composeAuthorColorResolver({ resolve: () => undefined })!;
+ const first = resolve({ name: 'Discovered Author' });
+ const second = resolve({ name: 'Discovered Author' });
+ expect(first).toMatch(/^#[0-9a-f]{6}$/i);
+ expect(first).toBe(second);
+ expect(first).toBe(fallbackAuthorColor({ name: 'Discovered Author' }));
+ });
+
+ it('does not throw when the host resolver throws', () => {
+ const resolve = composeAuthorColorResolver({
+ resolve: () => {
+ throw new Error('boom');
+ },
+ })!;
+ expect(resolve({ name: 'Alice' })).toMatch(/^#[0-9a-f]{6}$/i);
+ });
+});
+
+describe('stampTrackedChangeColors', () => {
+ const makeParagraph = (run: TextRun): ParagraphBlock => ({
+ kind: 'paragraph',
+ id: 'p1',
+ runs: [run],
+ });
+
+ it('stamps color on every tracked-change layer from the author identity', () => {
+ const run: TextRun = {
+ kind: 'text',
+ text: 'hi',
+ fontFamily: 'Arial',
+ fontSize: 12,
+ trackedChanges: [
+ { kind: 'insert', id: 'tc1', author: 'Alice' },
+ { kind: 'format', id: 'tc2', author: 'Bob' },
+ ],
+ };
+ run.trackedChange = run.trackedChanges![0];
+
+ const blocks: FlowBlock[] = [makeParagraph(run)];
+ stampTrackedChangeColors(blocks, composeAuthorColorResolver({ overrides: { Alice: '#123456', Bob: '#654321' } })!);
+
+ expect(run.trackedChanges![0]!.color).toBe('#123456');
+ expect(run.trackedChanges![1]!.color).toBe('#654321');
+ // trackedChange mirror (first layer) is colored too.
+ expect(run.trackedChange!.color).toBe('#123456');
+ });
+
+ it('clears stale colors when no resolver is provided', () => {
+ const run: TextRun = {
+ kind: 'text',
+ text: 'hi',
+ fontFamily: 'Arial',
+ fontSize: 12,
+ trackedChanges: [{ kind: 'insert', id: 'tc1', author: 'Alice', color: '#123456' }],
+ };
+ run.trackedChange = run.trackedChanges![0];
+
+ stampTrackedChangeColors([makeParagraph(run)], undefined);
+
+ expect(run.trackedChanges![0]!.color).toBeUndefined();
+ expect(run.trackedChange!.color).toBeUndefined();
+ });
+
+ it('leaves runs without tracked changes untouched', () => {
+ const run: TextRun = { kind: 'text', text: 'plain', fontFamily: 'Arial', fontSize: 12 };
+ stampTrackedChangeColors([makeParagraph(run)], composeAuthorColorResolver({ overrides: {} })!);
+ expect((run as TextRun).color).toBeUndefined();
+ });
+});
diff --git a/packages/layout-engine/contracts/src/author-colors.ts b/packages/layout-engine/contracts/src/author-colors.ts
new file mode 100644
index 0000000000..3b4206a612
--- /dev/null
+++ b/packages/layout-engine/contracts/src/author-colors.ts
@@ -0,0 +1,217 @@
+/**
+ * Per-author tracked-change color resolution.
+ *
+ * Hosts configure per-author colors through `modules.trackChanges.authorColors`
+ * on the `superdoc` package. SuperDoc composes those knobs into a single
+ * resolver and threads it down into `toFlowBlocks` (see the pm-adapter
+ * `AdapterOptions.resolveTrackedChangeColor` field). The pm-adapter calls the
+ * composed resolver while preparing FlowBlock data so every tracked-change
+ * layer carries a paint-ready `color`; DomPainter then only reads `meta.color`
+ * and stamps element-scoped CSS variables.
+ *
+ * This lives in `@superdoc/contracts` (the shared, publishable foundation) so
+ * pm-adapter, super-editor, and the superdoc package can all import the
+ * resolver/types without leaking a private workspace specifier into the
+ * published `.d.ts` surface. The painter must never invoke app callbacks or
+ * import upstream SuperDoc packages — resolving on the data-preparation side
+ * keeps that boundary intact.
+ */
+
+import type { FlowBlock, TextRun, TrackChangeAuthor, TrackedChangeMeta } from './index.js';
+
+/**
+ * A composed resolver mapping a tracked-change author identity to a color.
+ * Returns `undefined` only when the resolver itself declines (it normally
+ * falls back to a deterministic color); the field is left absent entirely when
+ * per-author colors are disabled.
+ */
+export type TrackChangeAuthorColorResolver = (author: TrackChangeAuthor) => string | undefined;
+
+/**
+ * Host-facing per-author tracked-change color configuration. Mirrors the
+ * `modules.trackChanges.authorColors` shape on the public `superdoc` package.
+ */
+export interface AuthorColorsConfig {
+ /** When `false`, per-author colors are not applied. Defaults to enabled. */
+ enabled?: boolean;
+ /**
+ * Color overrides keyed by author identity. Both `email` and `name` keys are
+ * supported (email is checked first); matching is exact.
+ */
+ overrides?: Record;
+ /**
+ * Resolver consulted after `overrides`. Return a CSS color string, or
+ * `undefined`/nullish to fall through to the deterministic fallback.
+ */
+ resolve?: (author: TrackChangeAuthor) => string | undefined | null;
+}
+
+/**
+ * Curated, high-contrast fallback palette. Used when neither `overrides` nor
+ * `resolve` produces a color so imported/discovered authors the host did not
+ * configure ahead of time still get a stable, distinct color.
+ */
+const FALLBACK_PALETTE = [
+ '#1f6feb',
+ '#d1242f',
+ '#8250df',
+ '#bf3989',
+ '#1a7f37',
+ '#9a6700',
+ '#bc4c00',
+ '#0969da',
+ '#cf222e',
+ '#6639ba',
+ '#116329',
+ '#7d4e00',
+];
+
+/** Stable identity string for an author (used for hashing + dedupe). */
+export const authorIdentityKey = (author: TrackChangeAuthor | undefined): string => {
+ if (!author) return '';
+ const name = typeof author.name === 'string' ? author.name : '';
+ const email = typeof author.email === 'string' ? author.email : '';
+ return `${name} ${email}`;
+};
+
+/** Deterministic 32-bit FNV-1a hash of a string. */
+const hashString = (value: string): number => {
+ let hash = 0x811c9dc5;
+ for (let i = 0; i < value.length; i += 1) {
+ hash ^= value.charCodeAt(i);
+ hash = Math.imul(hash, 0x01000193);
+ }
+ return hash >>> 0;
+};
+
+/**
+ * Deterministic fallback color derived from the author identity. The same
+ * identity always maps to the same palette entry, so colors stay stable across
+ * reloads and across the paint / snapshot surfaces.
+ */
+export const fallbackAuthorColor = (author: TrackChangeAuthor | undefined): string => {
+ const key = authorIdentityKey(author);
+ const index = hashString(key) % FALLBACK_PALETTE.length;
+ return FALLBACK_PALETTE[index]!;
+};
+
+const isNonEmptyString = (value: unknown): value is string => typeof value === 'string' && value.length > 0;
+
+/**
+ * Composes the host `authorColors` config into a single resolver.
+ *
+ * Resolution order per author:
+ * 1. `overrides` by identity — `email` first, then `name` (exact match).
+ * 2. `resolve(author)`.
+ * 3. A deterministic fallback color from the author identity.
+ *
+ * Returns `undefined` when colors are disabled (`enabled === false`) or no
+ * config was provided, so callers can leave the existing default palette in
+ * place by simply not threading a resolver.
+ */
+export const composeAuthorColorResolver = (
+ config?: AuthorColorsConfig | null,
+): TrackChangeAuthorColorResolver | undefined => {
+ if (!config || config.enabled === false) return undefined;
+ const overrides = config.overrides && typeof config.overrides === 'object' ? config.overrides : undefined;
+ const resolve = typeof config.resolve === 'function' ? config.resolve : undefined;
+
+ return (author: TrackChangeAuthor): string | undefined => {
+ const safeAuthor = author ?? {};
+ if (overrides) {
+ if (isNonEmptyString(safeAuthor.email) && isNonEmptyString(overrides[safeAuthor.email])) {
+ return overrides[safeAuthor.email];
+ }
+ if (isNonEmptyString(safeAuthor.name) && isNonEmptyString(overrides[safeAuthor.name])) {
+ return overrides[safeAuthor.name];
+ }
+ }
+ if (resolve) {
+ try {
+ const resolved = resolve(safeAuthor);
+ if (isNonEmptyString(resolved)) return resolved;
+ } catch {
+ // A throwing host resolver must not break rendering; fall through.
+ }
+ }
+ return fallbackAuthorColor(safeAuthor);
+ };
+};
+
+/** Maps tracked-change metadata to the author identity the resolver expects. */
+export const authorFromTrackedChangeMeta = (meta: TrackedChangeMeta): TrackChangeAuthor => ({
+ name: meta.author,
+ email: meta.authorEmail,
+ image: meta.authorImage,
+});
+
+const applyColorToLayer = (meta: TrackedChangeMeta, resolve: TrackChangeAuthorColorResolver | undefined): void => {
+ const color = resolve?.(authorFromTrackedChangeMeta(meta));
+ if (isNonEmptyString(color)) {
+ meta.color = color;
+ return;
+ }
+ delete meta.color;
+};
+
+const stampRunTrackedChangeColors = (run: TextRun, resolve: TrackChangeAuthorColorResolver | undefined): void => {
+ if (Array.isArray(run.trackedChanges)) {
+ for (const layer of run.trackedChanges) {
+ applyColorToLayer(layer, resolve);
+ }
+ }
+ if (run.trackedChange) {
+ applyColorToLayer(run.trackedChange, resolve);
+ }
+};
+
+const stampBlockTrackedChangeColors = (
+ block: FlowBlock | undefined,
+ resolve: TrackChangeAuthorColorResolver | undefined,
+): void => {
+ if (!block) return;
+ switch (block.kind) {
+ case 'paragraph': {
+ for (const run of block.runs) {
+ stampRunTrackedChangeColors(run as TextRun, resolve);
+ }
+ break;
+ }
+ case 'list': {
+ for (const item of block.items) {
+ stampBlockTrackedChangeColors(item.paragraph, resolve);
+ }
+ break;
+ }
+ case 'table': {
+ for (const row of block.rows) {
+ for (const cell of row.cells) {
+ stampBlockTrackedChangeColors(cell.paragraph, resolve);
+ if (Array.isArray(cell.blocks)) {
+ for (const nested of cell.blocks) {
+ stampBlockTrackedChangeColors(nested, resolve);
+ }
+ }
+ }
+ }
+ break;
+ }
+ default:
+ break;
+ }
+};
+
+/**
+ * Walks every tracked-change layer in the converted FlowBlocks and stamps
+ * `meta.color` from the resolver. Passing `undefined` clears existing colors,
+ * which prevents stale author colors from surviving on reused cached blocks
+ * after the host disables per-author colors.
+ */
+export const stampTrackedChangeColors = (
+ blocks: FlowBlock[],
+ resolve: TrackChangeAuthorColorResolver | undefined,
+): void => {
+ for (const block of blocks) {
+ stampBlockTrackedChangeColors(block, resolve);
+ }
+};
diff --git a/packages/layout-engine/contracts/src/index.ts b/packages/layout-engine/contracts/src/index.ts
index e52e3e8ffb..e12ab7ea53 100644
--- a/packages/layout-engine/contracts/src/index.ts
+++ b/packages/layout-engine/contracts/src/index.ts
@@ -101,6 +101,14 @@ export type {
import type { LayoutSourceIdentity } from './layout-identity.js';
export { cloneColumnLayout, normalizeColumnLayout, widthsEqual } from './column-layout.js';
export type { NormalizedColumnLayout } from './column-layout.js';
+export {
+ composeAuthorColorResolver,
+ fallbackAuthorColor,
+ authorIdentityKey,
+ authorFromTrackedChangeMeta,
+ stampTrackedChangeColors,
+} from './author-colors.js';
+export type { AuthorColorsConfig, TrackChangeAuthorColorResolver } from './author-colors.js';
export {
getSdtContainerKey,
getSdtContainerKeyForBlock,
@@ -255,6 +263,20 @@ export type TrackedChangeKind = 'insert' | 'delete' | 'format';
export type TrackedChangesMode = 'review' | 'original' | 'final' | 'off';
+/**
+ * Identity of a tracked-change author, used to resolve a per-author color.
+ *
+ * Mirrors the author metadata carried on {@link TrackedChangeMeta}
+ * (`author` → `name`, `authorEmail` → `email`, `authorImage` → `image`).
+ * Hosts configure per-author colors through this shape (see the
+ * `modules.trackChanges.authorColors` config on the `superdoc` package).
+ */
+export type TrackChangeAuthor = {
+ name?: string;
+ email?: string;
+ image?: string;
+};
+
/** Formatting mark for track-format metadata. */
export type RunMark = {
type: string;
@@ -281,6 +303,15 @@ export type TrackedChangeMeta = {
date?: string;
before?: RunMark[];
after?: RunMark[];
+ /**
+ * Paint-ready per-author color, resolved upstream (in/around the
+ * pm-adapter data-preparation pass) from the author identity. DomPainter
+ * reads only this field and stamps the element-scoped tracked-change CSS
+ * variables from it — it never invokes resolvers or touches app config.
+ * Undefined when per-author colors are disabled or unconfigured, in which
+ * case the static default tracked-change palette applies.
+ */
+ color?: string;
};
export type FlowRunLinkTarget = '_blank' | '_self' | '_parent' | '_top';
@@ -1896,6 +1927,64 @@ export type Measure =
| ColumnBreakMeasure;
/** A rendered page containing positioned fragments. Page numbers are 1-indexed. */
+/**
+ * SD-2656: per-page footnote planning ledger.
+ *
+ * The single source of truth that body pagination, footnote placement, and
+ * continuation carry must all agree on. Without it the three subsystems read
+ * different numbers (body reserves X, planner paints Y, carry-forward thinks
+ * Z) and the resulting drift compounds across the document.
+ *
+ * Mandatory invariants checked by `tools/sd-2656-footnote-analyzer`:
+ * 1. `actualBandHeight <= appliedBodyReserve` (band fits)
+ * 2. `mandatorySlices` always equals `full(non-last) + firstLine(last)` of
+ * the page's anchored cluster (rule).
+ * 3. `continuationIn[P]` matches `continuationOut[P-1]` (carry parity).
+ * 4. `deadReserve = appliedBodyReserve - actualBandHeight` is small (drift
+ * fuel above ~30 px is a planning bug).
+ */
+export type FootnoteContinuationEntry = {
+ /** Footnote id (OOXML id, not the Word visible number). */
+ id: string;
+ /** How many ranges remain to render. */
+ remainingRangeCount: number;
+ /** Total height of the remaining ranges. */
+ remainingHeightPx: number;
+};
+
+export type FootnotePageLedger = {
+ pageIndex: number;
+ /** Ordered footnote ids whose body refs are anchored on this page. */
+ anchorIds: string[];
+ /** Slices required by the rule: full of non-last + firstLine of last. */
+ mandatorySliceIds: string[];
+ /** Slices for content drained from prior pages. */
+ continuationSliceIds: string[];
+ /** Slices for last-anchor content beyond firstLine (rendered only if there
+ * is leftover space after mandatory + continuation). */
+ extendedSliceIds: string[];
+ /** Continuations arriving from page-1. */
+ continuationIn: FootnoteContinuationEntry[];
+ /** Continuations deferred to page+1. */
+ continuationOut: FootnoteContinuationEntry[];
+ /** Mandatory-reserve px: mandatorySlices height + overhead. */
+ mandatoryReservePx: number;
+ /** SD-2656 Phase 7: Word-like "preferred" reserve px. Body slicer is allowed
+ * to reserve this much when doing so does not cause cluster spill or
+ * continuation overflow. = full(non-last) + asMuchAsFits(last) + overhead. */
+ preferredReservePx: number;
+ /** Total painted band height in px, including separator + gaps. */
+ actualBandHeightPx: number;
+ /** Body's applied reserve (i.e. `page.footnoteReserved`) for this page. */
+ appliedBodyReservePx: number;
+ /** appliedBodyReservePx - actualBandHeightPx — wasted body area. */
+ deadReservePx: number;
+ /** Number of measured lines actually rendered for the LAST anchor on this
+ * page (0 if there is no cluster anchor). Used to flag "mandatory-only"
+ * pages where Word would have rendered more. */
+ lastAnchorRenderedLines: number;
+};
+
export type Page = {
number: number;
fragments: Fragment[];
@@ -1906,6 +1995,12 @@ export type Page = {
* decoration boxes anchored to the real bottom margin while the body shrinks.
*/
footnoteReserved?: number;
+ /**
+ * SD-2656: page-level footnote planning ledger. Populated by the layout
+ * bridge when footnotes are present. Read by the diagnostic toolkit and
+ * (in later phases) by body pagination itself.
+ */
+ footnoteLedger?: FootnotePageLedger;
numberText?: string;
size?: { w: number; h: number };
orientation?: 'portrait' | 'landscape';
diff --git a/packages/layout-engine/contracts/src/resolved-layout.ts b/packages/layout-engine/contracts/src/resolved-layout.ts
index 08fe933979..97e9b6c21d 100644
--- a/packages/layout-engine/contracts/src/resolved-layout.ts
+++ b/packages/layout-engine/contracts/src/resolved-layout.ts
@@ -487,6 +487,14 @@ export type ResolvedListMarkerItem = {
italic?: boolean;
color?: string;
letterSpacing?: number;
+ /**
+ * SD-2656: caps marks from the level rPr ( w:caps / w:smallCaps ). When
+ * `allCaps` is true the painter applies CSS text-transform: uppercase to
+ * the marker text — matching Word's legal/contract list rendering
+ * ("FIRST:", "SECOND:", "THIRD:") for `ordinalText` numbering.
+ */
+ allCaps?: boolean;
+ smallCaps?: boolean;
};
/** Optional DOCX source evidence for list-marker observations. */
sourceAnchor?: SourceAnchor;
diff --git a/packages/layout-engine/layout-bridge/package.json b/packages/layout-engine/layout-bridge/package.json
index b21462d905..7d0fcf4798 100644
--- a/packages/layout-engine/layout-bridge/package.json
+++ b/packages/layout-engine/layout-bridge/package.json
@@ -31,7 +31,6 @@
"devDependencies": {
"@superdoc/layout-resolved": "workspace:*",
"@superdoc/painter-dom": "workspace:*",
- "@superdoc/pm-adapter": "workspace:*",
"@types/node": "catalog:",
"tsup": "catalog:",
"typescript": "catalog:",
diff --git a/packages/layout-engine/layout-bridge/src/footnote-scorer.ts b/packages/layout-engine/layout-bridge/src/footnote-scorer.ts
new file mode 100644
index 0000000000..1376e1b0a0
--- /dev/null
+++ b/packages/layout-engine/layout-bridge/src/footnote-scorer.ts
@@ -0,0 +1,400 @@
+import type { FootnotePageLedger, Layout } from '@superdoc/contracts';
+
+export type FootnoteWindowScoreReason =
+ | 'globally-safe'
+ | 'cluster-spill'
+ | 'new-mandatory-only'
+ | 'candidate-not-improved'
+ | 'page-count-grew'
+ | 'dead-reserve-bloat';
+
+export type FootnotePreferredReserveCandidate = {
+ pageIndex: number;
+ anchorIds: string[];
+ mandatoryReservePx: number;
+ preferredReservePx: number;
+ reserveDeltaPx: number;
+ actualBandHeightPx: number;
+ lastAnchorRenderedLines: number;
+};
+
+export type FootnoteWindowStats = {
+ totalPages: number;
+ mandatoryOnlyCount: number;
+ deadReserveSum: number;
+ clusterSplitCount: number;
+ candidateRenderedLines?: number;
+ /**
+ * Analyzer-only metric. Runtime layout does not know the Word baseline, but
+ * the scorer can carry this when a caller has external alignment data.
+ */
+ driftEvents?: number;
+};
+
+export type FootnoteWindowScoreInput = {
+ beforeLayout: Layout;
+ afterLayout: Layout;
+ candidatePageIndex: number;
+ candidateAnchorId?: string;
+ beforeLedger: FootnotePageLedger[];
+ afterLedger: FootnotePageLedger[];
+ windowAhead?: number;
+ preferredDeltaThresholdPx?: number;
+ mandatoryOnlyTolerancePx?: number;
+ deadReserveBloatThresholdPx?: number;
+ wholeDocumentDeadReserveBloatThresholdPx?: number;
+};
+
+export type FootnoteWindowScoreResult = {
+ accept: boolean;
+ reason: FootnoteWindowScoreReason;
+ before: FootnoteWindowStats;
+ after: FootnoteWindowStats;
+};
+
+type FootnoteLedgerDiagnostics = {
+ mandatoryOnlyCount: number;
+ mandatoryOnlyAnchorIds: Set;
+ deadReserveSum: number;
+ clusterSplitCount: number;
+ clusterSplitAnchorIds: Set;
+};
+
+const DEFAULT_WINDOW_AHEAD = 3;
+const DEFAULT_PREFERRED_DELTA_THRESHOLD_PX = 8;
+const DEFAULT_MANDATORY_ONLY_TOLERANCE_PX = 2;
+const DEFAULT_DEAD_RESERVE_BLOAT_THRESHOLD_PX = 128;
+const DEFAULT_WHOLE_DOCUMENT_DEAD_RESERVE_BLOAT_THRESHOLD_PX = 128;
+const FULL_ANCHOR_RENDER_SENTINEL = Number.MAX_SAFE_INTEGER;
+const DEFAULT_TRIAL_TARGET_COUNT = 12;
+
+export const isMandatoryOnlyFootnotePage = (
+ ledger: FootnotePageLedger,
+ preferredDeltaThresholdPx = DEFAULT_PREFERRED_DELTA_THRESHOLD_PX,
+ mandatoryOnlyTolerancePx = DEFAULT_MANDATORY_ONLY_TOLERANCE_PX,
+): boolean => {
+ if (ledger.anchorIds.length === 0) return false;
+ return (
+ Math.abs(ledger.actualBandHeightPx - ledger.mandatoryReservePx) <= mandatoryOnlyTolerancePx &&
+ ledger.preferredReservePx - ledger.mandatoryReservePx > preferredDeltaThresholdPx &&
+ ledger.lastAnchorRenderedLines <= 1
+ );
+};
+
+/**
+ * SD-2656 (post-Vivienne-feedback): a page whose LAST anchor partially rendered
+ * but spilled to a later page. The user-visible bug is a footnote split across
+ * pages even when the preferred reserve would fit the whole anchor on the
+ * anchor page (Word does keep it together).
+ *
+ * The "mandatory-only" predicate catches first-line-only splits; this predicate
+ * catches partial splits (lastAnchorRenderedLines > 1 but the rest still spilled).
+ * Both feed into the same scorer trial. The scorer's accept criteria
+ * (no new cluster spills, no new mandatory-only pages, bounded dead-reserve
+ * growth, candidate rendered lines improved) still gates whether the bump
+ * actually lands.
+ */
+export const isSplitLastAnchorFootnotePage = (
+ ledger: FootnotePageLedger,
+ preferredDeltaThresholdPx = DEFAULT_PREFERRED_DELTA_THRESHOLD_PX,
+): boolean => {
+ if (ledger.anchorIds.length === 0) return false;
+ const lastAnchorId = ledger.anchorIds[ledger.anchorIds.length - 1];
+ const lastAnchorSpilled = ledger.continuationOut.some((entry) => entry.id === lastAnchorId);
+ if (!lastAnchorSpilled) return false;
+ return (
+ ledger.preferredReservePx - ledger.mandatoryReservePx > preferredDeltaThresholdPx &&
+ ledger.actualBandHeightPx < ledger.preferredReservePx - preferredDeltaThresholdPx
+ );
+};
+
+export const getPreferredReserveCandidates = (
+ ledgers: FootnotePageLedger[],
+ preferredDeltaThresholdPx = DEFAULT_PREFERRED_DELTA_THRESHOLD_PX,
+ mandatoryOnlyTolerancePx = DEFAULT_MANDATORY_ONLY_TOLERANCE_PX,
+): FootnotePreferredReserveCandidate[] => {
+ return ledgers
+ .filter(
+ (ledger) =>
+ isMandatoryOnlyFootnotePage(ledger, preferredDeltaThresholdPx, mandatoryOnlyTolerancePx) ||
+ isSplitLastAnchorFootnotePage(ledger, preferredDeltaThresholdPx),
+ )
+ .map((ledger) => ({
+ pageIndex: ledger.pageIndex,
+ anchorIds: ledger.anchorIds.slice(),
+ mandatoryReservePx: ledger.mandatoryReservePx,
+ preferredReservePx: ledger.preferredReservePx,
+ reserveDeltaPx: ledger.preferredReservePx - ledger.mandatoryReservePx,
+ actualBandHeightPx: ledger.actualBandHeightPx,
+ lastAnchorRenderedLines: ledger.lastAnchorRenderedLines,
+ }));
+};
+
+export const getPreferredReserveTrialTargets = (
+ candidate: FootnotePreferredReserveCandidate,
+ currentReservePx: number,
+ preferredDeltaThresholdPx = DEFAULT_PREFERRED_DELTA_THRESHOLD_PX,
+ maxTargets = DEFAULT_TRIAL_TARGET_COUNT,
+): number[] => {
+ const current = Number.isFinite(currentReservePx) ? Math.max(0, currentReservePx) : 0;
+ const floor = Math.max(current, candidate.mandatoryReservePx);
+ const ceiling = Math.max(floor, candidate.preferredReservePx);
+ const delta = ceiling - floor;
+ if (delta <= preferredDeltaThresholdPx) return [];
+
+ const targets = new Set();
+ const addTarget = (value: number) => {
+ if (!Number.isFinite(value)) return;
+ const rounded = Math.ceil(Math.max(floor, Math.min(ceiling, value)));
+ if (rounded - floor > preferredDeltaThresholdPx) targets.add(rounded);
+ };
+
+ // Try full preferred first, then smaller partial reserves. Full preferred is
+ // Word-like when safe, but large legal footnotes often need an intermediate
+ // target: more than firstLine, less than the whole last footnote.
+ [1, 0.75, 0.5, 0.33, 0.25, 0.15].forEach((fraction) => addTarget(floor + delta * fraction));
+ [96, 72, 48, 24, 12].forEach((px) => addTarget(floor + Math.min(delta, px)));
+
+ return Array.from(targets)
+ .sort((a, b) => b - a)
+ .slice(0, Math.max(1, maxTargets));
+};
+
+export const collectFootnoteLedgers = (layout: Layout): FootnotePageLedger[] => {
+ return layout.pages.flatMap((page) => (page.footnoteLedger ? [page.footnoteLedger] : []));
+};
+
+const getWindowBounds = (layout: Layout, candidatePageIndex: number, windowAhead: number) => ({
+ windowStart: Math.max(0, candidatePageIndex),
+ windowEnd: Math.min(layout.pages.length - 1, candidatePageIndex + Math.max(0, windowAhead)),
+});
+
+const getDocumentBounds = (layout: Layout) => ({
+ windowStart: 0,
+ windowEnd: Math.max(0, layout.pages.length - 1),
+});
+
+const isInWindow = (ledger: FootnotePageLedger, windowStart: number, windowEnd: number) =>
+ ledger.pageIndex >= windowStart && ledger.pageIndex <= windowEnd;
+
+const getLastAnchorId = (ledger: FootnotePageLedger | undefined): string | undefined => {
+ if (!ledger || ledger.anchorIds.length === 0) return undefined;
+ return ledger.anchorIds[ledger.anchorIds.length - 1];
+};
+
+const collectLedgerDiagnostics = (
+ ledgers: FootnotePageLedger[],
+ windowStart: number,
+ windowEnd: number,
+ preferredDeltaThresholdPx: number,
+ mandatoryOnlyTolerancePx: number,
+): FootnoteLedgerDiagnostics => {
+ const diagnostics: FootnoteLedgerDiagnostics = {
+ mandatoryOnlyCount: 0,
+ mandatoryOnlyAnchorIds: new Set(),
+ deadReserveSum: 0,
+ clusterSplitCount: 0,
+ clusterSplitAnchorIds: new Set(),
+ };
+
+ for (const ledger of ledgers) {
+ if (!isInWindow(ledger, windowStart, windowEnd)) continue;
+
+ diagnostics.deadReserveSum += Math.max(0, ledger.deadReservePx);
+
+ if (isMandatoryOnlyFootnotePage(ledger, preferredDeltaThresholdPx, mandatoryOnlyTolerancePx)) {
+ diagnostics.mandatoryOnlyCount += 1;
+ const id = getLastAnchorId(ledger);
+ if (id) diagnostics.mandatoryOnlyAnchorIds.add(id);
+ }
+
+ const anchorIds = new Set(ledger.anchorIds);
+ let splitsCurrentAnchorCluster = false;
+ for (const entry of ledger.continuationOut) {
+ if (!anchorIds.has(entry.id)) continue;
+ diagnostics.clusterSplitAnchorIds.add(entry.id);
+ splitsCurrentAnchorCluster = true;
+ }
+ if (splitsCurrentAnchorCluster) diagnostics.clusterSplitCount += 1;
+ }
+
+ return diagnostics;
+};
+
+const hasNewId = (after: Set, before: Set): boolean => {
+ for (const id of after) {
+ if (!before.has(id)) return true;
+ }
+ return false;
+};
+
+const getCandidateRenderedLines = (
+ ledgers: FootnotePageLedger[],
+ candidateAnchorId: string | undefined,
+): number | undefined => {
+ if (!candidateAnchorId) return undefined;
+
+ const anchorLedger = ledgers.find((ledger) => ledger.anchorIds.includes(candidateAnchorId));
+ if (!anchorLedger) return undefined;
+
+ const lastAnchorId = getLastAnchorId(anchorLedger);
+ if (lastAnchorId === candidateAnchorId) return anchorLedger.lastAnchorRenderedLines;
+
+ // If the candidate is no longer the last anchor on its page, the mandatory
+ // rule requires it to be rendered fully before the new last anchor receives
+ // only its first line. Treat that as a direct improvement over first-line
+ // rendering while still letting continuationOut checks catch impossible
+ // split states elsewhere.
+ return FULL_ANCHOR_RENDER_SENTINEL;
+};
+
+const candidateRenderedLinesImproved = (before: FootnoteWindowStats, after: FootnoteWindowStats): boolean =>
+ typeof before.candidateRenderedLines === 'number' &&
+ typeof after.candidateRenderedLines === 'number' &&
+ after.candidateRenderedLines > before.candidateRenderedLines;
+
+export const summarizeFootnoteWindow = (
+ layout: Layout,
+ ledgers: FootnotePageLedger[],
+ candidatePageIndex: number,
+ windowAhead = DEFAULT_WINDOW_AHEAD,
+ preferredDeltaThresholdPx = DEFAULT_PREFERRED_DELTA_THRESHOLD_PX,
+ mandatoryOnlyTolerancePx = DEFAULT_MANDATORY_ONLY_TOLERANCE_PX,
+ candidateAnchorId?: string,
+): FootnoteWindowStats => {
+ const { windowStart, windowEnd } = getWindowBounds(layout, candidatePageIndex, windowAhead);
+ const diagnostics = collectLedgerDiagnostics(
+ ledgers,
+ windowStart,
+ windowEnd,
+ preferredDeltaThresholdPx,
+ mandatoryOnlyTolerancePx,
+ );
+
+ return {
+ totalPages: layout.pages.length,
+ mandatoryOnlyCount: diagnostics.mandatoryOnlyCount,
+ deadReserveSum: diagnostics.deadReserveSum,
+ // A current-page anchor split is a continuation created by the page's own
+ // anchor cluster. Continuation-in from prior pages is tracked separately and
+ // is not counted here as a newly introduced split.
+ clusterSplitCount: diagnostics.clusterSplitCount,
+ candidateRenderedLines: getCandidateRenderedLines(ledgers, candidateAnchorId),
+ };
+};
+
+export const scoreFootnoteWindow = (input: FootnoteWindowScoreInput): FootnoteWindowScoreResult => {
+ const windowAhead = input.windowAhead ?? DEFAULT_WINDOW_AHEAD;
+ const preferredDeltaThresholdPx = input.preferredDeltaThresholdPx ?? DEFAULT_PREFERRED_DELTA_THRESHOLD_PX;
+ const mandatoryOnlyTolerancePx = input.mandatoryOnlyTolerancePx ?? DEFAULT_MANDATORY_ONLY_TOLERANCE_PX;
+ const deadReserveBloatThresholdPx = input.deadReserveBloatThresholdPx ?? DEFAULT_DEAD_RESERVE_BLOAT_THRESHOLD_PX;
+ const wholeDocumentDeadReserveBloatThresholdPx =
+ input.wholeDocumentDeadReserveBloatThresholdPx ?? DEFAULT_WHOLE_DOCUMENT_DEAD_RESERVE_BLOAT_THRESHOLD_PX;
+ const beforeCandidateLedger = input.beforeLedger.find((ledger) => ledger.pageIndex === input.candidatePageIndex);
+ const candidateAnchorId = input.candidateAnchorId ?? getLastAnchorId(beforeCandidateLedger);
+
+ const before = summarizeFootnoteWindow(
+ input.beforeLayout,
+ input.beforeLedger,
+ input.candidatePageIndex,
+ windowAhead,
+ preferredDeltaThresholdPx,
+ mandatoryOnlyTolerancePx,
+ candidateAnchorId,
+ );
+ const after = summarizeFootnoteWindow(
+ input.afterLayout,
+ input.afterLedger,
+ input.candidatePageIndex,
+ windowAhead,
+ preferredDeltaThresholdPx,
+ mandatoryOnlyTolerancePx,
+ candidateAnchorId,
+ );
+ const beforeBounds = getWindowBounds(input.beforeLayout, input.candidatePageIndex, windowAhead);
+ const afterBounds = getWindowBounds(input.afterLayout, input.candidatePageIndex, windowAhead);
+ const beforeWindowDiagnostics = collectLedgerDiagnostics(
+ input.beforeLedger,
+ beforeBounds.windowStart,
+ beforeBounds.windowEnd,
+ preferredDeltaThresholdPx,
+ mandatoryOnlyTolerancePx,
+ );
+ const afterWindowDiagnostics = collectLedgerDiagnostics(
+ input.afterLedger,
+ afterBounds.windowStart,
+ afterBounds.windowEnd,
+ preferredDeltaThresholdPx,
+ mandatoryOnlyTolerancePx,
+ );
+ const beforeDocumentBounds = getDocumentBounds(input.beforeLayout);
+ const afterDocumentBounds = getDocumentBounds(input.afterLayout);
+ const beforeDocumentDiagnostics = collectLedgerDiagnostics(
+ input.beforeLedger,
+ beforeDocumentBounds.windowStart,
+ beforeDocumentBounds.windowEnd,
+ preferredDeltaThresholdPx,
+ mandatoryOnlyTolerancePx,
+ );
+ const afterDocumentDiagnostics = collectLedgerDiagnostics(
+ input.afterLedger,
+ afterDocumentBounds.windowStart,
+ afterDocumentBounds.windowEnd,
+ preferredDeltaThresholdPx,
+ mandatoryOnlyTolerancePx,
+ );
+
+ // SD-2656 (Vivienne feedback): a trial that ELIMINATES a cluster split is a
+ // direct user-visible win. Trade a larger dead-reserve growth for fewer
+ // footnotes splitting across pages. Without this relaxation the scorer
+ // accepts a smaller partial bump that improves mandatory-only count but
+ // leaves the split intact — the user sees no change.
+ const eliminatesSplitInWindow = beforeWindowDiagnostics.clusterSplitCount > afterWindowDiagnostics.clusterSplitCount;
+ const eliminatesSplitInDoc = beforeDocumentDiagnostics.clusterSplitCount > afterDocumentDiagnostics.clusterSplitCount;
+
+ if (after.totalPages > before.totalPages) {
+ // SD-2656 (post-Vivienne+Carlsbad p43): allow exactly +1 page when the
+ // trial eliminates a doc-level cluster split. Mirrors Word's behavior of
+ // growing the document by one page to keep a footnote together when body
+ // content is densely packed. Larger growth caps measured no improvement
+ // on Carlsbad (4 remaining splits hit other gates regardless).
+ const grewByOne = after.totalPages === before.totalPages + 1;
+ if (!(grewByOne && eliminatesSplitInDoc)) {
+ return { accept: false, reason: 'page-count-grew', before, after };
+ }
+ }
+ if (
+ after.clusterSplitCount > before.clusterSplitCount ||
+ hasNewId(afterWindowDiagnostics.clusterSplitAnchorIds, beforeWindowDiagnostics.clusterSplitAnchorIds)
+ ) {
+ return { accept: false, reason: 'cluster-spill', before, after };
+ }
+ if (
+ afterDocumentDiagnostics.clusterSplitAnchorIds.size > beforeDocumentDiagnostics.clusterSplitAnchorIds.size ||
+ hasNewId(afterDocumentDiagnostics.clusterSplitAnchorIds, beforeDocumentDiagnostics.clusterSplitAnchorIds)
+ ) {
+ return { accept: false, reason: 'cluster-spill', before, after };
+ }
+ if (hasNewId(afterWindowDiagnostics.mandatoryOnlyAnchorIds, beforeWindowDiagnostics.mandatoryOnlyAnchorIds)) {
+ return { accept: false, reason: 'new-mandatory-only', before, after };
+ }
+ if (hasNewId(afterDocumentDiagnostics.mandatoryOnlyAnchorIds, beforeDocumentDiagnostics.mandatoryOnlyAnchorIds)) {
+ return { accept: false, reason: 'new-mandatory-only', before, after };
+ }
+ const windowDeadAllowance = eliminatesSplitInWindow ? deadReserveBloatThresholdPx * 2 : deadReserveBloatThresholdPx;
+ const docDeadAllowance = eliminatesSplitInDoc
+ ? wholeDocumentDeadReserveBloatThresholdPx * 2
+ : wholeDocumentDeadReserveBloatThresholdPx;
+
+ if (after.deadReserveSum > before.deadReserveSum + windowDeadAllowance) {
+ return { accept: false, reason: 'dead-reserve-bloat', before, after };
+ }
+ if (afterDocumentDiagnostics.deadReserveSum > beforeDocumentDiagnostics.deadReserveSum + docDeadAllowance) {
+ return { accept: false, reason: 'dead-reserve-bloat', before, after };
+ }
+ if (!candidateRenderedLinesImproved(before, after)) {
+ return { accept: false, reason: 'candidate-not-improved', before, after };
+ }
+
+ return { accept: true, reason: 'globally-safe', before, after };
+};
diff --git a/packages/layout-engine/layout-bridge/src/incrementalLayout.ts b/packages/layout-engine/layout-bridge/src/incrementalLayout.ts
index 73390f3601..d035f504f8 100644
--- a/packages/layout-engine/layout-bridge/src/incrementalLayout.ts
+++ b/packages/layout-engine/layout-bridge/src/incrementalLayout.ts
@@ -1,5 +1,6 @@
import type {
FlowBlock,
+ FootnotePageLedger,
Layout,
Measure,
HeaderFooterLayout,
@@ -33,6 +34,7 @@ import {
import { FeatureFlags } from './featureFlags';
import { PageTokenLogger, HeaderFooterCacheLogger, globalMetrics } from './instrumentation';
import { HeaderFooterCacheState, invalidateHeaderFooterCache } from './cacheInvalidation';
+import { getPreferredReserveCandidates, getPreferredReserveTrialTargets, scoreFootnoteWindow } from './footnote-scorer';
export type HeaderFooterMeasureFn = (
block: FlowBlock,
@@ -320,6 +322,15 @@ const computeMaxFootnoteReserve = (layoutForPages: Layout, pageIndex: number, ba
const bottomWithReserve = normalizeMargin(page.margins?.bottom, DEFAULT_MARGINS.bottom);
const baseReserveSafe = Number.isFinite(baseReserve) ? Math.max(0, baseReserve) : 0;
const bottomMargin = Math.max(0, bottomWithReserve - baseReserveSafe);
+ // SD-2656: in the bodyMaxY-anchored band architecture, the actual band
+ // capacity is `pageH - bottomMargin - bodyMaxY`. Using this as the planner's
+ // maxReserve forces the planner to split (continuation) any fn body that
+ // can't fit under body's actual position — which is what Word does.
+ // Falls back to the legacy calc for pages without recorded bodyMaxY.
+ const bodyMaxY = (page as { bodyMaxY?: number }).bodyMaxY;
+ if (typeof bodyMaxY === 'number' && Number.isFinite(bodyMaxY) && bodyMaxY > topMargin) {
+ return Math.max(0, pageSize.h - bottomMargin - bodyMaxY);
+ }
const availableForBody = pageSize.h - topMargin - bottomMargin;
if (!Number.isFinite(availableForBody)) return 0;
return Math.max(0, availableForBody - MIN_FOOTNOTE_BODY_HEIGHT);
@@ -365,6 +376,30 @@ type FootnoteLayoutPlan = {
reserves: number[];
hasContinuationByColumn: Map;
separatorSpacingBefore: number;
+ // SD-2656 Phase 0: per-page ledger data captured during planning. The
+ // planner is the only place that knows mandatorySlices vs continuationSlices
+ // vs extendedSlices and the continuation in/out queues — surface that here
+ // so injectFragments can attach it to each Page object.
+ ledgersByPage: Map;
+};
+
+/**
+ * Planner-emitted per-page ledger fragments. Combined with the applied body
+ * reserve at injection time to form the full FootnotePageLedger.
+ */
+type FootnotePageLedgerDraft = {
+ anchorIds: string[];
+ mandatorySliceIds: string[];
+ continuationSliceIds: string[];
+ extendedSliceIds: string[];
+ continuationIn: Array<{ id: string; remainingRangeCount: number; remainingHeightPx: number }>;
+ continuationOut: Array<{ id: string; remainingRangeCount: number; remainingHeightPx: number }>;
+ mandatoryReservePx: number;
+ /** SD-2656 Phase 7: Word-like preferred reserve = full(non-last) + full(last) + overhead. */
+ preferredReservePx: number;
+ actualBandHeightPx: number;
+ /** Number of measured lines rendered for the last anchor on this page (0 if no cluster). */
+ lastAnchorRenderedLines: number;
};
const sumLineHeights = (
@@ -542,9 +577,17 @@ const splitRangeAtHeight = (
};
if (splitLine >= range.toLine) {
- return getRangeRenderHeight(fitted) <= availableHeight
- ? { fitted, remaining: null }
- : { fitted: null, remaining: range };
+ // SD-2656: when all lines fit, return the fitted range regardless of
+ // spacingAfter. spacingAfter is the gap to the *next* paragraph; for
+ // the last item placed in a band slice it shouldn't be charged against
+ // the available height. Without this, a single-fn band whose body lines
+ // fit exactly but whose post-paragraph spacing pushes the total over
+ // the limit gets force-split (1 line placed + 3 lines continuation),
+ // which is what caused the reference fixture's last fn to drip across 2 pages.
+ if (fitted.height <= availableHeight) {
+ return { fitted, remaining: null };
+ }
+ return { fitted: null, remaining: range };
}
const remaining: FootnoteRange = {
@@ -616,9 +659,18 @@ const fitFootnoteContent = (
if (range.kind === 'paragraph') {
const split = splitRangeAtHeight(range, remainingSpace, measuresById);
- if (split.fitted && getRangeRenderHeight(split.fitted) <= remainingSpace) {
- fittedRanges.push(split.fitted);
- usedHeight += getRangeRenderHeight(split.fitted);
+ if (split.fitted) {
+ // SD-2656: charge only the fitted *body* height (no spacingAfter)
+ // when the fitted range completes the input — it's the last item in
+ // this band slice, so trailing paragraph spacing is wasted. This
+ // matches the relaxed check inside splitRangeAtHeight above.
+ const fittedBodyHeight = split.fitted.height;
+ const fittedFullHeight = getRangeRenderHeight(split.fitted);
+ const charged = !split.remaining ? fittedBodyHeight : fittedFullHeight;
+ if (charged <= remainingSpace) {
+ fittedRanges.push(split.fitted);
+ usedHeight += charged;
+ }
}
if (split.remaining) {
remainingRanges = [split.remaining, ...inputRanges.slice(index + 1)];
@@ -767,9 +819,7 @@ export async function incrementalLayout(
}
// Dirty region computation
- const dirtyStart = performance.now();
const dirty = computeDirtyRegions(previousBlocks, nextBlocks);
- const dirtyTime = performance.now() - dirtyStart;
if (dirty.deletedBlockIds.length > 0) {
measureCache.invalidate(dirty.deletedBlockIds);
@@ -1171,8 +1221,6 @@ export async function incrementalLayout(
const layoutTime = layoutEnd - layoutStart;
perfLog(`[Perf] 4.2 Layout document (pagination): ${layoutTime.toFixed(2)}ms`);
- const pageCount = layout.pages.length;
-
// Two-pass convergence loop for page number token resolution.
// Steps: paginate -> build numbering context -> resolve PAGE/NUMPAGES tokens
// -> remeasure affected blocks -> re-paginate -> repeat until stable
@@ -1318,7 +1366,9 @@ export async function incrementalLayout(
const safeTopPadding = Math.max(0, topPadding);
const safeDividerHeight = Math.max(0, dividerHeight);
const continuationDividerHeight = safeDividerHeight;
- const continuationDividerWidthFactor = 0.3;
+ // §17.11.23 w:separator — "spans part of the width text extents"
+ // §17.11.1 w:continuationSeparator — "spans the width of the main story's text extents"
+ const SEPARATOR_DEFAULT_WIDTH_FACTOR = 0.5;
const footnoteWidth = resolveFootnoteMeasurementWidth(options, currentBlocks);
if (footnoteWidth > 0) {
@@ -1375,6 +1425,8 @@ export async function incrementalLayout(
const hasContinuationByColumn = new Map();
const rangesByFootnoteId = new Map();
const cappedPages = new Set();
+ // SD-2656 Phase 0: per-page ledger drafts captured during planning.
+ const ledgersByPage = new Map();
const allIds = collectFootnoteIdsByColumn(idsByColumn);
allIds.forEach((id) => {
@@ -1406,25 +1458,29 @@ export async function incrementalLayout(
// the footnotes actually need, the body grows its reserve to match on the next
// pass, and placement never exceeds maxReserve so footnotes cannot render past
// the page's bottom margin.
- let demand = 0;
- for (let columnIndex = 0; columnIndex < columnCount; columnIndex += 1) {
- const ids = idsByColumn.get(pageIndex)?.get(columnIndex) ?? [];
- let columnDemand = 0;
- ids.forEach((id, idx) => {
- const ranges = rangesByFootnoteId.get(id) ?? [];
- let rangesHeight = 0;
- ranges.forEach((range) => {
- const spacingAfter = 'spacingAfter' in range ? (range.spacingAfter ?? 0) : 0;
- rangesHeight += range.height + spacingAfter;
- });
- columnDemand += rangesHeight + (idx > 0 ? safeGap : 0);
+ // SD-2656: placement ceiling = maxReserve (the actual band capacity
+ // left by the body after its ordered-cluster reservation).
+ const placementCeiling = maxReserve;
+
+ // SD-2656: per-footnote full and first-line heights, used to
+ // estimate next-page cluster demand for the carry-forward bump.
+ const fullHeightOf = (id: string): number => {
+ const ranges = rangesByFootnoteId.get(id) ?? [];
+ let total = 0;
+ ranges.forEach((range) => {
+ const spacingAfter = 'spacingAfter' in range ? (range.spacingAfter ?? 0) : 0;
+ total += range.height + spacingAfter;
});
- if (columnDemand > 0) {
- columnDemand += safeSeparatorSpacingBefore + safeDividerHeight + safeTopPadding;
+ return total;
+ };
+ const firstLineOf = (id: string): number => {
+ const measured = firstLineHeightById.get(id);
+ if (typeof measured === 'number' && Number.isFinite(measured) && measured > 0) {
+ return measured;
}
- if (columnDemand > demand) demand = columnDemand;
- }
- const placementCeiling = demand > 0 ? Math.min(Math.ceil(demand), maxReserve) : maxReserve;
+ const ranges = rangesByFootnoteId.get(id) ?? [];
+ return ranges.length > 0 ? ranges[0].height : 0;
+ };
const pendingForPage = new Map>();
pendingByColumn.forEach((entries, columnIndex) => {
@@ -1433,6 +1489,25 @@ export async function incrementalLayout(
list.push(...entries);
pendingForPage.set(targetIndex, list);
});
+ // SD-2656 Phase 0: capture continuationIn for the ledger BEFORE we
+ // start placing on this page (pendingForPage will be consumed by
+ // placement).
+ const continuationInForPage: Array<{ id: string; remainingRangeCount: number; remainingHeightPx: number }> =
+ [];
+ pendingForPage.forEach((entries) => {
+ entries.forEach((entry) => {
+ let total = 0;
+ entry.ranges.forEach((range) => {
+ const spacingAfter = 'spacingAfter' in range ? (range.spacingAfter ?? 0) : 0;
+ total += range.height + spacingAfter;
+ });
+ continuationInForPage.push({
+ id: entry.id,
+ remainingRangeCount: entry.ranges.length,
+ remainingHeightPx: total,
+ });
+ });
+ });
pendingByColumn = new Map();
const pageSlices: FootnoteSlice[] = [];
@@ -1442,13 +1517,20 @@ export async function incrementalLayout(
let usedHeight = 0;
const columnSlices: FootnoteSlice[] = [];
const nextPending: Array<{ id: string; ranges: FootnoteRange[] }> = [];
- let stopPlacement = false;
const columnKey = footnoteColumnKey(pageIndex, columnIndex);
+ // SD-2656: planner enforcement of the ordered-cluster rule. For
+ // new anchors that are NOT the last on this page, partial
+ // placement is forbidden — they must fit fully, otherwise the
+ // body reserved space for `full(non-last)` that the planner
+ // would waste on a single line. For the LAST anchor (and for
+ // incoming continuations), forceFirst keeps the existing
+ // behavior (place at least one slice when budget allows).
const placeFootnote = (
id: string,
ranges: FootnoteRange[],
isContinuation: boolean,
+ isLastOnPage: boolean,
): { placed: boolean; remaining: FootnoteRange[] } => {
if (!ranges || ranges.length === 0) {
return { placed: false, remaining: [] };
@@ -1464,6 +1546,15 @@ export async function incrementalLayout(
const overhead = isFirstSlice ? separatorBefore + separatorHeight + safeTopPadding : 0;
const gapBefore = !isFirstSlice ? safeGap : 0;
const availableHeight = Math.max(0, placementCeiling - usedHeight - overhead - gapBefore);
+ // SD-2656: forceFirst applies whenever the anchor is allowed to
+ // split — i.e. the LAST anchor on the cluster (rule), or a
+ // continuation draining leftover space. Not gated on
+ // isFirstSlice — the last anchor is usually placed AFTER its
+ // non-last siblings, so it's rarely the first slice on the
+ // column. Without this, fn N on a cluster of [A..N-1, N] fails
+ // to render its first line and the rule "last anchor renders
+ // at least firstLine" is violated.
+ const allowForceFirst = (isLastOnPage || isContinuation) && placementCeiling > 0;
const { slice, remainingRanges } = fitFootnoteContent(
id,
ranges,
@@ -1472,12 +1563,18 @@ export async function incrementalLayout(
columnIndex,
isContinuation,
measuresById,
- isFirstSlice && placementCeiling > 0,
+ allowForceFirst,
);
if (slice.ranges.length === 0) {
return { placed: false, remaining: ranges };
}
+ // Non-last new anchor that only partially fit: refuse the
+ // placement entirely. The whole anchor defers to the next page
+ // so the rule "non-last anchors complete on their page" holds.
+ if (!isLastOnPage && !isContinuation && remainingRanges.length > 0) {
+ return { placed: false, remaining: ranges };
+ }
if (isFirstSlice) {
usedHeight += overhead;
@@ -1494,44 +1591,61 @@ export async function incrementalLayout(
return { placed: true, remaining: remainingRanges };
};
+ // SD-2656: reserve cluster room BEFORE placing continuations, so
+ // a huge incoming continuation can't eat the band and starve the
+ // current page's cluster. Continuations render at the TOP of the
+ // band (Word's order) because we place them first onto
+ // columnSlices, but their availableHeight is capped at
+ // (placementCeiling - clusterReserve).
+ const ids = idsByColumn.get(pageIndex)?.get(columnIndex) ?? [];
+ const lastIdx = ids.length - 1;
+ let clusterReserve = 0;
+ for (let i = 0; i < ids.length; i += 1) {
+ const isLast = i === lastIdx;
+ clusterReserve += isLast ? firstLineOf(ids[i]) : fullHeightOf(ids[i]);
+ if (i > 0) clusterReserve += safeGap;
+ }
+
+ // Continuations first (visual top). Pretend cluster's room is
+ // already used so placeFootnote sees the lowered ceiling.
+ usedHeight += clusterReserve;
const pending = pendingForPage.get(columnIndex) ?? [];
- for (const entry of pending) {
- if (stopPlacement) {
- nextPending.push(entry);
- continue;
- }
+ for (let pendingIdx = 0; pendingIdx < pending.length; pendingIdx += 1) {
+ const entry = pending[pendingIdx];
if (!entry.ranges || entry.ranges.length === 0) continue;
- const result = placeFootnote(entry.id, entry.ranges, true);
+ const result = placeFootnote(entry.id, entry.ranges, true, false);
if (!result.placed) {
- nextPending.push(entry);
- stopPlacement = true;
- continue;
+ // Continuation doesn't fit alongside the cluster reservation
+ // — defer this and all later continuations to preserve order.
+ for (let deferIdx = pendingIdx; deferIdx < pending.length; deferIdx += 1) {
+ nextPending.push(pending[deferIdx]);
+ }
+ break;
}
if (result.remaining.length > 0) {
nextPending.push({ id: entry.id, ranges: result.remaining });
}
}
+ usedHeight -= clusterReserve;
- if (!stopPlacement) {
- const ids = idsByColumn.get(pageIndex)?.get(columnIndex) ?? [];
- for (let idIndex = 0; idIndex < ids.length; idIndex += 1) {
- const id = ids[idIndex];
- const ranges = rangesByFootnoteId.get(id) ?? [];
- if (ranges.length === 0) continue;
- const result = placeFootnote(id, ranges, false);
- if (!result.placed) {
- nextPending.push({ id, ranges });
- for (let remainingIndex = idIndex + 1; remainingIndex < ids.length; remainingIndex += 1) {
- const remainingId = ids[remainingIndex];
- const remainingRanges = rangesByFootnoteId.get(remainingId) ?? [];
- nextPending.push({ id: remainingId, ranges: remainingRanges });
- }
- stopPlacement = true;
- break;
- }
- if (result.remaining.length > 0) {
- nextPending.push({ id, ranges: result.remaining });
+ // New anchors second (visual bottom).
+ for (let idIndex = 0; idIndex < ids.length; idIndex += 1) {
+ const id = ids[idIndex];
+ const ranges = rangesByFootnoteId.get(id) ?? [];
+ if (ranges.length === 0) continue;
+ const isLastOnPage = idIndex === lastIdx;
+ const result = placeFootnote(id, ranges, false, isLastOnPage);
+ if (!result.placed) {
+ nextPending.push({ id, ranges });
+ for (let remainingIndex = idIndex + 1; remainingIndex < ids.length; remainingIndex += 1) {
+ const remainingId = ids[remainingIndex];
+ const remainingRanges = rangesByFootnoteId.get(remainingId) ?? [];
+ nextPending.push({ id: remainingId, ranges: remainingRanges });
}
+ break;
+ }
+ if (result.remaining.length > 0) {
+ nextPending.push({ id, ranges: result.remaining });
}
}
@@ -1553,7 +1667,208 @@ export async function incrementalLayout(
if (pageSlices.length > 0) {
slicesByPage.set(pageIndex, pageSlices);
}
- reserves[pageIndex] = pageReserve;
+ // SD-2656: MAX with any pre-existing value (set by an earlier
+ // page's pending-continuation bump) so we don't overwrite the
+ // bumped reserve.
+ reserves[pageIndex] = Math.max(reserves[pageIndex] ?? 0, pageReserve);
+
+ // SD-2656 Phase 0: build the per-page ledger draft. The planner is
+ // the only place that knows which slices were placed as
+ // continuations vs new anchors and what continuationOut carries to
+ // the next page. injectFragments combines this with the applied
+ // body reserve to populate page.footnoteLedger.
+ {
+ const idsOnPage = (() => {
+ const out: string[] = [];
+ for (let cIdx = 0; cIdx < columnCount; cIdx += 1) {
+ const colIds = idsByColumn.get(pageIndex)?.get(cIdx) ?? [];
+ for (const id of colIds) if (!out.includes(id)) out.push(id);
+ }
+ return out;
+ })();
+
+ // Slice classification: mandatorySlice = first placed slice of
+ // each new anchor (the rule's "render at least firstLine of
+ // last + full of non-last" is satisfied by the union of these);
+ // extendedSlice = subsequent slices of the same new anchor;
+ // continuationSlice = isContinuation slices (from prior pages).
+ const seenNewAnchor = new Set();
+ const mandatorySliceIds: string[] = [];
+ const continuationSliceIds: string[] = [];
+ const extendedSliceIds: string[] = [];
+ let actualBandHeight = 0;
+ const safeSepBefore = Math.max(0, separatorSpacingBefore);
+ const overheadBase = safeSepBefore + safeDividerHeight + safeTopPadding;
+ for (const slice of pageSlices) {
+ if (slice.isContinuation) {
+ continuationSliceIds.push(slice.id);
+ } else if (!seenNewAnchor.has(slice.id)) {
+ mandatorySliceIds.push(slice.id);
+ seenNewAnchor.add(slice.id);
+ } else {
+ extendedSliceIds.push(slice.id);
+ }
+ actualBandHeight += slice.totalHeight;
+ }
+ if (pageSlices.length > 0) {
+ actualBandHeight += overheadBase + safeGap * Math.max(0, pageSlices.length - 1);
+ }
+
+ // Mandatory reserve = full of non-last + firstLine of last for
+ // the page's anchor cluster (regardless of how the planner
+ // actually placed them — this is what the rule requires).
+ let mandatoryReserve = 0;
+ // SD-2656 Phase 7: Preferred reserve = full of every anchor on the
+ // cluster (Word-like — last anchor also renders fully when room
+ // exists). Body slicer may choose this when safe.
+ let preferredReserve = 0;
+ // SD-2656 (post-Vivienne Carlsbad p22): Any continuation flowing
+ // INTO this page (from a prior page's spill) must also fit on this
+ // page — it can't move anywhere else. Include it in BOTH reserves
+ // so the scorer's preferred target is large enough to actually
+ // fit the full cluster alongside the carry-over content.
+ let continuationInHeight = 0;
+ for (const entry of continuationInForPage) {
+ continuationInHeight += entry.remainingHeightPx;
+ }
+ if (continuationInHeight > 0) {
+ mandatoryReserve += continuationInHeight;
+ preferredReserve += continuationInHeight;
+ if (idsOnPage.length > 0) {
+ mandatoryReserve += safeGap;
+ preferredReserve += safeGap;
+ }
+ }
+ if (idsOnPage.length > 0) {
+ for (let i = 0; i < idsOnPage.length; i += 1) {
+ const isLast = i === idsOnPage.length - 1;
+ mandatoryReserve += isLast ? firstLineOf(idsOnPage[i]) : fullHeightOf(idsOnPage[i]);
+ preferredReserve += fullHeightOf(idsOnPage[i]);
+ if (i > 0) {
+ mandatoryReserve += safeGap;
+ preferredReserve += safeGap;
+ }
+ }
+ mandatoryReserve += overheadBase;
+ preferredReserve += overheadBase;
+ } else if (continuationInHeight > 0) {
+ // Continuation-only page (no new anchors). Still needs overhead.
+ mandatoryReserve += overheadBase;
+ preferredReserve += overheadBase;
+ }
+
+ // SD-2656 Phase 7: how many measured lines of the last anchor we
+ // actually rendered. Used to flag "mandatory-only" pages where
+ // Word would have rendered more of the last footnote.
+ let lastAnchorRenderedLines = 0;
+ if (idsOnPage.length > 0) {
+ const lastId = idsOnPage[idsOnPage.length - 1];
+ for (const slice of pageSlices) {
+ if (slice.id !== lastId || slice.isContinuation) continue;
+ for (const range of slice.ranges) {
+ // Only paragraph and list-item ranges have line tracking;
+ // table/image/drawing footnote ranges are single blocks.
+ if (range.kind === 'paragraph' || range.kind === 'list-item') {
+ lastAnchorRenderedLines += Math.max(0, range.toLine - range.fromLine);
+ } else {
+ lastAnchorRenderedLines += 1;
+ }
+ }
+ }
+ }
+
+ // continuationOut: what we just deferred to the next page.
+ const continuationOut: Array<{ id: string; remainingRangeCount: number; remainingHeightPx: number }> = [];
+ pendingByColumn.forEach((entries) => {
+ entries.forEach((entry) => {
+ let total = 0;
+ entry.ranges.forEach((range) => {
+ const spacingAfter = 'spacingAfter' in range ? (range.spacingAfter ?? 0) : 0;
+ total += range.height + spacingAfter;
+ });
+ continuationOut.push({
+ id: entry.id,
+ remainingRangeCount: entry.ranges.length,
+ remainingHeightPx: total,
+ });
+ });
+ });
+
+ ledgersByPage.set(pageIndex, {
+ anchorIds: idsOnPage,
+ mandatorySliceIds,
+ continuationSliceIds,
+ extendedSliceIds,
+ continuationIn: continuationInForPage,
+ continuationOut,
+ mandatoryReservePx: Math.ceil(mandatoryReserve),
+ preferredReservePx: Math.ceil(preferredReserve),
+ actualBandHeightPx: Math.ceil(actualBandHeight),
+ lastAnchorRenderedLines,
+ });
+ }
+
+ // SD-2656 Phase 3: bounded continuation draining.
+ //
+ // The carry-forward bump gives the next page enough room for
+ // (a) its own cluster (mandatory by the rule), AND
+ // (b) the portion of the inbound continuation that can
+ // realistically fit alongside (a) on the next page.
+ //
+ // Previously we summed continuationDemand + nextClusterDemand
+ // capped at physical body area. That over-reserved when the
+ // continuation chain was longer than one page: the next page
+ // couldn't drain ALL of it anyway, so reserving the whole chain
+ // just inflated dead reserve. Overflow now propagates naturally:
+ // any continuation beyond next-page capacity stays in
+ // pendingByColumn and lands on page+2, page+3, etc.
+ if (pageIndex + 1 < pageCount) {
+ let continuationDemand = 0;
+ pendingByColumn.forEach((entries) => {
+ entries.forEach((entry) => {
+ entry.ranges.forEach((range) => {
+ const spacingAfter = 'spacingAfter' in range ? (range.spacingAfter ?? 0) : 0;
+ continuationDemand += range.height + spacingAfter;
+ });
+ });
+ });
+ // Next page's mandatory cluster demand (ordered minimum).
+ let nextClusterDemand = 0;
+ for (let cIdx = 0; cIdx < columnCount; cIdx += 1) {
+ const idsNext = idsByColumn.get(pageIndex + 1)?.get(cIdx) ?? [];
+ if (idsNext.length === 0) continue;
+ let columnCluster = 0;
+ for (let i = 0; i < idsNext.length; i += 1) {
+ const isLast = i === idsNext.length - 1;
+ columnCluster += isLast ? firstLineOf(idsNext[i]) : fullHeightOf(idsNext[i]);
+ if (i > 0) columnCluster += safeGap;
+ }
+ if (columnCluster > nextClusterDemand) nextClusterDemand = columnCluster;
+ }
+ if (continuationDemand > 0 || nextClusterDemand > 0) {
+ const overhead = safeSeparatorSpacingBefore + continuationDividerHeight + safeTopPadding;
+ const nextPage = layoutForPages.pages?.[pageIndex + 1];
+ const nextPageSize = nextPage?.size ?? layoutForPages.pageSize ?? DEFAULT_PAGE_SIZE;
+ const nextTop = normalizeMargin(nextPage?.margins?.top, DEFAULT_MARGINS.top);
+ const nextBottomRaw = normalizeMargin(nextPage?.margins?.bottom, DEFAULT_MARGINS.bottom);
+ const physicalContentHeight = Math.max(0, nextPageSize.h - nextTop - nextBottomRaw);
+ const minBodyHeight = MIN_FOOTNOTE_BODY_HEIGHT * 20;
+ const nextPageMaxBand = Math.max(0, physicalContentHeight - minBodyHeight);
+ // The band has a single overhead block (separator + padding)
+ // whether or not we have a cluster.
+ const overheadForBand = nextClusterDemand > 0 || continuationDemand > 0 ? overhead : 0;
+ // Mandatory cluster room (cluster slices only, no overhead).
+ const clusterRoomPx =
+ nextClusterDemand > 0 ? Math.min(nextClusterDemand, Math.max(0, nextPageMaxBand - overheadForBand)) : 0;
+ // Continuation room = whatever's left after cluster + overhead.
+ const continuationRoomPx = Math.max(0, nextPageMaxBand - overheadForBand - clusterRoomPx);
+ const continuationToReservePx = Math.min(continuationDemand, continuationRoomPx);
+ // Final reserve: cluster + continuation + single overhead block,
+ // clamped at the physical band cap.
+ const finalReserve = Math.min(clusterRoomPx + continuationToReservePx + overheadForBand, nextPageMaxBand);
+ reserves[pageIndex + 1] = Math.max(reserves[pageIndex + 1] ?? 0, Math.ceil(finalReserve));
+ }
+ }
}
if (cappedPages.size > 0) {
@@ -1569,7 +1884,13 @@ export async function incrementalLayout(
});
}
- return { slicesByPage, reserves, hasContinuationByColumn, separatorSpacingBefore: safeSeparatorSpacingBefore };
+ return {
+ slicesByPage,
+ reserves,
+ hasContinuationByColumn,
+ separatorSpacingBefore: safeSeparatorSpacingBefore,
+ ledgersByPage,
+ };
};
const injectFragments = (
@@ -1586,6 +1907,27 @@ export async function incrementalLayout(
for (let pageIndex = 0; pageIndex < layoutForPages.pages.length; pageIndex++) {
const page = layoutForPages.pages[pageIndex];
page.footnoteReserved = Math.max(0, reservesByPageIndex[pageIndex] ?? plan.reserves[pageIndex] ?? 0);
+ // SD-2656 Phase 0: attach the per-page ledger. Combine the planner
+ // draft with the applied body reserve we just stamped. This is the
+ // single source of truth that Phase 1+ will read.
+ const draft = plan.ledgersByPage.get(pageIndex);
+ if (draft) {
+ page.footnoteLedger = {
+ pageIndex,
+ anchorIds: draft.anchorIds,
+ mandatorySliceIds: draft.mandatorySliceIds,
+ continuationSliceIds: draft.continuationSliceIds,
+ extendedSliceIds: draft.extendedSliceIds,
+ continuationIn: draft.continuationIn,
+ continuationOut: draft.continuationOut,
+ mandatoryReservePx: draft.mandatoryReservePx,
+ preferredReservePx: draft.preferredReservePx,
+ actualBandHeightPx: draft.actualBandHeightPx,
+ appliedBodyReservePx: page.footnoteReserved ?? 0,
+ deadReservePx: Math.max(0, (page.footnoteReserved ?? 0) - draft.actualBandHeightPx),
+ lastAnchorRenderedLines: draft.lastAnchorRenderedLines,
+ };
+ }
const slices = plan.slicesByPage.get(pageIndex) ?? [];
if (slices.length === 0) continue;
if (!page.margins) continue;
@@ -1609,7 +1951,26 @@ export async function incrementalLayout(
left: marginLeft,
contentWidth: pageContentWidth,
};
- const bandTopY = pageSize.h - (page.margins.bottom ?? 0);
+ // SD-2656: Word anchors the footnote band to the page's bottom
+ // margin (band bottom = pageH - originalBottomMargin), with any
+ // slack appearing as whitespace BETWEEN body and band. Our previous
+ // approach (band top = bodyMaxY) inverted that — whitespace landed
+ // BELOW the band instead, visibly different from Word on every
+ // page with a non-full band. We bottom-anchor per column, with
+ // bodyMaxY as a safety floor for the dense case (band would
+ // otherwise overlap body when planner-placed content fills the
+ // available reserve).
+ //
+ // `page.margins.bottom` is the convergence-inflated value (original
+ // + reserve). The original bottom margin is therefore margins.bottom
+ // minus the per-page reserve we just stashed.
+ const physicalBottomMargin = Math.max(0, (page.margins.bottom ?? 0) - (page.footnoteReserved ?? 0));
+ const pageBottomLimit = pageSize.h - physicalBottomMargin;
+ const bodyMaxYValue = (page as { bodyMaxY?: number }).bodyMaxY;
+ const bodyMaxY =
+ typeof bodyMaxYValue === 'number' && Number.isFinite(bodyMaxYValue)
+ ? bodyMaxYValue
+ : pageSize.h - (page.margins.bottom ?? 0);
const slicesByColumn = new Map();
slices.forEach((slice) => {
@@ -1630,12 +1991,24 @@ export async function incrementalLayout(
const columnKey = footnoteColumnKey(pageIndex, columnIndex);
const isContinuation = plan.hasContinuationByColumn.get(columnKey) ?? false;
+ // SD-2656: compute this column's total band height so we can
+ // bottom-anchor it (Word-style). totalBandHeight matches the
+ // planner's demand calc: separator-before + divider + top-padding
+ // + sum(slice heights) + gap-between-slices.
+ const colSeparatorHeight = isContinuation ? continuationDividerHeight : safeDividerHeight;
+ let colTotalBandHeight = Math.max(0, plan.separatorSpacingBefore) + colSeparatorHeight + safeTopPadding;
+ for (let s = 0; s < columnSlices.length; s += 1) {
+ colTotalBandHeight += columnSlices[s].totalHeight;
+ if (s > 0) colTotalBandHeight += safeGap;
+ }
+ const bandTopY = Math.max(bodyMaxY, pageBottomLimit - colTotalBandHeight);
+
// Optional visible separator line (Word-like). Uses a 1px filled rect.
let cursorY = bandTopY + Math.max(0, plan.separatorSpacingBefore);
const separatorHeight = isContinuation ? continuationDividerHeight : safeDividerHeight;
const separatorWidth = isContinuation
- ? Math.max(0, contentWidth * continuationDividerWidthFactor)
- : contentWidth;
+ ? contentWidth
+ : Math.max(0, contentWidth * SEPARATOR_DEFAULT_WIDTH_FACTOR);
if (separatorHeight > 0 && separatorWidth > 0) {
const separatorId = isContinuation
? `footnote-continuation-separator-page-${page.number}-col-${columnIndex}`
@@ -1815,10 +2188,83 @@ export async function incrementalLayout(
return { columns, idsByColumn };
};
- const relayout = (footnoteReservedByPageIndex: number[]) =>
+ // SD-3049: per-footnote total body height; accounting mirrors `computeFootnoteLayoutPlan`.
+ // SD-2656: alongside the total, compute the first valid line/run height
+ // so the body slicer can apply the ordered-cluster demand model.
+ let bodyHeightById = new Map();
+ let firstLineHeightById = new Map();
+ const refreshBodyHeights = (measures: Map) => {
+ const totalMap = new Map();
+ const firstLineMap = new Map();
+ footnotesInput.blocksById.forEach((blocks, footnoteId) => {
+ let total = 0;
+ let firstLine = 0;
+ for (const block of blocks) {
+ const measure = measures.get(block.id);
+ if (!measure) continue;
+ if (measure.kind === 'paragraph') {
+ const measureH = (measure as { totalHeight?: number }).totalHeight;
+ if (typeof measureH === 'number' && Number.isFinite(measureH)) total += measureH;
+ const spacing = (block as { attrs?: { spacing?: { after?: number; lineSpaceAfter?: number } } }).attrs
+ ?.spacing;
+ const after = spacing?.after ?? spacing?.lineSpaceAfter;
+ if (typeof after === 'number' && Number.isFinite(after) && after > 0) total += after;
+ // SD-2656: first paragraph's first line is the first valid run.
+ if (firstLine === 0) {
+ const lines = (measure as { lines?: Array<{ lineHeight?: number }> }).lines;
+ const lh = lines && lines.length > 0 ? lines[0].lineHeight : undefined;
+ if (typeof lh === 'number' && Number.isFinite(lh) && lh > 0) firstLine = lh;
+ }
+ } else if (measure.kind === 'image' || measure.kind === 'drawing') {
+ const measureH = (measure as { height?: number }).height;
+ if (typeof measureH === 'number' && Number.isFinite(measureH)) total += measureH;
+ // SD-2656: atomic content — first "line" is the whole thing.
+ if (firstLine === 0 && typeof measureH === 'number' && Number.isFinite(measureH)) firstLine = measureH;
+ } else if (measure.kind === 'table') {
+ const measureH = (measure as { totalHeight?: number }).totalHeight;
+ if (typeof measureH === 'number' && Number.isFinite(measureH)) total += measureH;
+ if (firstLine === 0 && typeof measureH === 'number' && Number.isFinite(measureH)) firstLine = measureH;
+ } else if (measure.kind === 'list' && block.kind === 'list') {
+ for (const item of block.items) {
+ const itemMeasure = measure.items.find((entry) => entry.itemId === item.id);
+ if (!itemMeasure?.paragraph?.lines) continue;
+ for (const line of itemMeasure.paragraph.lines) total += line.lineHeight ?? 0;
+ total += getParagraphSpacingAfter(item.paragraph);
+ }
+ // SD-2656: first list item's first line.
+ if (firstLine === 0) {
+ const firstItem = measure.items[0];
+ const lh = firstItem?.paragraph?.lines?.[0]?.lineHeight;
+ if (typeof lh === 'number' && Number.isFinite(lh) && lh > 0) firstLine = lh;
+ }
+ }
+ }
+ if (total > 0) totalMap.set(footnoteId, total);
+ if (firstLine > 0) firstLineMap.set(footnoteId, firstLine);
+ });
+ bodyHeightById = totalMap;
+ firstLineHeightById = firstLineMap;
+ };
+
+ // SD-2656: thread the planner's data-driven band overhead values
+ // (topPadding, dividerHeight, gap, separatorSpacingBefore) through
+ // `footnotes` so the layout-engine's body slicer computes the SAME
+ // `bandOverhead(refs)` budget the planner uses to size the band.
+ // Otherwise the slicer falls back to defaults that drift on docs with
+ // custom separator dimensions, packing body onto a page whose band
+ // can't actually fit the refs.
+ const relayout = (footnoteReservedByPageIndex: number[], plannerSeparatorSpacingBefore?: number) =>
layoutDocument(currentBlocks, currentMeasures, {
...options,
footnoteReservedByPageIndex,
+ footnotes: {
+ ...footnotesInput,
+ bodyHeightById,
+ firstLineHeightById,
+ ...(typeof plannerSeparatorSpacingBefore === 'number' && Number.isFinite(plannerSeparatorSpacingBefore)
+ ? { separatorSpacingBefore: plannerSeparatorSpacingBefore }
+ : {}),
+ },
headerContentHeights,
footerContentHeights,
headerContentHeightsBySectionRef,
@@ -1829,9 +2275,17 @@ export async function incrementalLayout(
remeasureParagraph(block as ParagraphBlock, maxWidth, firstLineIndent),
});
- // Pass 1: assign + reserve from current layout.
+ // SD-3049: every reachable footnote id, computed once. Used to keep
+ // `bodyHeightById` complete across convergence iterations even when refs
+ // migrate between pages — the assigned-by-column subset can drop ids
+ // mid-loop, which would zero their entries and cause oscillation.
+ const allFootnoteIds = new Set(footnotesInput.refs.map((ref) => ref.id));
+
+ // Pass 1: assign + reserve from current layout. Pre-measure ALL footnote
+ // bodies (the cache makes the assigned-only subset essentially free).
let { columns: pageColumns, idsByColumn } = resolveFootnoteAssignments(layout);
- let { measuresById } = await measureFootnoteBlocks(collectFootnoteIdsByColumn(idsByColumn));
+ let { measuresById } = await measureFootnoteBlocks(allFootnoteIds);
+ refreshBodyHeights(measuresById);
let plan = computeFootnoteLayoutPlan(layout, idsByColumn, measuresById, [], pageColumns);
let reserves = plan.reserves;
@@ -1841,9 +2295,13 @@ export async function incrementalLayout(
let reservesStabilized = false;
const seenReserveVectors: number[][] = [reserves.slice()];
for (let pass = 0; pass < MAX_FOOTNOTE_LAYOUT_PASSES; pass += 1) {
- layout = relayout(reserves);
+ layout = relayout(reserves, plan.separatorSpacingBefore);
({ columns: pageColumns, idsByColumn } = resolveFootnoteAssignments(layout));
- ({ measuresById } = await measureFootnoteBlocks(collectFootnoteIdsByColumn(idsByColumn)));
+ // SD-3049: measure the full set each iteration so `bodyHeightById`
+ // stays complete; refs migrating between pages must not drop their
+ // measured demand from the per-block lookup.
+ ({ measuresById } = await measureFootnoteBlocks(allFootnoteIds));
+ refreshBodyHeights(measuresById);
plan = computeFootnoteLayoutPlan(layout, idsByColumn, measuresById, reserves, pageColumns);
const nextReserves = plan.reserves;
const reservesStable =
@@ -1896,12 +2354,13 @@ export async function incrementalLayout(
return true;
};
const applyReserves = async (target: number[]) => {
- layout = relayout(target);
+ // Planner sized the band with the measured separator spacing; the
+ // body slicer must match or it packs too much and the band overflows.
+ layout = relayout(target, finalPlan.separatorSpacingBefore);
reservesAppliedToLayout = target;
({ columns: finalPageColumns, idsByColumn: finalIdsByColumn } = resolveFootnoteAssignments(layout));
- ({ blocks: finalBlocks, measuresById: finalMeasuresById } = await measureFootnoteBlocks(
- collectFootnoteIdsByColumn(finalIdsByColumn),
- ));
+ ({ blocks: finalBlocks, measuresById: finalMeasuresById } = await measureFootnoteBlocks(allFootnoteIds));
+ refreshBodyHeights(finalMeasuresById);
finalPlan = computeFootnoteLayoutPlan(
layout,
finalIdsByColumn,
@@ -1910,6 +2369,52 @@ export async function incrementalLayout(
finalPageColumns,
);
};
+ const buildFootnoteLedgers = (plan: FootnoteLayoutPlan, appliedReserves: number[], pageCount: number) => {
+ const ledgers: FootnotePageLedger[] = [];
+ for (let pageIndex = 0; pageIndex < pageCount; pageIndex += 1) {
+ const draft = plan.ledgersByPage.get(pageIndex);
+ if (!draft) continue;
+ const appliedBodyReservePx = Math.max(0, appliedReserves[pageIndex] ?? plan.reserves[pageIndex] ?? 0);
+ ledgers.push({
+ pageIndex,
+ anchorIds: draft.anchorIds,
+ mandatorySliceIds: draft.mandatorySliceIds,
+ continuationSliceIds: draft.continuationSliceIds,
+ extendedSliceIds: draft.extendedSliceIds,
+ continuationIn: draft.continuationIn,
+ continuationOut: draft.continuationOut,
+ mandatoryReservePx: draft.mandatoryReservePx,
+ preferredReservePx: draft.preferredReservePx,
+ actualBandHeightPx: draft.actualBandHeightPx,
+ appliedBodyReservePx,
+ deadReservePx: Math.max(0, appliedBodyReservePx - draft.actualBandHeightPx),
+ lastAnchorRenderedLines: draft.lastAnchorRenderedLines,
+ });
+ }
+ return ledgers;
+ };
+ const capReserveForRelayout = (
+ requestedReserve: number,
+ pageIndex: number,
+ referenceLayout: Layout,
+ referenceReserves: number[],
+ ): number => {
+ const requested = Number.isFinite(requestedReserve) ? Math.max(0, requestedReserve) : 0;
+ const page = referenceLayout.pages?.[pageIndex];
+ if (!page) return requested;
+
+ const pageSize = page.size ?? referenceLayout.pageSize ?? DEFAULT_PAGE_SIZE;
+ const topMargin = normalizeMargin(page.margins?.top, DEFAULT_MARGINS.top);
+ const bottomWithReserve = normalizeMargin(page.margins?.bottom, DEFAULT_MARGINS.bottom);
+ const currentReserve = Number.isFinite(referenceReserves[pageIndex])
+ ? Math.max(0, referenceReserves[pageIndex])
+ : 0;
+ const physicalBottomMargin = Math.max(0, bottomWithReserve - currentReserve);
+ const physicalContentHeight = pageSize.h - topMargin - physicalBottomMargin;
+ if (!Number.isFinite(physicalContentHeight)) return requested;
+
+ return Math.min(requested, Math.max(0, physicalContentHeight - MIN_FOOTNOTE_BODY_HEIGHT));
+ };
// Grow-only convergence: ensures every page reserves at least as much
// as its plan demands, so footnotes never render past the page bottom.
// Monotonic (reserves only increase) and safe under oscillation. Needs
@@ -1941,6 +2446,107 @@ export async function incrementalLayout(
return false;
};
+ const GROW_MAX_PASSES = 10;
+ const PREFERRED_RESERVE_MAX_CANDIDATES = 12;
+ const PREFERRED_RESERVE_MAX_ACCEPTED_CANDIDATES = PREFERRED_RESERVE_MAX_CANDIDATES;
+ const PREFERRED_RESERVE_WINDOW_AHEAD = 3;
+
+ // SD-2656: scored preferred-reserve trials.
+ //
+ // Ordered-minimum reserve is the correctness floor. Word sometimes
+ // spends more space on the last anchor's footnote, but applying that
+ // locally in the body slicer caused large downstream drift. This pass
+ // tries one candidate at a time after the mandatory layout has already
+ // stabilized, then keeps the candidate only if the page-window scorer
+ // proves the result is globally safe. The scorer guards both the local
+ // page window and the full document, so we can try candidates while
+ // still rejecting changes that create late-document slack.
+ const runPreferredReserveTrials = async () => {
+ let acceptedPreferredTrials = 0;
+ let rejectedPreferredTrials = 0;
+ const rejectedPreferredPages = new Set();
+
+ for (let candidatePass = 0; candidatePass < PREFERRED_RESERVE_MAX_CANDIDATES; candidatePass += 1) {
+ const beforeLayout = layout;
+ const beforePlan = finalPlan;
+ const beforeReserves = reservesAppliedToLayout.slice();
+ const beforeLedgers = buildFootnoteLedgers(beforePlan, beforeReserves, beforeLayout.pages.length);
+ const candidate = getPreferredReserveCandidates(beforeLedgers).find(
+ (entry) => !rejectedPreferredPages.has(entry.pageIndex),
+ );
+ if (!candidate) break;
+
+ const targetReserves = getPreferredReserveTrialTargets(candidate, beforeReserves[candidate.pageIndex] ?? 0);
+ let acceptedCandidate = false;
+
+ for (const targetReserve of targetReserves) {
+ const trialReserves = beforeReserves.slice();
+ const cappedPreferredReserve = capReserveForRelayout(
+ targetReserve,
+ candidate.pageIndex,
+ beforeLayout,
+ beforeReserves,
+ );
+ trialReserves[candidate.pageIndex] = Math.max(
+ trialReserves[candidate.pageIndex] ?? 0,
+ cappedPreferredReserve,
+ );
+
+ await applyReserves(trialReserves);
+ const trialConverged = await growReserves(GROW_MAX_PASSES);
+ const afterLedgers = buildFootnoteLedgers(finalPlan, reservesAppliedToLayout, layout.pages.length);
+ const score = scoreFootnoteWindow({
+ beforeLayout,
+ afterLayout: layout,
+ candidatePageIndex: candidate.pageIndex,
+ candidateAnchorId: candidate.anchorIds[candidate.anchorIds.length - 1],
+ beforeLedger: beforeLedgers,
+ afterLedger: afterLedgers,
+ windowAhead: PREFERRED_RESERVE_WINDOW_AHEAD,
+ });
+
+ if (trialConverged && score.accept) {
+ if (layoutDebugEnabled) {
+ console.log('[incrementalLayout] Accepted footnote preferred-reserve trial', {
+ pageIndex: candidate.pageIndex,
+ targetReserve,
+ score,
+ });
+ }
+ acceptedPreferredTrials += 1;
+ acceptedCandidate = true;
+ break;
+ }
+
+ if (layoutDebugEnabled) {
+ console.log('[incrementalLayout] Rejected footnote preferred-reserve trial', {
+ pageIndex: candidate.pageIndex,
+ targetReserve,
+ trialConverged,
+ score,
+ });
+ }
+
+ await applyReserves(beforeReserves);
+ }
+
+ if (acceptedCandidate) {
+ if (acceptedPreferredTrials >= PREFERRED_RESERVE_MAX_ACCEPTED_CANDIDATES) break;
+ continue;
+ }
+
+ rejectedPreferredTrials += 1;
+ rejectedPreferredPages.add(candidate.pageIndex);
+ }
+
+ if (layoutDebugEnabled && (acceptedPreferredTrials > 0 || rejectedPreferredTrials > 0)) {
+ console.log('[incrementalLayout] Footnote preferred-reserve trials', {
+ accepted: acceptedPreferredTrials,
+ rejected: rejectedPreferredTrials,
+ });
+ }
+ };
+
// Fast path for well-converged docs: if every page's current reserve
// already satisfies the plan and no page is carrying dead reserve,
// skip both the initial grow and the tighten loop entirely. Avoids
@@ -1955,39 +2561,52 @@ export async function incrementalLayout(
const p = plan[i] ?? 0;
if (p > a) return true; // under-reserved — grow must bump
if (a >= TIGHTEN_SLACK_PX && p === 0) return true; // dead reserve — tighten can reclaim
+ // SD-2656 Phase 4: dead reserve where plan > 0 (e.g. bump-inflated
+ // continuation page where final demand is much smaller).
+ if (a >= TIGHTEN_SLACK_PX && a - p > TIGHTEN_SLACK_PX) return true;
}
return false;
})();
if (needsWork) {
- const GROW_MAX_PASSES = 10;
if (!(await growReserves(GROW_MAX_PASSES))) {
console.warn(
'[incrementalLayout] Footnote post-reserve loop did not converge; some pages may have footnotes overflowing the reserved band.',
);
}
- // Opportunistic tighten: the grow loop is monotonic, so pages whose
- // plan no longer asks for a reserve (footnote content shifted to
- // later pages during an earlier pass) still carry their old reserve.
- // Zero those pages' reserves and regrow any that gain footnote
- // content after the body reflows. Revert if regrow can't stabilize
- // safely or would add pages. Iterate a few times — each tighten
- // + regrow can expose a fresh set of "reserved but plan==0" pages
- // after the body reflows.
+ // SD-2656 Phase 4: opportunistic tighten — pages whose body reserved
+ // significantly more than the planner now needs. Two cases:
+ //
+ // (a) planned === 0: footnote content shifted off this page in
+ // an earlier pass. The reserve is fully dead — tighten to 0.
+ //
+ // (b) planned > 0 but applied >> planned: previous pass's bump
+ // (e.g. for a continuation that was longer then than now)
+ // was preserved by the grow-only loop and never shrank back.
+ // Tighten to planned so body reclaims the dead space; grow
+ // will bump back up if the new bodyMaxY changes plan demand.
+ //
+ // Revert iff regrow can't stabilize or page count grows (safety net
+ // for cluster spills induced by absorbing body content).
const MAX_TIGHTEN_ITERATIONS = 8;
for (let iteration = 0; iteration < MAX_TIGHTEN_ITERATIONS; iteration += 1) {
- const pagesToTighten: number[] = [];
+ const pagesToTighten: Array<{ i: number; target: number }> = [];
for (let i = 0; i < reservesAppliedToLayout.length; i += 1) {
const applied = reservesAppliedToLayout[i] ?? 0;
const planned = finalPlan.reserves[i] ?? 0;
- if (applied >= TIGHTEN_SLACK_PX && planned === 0) pagesToTighten.push(i);
+ if (applied < TIGHTEN_SLACK_PX) continue;
+ if (planned === 0) {
+ pagesToTighten.push({ i, target: 0 });
+ } else if (applied - planned > TIGHTEN_SLACK_PX) {
+ pagesToTighten.push({ i, target: planned });
+ }
}
if (pagesToTighten.length === 0) break;
const safeApplied = reservesAppliedToLayout.slice();
const safePageCount = layout.pages.length;
const tightened = reservesAppliedToLayout.slice();
- for (const i of pagesToTighten) tightened[i] = 0;
+ for (const { i, target } of pagesToTighten) tightened[i] = target;
await applyReserves(tightened);
if (!(await growReserves(GROW_MAX_PASSES)) || layout.pages.length > safePageCount) {
await applyReserves(safeApplied);
@@ -1996,6 +2615,39 @@ export async function incrementalLayout(
}
}
+ // Absorb one-line footnote widows by bumping their reserve to
+ // preferred. The scorer would reject this as a page-count regression;
+ // for one-line tails the cost is bounded and Word's pagination always
+ // absorbs them.
+ const ONE_LINE_TAIL_PX = 24;
+ const runWidowOrphanAbsorb = async () => {
+ const ledgers = buildFootnoteLedgers(finalPlan, reservesAppliedToLayout, layout.pages.length);
+ const target = reservesAppliedToLayout.slice();
+ let bumped = 0;
+ for (const ledger of ledgers) {
+ const tailPx = ledger.continuationOut.reduce((s, e) => s + (e.remainingHeightPx || 0), 0);
+ if (tailPx <= 0 || tailPx > ONE_LINE_TAIL_PX) continue;
+ const requested = capReserveForRelayout(
+ ledger.preferredReservePx,
+ ledger.pageIndex,
+ layout,
+ reservesAppliedToLayout,
+ );
+ if (requested > (target[ledger.pageIndex] ?? 0)) {
+ target[ledger.pageIndex] = requested;
+ bumped += 1;
+ }
+ }
+ if (bumped === 0) return;
+ const safeApplied = reservesAppliedToLayout.slice();
+ await applyReserves(target);
+ if (!(await growReserves(GROW_MAX_PASSES))) {
+ await applyReserves(safeApplied);
+ }
+ };
+ await runWidowOrphanAbsorb();
+ await runPreferredReserveTrials();
+
const blockById = new Map();
finalBlocks.forEach((block) => {
blockById.set(block.id, block);
diff --git a/packages/layout-engine/layout-bridge/src/index.ts b/packages/layout-engine/layout-bridge/src/index.ts
index 08e2e752b3..62a30c97aa 100644
--- a/packages/layout-engine/layout-bridge/src/index.ts
+++ b/packages/layout-engine/layout-bridge/src/index.ts
@@ -70,6 +70,21 @@ export type {
} from './sectionAwareHeaderFooter';
export { incrementalLayout, measureCache, normalizeMargin } from './incrementalLayout';
export type { HeaderFooterLayoutResult, IncrementalLayoutResult } from './incrementalLayout';
+export {
+ collectFootnoteLedgers,
+ getPreferredReserveCandidates,
+ getPreferredReserveTrialTargets,
+ isMandatoryOnlyFootnotePage,
+ scoreFootnoteWindow,
+ summarizeFootnoteWindow,
+} from './footnote-scorer';
+export type {
+ FootnotePreferredReserveCandidate,
+ FootnoteWindowScoreInput,
+ FootnoteWindowScoreReason,
+ FootnoteWindowScoreResult,
+ FootnoteWindowStats,
+} from './footnote-scorer';
// Re-export computeDisplayPageNumber from layout-engine for section-aware page numbering
export { computeDisplayPageNumber } from '@superdoc/layout-engine';
export type { DisplayPageInfo, HeaderFooterConstraints } from '@superdoc/layout-engine';
diff --git a/packages/layout-engine/layout-bridge/test/footnoteBodyDemand.test.ts b/packages/layout-engine/layout-bridge/test/footnoteBodyDemand.test.ts
new file mode 100644
index 0000000000..dc20a075d8
--- /dev/null
+++ b/packages/layout-engine/layout-bridge/test/footnoteBodyDemand.test.ts
@@ -0,0 +1,437 @@
+/**
+ * SD-3049: Body break decisions consult footnote demand for refs anchored on this page.
+ *
+ * Today the body paginator's only footnote signal is `footnoteReservedByPageIndex`,
+ * a uniform per-page bottom-margin add-on derived from the previous pass's plan.
+ * On pass 1 this is empty, so the body fills the whole page; a ref + footnote body
+ * land near the page bottom; the reserve loop then claws back space, leaving a
+ * visible blank gap between the body's last fragment and the footnote separator.
+ *
+ * After SD-3049, when a fragment carrying a footnote ref is committed the paginator
+ * accumulates that footnote's measured body height into a per-page demand counter
+ * and uses it in the break decision. Body packs tight to "next-line + cumulative
+ * footnote demand exceeds page bottom".
+ *
+ * Verified target: body→separator gap stays within the legitimate separator overhead
+ * (≤ 28px = separatorSpacingBefore 12 + dividerHeight 6 + topPadding 6 + 4px slack).
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import type { FlowBlock, Measure } from '@superdoc/contracts';
+import { incrementalLayout } from '../src/incrementalLayout';
+
+const makeParagraph = (id: string, text: string, pmStart: number): FlowBlock => ({
+ kind: 'paragraph',
+ id,
+ runs: [{ text, fontFamily: 'Arial', fontSize: 12, pmStart, pmEnd: pmStart + text.length }],
+});
+
+const makeMeasure = (lineHeight: number, lineCount: number): Measure => ({
+ kind: 'paragraph',
+ lines: Array.from({ length: lineCount }, (_, i) => ({
+ fromRun: 0,
+ fromChar: i,
+ toRun: 0,
+ toChar: i + 1,
+ width: 200,
+ ascent: lineHeight * 0.8,
+ descent: lineHeight * 0.2,
+ lineHeight,
+ })),
+ totalHeight: lineCount * lineHeight,
+});
+
+describe('SD-3049: body break consults anchored footnote demand', () => {
+ it('packs body tight to the separator when footnote demand is known up-front', async () => {
+ // Page geometry:
+ // pageHeight = 600 + 144 = 744; margins top=72 bottom=72 → body region = 600px
+ // line height = 20 → 30 body lines fill the page exactly
+ // Document:
+ // 30 single-line body paragraphs, with a footnote ref in body line 25
+ // footnote = 5 lines × 12 = 60px, plus ~24px separator overhead
+ // Today (post-hoc reserve, pass 1 with no signal):
+ // pass 1: body fills 30 lines, ref ends up on page 1
+ // plan computes ~84px reserve for page 1
+ // pass 2: body capped at 600 - 84 = 516px → 25 lines (25*20=500, 26 doesn't fit)
+ // ref still on page 1 (it's at line 25), body bottom ≈ 500 + topMargin
+ // separator at body-bottom + 12 (separatorSpacingBefore) = ~512 + topMargin
+ // reserve area ends near page bottom
+ // GAP between body line 25 bottom and separator: ~12px legit + however much was clawed back
+ // Actually with all 25 lines fitting, the gap is the legit overhead. So this test may need
+ // a different shape to expose the bug.
+ //
+ // Better shape: ref in middle of doc with a LONG footnote so capping is sharp.
+
+ const BODY_LINES = 25;
+ const FOOTNOTE_LINES = 8; // 96px content + ~24px overhead = ~120px reserve
+ const LINE_H = 20;
+
+ let pos = 0;
+ const blocks: FlowBlock[] = [];
+ for (let i = 0; i < BODY_LINES; i += 1) {
+ const text = `Body line ${i + 1}.`;
+ blocks.push(makeParagraph(`body-${i}`, text, pos));
+ pos += text.length + 1;
+ }
+ // Ref inside body line 5 (early, so its demand is known well before page fills)
+ const refBlockIdx = 4;
+ const refBlock = blocks[refBlockIdx];
+ const refPos = (refBlock.kind === 'paragraph' ? (refBlock.runs?.[0]?.pmStart ?? 0) : 0) + 2;
+ const ftBlock = makeParagraph('footnote-1-0-paragraph', 'Footnote body content.', 0);
+
+ const measureBlock = vi.fn(async (b: FlowBlock) => {
+ if (b.id.startsWith('footnote-')) return makeMeasure(12, FOOTNOTE_LINES);
+ return makeMeasure(LINE_H, 1);
+ });
+
+ const margins = { top: 72, right: 72, bottom: 72, left: 72 };
+ const result = await incrementalLayout(
+ [],
+ null,
+ blocks,
+ {
+ pageSize: { w: 612, h: 600 + margins.top + margins.bottom },
+ margins,
+ footnotes: {
+ refs: [{ id: '1', pos: refPos }],
+ blocksById: new Map([['1', [ftBlock]]]),
+ topPadding: 6,
+ dividerHeight: 6,
+ },
+ },
+ measureBlock,
+ );
+
+ const page1 = result.layout.pages[0];
+ expect(page1).toBeTruthy();
+
+ // Compute body bottom Y on page 1. ParaFragment doesn't carry an explicit
+ // `height` field — derive from `y + (toLine - fromLine) * lineHeight`.
+ const bodyMaxBottom = page1.fragments
+ .filter((f) => !String(f.blockId).startsWith('footnote-'))
+ .reduce((max, f) => {
+ const y = (f as { y?: number }).y ?? 0;
+ const fromLine = (f as { fromLine?: number }).fromLine ?? 0;
+ const toLine = (f as { toLine?: number }).toLine ?? fromLine + 1;
+ const lineCount = Math.max(1, toLine - fromLine);
+ return Math.max(max, y + lineCount * LINE_H);
+ }, 0);
+
+ // Find the separator fragment's top Y on page 1.
+ const sepFrag = page1.fragments.find((f) => String(f.blockId).startsWith('footnote-separator'));
+ const sepTop = (sepFrag as { y?: number } | undefined)?.y ?? Infinity;
+
+ // SD-3049 success criterion: body→separator gap ≤ 28px (24 legit + 4 slack).
+ // Today this fails because the body left more space than necessary above the separator.
+ const gap = sepTop - bodyMaxBottom;
+ expect(gap).toBeLessThanOrEqual(28);
+ expect(gap).toBeGreaterThanOrEqual(0);
+ });
+
+ it('produces a tight body→separator gap for an image-only footnote', async () => {
+ const BODY_LINES = 25;
+ const LINE_H = 20;
+ const IMAGE_HEIGHT = 96;
+
+ let pos = 0;
+ const blocks: FlowBlock[] = [];
+ for (let i = 0; i < BODY_LINES; i += 1) {
+ const text = `Body line ${i + 1}.`;
+ blocks.push(makeParagraph(`body-${i}`, text, pos));
+ pos += text.length + 1;
+ }
+ const refBlockIdx = 4;
+ const refBlock = blocks[refBlockIdx];
+ const refPos = (refBlock.kind === 'paragraph' ? (refBlock.runs?.[0]?.pmStart ?? 0) : 0) + 2;
+ const ftImage: FlowBlock = { kind: 'image', id: 'footnote-1-0-image', src: '', width: 100, height: IMAGE_HEIGHT };
+
+ const measureBlock = vi.fn(async (b: FlowBlock) => {
+ if (b.kind === 'image') return { kind: 'image' as const, width: 100, height: IMAGE_HEIGHT };
+ return makeMeasure(LINE_H, 1);
+ });
+
+ const margins = { top: 72, right: 72, bottom: 72, left: 72 };
+ const result = await incrementalLayout(
+ [],
+ null,
+ blocks,
+ {
+ pageSize: { w: 612, h: 600 + margins.top + margins.bottom },
+ margins,
+ footnotes: {
+ refs: [{ id: '1', pos: refPos }],
+ blocksById: new Map([['1', [ftImage]]]),
+ topPadding: 6,
+ dividerHeight: 6,
+ },
+ },
+ measureBlock,
+ );
+
+ const page1 = result.layout.pages[0];
+ expect(page1).toBeTruthy();
+
+ const bodyMaxBottom = page1.fragments
+ .filter((f) => !String(f.blockId).startsWith('footnote-'))
+ .reduce((max, f) => {
+ const y = (f as { y?: number }).y ?? 0;
+ const fromLine = (f as { fromLine?: number }).fromLine ?? 0;
+ const toLine = (f as { toLine?: number }).toLine ?? fromLine + 1;
+ const lineCount = Math.max(1, toLine - fromLine);
+ return Math.max(max, y + lineCount * LINE_H);
+ }, 0);
+ const sepFrag = page1.fragments.find((f) => String(f.blockId).startsWith('footnote-separator'));
+ const sepTop = (sepFrag as { y?: number } | undefined)?.y ?? Infinity;
+
+ const gap = sepTop - bodyMaxBottom;
+ expect(gap).toBeLessThanOrEqual(28);
+ expect(gap).toBeGreaterThanOrEqual(0);
+ });
+
+ it('produces a tight body→separator gap for a list-only footnote', async () => {
+ const BODY_LINES = 25;
+ const LINE_H = 20;
+ const ITEM_LINE_H = 12;
+ const ITEMS = 8;
+
+ let pos = 0;
+ const blocks: FlowBlock[] = [];
+ for (let i = 0; i < BODY_LINES; i += 1) {
+ const text = `Body line ${i + 1}.`;
+ blocks.push(makeParagraph(`body-${i}`, text, pos));
+ pos += text.length + 1;
+ }
+ const refBlockIdx = 4;
+ const refBlock = blocks[refBlockIdx];
+ const refPos = (refBlock.kind === 'paragraph' ? (refBlock.runs?.[0]?.pmStart ?? 0) : 0) + 2;
+
+ const ftItemPara = (itemId: string): FlowBlock => ({
+ kind: 'paragraph',
+ id: `${itemId}-p`,
+ runs: [{ text: 'item', fontFamily: 'Arial', fontSize: 10, pmStart: 0, pmEnd: 4 }],
+ });
+ const ftList: FlowBlock = {
+ kind: 'list',
+ id: 'footnote-1-0-list',
+ listType: 'bullet',
+ items: Array.from({ length: ITEMS }, (_, i) => ({
+ id: `footnote-1-0-list-item-${i}`,
+ marker: { text: '•', font: { family: 'Arial', size: 10 } } as never,
+ paragraph: ftItemPara(`footnote-1-0-list-item-${i}`) as never,
+ })),
+ };
+
+ const measureBlock = vi.fn(async (b: FlowBlock) => {
+ if (b.kind === 'list') {
+ return {
+ kind: 'list' as const,
+ items: b.items.map((it) => ({
+ itemId: it.id,
+ markerWidth: 10,
+ markerTextWidth: 6,
+ indentLeft: 0,
+ paragraph: makeMeasure(ITEM_LINE_H, 1) as never,
+ })),
+ totalHeight: ITEMS * ITEM_LINE_H,
+ };
+ }
+ return makeMeasure(LINE_H, 1);
+ });
+
+ const margins = { top: 72, right: 72, bottom: 72, left: 72 };
+ const result = await incrementalLayout(
+ [],
+ null,
+ blocks,
+ {
+ pageSize: { w: 612, h: 600 + margins.top + margins.bottom },
+ margins,
+ footnotes: {
+ refs: [{ id: '1', pos: refPos }],
+ blocksById: new Map([['1', [ftList]]]),
+ topPadding: 6,
+ dividerHeight: 6,
+ },
+ },
+ measureBlock,
+ );
+
+ const page1 = result.layout.pages[0];
+ expect(page1).toBeTruthy();
+
+ const bodyMaxBottom = page1.fragments
+ .filter((f) => !String(f.blockId).startsWith('footnote-'))
+ .reduce((max, f) => {
+ const y = (f as { y?: number }).y ?? 0;
+ const fromLine = (f as { fromLine?: number }).fromLine ?? 0;
+ const toLine = (f as { toLine?: number }).toLine ?? fromLine + 1;
+ const lineCount = Math.max(1, toLine - fromLine);
+ return Math.max(max, y + lineCount * LINE_H);
+ }, 0);
+ const sepFrag = page1.fragments.find((f) => String(f.blockId).startsWith('footnote-separator'));
+ const sepTop = (sepFrag as { y?: number } | undefined)?.y ?? Infinity;
+
+ const gap = sepTop - bodyMaxBottom;
+ expect(gap).toBeLessThanOrEqual(28);
+ expect(gap).toBeGreaterThanOrEqual(0);
+ });
+
+ it('does not double-count demand when the same footnote id is referenced twice on a page', async () => {
+ // Two refs to footnote id `1` on the same page must contribute its body
+ // height once — the rendered footnote band dedupes per page, so the body
+ // paginator must too. Otherwise the page reserves 2× the real demand and
+ // leaves phantom whitespace above the separator.
+
+ const BODY_LINES = 25;
+ const LINE_H = 20;
+ const FOOTNOTE_LINES = 5;
+ const FOOTNOTE_LINE_H = 12;
+
+ let pos = 0;
+ const blocks: FlowBlock[] = [];
+ for (let i = 0; i < BODY_LINES; i += 1) {
+ const text = `Body line ${i + 1}.`;
+ blocks.push(makeParagraph(`body-${i}`, text, pos));
+ pos += text.length + 1;
+ }
+ const firstRefBlock = blocks[4];
+ const secondRefBlock = blocks[19];
+ const firstRefPos = (firstRefBlock.kind === 'paragraph' ? (firstRefBlock.runs?.[0]?.pmStart ?? 0) : 0) + 2;
+ const secondRefPos = (secondRefBlock.kind === 'paragraph' ? (secondRefBlock.runs?.[0]?.pmStart ?? 0) : 0) + 2;
+ const ftBlock = makeParagraph('footnote-1-0-paragraph', 'Footnote body.', 0);
+
+ const measureBlock = vi.fn(async (b: FlowBlock) => {
+ if (b.id.startsWith('footnote-')) return makeMeasure(FOOTNOTE_LINE_H, FOOTNOTE_LINES);
+ return makeMeasure(LINE_H, 1);
+ });
+
+ const margins = { top: 72, right: 72, bottom: 72, left: 72 };
+ const result = await incrementalLayout(
+ [],
+ null,
+ blocks,
+ {
+ pageSize: { w: 612, h: 600 + margins.top + margins.bottom },
+ margins,
+ footnotes: {
+ refs: [
+ { id: '1', pos: firstRefPos },
+ { id: '1', pos: secondRefPos },
+ ],
+ blocksById: new Map([['1', [ftBlock]]]),
+ topPadding: 6,
+ dividerHeight: 6,
+ },
+ },
+ measureBlock,
+ );
+
+ const page1 = result.layout.pages[0];
+ const bodyMaxBottom = page1.fragments
+ .filter((f) => !String(f.blockId).startsWith('footnote-'))
+ .reduce((max, f) => {
+ const y = (f as { y?: number }).y ?? 0;
+ const fromLine = (f as { fromLine?: number }).fromLine ?? 0;
+ const toLine = (f as { toLine?: number }).toLine ?? fromLine + 1;
+ return Math.max(max, y + Math.max(1, toLine - fromLine) * LINE_H);
+ }, 0);
+ const sepFrag = page1.fragments.find((f) => String(f.blockId).startsWith('footnote-separator'));
+ const sepTop = (sepFrag as { y?: number } | undefined)?.y ?? Infinity;
+
+ const gap = sepTop - bodyMaxBottom;
+ expect(gap).toBeLessThanOrEqual(28);
+ expect(gap).toBeGreaterThanOrEqual(0);
+ });
+
+ it('does not re-charge block demand on continuation pages of a multi-page paragraph', async () => {
+ // A single long paragraph carries one footnote ref. The footnote band
+ // only renders on the page that holds the ref's line — continuation pages
+ // must not get the demand subtracted from their effective body region, or
+ // they pack 13–15 lines instead of 20 and the document ends up with
+ // unnecessary extra pages.
+
+ const PARAGRAPH_LINES = 50;
+ const LINE_H = 20;
+ const FOOTNOTE_LINES = 5;
+ const FOOTNOTE_LINE_H = 20;
+
+ const block: FlowBlock = {
+ kind: 'paragraph',
+ id: 'long-para',
+ runs: [{ text: 'x'.repeat(100), fontFamily: 'Arial', fontSize: 12, pmStart: 0, pmEnd: 100 }],
+ };
+ const ftBlock = makeParagraph('footnote-1-0-paragraph', 'Footnote body.', 0);
+
+ const measureBlock = vi.fn(async (b: FlowBlock) => {
+ if (b.id.startsWith('footnote-')) return makeMeasure(FOOTNOTE_LINE_H, FOOTNOTE_LINES);
+ return makeMeasure(LINE_H, PARAGRAPH_LINES);
+ });
+
+ const margins = { top: 100, right: 100, bottom: 100, left: 100 };
+ const result = await incrementalLayout(
+ [],
+ null,
+ [block],
+ {
+ pageSize: { w: 612, h: 600 },
+ margins,
+ footnotes: {
+ refs: [{ id: '1', pos: 5 }],
+ blocksById: new Map([['1', [ftBlock]]]),
+ topPadding: 6,
+ dividerHeight: 6,
+ },
+ },
+ measureBlock,
+ );
+
+ // 50 lines × 20 = 1000px. Body region per page = 400px. Footnote band on
+ // page 1 reduces P1 capacity; P2+ are unconstrained.
+ //
+ // Baseline outcome (no preferred-reserve scorer acceptance): 3 pages.
+ // Per-page-recharge bug (now fixed): 4 pages.
+ //
+ // SD-2656 (post-Vivienne+Carlsbad p43): with the +1-page-if-eliminates-split
+ // relaxation, the scorer now accepts a one-page growth to fully fit the
+ // 5-line footnote on the anchor page (previously split). New outcome is 4
+ // pages — the same as the recharge bug numerically but for a different,
+ // intentional reason (split-elimination). This test still guards against
+ // per-page recharge: anything > 4 pages would indicate recharge regression.
+ expect(result.layout.pages.length).toBeLessThanOrEqual(4);
+ });
+
+ it('does not change layout when document has no footnotes (no-op invariant)', async () => {
+ // Regression guard: the new code path must not affect layouts without footnotes.
+ const BODY_LINES = 50;
+ const LINE_H = 20;
+ let pos = 0;
+ const blocks: FlowBlock[] = [];
+ for (let i = 0; i < BODY_LINES; i += 1) {
+ const text = `Body line ${i + 1}.`;
+ blocks.push(makeParagraph(`body-${i}`, text, pos));
+ pos += text.length + 1;
+ }
+ const measureBlock = vi.fn(async () => makeMeasure(LINE_H, 1));
+
+ const margins = { top: 72, right: 72, bottom: 72, left: 72 };
+ const result = await incrementalLayout(
+ [],
+ null,
+ blocks,
+ {
+ pageSize: { w: 612, h: 600 + margins.top + margins.bottom },
+ margins,
+ },
+ measureBlock,
+ );
+
+ // 50 body lines × 20px = 1000px. Body region per page = 600px → 30 lines per page.
+ // Expect: 2 pages exactly, with no fragment kind starting "footnote-".
+ expect(result.layout.pages.length).toBe(2);
+ for (const page of result.layout.pages) {
+ for (const f of page.fragments) {
+ expect(String(f.blockId).startsWith('footnote-')).toBe(false);
+ }
+ }
+ });
+});
diff --git a/packages/layout-engine/layout-bridge/test/footnoteCompleteness.test.ts b/packages/layout-engine/layout-bridge/test/footnoteCompleteness.test.ts
new file mode 100644
index 0000000000..c77db52dfb
--- /dev/null
+++ b/packages/layout-engine/layout-bridge/test/footnoteCompleteness.test.ts
@@ -0,0 +1,290 @@
+import { describe, it, expect, vi } from 'vitest';
+import type { FlowBlock, Measure, ParagraphBlock } from '@superdoc/contracts';
+import { incrementalLayout } from '../src/incrementalLayout';
+
+/**
+ * SD-2656: every footnote ref in the input MUST have its body content
+ * rendered somewhere in the output. The new no-reserve architecture had
+ * a bug (caught visually on the reference fixture's page 16) where two footnotes anchored
+ * in the same paragraph could end up with the second one missing from the
+ * band — body extended too far, the planner ran out of band space, and
+ * the second fn was pushed to "pending" without being rendered.
+ */
+describe('SD-2656: footnote completeness — every ref renders', () => {
+ it('renders every anchored footnote even when many cluster on one page', async () => {
+ const BODY_LINE_HEIGHT = 24;
+ const FN_LINE_HEIGHT = 14;
+ const FN_LINES = 2;
+
+ // 12 body lines, each ~24 px, plus 4 fn refs anchored in the same
+ // single body block. Each footnote is short. The page should easily
+ // hold body + all 4 fns + overhead.
+ let pos = 0;
+ const text = 'a b c d e f g h i j k l';
+ const block: FlowBlock = {
+ kind: 'paragraph',
+ id: 'body-0',
+ runs: [{ text, fontFamily: 'Arial', fontSize: 12, pmStart: pos, pmEnd: pos + text.length }],
+ };
+ pos += text.length;
+
+ const refs = [
+ { id: '1', pos: 4 },
+ { id: '2', pos: 8 },
+ { id: '3', pos: 14 },
+ { id: '4', pos: 22 },
+ ];
+ const fnBlocks = new Map();
+ for (const r of refs) {
+ fnBlocks.set(r.id, [
+ {
+ kind: 'paragraph',
+ id: `footnote-${r.id}-0-paragraph`,
+ runs: [{ text: `fn body ${r.id}`, fontFamily: 'Arial', fontSize: 10, pmStart: 0, pmEnd: 12 }],
+ },
+ ]);
+ }
+
+ const measureBlock = vi.fn(async (block: FlowBlock) => {
+ if (block.id.startsWith('footnote-')) {
+ const lines = Array.from({ length: FN_LINES }, (_, i) => ({
+ fromRun: 0,
+ fromChar: i,
+ toRun: 0,
+ toChar: i + 1,
+ width: 200,
+ ascent: FN_LINE_HEIGHT * 0.8,
+ descent: FN_LINE_HEIGHT * 0.2,
+ lineHeight: FN_LINE_HEIGHT,
+ }));
+ return { kind: 'paragraph', lines, totalHeight: lines.length * FN_LINE_HEIGHT } as Measure;
+ }
+ const lineCount = 12;
+ const lines = Array.from({ length: lineCount }, (_, i) => ({
+ fromRun: 0,
+ fromChar: i,
+ toRun: 0,
+ toChar: i + 1,
+ width: 200,
+ ascent: BODY_LINE_HEIGHT * 0.8,
+ descent: BODY_LINE_HEIGHT * 0.2,
+ lineHeight: BODY_LINE_HEIGHT,
+ }));
+ return { kind: 'paragraph', lines, totalHeight: lineCount * BODY_LINE_HEIGHT } as Measure;
+ });
+
+ const margins = { top: 72, right: 72, bottom: 72, left: 72 };
+ const pageHeight = 900;
+
+ const result = await incrementalLayout(
+ [],
+ null,
+ [block],
+ {
+ pageSize: { w: 612, h: pageHeight },
+ margins,
+ footnotes: { refs, blocksById: fnBlocks, topPadding: 4, dividerHeight: 2 },
+ },
+ measureBlock,
+ );
+
+ // Every ref id should appear in at least one fn fragment somewhere
+ // in the rendered layout (band painter is required to either place
+ // the fn fully or split it across pages — never silently drop).
+ const renderedFnIds = new Set();
+ for (const page of result.layout.pages) {
+ for (const f of page.fragments) {
+ if (typeof f.blockId !== 'string') continue;
+ const m = f.blockId.match(/^footnote-(\d+)-/);
+ if (m) renderedFnIds.add(m[1]);
+ }
+ }
+ for (const r of refs) {
+ expect(renderedFnIds.has(r.id)).toBe(true);
+ }
+ });
+
+ // Reproduces the reference fixture's page-10 case: a long stretch of body
+ // before a paragraph that anchors two short fns. Earlier SD dropped fn 2
+ // because the legacy convergence loop left a stale per-page reserve that
+ // misled body's demand check.
+ it('places both fn 1 and fn 2 at the tail of a dense body page', async () => {
+ const BODY_LH = 37;
+ const FN_LH = 14;
+ const SP_AFTER = 16;
+
+ let pos = 0;
+ const bodyBlocks: FlowBlock[] = [];
+ for (let i = 0; i < 17; i += 1) {
+ const t = `dense body paragraph ${i.toString().padStart(2, '0')}`;
+ bodyBlocks.push({
+ kind: 'paragraph',
+ id: `body-${i}`,
+ runs: [{ text: t, fontFamily: 'Arial', fontSize: 12, pmStart: pos, pmEnd: pos + t.length }],
+ });
+ pos += t.length + 1;
+ }
+ const tail = 'paragraph ending with two refs ab cd';
+ bodyBlocks.push({
+ kind: 'paragraph',
+ id: 'anchor-para',
+ runs: [{ text: tail, fontFamily: 'Arial', fontSize: 12, pmStart: pos, pmEnd: pos + tail.length }],
+ });
+ const refs2 = [
+ { id: '1', pos: pos + 30 },
+ { id: '2', pos: pos + 33 },
+ ];
+ const fnBlocks2 = new Map();
+ for (const r of refs2) {
+ fnBlocks2.set(r.id, [
+ {
+ kind: 'paragraph',
+ id: `footnote-${r.id}-0-paragraph`,
+ runs: [{ text: `short fn ${r.id} body`, fontFamily: 'Arial', fontSize: 10, pmStart: 0, pmEnd: 22 }],
+ attrs: { spacing: { after: SP_AFTER } },
+ } as ParagraphBlock,
+ ]);
+ }
+ const measureBlock2 = vi.fn(async (b: FlowBlock) => {
+ if (b.id.startsWith('footnote-')) {
+ return {
+ kind: 'paragraph',
+ lines: [
+ { fromRun: 0, fromChar: 0, toRun: 0, toChar: 22, width: 200, ascent: 11, descent: 3, lineHeight: FN_LH },
+ ],
+ totalHeight: FN_LH,
+ } as Measure;
+ }
+ return {
+ kind: 'paragraph',
+ lines: [
+ { fromRun: 0, fromChar: 0, toRun: 0, toChar: 30, width: 200, ascent: 29, descent: 8, lineHeight: BODY_LH },
+ ],
+ totalHeight: BODY_LH,
+ } as Measure;
+ });
+ const result2 = await incrementalLayout(
+ [],
+ null,
+ bodyBlocks,
+ {
+ pageSize: { w: 612, h: 1056 },
+ margins: { top: 96, right: 72, bottom: 96, left: 72 },
+ footnotes: { refs: refs2, blocksById: fnBlocks2, topPadding: 4, dividerHeight: 6 },
+ },
+ measureBlock2,
+ );
+ const renderedFnIds2 = new Set();
+ for (const page of result2.layout.pages) {
+ for (const f of page.fragments) {
+ if (typeof f.blockId !== 'string') continue;
+ const m = f.blockId.match(/^footnote-(\d+)-/);
+ if (m) renderedFnIds2.add(m[1]);
+ }
+ }
+ expect(renderedFnIds2.has('1')).toBe(true);
+ expect(renderedFnIds2.has('2')).toBe(true);
+ // Both fns must live on the same page as their anchor paragraph.
+ let anchorPage = -1;
+ for (let pi = 0; pi < result2.layout.pages.length; pi++) {
+ if (result2.layout.pages[pi].fragments.some((f) => f.blockId === 'anchor-para')) {
+ anchorPage = pi;
+ break;
+ }
+ }
+ expect(anchorPage).toBeGreaterThanOrEqual(0);
+ const pagesOf2 = (id: string) =>
+ result2.layout.pages
+ .map((p, idx) =>
+ p.fragments.some((f) => typeof f.blockId === 'string' && f.blockId.startsWith(`footnote-${id}-`)) ? idx : -1,
+ )
+ .filter((i) => i >= 0);
+ expect(pagesOf2('1')).toContain(anchorPage);
+ expect(pagesOf2('2')).toContain(anchorPage);
+ });
+
+ it('keeps both refs from the same paragraph on the same page when they fit', async () => {
+ // Mirrors the reference fixture's page-16 scenario: a paragraph with two
+ // closely-clustered refs whose anchors live on different lines of
+ // the SAME paragraph. Both should land on the same page's band.
+ const BODY_LINE_HEIGHT = 24;
+ const FN_LINE_HEIGHT = 14;
+
+ const text = 'L1 line1 L2 line2 L3 line3';
+ const block: FlowBlock = {
+ kind: 'paragraph',
+ id: 'two-ref-para',
+ runs: [{ text, fontFamily: 'Arial', fontSize: 12, pmStart: 0, pmEnd: text.length }],
+ };
+ const refs = [
+ { id: 'A', pos: 8 },
+ { id: 'B', pos: 16 },
+ ];
+ const fnBlocks = new Map();
+ for (const r of refs) {
+ fnBlocks.set(r.id, [
+ {
+ kind: 'paragraph',
+ id: `footnote-${r.id}-0-paragraph`,
+ runs: [{ text: `fn ${r.id}`, fontFamily: 'Arial', fontSize: 10, pmStart: 0, pmEnd: 8 }],
+ },
+ ]);
+ }
+ const measureBlock = vi.fn(async (b: FlowBlock) => {
+ if (b.id.startsWith('footnote-')) {
+ return {
+ kind: 'paragraph',
+ lines: [
+ {
+ fromRun: 0,
+ fromChar: 0,
+ toRun: 0,
+ toChar: 4,
+ width: 200,
+ ascent: 11,
+ descent: 3,
+ lineHeight: FN_LINE_HEIGHT,
+ },
+ ],
+ totalHeight: FN_LINE_HEIGHT,
+ } as Measure;
+ }
+ const lines = Array.from({ length: 6 }, (_, i) => ({
+ fromRun: 0,
+ fromChar: i,
+ toRun: 0,
+ toChar: i + 1,
+ width: 200,
+ ascent: 19,
+ descent: 5,
+ lineHeight: BODY_LINE_HEIGHT,
+ }));
+ return { kind: 'paragraph', lines, totalHeight: 6 * BODY_LINE_HEIGHT } as Measure;
+ });
+
+ const result = await incrementalLayout(
+ [],
+ null,
+ [block],
+ {
+ pageSize: { w: 612, h: 900 },
+ margins: { top: 72, right: 72, bottom: 72, left: 72 },
+ footnotes: { refs, blocksById: fnBlocks, topPadding: 4, dividerHeight: 2 },
+ },
+ measureBlock,
+ );
+
+ // Collect the page each fn id landed on.
+ const pageOfFn = new Map();
+ for (let pageIndex = 0; pageIndex < result.layout.pages.length; pageIndex++) {
+ for (const f of result.layout.pages[pageIndex].fragments) {
+ if (typeof f.blockId !== 'string') continue;
+ const m = f.blockId.match(/^footnote-([A-Z])-/);
+ if (m) pageOfFn.set(m[1], pageIndex);
+ }
+ }
+ expect(pageOfFn.has('A')).toBe(true);
+ expect(pageOfFn.has('B')).toBe(true);
+ expect(pageOfFn.get('A')).toBe(pageOfFn.get('B'));
+ });
+});
diff --git a/packages/layout-engine/layout-bridge/test/footnoteContinuationDemand.test.ts b/packages/layout-engine/layout-bridge/test/footnoteContinuationDemand.test.ts
new file mode 100644
index 0000000000..ddaa613476
--- /dev/null
+++ b/packages/layout-engine/layout-bridge/test/footnoteContinuationDemand.test.ts
@@ -0,0 +1,140 @@
+/**
+ * SD-3050: Continuation-aware break — body pagination on page N+1 must reserve
+ * for footnote slices that continued from page N (before the body lays out, so
+ * body content does not need to be re-broken on a later pass).
+ *
+ * After PR #2881 the reserve loop converges to a layout where reserves[N+1]
+ * includes carry-forward height. SD-3050 verifies the final layout assigns
+ * the right body height on continuation pages and the loop reaches that state.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import type { FlowBlock, Measure } from '@superdoc/contracts';
+import { incrementalLayout } from '../src/incrementalLayout';
+
+const makeParagraph = (id: string, text: string, pmStart: number): FlowBlock => ({
+ kind: 'paragraph',
+ id,
+ runs: [{ text, fontFamily: 'Arial', fontSize: 12, pmStart, pmEnd: pmStart + text.length }],
+});
+
+const makeMeasure = (lineHeight: number, lineCount: number): Measure => ({
+ kind: 'paragraph',
+ lines: Array.from({ length: lineCount }, (_, i) => ({
+ fromRun: 0,
+ fromChar: i,
+ toRun: 0,
+ toChar: i + 1,
+ width: 200,
+ ascent: lineHeight * 0.8,
+ descent: lineHeight * 0.2,
+ lineHeight,
+ })),
+ totalHeight: lineCount * lineHeight,
+});
+
+describe('SD-3050: continuation-aware body pagination', () => {
+ it('reserves carry-forward demand on the continuation page so body packs tight', async () => {
+ // Page geometry: body region 600px.
+ // Document: enough body paragraphs to require ≥2 pages of body content
+ // by themselves (40 paragraphs × 20px = 800px > 600px region). The ref
+ // is anchored on page 1, and the footnote is large enough that page 1's
+ // band cannot fit it — forcing carry-forward to page 2's band.
+ //
+ // Under the bodyMaxY-anchored architecture the page count is driven by
+ // body content, so this fixture must produce ≥2 pages from body alone
+ // (the planner does not synthesize standalone pages just for footnote
+ // continuation). The continuation invariant — "page 2 reserves
+ // carry-forward demand BEFORE body lays out so body packs tight" — is
+ // exactly what we assert against the converged final layout.
+ //
+ // pageH = 744; maxReserve ≈ 599 (page minus margins minus 1px floor).
+ // Footnote demand ≈ 720px + overhead, exceeds maxReserve, overflows to p2.
+
+ const BODY_LINES = 40;
+ const FOOTNOTE_LINES = 60;
+ const LINE_H = 20;
+ const FOOTNOTE_LINE_H = 12;
+
+ let pos = 0;
+ const blocks: FlowBlock[] = [];
+ for (let i = 0; i < BODY_LINES; i += 1) {
+ const text = `Body line ${i + 1}.`;
+ blocks.push(makeParagraph(`body-${i}`, text, pos));
+ pos += text.length + 1;
+ }
+ // Ref in the very first body paragraph
+ const refBlock = blocks[0];
+ const refPos = (refBlock.kind === 'paragraph' ? (refBlock.runs?.[0]?.pmStart ?? 0) : 0) + 2;
+ const ftBlock = makeParagraph('footnote-1-0-paragraph', 'Big footnote.', 0);
+
+ const measureBlock = vi.fn(async (b: FlowBlock) => {
+ if (b.id.startsWith('footnote-')) return makeMeasure(FOOTNOTE_LINE_H, FOOTNOTE_LINES);
+ return makeMeasure(LINE_H, 1);
+ });
+
+ const margins = { top: 72, right: 72, bottom: 72, left: 72 };
+ const result = await incrementalLayout(
+ [],
+ null,
+ blocks,
+ {
+ pageSize: { w: 612, h: 600 + margins.top + margins.bottom },
+ margins,
+ footnotes: {
+ refs: [{ id: '1', pos: refPos }],
+ blocksById: new Map([['1', [ftBlock]]]),
+ topPadding: 6,
+ dividerHeight: 6,
+ },
+ },
+ measureBlock,
+ );
+
+ // The footnote should span pages 1 and 2.
+ expect(result.layout.pages.length).toBeGreaterThanOrEqual(2);
+
+ const page2 = result.layout.pages[1];
+ expect(page2).toBeTruthy();
+
+ // Page 2 must have a continuation reserve > 0 (carry-forward demand).
+ expect(page2.footnoteReserved ?? 0).toBeGreaterThan(0);
+
+ // Page 2 must contain a continuation footnote fragment AND it must fit
+ // strictly within the reserved band (no overflow into the bottom margin).
+ const footFrags = page2.fragments.filter((f) => String(f.blockId).startsWith('footnote-'));
+ expect(footFrags.length).toBeGreaterThan(0);
+
+ // Footnote fragments must not overflow the physical page bottom margin.
+ // Note: page.margins.bottom is the *inflated* margin (incl. reserve);
+ // the physical edge we must not cross is pageH minus the original
+ // bottom margin (the un-inflated value used for the page footer).
+ const pageH = page2.size?.h ?? 744;
+ for (const f of footFrags) {
+ const y = (f as { y?: number }).y ?? 0;
+ const h = (f as { height?: number }).height ?? 0;
+ // Para fragments don't carry an explicit height field — derive when
+ // the fragment is a paragraph slice; for drawing fragments h is set.
+ const fromLine = (f as { fromLine?: number }).fromLine;
+ const toLine = (f as { toLine?: number }).toLine;
+ const derivedH =
+ h || (typeof fromLine === 'number' && typeof toLine === 'number' ? (toLine - fromLine) * FOOTNOTE_LINE_H : 0);
+ expect(y + derivedH).toBeLessThanOrEqual(pageH - margins.bottom + 1);
+ }
+
+ // Body on page 2 must NOT fill the page top-to-bottom — the reserve must
+ // shrink the body region on the converged layout.
+ const bodyMaxBottom = page2.fragments
+ .filter((f) => !String(f.blockId).startsWith('footnote-'))
+ .reduce((max, f) => {
+ const y = (f as { y?: number }).y ?? 0;
+ const fromLine = (f as { fromLine?: number }).fromLine ?? 0;
+ const toLine = (f as { toLine?: number }).toLine ?? fromLine + 1;
+ const lineCount = Math.max(1, toLine - fromLine);
+ return Math.max(max, y + lineCount * LINE_H);
+ }, 0);
+
+ const reserveTop = pageH - margins.bottom - (page2.footnoteReserved ?? 0);
+ expect(bodyMaxBottom).toBeLessThanOrEqual(reserveTop + 1);
+ });
+});
diff --git a/packages/layout-engine/layout-bridge/test/footnoteMultiPass.test.ts b/packages/layout-engine/layout-bridge/test/footnoteMultiPass.test.ts
index d2e011136a..64b2b26866 100644
--- a/packages/layout-engine/layout-bridge/test/footnoteMultiPass.test.ts
+++ b/packages/layout-engine/layout-bridge/test/footnoteMultiPass.test.ts
@@ -63,7 +63,14 @@ describe('Footnote multi-pass reserve loop', () => {
it('runs multiple layout passes when footnotes shift pages and stabilizes correctly', async () => {
const BODY_LINE_HEIGHT = 20;
const FOOTNOTE_LINE_HEIGHT = 12;
- const LINES_ON_PAGE_1_WITHOUT_RESERVE = 12;
+ // 20 body paragraphs so body content naturally spans 2 pages in the
+ // bodyMaxY-anchored architecture (12 lines on p1 + 8 on p2 without
+ // reserves). The ref lives in the *last* paragraph (page 2), and the
+ // footnote is large enough that page 2's band reserve shifts body
+ // breaks — re-pushing some content forward. The reserve loop iterates
+ // until the layout stabilizes (page count, ref placement, reserves all
+ // settle).
+ const LINES_ON_PAGE_1_WITHOUT_RESERVE = 20;
const FOOTNOTE_LINES = 5;
let pos = 0;
@@ -73,7 +80,7 @@ describe('Footnote multi-pass reserve loop', () => {
bodyBlocks.push(makeParagraph(`body-${i}`, text, pos));
pos += text.length + 1; // +1 for implied break
}
- // Ref in last body block (so on page 1 when no reserve, then moves to page 2 when we reserve)
+ // Ref in last body block (lives on page 2 in the converged layout).
const refPos = pos - 2; // inside last paragraph
const footnoteBlock = makeParagraph(
'footnote-1-0-paragraph',
@@ -89,7 +96,7 @@ describe('Footnote multi-pass reserve loop', () => {
return makeMeasure(BODY_LINE_HEIGHT, textLength);
});
- // Content height 240px: 12 * 20 = 240. With ~80px reserve → 160px → 8 lines on page 1.
+ // Content height 240px (= 12 body lines per page without reserves).
const contentHeight = 240;
const margins = { top: 72, right: 72, bottom: 72, left: 72 };
const pageHeight = contentHeight + margins.top + margins.bottom;
@@ -113,13 +120,16 @@ describe('Footnote multi-pass reserve loop', () => {
measureBlock,
);
- const footnoteReserveCalls = layoutDocSpy.mock.calls.filter((call) =>
- (call[2] as { footnoteReservedByPageIndex?: number[] })?.footnoteReservedByPageIndex?.some((h) => h > 0),
- );
layoutDocSpy.mockRestore();
- expect(footnoteReserveCalls.length).toBeGreaterThanOrEqual(2);
-
+ // The SD-2656 bodyMaxY-anchored architecture is allowed to converge in a
+ // single layout pass — the slicer's range-aware demand (charged line by
+ // line as body commits) decides break points in-line, so the reserve
+ // back-and-forth that the legacy multi-pass loop needed is unnecessary
+ // for most cases. What matters for "stabilizes correctly" is the
+ // converged final layout, asserted below: ref migrates to page 2 along
+ // with its footnote, page 2 reserves space for the band, body doesn't
+ // overlap the band.
const { layout } = result;
expect(layout.pages.length).toBeGreaterThanOrEqual(2);
@@ -131,19 +141,30 @@ describe('Footnote multi-pass reserve loop', () => {
const pageOfFootnote = layout.pages.find((p) => p.fragments.some((f) => f.blockId === footnoteBlock.id));
expect(pageOfFootnote).toBe(page2);
- // Sanity: footnote band does not overlap body (reserve is at bottom; body content ends above it)
+ // Sanity: footnote band does not overlap body.
+ // In the bodyMaxY-anchored architecture the band paints immediately
+ // below the last body fragment (at `page.bodyMaxY`), so the structural
+ // invariant is "page.bodyMaxY sits at or below the bottom of every
+ // body fragment, AND the band itself ends at or above the physical page
+ // bottom (pageH - bottomMargin)". Using `page.bodyMaxY` here instead of
+ // the legacy `pageH - bottomMargin - reserve` formula keeps the test
+ // aligned with the band's actual paint anchor.
const bodyFragmentsOnPage2 = page2.fragments.filter(
(f) => f.blockId !== footnoteBlock.id && !String(f.blockId).startsWith('footnote-separator'),
);
- const footnoteBandTop =
- (page2.size?.h ?? pageHeight) - (page2.margins?.bottom ?? margins.bottom) - (page2.footnoteReserved ?? 0);
+ const bodyMaxY = (page2 as { bodyMaxY?: number }).bodyMaxY ?? 0;
+ expect(bodyMaxY).toBeGreaterThan(0);
for (const f of bodyFragmentsOnPage2) {
const fragBottom =
'y' in f && typeof f.y === 'number' && 'height' in f
? f.y + (f.height as number)
: ((f as { y?: number }).y ?? 0);
- expect(fragBottom).toBeLessThanOrEqual(footnoteBandTop + 1);
+ expect(fragBottom).toBeLessThanOrEqual(bodyMaxY + 1);
}
+ // Band must fit within the physical page bottom (no overflow into the
+ // bottom margin / footer region).
+ const physicalBottom = (page2.size?.h ?? pageHeight) - (margins.bottom ?? 72);
+ expect(bodyMaxY + (page2.footnoteReserved ?? 0)).toBeLessThanOrEqual(physicalBottom + 1);
});
it('does not exhaust max reserve passes when reserves oscillate between pages', async () => {
diff --git a/packages/layout-engine/layout-bridge/test/footnoteOrderedCluster.test.ts b/packages/layout-engine/layout-bridge/test/footnoteOrderedCluster.test.ts
new file mode 100644
index 0000000000..b61debe07a
--- /dev/null
+++ b/packages/layout-engine/layout-bridge/test/footnoteOrderedCluster.test.ts
@@ -0,0 +1,222 @@
+import { describe, it, expect, vi } from 'vitest';
+import type { FlowBlock, Measure } from '@superdoc/contracts';
+import { incrementalLayout } from '../src/incrementalLayout';
+
+/**
+ * SD-2656: ordered-cluster rule.
+ *
+ * For a body page with N footnote refs [r1, r2, ..., rN]:
+ * - r1 through r_{N-1} MUST render completely on that page.
+ * - rN MUST render at least the first valid line/run on that page.
+ * - Only rN may continue onto subsequent pages.
+ *
+ * These tests build small synthetic fixtures where the rule is decisive:
+ * footnote bodies large enough that the legacy "sum of fullHeight for every
+ * anchor" demand model would split the cluster, but small enough that the
+ * ordered-cluster demand (full of non-last + firstLine of last) leaves room
+ * for the whole cluster on one body page.
+ */
+
+const BODY_LH = 24;
+const FN_LH = 14;
+const PAGE_H = 800;
+const PAGE_W = 612;
+const MARGINS = { top: 72, right: 72, bottom: 72, left: 72 };
+
+type ClusterCase = {
+ /** Number of refs introduced on the anchor body line. */
+ anchorCount: number;
+ /**
+ * Per-footnote line count. Index i → footnote i+1's body height in lines.
+ * The last entry is typically larger so the rule is exercised.
+ */
+ fnLineCounts: number[];
+ /**
+ * Optional: per-footnote paragraph count (default 1 each). If > 1, the
+ * footnote body is split across multiple paragraphs to exercise the
+ * multi-paragraph completion rule.
+ */
+ fnParagraphCounts?: number[];
+};
+
+/**
+ * Builds a single body paragraph that anchors N footnotes near its end.
+ * Each footnote is a single paragraph whose measured height is
+ * `lineCount * FN_LH`.
+ */
+async function runClusterCase(c: ClusterCase) {
+ expect(c.fnLineCounts.length).toBe(c.anchorCount);
+ const text = 'cluster body with anchors here.';
+ const block: FlowBlock = {
+ kind: 'paragraph',
+ id: 'body-0',
+ runs: [{ text, fontFamily: 'Arial', fontSize: 12, pmStart: 0, pmEnd: text.length }],
+ };
+ const refs = Array.from({ length: c.anchorCount }, (_, i) => ({
+ id: String(i + 1),
+ pos: text.length - c.anchorCount + i, // last few positions
+ }));
+ const fnBlocks = new Map();
+ refs.forEach((r, refIdx) => {
+ const paraCount = c.fnParagraphCounts?.[refIdx] ?? 1;
+ const blocks: FlowBlock[] = [];
+ for (let p = 0; p < paraCount; p += 1) {
+ blocks.push({
+ kind: 'paragraph',
+ id: `footnote-${r.id}-${p}-paragraph`,
+ runs: [{ text: `fn ${r.id} para ${p}`, fontFamily: 'Arial', fontSize: 10, pmStart: 0, pmEnd: 16 }],
+ });
+ }
+ fnBlocks.set(r.id, blocks);
+ });
+
+ const measureBlock = vi.fn(async (b: FlowBlock) => {
+ if (b.id.startsWith('footnote-')) {
+ const m = b.id.match(/^footnote-(\d+)-(\d+)/);
+ const idx = m ? Number(m[1]) - 1 : 0;
+ // Total lines for the footnote split across its paragraphs.
+ const totalLines = c.fnLineCounts[idx] ?? 1;
+ const paraCount = c.fnParagraphCounts?.[idx] ?? 1;
+ // Distribute lines roughly evenly across paragraphs.
+ const linesPerPara = Math.max(1, Math.ceil(totalLines / paraCount));
+ const lines = Array.from({ length: linesPerPara }, () => ({
+ fromRun: 0,
+ fromChar: 0,
+ toRun: 0,
+ toChar: 1,
+ width: 200,
+ ascent: FN_LH * 0.8,
+ descent: FN_LH * 0.2,
+ lineHeight: FN_LH,
+ }));
+ return { kind: 'paragraph', lines, totalHeight: linesPerPara * FN_LH } as Measure;
+ }
+ // body block: 6 lines, all anchors fit on the first line
+ const lines = Array.from({ length: 6 }, () => ({
+ fromRun: 0,
+ fromChar: 0,
+ toRun: 0,
+ toChar: 1,
+ width: 200,
+ ascent: BODY_LH * 0.8,
+ descent: BODY_LH * 0.2,
+ lineHeight: BODY_LH,
+ }));
+ return { kind: 'paragraph', lines, totalHeight: 6 * BODY_LH } as Measure;
+ });
+
+ const result = await incrementalLayout(
+ [],
+ null,
+ [block],
+ {
+ pageSize: { w: PAGE_W, h: PAGE_H },
+ margins: MARGINS,
+ footnotes: { refs, blocksById: fnBlocks, topPadding: 4, dividerHeight: 2 },
+ },
+ measureBlock,
+ );
+
+ // Collect footnote slices per page in document order.
+ // blockId convention from FootnotesBuilder: "footnote--..."
+ type SliceInfo = { id: string; pageIndex: number; continuesOnNext: boolean; fromLine: number; toLine: number };
+ const slices: SliceInfo[] = [];
+ result.layout.pages.forEach((page, pageIndex) => {
+ for (const frag of page.fragments) {
+ if (typeof frag.blockId !== 'string') continue;
+ const m = frag.blockId.match(/^footnote-(\d+)-/);
+ if (!m || frag.kind !== 'para') continue;
+ slices.push({
+ id: m[1],
+ pageIndex,
+ continuesOnNext: !!(frag as { continuesOnNext?: boolean }).continuesOnNext,
+ fromLine: (frag as { fromLine?: number }).fromLine ?? 0,
+ toLine: (frag as { toLine?: number }).toLine ?? 0,
+ });
+ }
+ });
+ return { slices, refs };
+}
+
+describe('SD-2656: ordered-cluster rule', () => {
+ it('1-anchor cluster: the single anchor starts on its anchor page', async () => {
+ const { slices } = await runClusterCase({
+ anchorCount: 1,
+ fnLineCounts: [3],
+ });
+ // Anchor is on page 0 → fn 1 must have at least one slice on page 0.
+ const fn1OnPage0 = slices.filter((s) => s.id === '1' && s.pageIndex === 0);
+ expect(fn1OnPage0.length).toBeGreaterThan(0);
+ expect(fn1OnPage0[0].fromLine).toBe(0);
+ });
+
+ it('2-anchor cluster: A completes on anchor page, only B may split', async () => {
+ // fn 1: 3 lines (must fully complete on page 0).
+ // fn 2: 8 lines (large; may split — only fn 2 is allowed to continue).
+ const { slices } = await runClusterCase({
+ anchorCount: 2,
+ fnLineCounts: [3, 8],
+ });
+ const fn1Page0 = slices.filter((s) => s.id === '1' && s.pageIndex === 0);
+ const fn2Page0 = slices.filter((s) => s.id === '2' && s.pageIndex === 0);
+
+ // fn 1 (non-last) must render fully on page 0 — its last slice on page 0
+ // must NOT have continuesOnNext.
+ expect(fn1Page0.length).toBeGreaterThan(0);
+ expect(fn1Page0[fn1Page0.length - 1].continuesOnNext).toBe(false);
+
+ // fn 2 (last) must have at least one rendered line on page 0.
+ expect(fn2Page0.length).toBeGreaterThan(0);
+ expect(fn2Page0[0].fromLine).toBe(0);
+
+ // Only fn 2 may produce a slice on a later page. fn 1 must not.
+ const fn1Later = slices.filter((s) => s.id === '1' && s.pageIndex > 0);
+ expect(fn1Later.length).toBe(0);
+ });
+
+ it('multi-paragraph non-last footnote: ALL paragraphs render on anchor page (no orphan tail)', async () => {
+ // fn 1: 3 paragraphs (6 lines total). MUST fully render on anchor page.
+ // fn 2: 2 paragraphs (3 lines total). Last anchor, may split if needed.
+ const { slices } = await runClusterCase({
+ anchorCount: 2,
+ fnLineCounts: [6, 3],
+ fnParagraphCounts: [3, 2],
+ });
+
+ // fn 1 (non-last) must have NO slices on any page after the anchor page.
+ const fn1Pages = new Set(slices.filter((s) => s.id === '1').map((s) => s.pageIndex));
+ const fn1AnchorPage = Math.min(...fn1Pages);
+ const fn1Trailing = [...fn1Pages].filter((p) => p > fn1AnchorPage);
+ expect(fn1Trailing).toEqual([]);
+
+ // Last slice on the anchor page must not be a mid-paragraph continuation.
+ const fn1OnAnchor = slices.filter((s) => s.id === '1' && s.pageIndex === fn1AnchorPage);
+ expect(fn1OnAnchor.length).toBeGreaterThan(0);
+ expect(fn1OnAnchor[fn1OnAnchor.length - 1].continuesOnNext).toBe(false);
+ });
+
+ it('3-anchor cluster: A and B complete on anchor page, only C may split', async () => {
+ // fn 1, fn 2: short (must fully complete).
+ // fn 3: large (the only one allowed to split).
+ const { slices } = await runClusterCase({
+ anchorCount: 3,
+ fnLineCounts: [2, 2, 10],
+ });
+ const fn1Page0 = slices.filter((s) => s.id === '1' && s.pageIndex === 0);
+ const fn2Page0 = slices.filter((s) => s.id === '2' && s.pageIndex === 0);
+ const fn3Page0 = slices.filter((s) => s.id === '3' && s.pageIndex === 0);
+
+ expect(fn1Page0.length).toBeGreaterThan(0);
+ expect(fn1Page0[fn1Page0.length - 1].continuesOnNext).toBe(false);
+
+ expect(fn2Page0.length).toBeGreaterThan(0);
+ expect(fn2Page0[fn2Page0.length - 1].continuesOnNext).toBe(false);
+
+ expect(fn3Page0.length).toBeGreaterThan(0);
+ expect(fn3Page0[0].fromLine).toBe(0);
+
+ // fn 1 and fn 2 must not appear on later pages.
+ expect(slices.filter((s) => s.id === '1' && s.pageIndex > 0).length).toBe(0);
+ expect(slices.filter((s) => s.id === '2' && s.pageIndex > 0).length).toBe(0);
+ });
+});
diff --git a/packages/layout-engine/layout-bridge/test/footnotePageOverflow.test.ts b/packages/layout-engine/layout-bridge/test/footnotePageOverflow.test.ts
new file mode 100644
index 0000000000..bbd15616b7
--- /dev/null
+++ b/packages/layout-engine/layout-bridge/test/footnotePageOverflow.test.ts
@@ -0,0 +1,241 @@
+/**
+ * SD-2656: Hard invariants that no body or footnote fragment may extend past
+ * the page's physical bottom margin.
+ *
+ * The existing footnoteBandOverflow tests cover oversized-footnote splits.
+ * These tests are wider: they apply to every fixture and every page, and
+ * they fail loud when the layout engine produces a Page whose painted
+ * content cannot all fit between the top and bottom margins.
+ *
+ * Why this matters (SD-2656 case study):
+ * The range-aware footnote demand fix moved the band to bodyMaxY. On
+ * dense pages this could leave the band with less space than the planner
+ * thought it had, painting fn body content past `pageH - bottomMargin`.
+ * In the browser, that content was clipped (invisible) — which a screenshot
+ * diff against Word made obvious, but no unit test caught.
+ *
+ * These tests would have caught it.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import type { FlowBlock, Measure, Fragment } from '@superdoc/contracts';
+import { incrementalLayout } from '../src/incrementalLayout';
+
+const PAGE_BOTTOM_TOLERANCE_PX = 1;
+
+const makeParagraph = (id: string, text: string, pmStart: number): FlowBlock => ({
+ kind: 'paragraph',
+ id,
+ runs: [{ text, fontFamily: 'Arial', fontSize: 12, pmStart, pmEnd: pmStart + text.length }],
+});
+
+const makeMeasure = (lineHeight: number, lineCount: number, textLen = 30): Measure => ({
+ kind: 'paragraph',
+ lines: Array.from({ length: lineCount }, (_, i) => ({
+ fromRun: 0,
+ fromChar: i * textLen,
+ toRun: 0,
+ toChar: (i + 1) * textLen,
+ width: 200,
+ ascent: lineHeight * 0.8,
+ descent: lineHeight * 0.2,
+ lineHeight,
+ })),
+ totalHeight: lineCount * lineHeight,
+});
+
+/**
+ * Compute every fragment's bottom-Y on a given page. Para fragments report
+ * `toLine - fromLine` × line-height (the renderer's effective height); drawing
+ * fragments report `height` directly.
+ */
+const fragmentBottom = (f: Fragment, lineHeight: number): number => {
+ const y = (f as { y?: number }).y ?? 0;
+ if (f.kind === 'para') {
+ const fromLine = (f as { fromLine?: number }).fromLine ?? 0;
+ const toLine = (f as { toLine?: number }).toLine ?? fromLine + 1;
+ return y + (toLine - fromLine) * lineHeight;
+ }
+ if (typeof (f as { height?: number }).height === 'number') {
+ return y + (f as { height: number }).height;
+ }
+ return y;
+};
+
+const assertNoOverflow = (
+ layout: {
+ pages: { size?: { h: number }; fragments: Fragment[]; margins?: { bottom?: number } }[];
+ pageSize?: { h: number };
+ },
+ bottomMargin: number,
+ bodyLineHeight: number,
+ footnoteLineHeight: number,
+) => {
+ for (let pageIdx = 0; pageIdx < layout.pages.length; pageIdx++) {
+ const page = layout.pages[pageIdx];
+ const pageH = page.size?.h ?? layout.pageSize?.h ?? 0;
+ // We deliberately use the *physical* bottom margin (the one the layout
+ // engine was given), not page.margins.bottom — the convergence loop
+ // inflates page.margins.bottom by the per-page reserve, which would make
+ // the test trivially pass.
+ const pageBottomLimit = pageH - bottomMargin;
+ for (const f of page.fragments) {
+ const isFootnote = typeof f.blockId === 'string' && f.blockId.startsWith('footnote-');
+ const lh = isFootnote ? footnoteLineHeight : bodyLineHeight;
+ const bottom = fragmentBottom(f, lh);
+ if (bottom > pageBottomLimit + PAGE_BOTTOM_TOLERANCE_PX) {
+ throw new Error(
+ `Fragment ${f.blockId ?? '?'} on page ${pageIdx + 1} extends to y=${bottom.toFixed(1)}, ` +
+ `past pageBottomLimit=${pageBottomLimit} (pageH=${pageH}, bottomMargin=${bottomMargin}).`,
+ );
+ }
+ }
+ }
+};
+
+describe('SD-2656: hard invariant — no fragment may extend past the page bottom margin', () => {
+ it('holds when body has multiple fns clustered on a single anchor paragraph', async () => {
+ // 12 body paragraphs, paragraph 8 anchors 3 fns; each fn body is 5 lines.
+ // Page area is sized so all 3 fn bodies fit on page 1 if the band is sized
+ // correctly, or fn 3 must split / spill to page 2 otherwise. Either is OK
+ // — the invariant is that NO fragment overflows.
+ let pos = 0;
+ const blocks: FlowBlock[] = [];
+ for (let i = 0; i < 12; i += 1) {
+ const text = `Body paragraph ${i}`;
+ blocks.push(makeParagraph(`body-${i}`, text, pos));
+ pos += text.length + 1;
+ }
+ const anchorBlock = blocks[7];
+ const anchorPos = anchorBlock.kind === 'paragraph' ? (anchorBlock.runs?.[0]?.pmStart ?? 0) + 1 : 0;
+ const refs = [
+ { id: 'a', pos: anchorPos },
+ { id: 'b', pos: anchorPos + 2 },
+ { id: 'c', pos: anchorPos + 4 },
+ ];
+ const fnBlocks = new Map();
+ for (const r of refs) {
+ fnBlocks.set(r.id, [makeParagraph(`footnote-${r.id}-0-paragraph`, `fn ${r.id} body`, 0)]);
+ }
+ const BODY_LH = 20;
+ const FN_LH = 12;
+ const measureBlock = vi.fn(async (b: FlowBlock) =>
+ b.id.startsWith('footnote-') ? makeMeasure(FN_LH, 5) : makeMeasure(BODY_LH, 1),
+ );
+
+ const margins = { top: 72, right: 72, bottom: 72, left: 72 };
+ const result = await incrementalLayout(
+ [],
+ null,
+ blocks,
+ {
+ pageSize: { w: 612, h: 12 * BODY_LH + margins.top + margins.bottom + 50 },
+ margins,
+ footnotes: { refs, blocksById: fnBlocks, topPadding: 4, dividerHeight: 2 },
+ },
+ measureBlock,
+ );
+ expect(() => assertNoOverflow(result.layout, margins.bottom, BODY_LH, FN_LH)).not.toThrow();
+ });
+
+ it('holds when a footnote body is taller than half the page', async () => {
+ // Single fn whose body is 30 lines × 12 = 360 px. Page area is small
+ // enough that the fn cannot fit on one page — planner must split.
+ const block = makeParagraph('p0', 'Body with one anchor here.', 0);
+ const anchorPos = block.kind === 'paragraph' ? (block.runs?.[0]?.pmStart ?? 0) + 1 : 0;
+ const fnBlock = makeParagraph('footnote-1-0-paragraph', 'large fn body', 0);
+ const BODY_LH = 20;
+ const FN_LH = 12;
+ const measureBlock = vi.fn(async (b: FlowBlock) =>
+ b.id.startsWith('footnote-') ? makeMeasure(FN_LH, 30) : makeMeasure(BODY_LH, 1),
+ );
+ const margins = { top: 72, right: 72, bottom: 72, left: 72 };
+ const result = await incrementalLayout(
+ [],
+ null,
+ [block],
+ {
+ pageSize: { w: 612, h: 350 + margins.top + margins.bottom }, // content area = 350 px
+ margins,
+ footnotes: {
+ refs: [{ id: '1', pos: anchorPos }],
+ blocksById: new Map([['1', [fnBlock]]]),
+ topPadding: 4,
+ dividerHeight: 2,
+ },
+ },
+ measureBlock,
+ );
+ expect(() => assertNoOverflow(result.layout, margins.bottom, BODY_LH, FN_LH)).not.toThrow();
+ });
+
+ it('holds when many anchored fns cumulate to more than fits in a single band', async () => {
+ // The dense-cluster scenario: one body paragraph with 6 short fn anchors,
+ // each fn body taking 4 lines. Total band demand = 6 × 48 + overhead, which
+ // may exceed any single page's available band space — planner must defer
+ // some fns to the next page (matching Word's behavior on the reference fixture's p25).
+ const block = makeParagraph('p0', 'Six anchors here', 0);
+ const blockPmStart = block.kind === 'paragraph' ? (block.runs?.[0]?.pmStart ?? 0) : 0;
+ const refs = Array.from({ length: 6 }, (_, i) => ({ id: `${i + 1}`, pos: blockPmStart + i + 1 }));
+ const fnBlocks = new Map();
+ for (const r of refs) {
+ fnBlocks.set(r.id, [makeParagraph(`footnote-${r.id}-0-paragraph`, `fn ${r.id} body`, 0)]);
+ }
+ const BODY_LH = 20;
+ const FN_LH = 12;
+ const measureBlock = vi.fn(async (b: FlowBlock) =>
+ b.id.startsWith('footnote-') ? makeMeasure(FN_LH, 4) : makeMeasure(BODY_LH, 1),
+ );
+ const margins = { top: 72, right: 72, bottom: 72, left: 72 };
+ const result = await incrementalLayout(
+ [],
+ null,
+ [block],
+ {
+ pageSize: { w: 612, h: 300 + margins.top + margins.bottom },
+ margins,
+ footnotes: { refs, blocksById: fnBlocks, topPadding: 4, dividerHeight: 2 },
+ },
+ measureBlock,
+ );
+ expect(() => assertNoOverflow(result.layout, margins.bottom, BODY_LH, FN_LH)).not.toThrow();
+ });
+
+ it('every footnote ref renders its body somewhere in the layout', async () => {
+ // Companion invariant: even when the planner splits or defers fns, every
+ // ref id in the input must appear as at least one fragment in the output.
+ const block = makeParagraph('p0', 'Three anchors', 0);
+ const blockPmStart = block.kind === 'paragraph' ? (block.runs?.[0]?.pmStart ?? 0) : 0;
+ const refs = [
+ { id: 'A', pos: blockPmStart + 1 },
+ { id: 'B', pos: blockPmStart + 3 },
+ { id: 'C', pos: blockPmStart + 5 },
+ ];
+ const fnBlocks = new Map();
+ for (const r of refs) {
+ fnBlocks.set(r.id, [makeParagraph(`footnote-${r.id}-0-paragraph`, `fn ${r.id} body`, 0)]);
+ }
+ const measureBlock = vi.fn(async (b: FlowBlock) =>
+ b.id.startsWith('footnote-') ? makeMeasure(12, 8) : makeMeasure(20, 1),
+ );
+ const result = await incrementalLayout(
+ [],
+ null,
+ [block],
+ {
+ pageSize: { w: 612, h: 600 },
+ margins: { top: 72, right: 72, bottom: 72, left: 72 },
+ footnotes: { refs, blocksById: fnBlocks, topPadding: 4, dividerHeight: 2 },
+ },
+ measureBlock,
+ );
+ const rendered = new Set();
+ for (const page of result.layout.pages) {
+ for (const f of page.fragments) {
+ const m = typeof f.blockId === 'string' ? f.blockId.match(/^footnote-([^-]+)-/) : null;
+ if (m && !m[1].startsWith('separator') && !m[1].startsWith('continuation')) rendered.add(m[1]);
+ }
+ }
+ for (const r of refs) expect(rendered.has(r.id)).toBe(true);
+ });
+});
diff --git a/packages/layout-engine/layout-bridge/test/footnotePreferredReserve.test.ts b/packages/layout-engine/layout-bridge/test/footnotePreferredReserve.test.ts
new file mode 100644
index 0000000000..6ea579219d
--- /dev/null
+++ b/packages/layout-engine/layout-bridge/test/footnotePreferredReserve.test.ts
@@ -0,0 +1,186 @@
+import { describe, it, expect, vi } from 'vitest';
+import type { FlowBlock, Measure, FootnotePageLedger } from '@superdoc/contracts';
+import { incrementalLayout } from '../src/incrementalLayout';
+
+/**
+ * SD-2656 Phase 7: preferred-reserve / mandatory-or-preferred body acceptance.
+ *
+ * The ordered-cluster rule (Phase 1) defined the MANDATORY minimum:
+ * full(non-last anchors) + firstLine(last anchor)
+ *
+ * Word does NOT lay out at the mandatory minimum when there is room to spare —
+ * it gives the footnote band more vertical space (the "preferred" reserve)
+ * and pushes body text down. SuperDoc's body slicer must do the same:
+ *
+ * 1) accept body lines only while mandatory still fits (hard rule)
+ * 2) when room exists, reserve the preferred amount (full of last too)
+ *
+ * These tests express the preferred behavior and currently FAIL — the body
+ * slicer reserves only the mandatory minimum.
+ */
+
+const PAGE_H = 800;
+const PAGE_W = 612;
+const MARGINS = { top: 72, right: 72, bottom: 72, left: 72 };
+const BODY_LH = 24;
+const FN_LH = 14;
+
+type FootnoteShape = {
+ /** Total measured lines for the footnote body. */
+ lines: number;
+};
+
+async function runScenario(opts: {
+ /** Number of body paragraphs (small content; the footnote band is what we test). */
+ bodyParagraphs: number;
+ /** Footnote shapes in order — first is anchored first, last is the "last anchor". */
+ footnotes: FootnoteShape[];
+}) {
+ const blocks: FlowBlock[] = [];
+ let pos = 0;
+ for (let i = 0; i < opts.bodyParagraphs; i += 1) {
+ const text = `body line ${i + 1}.`;
+ blocks.push({
+ kind: 'paragraph',
+ id: `body-${i}`,
+ runs: [{ text, fontFamily: 'Arial', fontSize: 12, pmStart: pos, pmEnd: pos + text.length }],
+ });
+ pos += text.length + 1;
+ }
+ // All refs on the very first body paragraph, positioned near pmStart so the
+ // anchor positions resolve to a body-0 fragment (positions near pmEnd may
+ // fall outside the line range under the layout engine's pm-position
+ // semantics).
+ const firstBlock = blocks[0];
+ const firstRunStart = (firstBlock.kind === 'paragraph' ? firstBlock.runs?.[0]?.pmStart : undefined) ?? 0;
+ const refs = opts.footnotes.map((_, i) => ({
+ id: String(i + 1),
+ pos: firstRunStart + 2 + i,
+ }));
+
+ const fnBlocks = new Map();
+ refs.forEach((r) => {
+ fnBlocks.set(r.id, [
+ {
+ kind: 'paragraph',
+ id: `footnote-${r.id}-paragraph`,
+ runs: [{ text: `fn ${r.id}`, fontFamily: 'Arial', fontSize: 10, pmStart: 0, pmEnd: 6 }],
+ },
+ ]);
+ });
+
+ const measureBlock = vi.fn(async (b: FlowBlock) => {
+ if (b.id.startsWith('footnote-')) {
+ const m = b.id.match(/^footnote-(\d+)-/);
+ const fnIdx = m ? Number(m[1]) - 1 : 0;
+ const totalLines = opts.footnotes[fnIdx]?.lines ?? 1;
+ return {
+ kind: 'paragraph',
+ lines: Array.from({ length: totalLines }, () => ({
+ fromRun: 0,
+ fromChar: 0,
+ toRun: 0,
+ toChar: 1,
+ width: 200,
+ ascent: FN_LH * 0.8,
+ descent: FN_LH * 0.2,
+ lineHeight: FN_LH,
+ })),
+ totalHeight: totalLines * FN_LH,
+ } as Measure;
+ }
+ // Body block is a paragraph with a single run; the line spans its full
+ // character range so anchor positions inside the paragraph resolve to it.
+ const paragraphRun = b.kind === 'paragraph' ? b.runs?.[0] : undefined;
+ const charCount = paragraphRun ? Math.max(1, (paragraphRun.pmEnd ?? 1) - (paragraphRun.pmStart ?? 0)) : 1;
+ return {
+ kind: 'paragraph',
+ lines: [
+ {
+ fromRun: 0,
+ fromChar: 0,
+ toRun: 0,
+ toChar: charCount,
+ width: 200,
+ ascent: BODY_LH * 0.8,
+ descent: BODY_LH * 0.2,
+ lineHeight: BODY_LH,
+ },
+ ],
+ totalHeight: BODY_LH,
+ } as Measure;
+ });
+
+ const result = await incrementalLayout(
+ [],
+ null,
+ blocks,
+ {
+ pageSize: { w: PAGE_W, h: PAGE_H },
+ margins: MARGINS,
+ footnotes: { refs, blocksById: fnBlocks, topPadding: 4, dividerHeight: 2 },
+ },
+ measureBlock,
+ );
+
+ return { layout: result.layout, refs };
+}
+
+describe('SD-2656 Phase 7: preferred-reserve body acceptance', () => {
+ // Skipped: documents the Word-like preferred-reserve behavior we want.
+ // The planner currently leaves "first-line-only" pages where Word would
+ // have rendered the whole footnote. A naive implementation (always reserve
+ // preferred, break body when it doesn't fit) regressed total drift on
+ // IT-923 because the inflated reserve cascades into more cluster spills
+ // downstream. The right implementation must guard against propagation —
+ // future work tracked in SD-2656 Phase 7.
+ it.skip('single long last footnote: renders MORE than firstLine when capacity exists', async () => {
+ // Page content area = 800-144 = 656px. BODY_LH=24 → ~27 body lines fit.
+ // Body has 26 paragraphs — packs tight under mandatory reserve.
+ // FN has 8 lines × 14 = 112px. Mandatory reserve = 14 + ~10 overhead = 24px.
+ // Preferred reserve = 112 + 10 = 122px. Body packed to mandatory has
+ // (656 - 24) = 632px = 26.3 lines; preferred has (656 - 122) = 534px = 22.2
+ // lines. So preferred forces ~4 body paragraphs to page 2 but renders the
+ // full 8-line footnote on the anchor page (Word-like).
+ const { layout } = await runScenario({
+ bodyParagraphs: 26,
+ footnotes: [{ lines: 8 }],
+ });
+ const page0 = layout.pages[0];
+ const ledger = page0.footnoteLedger as FootnotePageLedger;
+ expect(ledger).toBeDefined();
+ expect(ledger.anchorIds).toEqual(['1']);
+ // The legacy "ordered-minimum" body slicer commits lastAnchorRenderedLines=1.
+ // Preferred behavior: render the full 8 lines because there is room and
+ // it's the only way to avoid "first-line-only" pages.
+ expect(ledger.lastAnchorRenderedLines).toBeGreaterThanOrEqual(8);
+ // FN fully placed on anchor page — no continuation.
+ expect(ledger.continuationOut).toEqual([]);
+ });
+
+ it('mandatory minimum: huge footnote keeps body anchor on page', async () => {
+ // 50 body paragraphs + 30-line footnote. Tests the Phase 1 ordered-minimum
+ // invariant: regardless of how much of the footnote actually fits on page 0,
+ // the body anchor must remain there (no migration to a later page).
+ //
+ // SD-2656 (post-Vivienne+Carlsbad p43): under the +1-page-if-eliminates-split
+ // relaxation, the scorer may accept a one-page growth that fully fits the
+ // 30-line footnote on the anchor page, eliminating the continuation. So
+ // continuationOut may be empty under V1 (full fit) or non-empty under
+ // tighter scenarios — both are valid. The invariant under test is that the
+ // body anchor stays on page 0 either way.
+ const { layout } = await runScenario({
+ bodyParagraphs: 50,
+ footnotes: [{ lines: 30 }],
+ });
+ const page0 = layout.pages[0];
+ const ledger = page0.footnoteLedger as FootnotePageLedger;
+ expect(ledger).toBeDefined();
+ expect(ledger.anchorIds).toEqual(['1']);
+ // Mandatory minimum still satisfied — at least firstLine on the anchor page.
+ expect(ledger.lastAnchorRenderedLines).toBeGreaterThanOrEqual(1);
+ // The body anchor must remain on page 0 (no migration to a later page).
+ const bodyOnPage0 = layout.pages[0].fragments.some((f) => f.blockId === 'body-0');
+ expect(bodyOnPage0).toBe(true);
+ });
+});
diff --git a/packages/layout-engine/layout-bridge/test/footnoteRefMigration.test.ts b/packages/layout-engine/layout-bridge/test/footnoteRefMigration.test.ts
new file mode 100644
index 0000000000..52b791517e
--- /dev/null
+++ b/packages/layout-engine/layout-bridge/test/footnoteRefMigration.test.ts
@@ -0,0 +1,129 @@
+/**
+ * SD-3051: Stability guarantee — when block-aware breaks (SD-3049) cause refs
+ * to migrate between pages during the convergence loop, the final layout must
+ * be deterministic across repeated runs of the same input. The reserve loop
+ * already has cycle detection (incrementalLayout.ts:1864) and growReserves is
+ * monotonic; this regression test guards against future regressions of those
+ * properties.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import type { FlowBlock, Measure } from '@superdoc/contracts';
+import { incrementalLayout } from '../src/incrementalLayout';
+
+const makeParagraph = (id: string, text: string, pmStart: number): FlowBlock => ({
+ kind: 'paragraph',
+ id,
+ runs: [{ text, fontFamily: 'Arial', fontSize: 12, pmStart, pmEnd: pmStart + text.length }],
+});
+
+const makeMeasure = (lineHeight: number, lineCount: number): Measure => ({
+ kind: 'paragraph',
+ lines: Array.from({ length: lineCount }, (_, i) => ({
+ fromRun: 0,
+ fromChar: i,
+ toRun: 0,
+ toChar: i + 1,
+ width: 200,
+ ascent: lineHeight * 0.8,
+ descent: lineHeight * 0.2,
+ lineHeight,
+ })),
+ totalHeight: lineCount * lineHeight,
+});
+
+describe('SD-3051: footnote layout is deterministic across runs', () => {
+ /**
+ * Builds a fixture that exercises the migration-prone path: multiple refs
+ * spread across pages with footnotes large enough that block-aware breaks
+ * shift refs between pages relative to a reserve-naive layout.
+ */
+ const buildFixture = () => {
+ const BODY_LINES = 40;
+ const FOOTNOTE_LINES = 6;
+ const LINE_H = 20;
+ const FOOTNOTE_LINE_H = 12;
+
+ let pos = 0;
+ const blocks: FlowBlock[] = [];
+ for (let i = 0; i < BODY_LINES; i += 1) {
+ const text = `Body line ${i + 1}.`;
+ blocks.push(makeParagraph(`body-${i}`, text, pos));
+ pos += text.length + 1;
+ }
+ // Three refs, spread so they fall on the boundary of pages
+ const refIndexes = [10, 20, 30];
+ const refs = refIndexes.map((idx, n) => {
+ const refBlock = blocks[idx];
+ const refPos = (refBlock.kind === 'paragraph' ? (refBlock.runs?.[0]?.pmStart ?? 0) : 0) + 2;
+ return { id: String(n + 1), pos: refPos };
+ });
+ const blocksById = new Map();
+ for (let n = 1; n <= 3; n += 1) {
+ blocksById.set(String(n), [makeParagraph(`footnote-${n}-0-paragraph`, `Footnote ${n}.`, 0)]);
+ }
+
+ const measureBlock = vi.fn(async (b: FlowBlock) => {
+ if (b.id.startsWith('footnote-')) return makeMeasure(FOOTNOTE_LINE_H, FOOTNOTE_LINES);
+ return makeMeasure(LINE_H, 1);
+ });
+
+ const margins = { top: 72, right: 72, bottom: 72, left: 72 };
+ return {
+ blocks,
+ options: {
+ pageSize: { w: 612, h: 600 + margins.top + margins.bottom },
+ margins,
+ footnotes: { refs, blocksById, topPadding: 6, dividerHeight: 6 },
+ },
+ measureBlock,
+ };
+ };
+
+ it('produces identical page counts and reserves on repeated runs', async () => {
+ const f1 = buildFixture();
+ const r1 = await incrementalLayout([], null, f1.blocks, f1.options, f1.measureBlock);
+
+ const f2 = buildFixture();
+ const r2 = await incrementalLayout([], null, f2.blocks, f2.options, f2.measureBlock);
+
+ expect(r1.layout.pages.length).toBe(r2.layout.pages.length);
+
+ for (let i = 0; i < r1.layout.pages.length; i += 1) {
+ expect(r1.layout.pages[i].footnoteReserved ?? 0).toBe(r2.layout.pages[i].footnoteReserved ?? 0);
+ }
+ });
+
+ it('produces identical ref-to-page assignments on repeated runs', async () => {
+ const refToPage = (result: Awaited>) => {
+ const out = new Map();
+ result.layout.pages.forEach((page, pageIndex) => {
+ for (const f of page.fragments) {
+ const id = String(f.blockId);
+ // The first non-continuation fragment of each footnote indicates
+ // the anchor page. Continuation fragments will be assigned to
+ // later pages, so we record the *minimum* page seen.
+ const match = id.match(/^footnote-(\d+)-/);
+ if (!match) continue;
+ const fnId = match[1];
+ if (!out.has(fnId)) out.set(fnId, pageIndex);
+ else out.set(fnId, Math.min(out.get(fnId) ?? pageIndex, pageIndex));
+ }
+ });
+ return out;
+ };
+
+ const f1 = buildFixture();
+ const r1 = await incrementalLayout([], null, f1.blocks, f1.options, f1.measureBlock);
+ const a1 = refToPage(r1);
+
+ const f2 = buildFixture();
+ const r2 = await incrementalLayout([], null, f2.blocks, f2.options, f2.measureBlock);
+ const a2 = refToPage(r2);
+
+ expect(a1.size).toBe(a2.size);
+ a1.forEach((page, fnId) => {
+ expect(a2.get(fnId)).toBe(page);
+ });
+ });
+});
diff --git a/packages/layout-engine/layout-bridge/test/footnoteScorer.test.ts b/packages/layout-engine/layout-bridge/test/footnoteScorer.test.ts
new file mode 100644
index 0000000000..9969abcb99
--- /dev/null
+++ b/packages/layout-engine/layout-bridge/test/footnoteScorer.test.ts
@@ -0,0 +1,493 @@
+import { describe, expect, it } from 'vitest';
+import type { FootnotePageLedger, Layout } from '@superdoc/contracts';
+import {
+ getPreferredReserveCandidates,
+ getPreferredReserveTrialTargets,
+ scoreFootnoteWindow,
+ summarizeFootnoteWindow,
+} from '../src/footnote-scorer';
+
+const makeLedger = (pageIndex: number, overrides: Partial = {}): FootnotePageLedger => ({
+ pageIndex,
+ anchorIds: [],
+ mandatorySliceIds: [],
+ continuationSliceIds: [],
+ extendedSliceIds: [],
+ continuationIn: [],
+ continuationOut: [],
+ mandatoryReservePx: 0,
+ preferredReservePx: 0,
+ actualBandHeightPx: 0,
+ appliedBodyReservePx: 0,
+ deadReservePx: 0,
+ lastAnchorRenderedLines: 0,
+ ...overrides,
+});
+
+const makeLayout = (pageCount: number, ledgers: FootnotePageLedger[]): Layout =>
+ ({
+ pages: Array.from({ length: pageCount }, (_, pageIndex) => ({
+ number: pageIndex + 1,
+ fragments: [],
+ footnoteLedger: ledgers.find((ledger) => ledger.pageIndex === pageIndex),
+ })),
+ }) as Layout;
+
+describe('SD-2656 footnote preferred-reserve scorer', () => {
+ it('selects only mandatory-only pages as preferred-reserve candidates', () => {
+ const ledgers = [
+ makeLedger(0, {
+ anchorIds: ['1'],
+ mandatoryReservePx: 36,
+ preferredReservePx: 121,
+ actualBandHeightPx: 36,
+ lastAnchorRenderedLines: 1,
+ }),
+ makeLedger(1, {
+ anchorIds: ['2'],
+ mandatoryReservePx: 44,
+ preferredReservePx: 96,
+ actualBandHeightPx: 72,
+ lastAnchorRenderedLines: 3,
+ }),
+ makeLedger(2, {
+ anchorIds: ['3'],
+ mandatoryReservePx: 40,
+ preferredReservePx: 44,
+ actualBandHeightPx: 40,
+ lastAnchorRenderedLines: 1,
+ }),
+ ];
+
+ expect(getPreferredReserveCandidates(ledgers)).toEqual([
+ {
+ pageIndex: 0,
+ anchorIds: ['1'],
+ mandatoryReservePx: 36,
+ preferredReservePx: 121,
+ reserveDeltaPx: 85,
+ actualBandHeightPx: 36,
+ lastAnchorRenderedLines: 1,
+ },
+ ]);
+ });
+
+ it('also flags pages where the last anchor partially rendered but spilled (Vivienne feedback)', () => {
+ // SD-2656: a page is also a candidate when the last anchor rendered >1 line
+ // yet still spilled to the next page. The legacy filter (lastAnchorRenderedLines<=1)
+ // missed these "partial split" cases reported by Vivienne — footnotes splitting
+ // across pages even when preferred reserve would fit them on the anchor page.
+ const ledgers = [
+ // mandatory-only first-line case (legacy candidate) — should still match.
+ makeLedger(0, {
+ anchorIds: ['1'],
+ mandatoryReservePx: 36,
+ preferredReservePx: 121,
+ actualBandHeightPx: 36,
+ lastAnchorRenderedLines: 1,
+ continuationOut: [{ id: '1', remainingRangeCount: 1, remainingHeightPx: 80 }],
+ }),
+ // Vivienne b89cc7aa page 16 pattern: single anchor [4], mand=36, pref=82,
+ // actual=51, lastL=2, fn4 spilled. Old filter missed this (lastL>1).
+ makeLedger(1, {
+ anchorIds: ['4'],
+ mandatoryReservePx: 36,
+ preferredReservePx: 82,
+ actualBandHeightPx: 51,
+ lastAnchorRenderedLines: 2,
+ continuationOut: [{ id: '4', remainingRangeCount: 1, remainingHeightPx: 30 }],
+ }),
+ // Carlsbad page 26 pattern: single anchor [24], mand=42, pref=150, actual=116,
+ // lastL=5, fn24 spilled. Old filter missed this.
+ makeLedger(2, {
+ anchorIds: ['24'],
+ mandatoryReservePx: 42,
+ preferredReservePx: 150,
+ actualBandHeightPx: 116,
+ lastAnchorRenderedLines: 5,
+ continuationOut: [{ id: '24', remainingRangeCount: 2, remainingHeightPx: 30 }],
+ }),
+ // Counter-example: last anchor rendered fully (no spill). Must NOT be a candidate.
+ makeLedger(3, {
+ anchorIds: ['5'],
+ mandatoryReservePx: 36,
+ preferredReservePx: 96,
+ actualBandHeightPx: 96,
+ lastAnchorRenderedLines: 5,
+ continuationOut: [],
+ }),
+ ];
+
+ const candidates = getPreferredReserveCandidates(ledgers).map((c) => c.pageIndex);
+ expect(candidates).toEqual([0, 1, 2]);
+ });
+
+ it('summarizes only the candidate page window', () => {
+ const ledgers = [
+ makeLedger(0, {
+ anchorIds: ['1'],
+ mandatoryReservePx: 36,
+ preferredReservePx: 121,
+ actualBandHeightPx: 36,
+ deadReservePx: 0,
+ lastAnchorRenderedLines: 1,
+ }),
+ makeLedger(4, {
+ anchorIds: ['9'],
+ mandatoryReservePx: 36,
+ preferredReservePx: 140,
+ actualBandHeightPx: 36,
+ deadReservePx: 50,
+ lastAnchorRenderedLines: 1,
+ }),
+ ];
+
+ expect(summarizeFootnoteWindow(makeLayout(5, ledgers), ledgers, 0, 1)).toMatchObject({
+ totalPages: 5,
+ mandatoryOnlyCount: 1,
+ deadReserveSum: 0,
+ clusterSplitCount: 0,
+ });
+ });
+
+ it('creates partial preferred-reserve targets when full preferred may be unsafe', () => {
+ const [candidate] = getPreferredReserveCandidates([
+ makeLedger(0, {
+ anchorIds: ['17', '18', '19'],
+ mandatoryReservePx: 133,
+ preferredReservePx: 601,
+ actualBandHeightPx: 133,
+ lastAnchorRenderedLines: 1,
+ }),
+ ]);
+
+ const targets = getPreferredReserveTrialTargets(candidate, 133);
+
+ expect(targets[0]).toBe(601);
+ expect(targets).toContain(367);
+ expect(targets).toContain(229);
+ expect(targets.every((target) => target > 133 && target <= 601)).toBe(true);
+ });
+
+ it('accepts a trial only when it reduces mandatory-only pages without growing pages or slack', () => {
+ const beforeLedger = [
+ makeLedger(0, {
+ anchorIds: ['1'],
+ mandatoryReservePx: 36,
+ preferredReservePx: 121,
+ actualBandHeightPx: 36,
+ lastAnchorRenderedLines: 1,
+ }),
+ ];
+ const afterLedger = [
+ makeLedger(0, {
+ anchorIds: ['1'],
+ mandatoryReservePx: 36,
+ preferredReservePx: 121,
+ actualBandHeightPx: 121,
+ lastAnchorRenderedLines: 8,
+ }),
+ ];
+
+ const result = scoreFootnoteWindow({
+ beforeLayout: makeLayout(1, beforeLedger),
+ afterLayout: makeLayout(1, afterLedger),
+ candidatePageIndex: 0,
+ beforeLedger,
+ afterLedger,
+ });
+
+ expect(result.accept).toBe(true);
+ expect(result.reason).toBe('globally-safe');
+ expect(result.before.mandatoryOnlyCount).toBe(1);
+ expect(result.after.mandatoryOnlyCount).toBe(0);
+ });
+
+ it('rejects a trial that grows page count even if the candidate page improves', () => {
+ const beforeLedger = [
+ makeLedger(0, {
+ anchorIds: ['1'],
+ mandatoryReservePx: 36,
+ preferredReservePx: 121,
+ actualBandHeightPx: 36,
+ lastAnchorRenderedLines: 1,
+ }),
+ ];
+ const afterLedger = [
+ makeLedger(0, {
+ anchorIds: ['1'],
+ mandatoryReservePx: 36,
+ preferredReservePx: 121,
+ actualBandHeightPx: 121,
+ lastAnchorRenderedLines: 8,
+ }),
+ ];
+
+ const result = scoreFootnoteWindow({
+ beforeLayout: makeLayout(1, beforeLedger),
+ afterLayout: makeLayout(2, afterLedger),
+ candidatePageIndex: 0,
+ beforeLedger,
+ afterLedger,
+ });
+
+ expect(result.accept).toBe(false);
+ expect(result.reason).toBe('page-count-grew');
+ });
+
+ it('allows extra dead-reserve growth when the trial eliminates a cluster split (Vivienne feedback)', () => {
+ // SD-2656: a trial that removes a footnote-spanning split is a direct
+ // user-visible win, so the scorer trades up to 2x the normal dead-reserve
+ // growth allowance. Without this, the scorer rejected the full preferred
+ // bump on b89cc7aa page 9 (148 px doc-wide dead-reserve > 128 threshold)
+ // and accepted a smaller partial bump that left the split intact.
+ const beforeLedger = [
+ makeLedger(0, {
+ anchorIds: ['2', '3'],
+ mandatoryReservePx: 53,
+ preferredReservePx: 130,
+ actualBandHeightPx: 115,
+ deadReservePx: 0,
+ lastAnchorRenderedLines: 5,
+ continuationOut: [{ id: '3', remainingRangeCount: 1, remainingHeightPx: 30 }],
+ }),
+ makeLedger(1, {
+ anchorIds: [],
+ deadReservePx: 0,
+ continuationIn: [{ id: '3', remainingRangeCount: 1, remainingHeightPx: 30 }],
+ }),
+ ];
+ // After bumping page 0 to preferred: fn3 fully renders, split eliminated,
+ // but 148 px of dead reserve appears doc-wide (over the 128 default).
+ const afterLedger = [
+ makeLedger(0, {
+ anchorIds: ['2', '3'],
+ mandatoryReservePx: 53,
+ preferredReservePx: 130,
+ actualBandHeightPx: 130,
+ deadReservePx: 0,
+ lastAnchorRenderedLines: 7,
+ }),
+ makeLedger(1, {
+ anchorIds: [],
+ deadReservePx: 148,
+ }),
+ ];
+
+ const result = scoreFootnoteWindow({
+ beforeLayout: makeLayout(2, beforeLedger),
+ afterLayout: makeLayout(2, afterLedger),
+ candidatePageIndex: 0,
+ candidateAnchorId: '3',
+ beforeLedger,
+ afterLedger,
+ });
+
+ expect(result.accept).toBe(true);
+ expect(result.reason).toBe('globally-safe');
+ });
+
+ it('accepts a direct candidate-line improvement without requiring unrelated pages to change', () => {
+ const beforeLedger = [
+ makeLedger(0, {
+ anchorIds: ['1'],
+ mandatoryReservePx: 36,
+ preferredReservePx: 121,
+ actualBandHeightPx: 36,
+ lastAnchorRenderedLines: 1,
+ }),
+ makeLedger(1, {
+ anchorIds: ['2'],
+ mandatoryReservePx: 36,
+ preferredReservePx: 75,
+ actualBandHeightPx: 36,
+ lastAnchorRenderedLines: 1,
+ }),
+ ];
+ const afterLedger = [
+ makeLedger(0, {
+ anchorIds: ['1'],
+ mandatoryReservePx: 36,
+ preferredReservePx: 121,
+ actualBandHeightPx: 75,
+ lastAnchorRenderedLines: 4,
+ }),
+ makeLedger(1, {
+ anchorIds: ['2'],
+ mandatoryReservePx: 36,
+ preferredReservePx: 75,
+ actualBandHeightPx: 36,
+ lastAnchorRenderedLines: 1,
+ }),
+ ];
+
+ const result = scoreFootnoteWindow({
+ beforeLayout: makeLayout(2, beforeLedger),
+ afterLayout: makeLayout(2, afterLedger),
+ candidatePageIndex: 0,
+ candidateAnchorId: '1',
+ beforeLedger,
+ afterLedger,
+ });
+
+ expect(result.accept).toBe(true);
+ expect(result.reason).toBe('globally-safe');
+ expect(result.before.candidateRenderedLines).toBe(1);
+ expect(result.after.candidateRenderedLines).toBe(4);
+ });
+
+ it('rejects a direct candidate improvement that creates a new mandatory-only anchor', () => {
+ const beforeLedger = [
+ makeLedger(0, {
+ anchorIds: ['1'],
+ mandatoryReservePx: 36,
+ preferredReservePx: 121,
+ actualBandHeightPx: 36,
+ lastAnchorRenderedLines: 1,
+ }),
+ ];
+ const afterLedger = [
+ makeLedger(0, {
+ anchorIds: ['1'],
+ mandatoryReservePx: 36,
+ preferredReservePx: 121,
+ actualBandHeightPx: 75,
+ lastAnchorRenderedLines: 4,
+ }),
+ makeLedger(1, {
+ anchorIds: ['2'],
+ mandatoryReservePx: 36,
+ preferredReservePx: 75,
+ actualBandHeightPx: 36,
+ lastAnchorRenderedLines: 1,
+ }),
+ ];
+
+ const result = scoreFootnoteWindow({
+ beforeLayout: makeLayout(2, beforeLedger),
+ afterLayout: makeLayout(2, afterLedger),
+ candidatePageIndex: 0,
+ candidateAnchorId: '1',
+ beforeLedger,
+ afterLedger,
+ });
+
+ expect(result.accept).toBe(false);
+ expect(result.reason).toBe('new-mandatory-only');
+ });
+
+ it('rejects a reserve trial that does not render more of the target footnote', () => {
+ const beforeLedger = [
+ makeLedger(0, {
+ anchorIds: ['1'],
+ mandatoryReservePx: 36,
+ preferredReservePx: 121,
+ actualBandHeightPx: 36,
+ lastAnchorRenderedLines: 1,
+ }),
+ ];
+ const afterLedger = [
+ makeLedger(0, {
+ anchorIds: ['1'],
+ mandatoryReservePx: 36,
+ preferredReservePx: 121,
+ actualBandHeightPx: 64,
+ lastAnchorRenderedLines: 1,
+ }),
+ ];
+
+ const result = scoreFootnoteWindow({
+ beforeLayout: makeLayout(1, beforeLedger),
+ afterLayout: makeLayout(1, afterLedger),
+ candidatePageIndex: 0,
+ candidateAnchorId: '1',
+ beforeLedger,
+ afterLedger,
+ });
+
+ expect(result.accept).toBe(false);
+ expect(result.reason).toBe('candidate-not-improved');
+ expect(result.after.candidateRenderedLines).toBe(result.before.candidateRenderedLines);
+ });
+
+ it('rejects a locally safe trial that creates a new mandatory-only anchor outside the page window', () => {
+ const beforeLedger = [
+ makeLedger(0, {
+ anchorIds: ['1'],
+ mandatoryReservePx: 36,
+ preferredReservePx: 121,
+ actualBandHeightPx: 36,
+ lastAnchorRenderedLines: 1,
+ }),
+ ];
+ const afterLedger = [
+ makeLedger(0, {
+ anchorIds: ['1'],
+ mandatoryReservePx: 36,
+ preferredReservePx: 121,
+ actualBandHeightPx: 75,
+ lastAnchorRenderedLines: 4,
+ }),
+ makeLedger(4, {
+ anchorIds: ['9'],
+ mandatoryReservePx: 36,
+ preferredReservePx: 96,
+ actualBandHeightPx: 36,
+ lastAnchorRenderedLines: 1,
+ }),
+ ];
+
+ const result = scoreFootnoteWindow({
+ beforeLayout: makeLayout(5, beforeLedger),
+ afterLayout: makeLayout(5, afterLedger),
+ candidatePageIndex: 0,
+ candidateAnchorId: '1',
+ beforeLedger,
+ afterLedger,
+ windowAhead: 1,
+ });
+
+ expect(result.accept).toBe(false);
+ expect(result.reason).toBe('new-mandatory-only');
+ });
+
+ it('rejects a locally safe trial that bloats dead reserve outside the page window', () => {
+ const beforeLedger = [
+ makeLedger(0, {
+ anchorIds: ['1'],
+ mandatoryReservePx: 36,
+ preferredReservePx: 121,
+ actualBandHeightPx: 36,
+ lastAnchorRenderedLines: 1,
+ }),
+ makeLedger(4, {
+ deadReservePx: 0,
+ }),
+ ];
+ const afterLedger = [
+ makeLedger(0, {
+ anchorIds: ['1'],
+ mandatoryReservePx: 36,
+ preferredReservePx: 121,
+ actualBandHeightPx: 75,
+ lastAnchorRenderedLines: 4,
+ }),
+ makeLedger(4, {
+ deadReservePx: 256,
+ }),
+ ];
+
+ const result = scoreFootnoteWindow({
+ beforeLayout: makeLayout(5, beforeLedger),
+ afterLayout: makeLayout(5, afterLedger),
+ candidatePageIndex: 0,
+ candidateAnchorId: '1',
+ beforeLedger,
+ afterLedger,
+ windowAhead: 1,
+ });
+
+ expect(result.accept).toBe(false);
+ expect(result.reason).toBe('dead-reserve-bloat');
+ });
+});
diff --git a/packages/layout-engine/layout-bridge/test/footnoteSeparatorWidth.test.ts b/packages/layout-engine/layout-bridge/test/footnoteSeparatorWidth.test.ts
new file mode 100644
index 0000000000..b2c9b15794
--- /dev/null
+++ b/packages/layout-engine/layout-bridge/test/footnoteSeparatorWidth.test.ts
@@ -0,0 +1,112 @@
+/**
+ * SD-2985: separator widths must match ECMA-376 normative text.
+ * - §17.11.23 w:separator — "a horizontal line which spans PART OF the width text extents"
+ * - §17.11.1 w:continuationSeparator — "a horizontal line which spans THE WIDTH of the main story's text extents"
+ *
+ * The default-content separator (no imported content overrides) renders at ~half column.
+ * The continuation separator renders at full column.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import type { FlowBlock, Measure } from '@superdoc/contracts';
+import { incrementalLayout } from '../src/incrementalLayout';
+
+const makeParagraph = (id: string, text: string, pmStart = 0): FlowBlock => ({
+ kind: 'paragraph',
+ id,
+ runs: [{ text, fontFamily: 'Arial', fontSize: 12, pmStart, pmEnd: pmStart + text.length }],
+});
+
+const makeMeasure = (lineHeight: number, lineCount: number): Measure => ({
+ kind: 'paragraph',
+ lines: Array.from({ length: lineCount }, (_, i) => ({
+ fromRun: 0,
+ fromChar: i,
+ toRun: 0,
+ toChar: i + 1,
+ width: 200,
+ ascent: lineHeight * 0.8,
+ descent: lineHeight * 0.2,
+ lineHeight,
+ })),
+ totalHeight: lineCount * lineHeight,
+});
+
+type Frag = { blockId: string; width: number };
+
+const findSeparator = (page: { fragments: Frag[] }, kind: 'standard' | 'continuation') => {
+ const needle = kind === 'continuation' ? 'footnote-continuation-separator' : 'footnote-separator';
+ return page.fragments.find((f) => typeof f.blockId === 'string' && f.blockId.startsWith(needle));
+};
+
+describe('SD-2985: separator widths match ECMA-376 §17.11.1 / §17.11.23', () => {
+ it('standard separator spans roughly half the column width', async () => {
+ const body = makeParagraph('body-1', 'Body referencing a footnote.', 0);
+ const ft = makeParagraph('footnote-1-0-paragraph', 'Note.', 0);
+ const margins = { top: 72, right: 72, bottom: 72, left: 72 };
+ const pageW = 612;
+ const contentWidth = pageW - margins.left - margins.right;
+
+ const result = await incrementalLayout(
+ [],
+ null,
+ [body],
+ {
+ pageSize: { w: pageW, h: 800 },
+ margins,
+ footnotes: {
+ refs: [{ id: '1', pos: 1 }],
+ blocksById: new Map([['1', [ft]]]),
+ topPadding: 6,
+ dividerHeight: 1,
+ },
+ },
+ vi.fn(async (b) => (b.id.startsWith('footnote-') ? makeMeasure(12, 1) : makeMeasure(20, 1))),
+ );
+
+ const sep = findSeparator(result.layout.pages[0], 'standard');
+ expect(sep).toBeDefined();
+ expect(sep!.width).toBeGreaterThan(0.4 * contentWidth);
+ expect(sep!.width).toBeLessThan(0.6 * contentWidth);
+ });
+
+ it('continuation separator spans the full column width', async () => {
+ const LINE_H = 20;
+ const FOOTNOTE_LINE_H = 12;
+ const margins = { top: 72, right: 72, bottom: 72, left: 72 };
+ const pageW = 612;
+ const contentWidth = pageW - margins.left - margins.right;
+ const blocks: FlowBlock[] = [];
+ // Body content must naturally span ≥2 pages in the bodyMaxY-anchored
+ // architecture (the planner does not synthesize standalone pages for
+ // footnote continuation). 40 body paragraphs × 20px = 800px > 600px
+ // region forces 2 body pages; the oversized footnote on page 1 then
+ // requires a continuation separator on page 2.
+ for (let i = 0; i < 40; i += 1) {
+ blocks.push(makeParagraph(`body-${i}`, `Body line ${i + 1}.`, i * 20));
+ }
+ const ftBlock = makeParagraph('footnote-1-0-paragraph', 'Big footnote.', 0);
+
+ const result = await incrementalLayout(
+ [],
+ null,
+ blocks,
+ {
+ pageSize: { w: pageW, h: 600 + margins.top + margins.bottom },
+ margins,
+ footnotes: {
+ refs: [{ id: '1', pos: 2 }],
+ blocksById: new Map([['1', [ftBlock]]]),
+ topPadding: 6,
+ dividerHeight: 1,
+ },
+ },
+ vi.fn(async (b) => (b.id.startsWith('footnote-') ? makeMeasure(FOOTNOTE_LINE_H, 60) : makeMeasure(LINE_H, 1))),
+ );
+
+ expect(result.layout.pages.length).toBeGreaterThanOrEqual(2);
+ const page2 = result.layout.pages[1];
+ const sep = findSeparator(page2, 'continuation');
+ expect(sep).toBeDefined();
+ expect(sep!.width).toBeCloseTo(contentWidth, 0);
+ });
+});
diff --git a/packages/layout-engine/layout-bridge/test/headerFooterLayout.test.ts b/packages/layout-engine/layout-bridge/test/headerFooterLayout.test.ts
index 1ed4aa8cff..690f251187 100644
--- a/packages/layout-engine/layout-bridge/test/headerFooterLayout.test.ts
+++ b/packages/layout-engine/layout-bridge/test/headerFooterLayout.test.ts
@@ -1,6 +1,6 @@
import { describe, expect, it, vi } from 'vitest';
import type { FlowBlock, Measure } from '@superdoc/contracts';
-import { toFlowBlocks } from '@superdoc/pm-adapter';
+import { toFlowBlocks } from '@core/layout-adapter';
import { layoutHeaderFooterWithCache, HeaderFooterLayoutCache } from '../src/layoutHeaderFooter';
const makeBlock = (id: string, text = 'Hello'): FlowBlock => ({
@@ -141,7 +141,7 @@ describe('layoutHeaderFooterWithCache', () => {
],
};
- // 2. Convert PM JSON to FlowBlocks using PM adapter
+ // 2. Convert PM JSON to FlowBlocks using the v1 layout adapter
const { blocks: headerBlocks } = toFlowBlocks(headerPmDoc, { blockIdPrefix: 'header-default-' });
const { blocks: footerBlocks } = toFlowBlocks(footerPmDoc, { blockIdPrefix: 'footer-default-' });
diff --git a/packages/layout-engine/layout-engine/src/index.test.ts b/packages/layout-engine/layout-engine/src/index.test.ts
index f6e3f4fe97..14c53262a4 100644
--- a/packages/layout-engine/layout-engine/src/index.test.ts
+++ b/packages/layout-engine/layout-engine/src/index.test.ts
@@ -6379,3 +6379,104 @@ describe('alternateHeaders (odd/even header differentiation)', () => {
expect(p6Fragment!.y).toBeCloseTo(70, 0);
});
});
+
+// SD-2656: bodyMaxY anchors the footnote band painter at the actual bottom
+// of body content. Without these tests the reviewer's multi-column trailing-
+// spacing bug (advanceColumn resets trailingSpacing while preserving
+// maxCursorY) regresses silently.
+describe('bodyMaxY', () => {
+ type PageWithBodyMaxY = { bodyMaxY?: number };
+
+ it('subtracts trailing paragraph spacing on a single-column page', () => {
+ const blocks: FlowBlock[] = [
+ { kind: 'paragraph', id: 'p1', runs: [] },
+ { kind: 'paragraph', id: 'p2', runs: [] },
+ {
+ kind: 'paragraph',
+ id: 'p3',
+ runs: [],
+ attrs: { spacing: { after: 20 } },
+ },
+ ];
+ const measures: Measure[] = [makeMeasure([24]), makeMeasure([24]), makeMeasure([24])];
+
+ const layout = layoutDocument(blocks, measures, DEFAULT_OPTIONS);
+
+ expect(layout.pages).toHaveLength(1);
+ const bodyMaxY = (layout.pages[0] as PageWithBodyMaxY).bodyMaxY;
+ expect(bodyMaxY).toBeDefined();
+ // 3 paragraphs × 24 px + 50 px topMargin = 122. Trailing spacing.after=20
+ // is "below the last line" so it is excluded from bodyMaxY.
+ expect(bodyMaxY).toBeCloseTo(122, 1);
+ });
+
+ it('does not subtract trailing spacing when the last column does not own maxCursorY', () => {
+ // Two-column page where column 0 is taller than column 1.
+ // Column 0 should set maxCursorY high; column 1 finishes shorter and
+ // carries a non-zero trailingSpacing. advanceColumn resets trailingSpacing
+ // to 0 mid-flight but the state observed at end-of-page is column 1's.
+ // bodyMaxY must reflect column 0's max, NOT subtract column 1's trailing.
+ const measures: Measure[] = [makeMeasure([40, 40, 40, 40, 40]), makeMeasure([40])];
+
+ const buildBlocks = (trailingAfter: number): FlowBlock[] => [
+ { kind: 'paragraph', id: 'tall', runs: [] },
+ {
+ kind: 'paragraph',
+ id: 'short',
+ runs: [],
+ attrs: trailingAfter > 0 ? { spacing: { after: trailingAfter } } : undefined,
+ },
+ ];
+
+ const layoutOptions: LayoutOptions = {
+ pageSize: { w: 600, h: 800 },
+ margins: { top: 40, right: 40, bottom: 40, left: 40 },
+ columns: { count: 2, gap: 20 },
+ };
+
+ const layoutWithSpacing = layoutDocument(buildBlocks(30), measures, layoutOptions);
+ const layoutWithoutSpacing = layoutDocument(buildBlocks(0), measures, layoutOptions);
+
+ expect(layoutWithSpacing.pages).toHaveLength(1);
+ expect(layoutWithoutSpacing.pages).toHaveLength(1);
+ // The presence of column-1 trailing spacing must NOT change bodyMaxY,
+ // because the trailing spacing belongs to a column whose cursorY is
+ // shorter than maxCursorY (set by column 0). Without the guard, the
+ // bodyMaxY would shrink by ~30 px and the band painter would clip the
+ // last line of column 0.
+ const withSpacingBodyMaxY = (layoutWithSpacing.pages[0] as PageWithBodyMaxY).bodyMaxY;
+ const withoutSpacingBodyMaxY = (layoutWithoutSpacing.pages[0] as PageWithBodyMaxY).bodyMaxY;
+ expect(withSpacingBodyMaxY).toBeDefined();
+ expect(withoutSpacingBodyMaxY).toBeDefined();
+ expect(withSpacingBodyMaxY).toBeCloseTo(withoutSpacingBodyMaxY!, 1);
+ });
+
+ it('subtracts trailing spacing in a single-column page where last cursor == maxCursorY', () => {
+ // Sanity: in a single-column page the last fragment also sets maxCursorY,
+ // so the trailingAttachedToMax branch fires and we DO subtract.
+ const blocks: FlowBlock[] = [
+ {
+ kind: 'paragraph',
+ id: 'only',
+ runs: [],
+ attrs: { spacing: { after: 25 } },
+ },
+ ];
+ const measures: Measure[] = [makeMeasure([30, 30])];
+
+ const layout = layoutDocument(blocks, measures, DEFAULT_OPTIONS);
+ const bodyMaxY = (layout.pages[0] as PageWithBodyMaxY).bodyMaxY;
+ expect(bodyMaxY).toBeDefined();
+ // topMargin=50, 60 px paragraph, trailing spacing.after=25 excluded → 110
+ expect(bodyMaxY).toBeCloseTo(110, 1);
+ });
+
+ it('clamps bodyMaxY to topMargin when content is empty', () => {
+ // Empty body: just an empty paragraph that produces no fragment height.
+ const layout = layoutDocument([{ kind: 'paragraph', id: 'empty', runs: [] }], [makeMeasure([0])], DEFAULT_OPTIONS);
+ expect(layout.pages.length).toBeGreaterThanOrEqual(1);
+ const bodyMaxY = (layout.pages[0] as PageWithBodyMaxY).bodyMaxY;
+ expect(bodyMaxY).toBeDefined();
+ expect(bodyMaxY).toBeGreaterThanOrEqual(DEFAULT_OPTIONS.margins!.top);
+ });
+});
diff --git a/packages/layout-engine/layout-engine/src/index.ts b/packages/layout-engine/layout-engine/src/index.ts
index 2d4d1d3c62..00cb67ea06 100644
--- a/packages/layout-engine/layout-engine/src/index.ts
+++ b/packages/layout-engine/layout-engine/src/index.ts
@@ -38,7 +38,7 @@ import {
applyPendingToActive,
SINGLE_COLUMN_DEFAULT,
} from './section-breaks.js';
-import { layoutParagraphBlock } from './layout-paragraph.js';
+import { layoutParagraphBlock, type FootnoteAnchorRef } from './layout-paragraph.js';
import { layoutImageBlock } from './layout-image.js';
import { layoutDrawingBlock } from './layout-drawing.js';
import { layoutTableBlock, createAnchoredTableFragment, ANCHORED_TABLE_FULL_WIDTH_RATIO } from './layout-table.js';
@@ -476,10 +476,30 @@ export type LayoutOptions = {
*/
footnoteReservedByPageIndex?: number[];
/**
- * Optional footnote metadata consumed by higher-level orchestration (e.g. layout-bridge).
- * The core layout engine does not interpret this field directly.
+ * Footnote metadata. The core layout engine consumes only the fields below
+ * (SD-3049: ref positions + per-footnote body heights for block-aware breaks).
+ * Higher-level orchestration (layout-bridge) attaches additional fields
+ * (`blocksById`, separator dimensions, etc.) which the engine ignores.
*/
- footnotes?: unknown;
+ footnotes?: {
+ refs?: Array<{ id: string; pos: number }>;
+ /**
+ * SD-3049: total measured body height per footnote id (sum of measured
+ * paragraph heights + per-paragraph spacingAfter + inter-footnote gap +
+ * separator overhead). Used by the body paginator to consult footnote
+ * demand at fragment-commit time so body packs tight to the demand.
+ */
+ bodyHeightById?: Map;
+ /**
+ * SD-2656: per-footnote first valid line/run height. The ordered-cluster
+ * rule (Word-style) requires only the LAST anchor on a page to fit its
+ * first line; all earlier anchors must fit fully (bodyHeightById). When
+ * present, the body slicer uses this value for the last anchor in the
+ * candidate cluster, otherwise falls back to bodyHeightById.
+ */
+ firstLineHeightById?: Map;
+ [key: string]: unknown;
+ };
/**
* Actual measured header content heights per variant type.
* When provided, the layout engine will ensure body content starts below
@@ -1190,6 +1210,226 @@ export function layoutDocument(blocks: FlowBlock[], measures: Measure[], options
// Pending-to-active application moved to section-breaks.applyPendingToActive
+ /**
+ * SD-3049: per-block footnote demand lookup. Resolves each footnote ref's pos
+ * to the body block whose pm range contains it; sums those refs' measured
+ * body heights into a `Map`. The body paragraph layout
+ * consults this map at fragment-commit time to keep body packing tight to
+ * footnote demand instead of relying on the post-hoc page-level reserve.
+ *
+ * Builds once per layoutDocument call. Empty-map fallback when there are
+ * no footnotes — the consumer's lookup is a no-op in that case.
+ *
+ * Recurses into table cells so refs inside table-cell paragraphs are
+ * charged to the *containing table block* (the unit `layoutTableBlock` lays
+ * out and breaks at). This is a conservative approximation: demand from a
+ * cell ref is charged to the whole table even if the table spans pages, so
+ * the table may break one row earlier than strictly necessary. The existing
+ * `footnoteBandOverflow.test.ts` is the safety net guaranteeing the band
+ * never overflows the page bottom margin.
+ */
+ // SD-2656: per-block footnote anchor entries. Stored as a sorted list of
+ // {pmPos, height} so the slicer can ask range-aware questions ("how much
+ // footnote demand is anchored in lines [pmStart, pmEnd) of this block?").
+ // Word's body break respects per-line anchor positions; charging the whole
+ // block's demand at block entry (the old behavior) over-defers paragraphs
+ // that have multiple anchors but where the first line only contains one of
+ // them.
+ // SD-2656: each anchor carries both full body height and first-line height.
+ // The body slicer applies the ordered-cluster rule at break time:
+ // demand = sum(fullHeight of cluster[0..N-1]) + firstLineHeight(cluster[N-1])
+ // i.e. all anchors except the last must fit fully; only the last may split.
+ // Aliased to the public FootnoteAnchorRef so callers across packages share
+ // one type.
+ type FootnoteAnchorEntry = FootnoteAnchorRef;
+ const footnoteAnchorsByBlockId: Map = (() => {
+ const out = new Map();
+ const refs = options.footnotes?.refs;
+ const bodyHeights = options.footnotes?.bodyHeightById;
+ const firstLineHeights = options.footnotes?.firstLineHeightById;
+ if (!Array.isArray(refs) || refs.length === 0 || !bodyHeights) return out;
+
+ /**
+ * Resolve `(pmStart, pmEnd)` for a block. Falls back to scanning paragraph
+ * runs when `attrs.pmStart` is absent — the converter sometimes attaches
+ * positions only to runs rather than to block.attrs.
+ */
+ const resolveBlockPmRange = (block: FlowBlock): { pmStart: number; pmEnd: number } | null => {
+ const attrsRange = (block as { attrs?: { pmStart?: number; pmEnd?: number } }).attrs;
+ let pmStart = typeof attrsRange?.pmStart === 'number' ? attrsRange.pmStart : undefined;
+ let pmEnd = typeof attrsRange?.pmEnd === 'number' ? attrsRange.pmEnd : undefined;
+ if (pmStart == null && block.kind === 'paragraph') {
+ const runs = block.runs;
+ if (Array.isArray(runs)) {
+ for (const run of runs) {
+ const rs = (run as { pmStart?: number }).pmStart;
+ const re = (run as { pmEnd?: number }).pmEnd;
+ if (typeof rs === 'number') pmStart = pmStart == null ? rs : Math.min(pmStart, rs);
+ if (typeof re === 'number') pmEnd = pmEnd == null ? re : Math.max(pmEnd, re);
+ }
+ }
+ }
+ if (pmStart == null) return null;
+ return { pmStart, pmEnd: pmEnd ?? pmStart + 1 };
+ };
+
+ /**
+ * For each ref, walk the block tree to find the top-level FlowBlock whose
+ * pm range contains the ref. Tables: walks rows → cells → cell.blocks /
+ * cell.paragraph; demand is attributed to the *table* block, not the cell,
+ * because the table is the unit the body paginator places on a page.
+ */
+ // Dedupe refs by footnote id: the rendered footnote band only carries each id
+ // once per page, so charging body demand once is the matching accounting.
+ // Keeping the first ref position is sufficient — block-aware breaks only care
+ // that the demand lands on *some* containing block.
+ const refByPos = new Map();
+ const seenIds = new Set();
+ for (const ref of refs) {
+ if (seenIds.has(ref.id)) continue;
+ seenIds.add(ref.id);
+ refByPos.set(ref.pos, ref.id);
+ }
+
+ const recordIfHit = (range: { pmStart: number; pmEnd: number }, topLevelId: string): void => {
+ for (const [pos, refId] of refByPos.entries()) {
+ if (pos < range.pmStart || pos > range.pmEnd) continue;
+ const fullHeight = bodyHeights.get(refId);
+ if (typeof fullHeight !== 'number' || !Number.isFinite(fullHeight) || fullHeight <= 0) continue;
+ const firstLineRaw = firstLineHeights?.get(refId);
+ // SD-2656: firstLine defaults to fullHeight when not provided — i.e.
+ // legacy callers / atomic footnotes (image, drawing) get the safe
+ // upper bound. Real paragraph footnotes provide a smaller value.
+ const firstLineHeight =
+ typeof firstLineRaw === 'number' && Number.isFinite(firstLineRaw) && firstLineRaw > 0
+ ? Math.min(firstLineRaw, fullHeight)
+ : fullHeight;
+ const list = out.get(topLevelId) ?? [];
+ list.push({ pmPos: pos, refId, fullHeight, firstLineHeight });
+ out.set(topLevelId, list);
+ refByPos.delete(pos);
+ }
+ };
+
+ for (const block of blocks) {
+ if (refByPos.size === 0) break;
+ const range = resolveBlockPmRange(block);
+ if (range) recordIfHit(range, block.id);
+
+ if (block.kind === 'table') {
+ for (const row of block.rows ?? []) {
+ for (const cell of row.cells ?? []) {
+ const cellChildren: FlowBlock[] = cell.blocks
+ ? (cell.blocks as FlowBlock[])
+ : cell.paragraph
+ ? [cell.paragraph as FlowBlock]
+ : [];
+ for (const child of cellChildren) {
+ const childRange = resolveBlockPmRange(child);
+ if (childRange) recordIfHit(childRange, block.id);
+ }
+ }
+ }
+ }
+ }
+
+ // Keep each block's anchors sorted by pmPos so range queries are linear.
+ for (const list of out.values()) list.sort((a, b) => a.pmPos - b.pmPos);
+ return out;
+ })();
+
+ /**
+ * SD-2656: return the ordered list of footnote anchor entries in
+ * `[pmStart, pmEnd]` of the given block (or the whole block if no range).
+ * Each entry carries `fullHeight` and `firstLineHeight`. The body slicer
+ * combines this candidate list with PageState's committed anchors and
+ * applies the ordered-cluster rule.
+ */
+ const getFootnoteAnchorsForBlockId = (blockId: string, pmStart?: number, pmEnd?: number): FootnoteAnchorEntry[] => {
+ const entries = footnoteAnchorsByBlockId.get(blockId);
+ if (!entries || entries.length === 0) return [];
+ if (pmStart == null || pmEnd == null) return entries;
+ const out: FootnoteAnchorEntry[] = [];
+ for (const e of entries) {
+ if (e.pmPos >= pmStart && e.pmPos <= pmEnd) out.push(e);
+ }
+ return out;
+ };
+
+ /**
+ * Range-aware demand lookup under the ordered-cluster rule:
+ *
+ * demand = sum(fullHeight of cluster[0..N-1]) + firstLineHeight(cluster[N-1])
+ *
+ * where `cluster` = committed anchors on the current page followed by the
+ * candidate anchors in this block range. With no committed list provided,
+ * treats the in-range entries as the full cluster.
+ */
+ const getFootnoteDemandForBlockId = (
+ blockId: string,
+ pmStart?: number,
+ pmEnd?: number,
+ committed?: ReadonlyArray,
+ ): number => {
+ const candidate = getFootnoteAnchorsForBlockId(blockId, pmStart, pmEnd);
+ if (candidate.length === 0 && (!committed || committed.length === 0)) return 0;
+ const cluster = committed && committed.length > 0 ? [...committed, ...candidate] : candidate;
+ if (cluster.length === 0) return 0;
+ let total = 0;
+ for (let i = 0; i < cluster.length - 1; i += 1) total += cluster[i].fullHeight;
+ total += cluster[cluster.length - 1].firstLineHeight;
+ return total;
+ };
+
+ /**
+ * Range-aware ref count. Used by the slicer to compute band overhead
+ * (separator + per-extra-ref gap + safety margin) for the candidate slice.
+ */
+ const getFootnoteRefCountForBlockId = (blockId: string, pmStart?: number, pmEnd?: number): number => {
+ const entries = footnoteAnchorsByBlockId.get(blockId);
+ if (!entries || entries.length === 0) return 0;
+ if (pmStart == null || pmEnd == null) return entries.length;
+ let count = 0;
+ for (const e of entries) {
+ if (e.pmPos >= pmStart && e.pmPos <= pmEnd) count += 1;
+ }
+ return count;
+ };
+
+ /**
+ * SD-2656: per-page footnote-band overhead in pixels. Matches the planner's
+ * data-driven formula (incrementalLayout.ts:1488 — `separatorBefore +
+ * separatorHeight + topPadding + (refs-1)*gap`). The slicer consults this
+ * via ctx so its body-fit budget matches the planner's band-size budget
+ * exactly. The defaults below mirror the planner's defaults so legacy /
+ * test callers that don't populate overhead fields still get correct math.
+ */
+ const getFootnoteBandOverhead = (() => {
+ const fn = options.footnotes as
+ | {
+ topPadding?: number;
+ dividerHeight?: number;
+ separatorSpacingBefore?: number;
+ gap?: number;
+ }
+ | undefined;
+ const safeNum = (v: number | undefined, fallback: number): number =>
+ typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : fallback;
+ // Defaults match incrementalLayout.ts:1330-1342 (gap=2, topPadding=6,
+ // dividerHeight=6) and DEFAULT_FOOTNOTE_SEPARATOR_SPACING_BEFORE=12.
+ // The planner threads its measured `separatorSpacingBefore` (typically
+ // the first-fn lineHeight) through `options.footnotes` so subsequent
+ // passes converge with this slicer.
+ const topPadding = safeNum(fn?.topPadding, 6);
+ const dividerHeight = safeNum(fn?.dividerHeight, 6);
+ const separatorSpacingBefore = safeNum(fn?.separatorSpacingBefore, 12);
+ const gap = safeNum(fn?.gap, 2);
+ return (refsTotal: number): number => {
+ if (refsTotal <= 0) return 0;
+ return topPadding + dividerHeight + separatorSpacingBefore + Math.max(0, refsTotal - 1) * gap;
+ };
+ })();
+
// Paginator encapsulation for page/column helpers
let pageCount = 0;
// Page numbering state
@@ -1246,16 +1486,23 @@ export function layoutDocument(blocks: FlowBlock[], measures: Measure[], options
// Map
const sectionFirstPageNumbers = new Map();
+ // SD-3049: read the page-level reserve via a single helper so the same
+ // value flows into both `getActiveBottomMargin` (existing behavior) and
+ // `getFootnoteReserveForPage` (new — for the block-aware break decision).
+ const readFootnoteReserveForPageIndex = (pageIndex: number): number => {
+ const reserves = options.footnoteReservedByPageIndex;
+ const reserve = Array.isArray(reserves) ? reserves[pageIndex] : 0;
+ return typeof reserve === 'number' && Number.isFinite(reserve) && reserve > 0 ? reserve : 0;
+ };
+
const paginator = createPaginator({
margins: paginatorMargins,
getActiveTopMargin: () => activeTopMargin,
getActiveBottomMargin: () => {
- const reserves = options.footnoteReservedByPageIndex;
const pageIndex = Math.max(0, pageCount - 1);
- const reserve = Array.isArray(reserves) ? reserves[pageIndex] : 0;
- const reservePx = typeof reserve === 'number' && Number.isFinite(reserve) && reserve > 0 ? reserve : 0;
- return activeBottomMargin + reservePx;
+ return activeBottomMargin + readFootnoteReserveForPageIndex(pageIndex);
},
+ getFootnoteReserveForPage: (pageIndex: number) => readFootnoteReserveForPageIndex(pageIndex),
getActiveHeaderDistance: () => activeHeaderDistance,
getActiveFooterDistance: () => activeFooterDistance,
getActivePageSize: () => activePageSize,
@@ -2365,6 +2612,10 @@ export function layoutDocument(blocks: FlowBlock[], measures: Measure[], options
floatManager,
remeasureParagraph: options.remeasureParagraph,
overrideSpacingAfter,
+ getFootnoteDemandForBlockId,
+ getFootnoteRefCountForBlockId,
+ getFootnoteBandOverhead,
+ getFootnoteAnchorsForBlockId,
},
anchorsForPara
? {
@@ -2943,6 +3194,28 @@ export function layoutDocument(blocks: FlowBlock[], measures: Measure[], options
state.page.columnRegions = regions;
}
+ // SD-2656: stash each page's actual body-bottom on the Page so the band
+ // painter can render the separator immediately under the last body
+ // fragment instead of at the legacy reserve-derived position. Trailing
+ // paragraph spacing is subtracted because it's "below the last line" and
+ // shouldn't push the separator down by that much — but only when the
+ // current column's cursorY is the one that set maxCursorY. In a multi-
+ // column page, `advanceColumn` preserves maxCursorY across columns while
+ // resetting trailingSpacing to 0; the trailingSpacing observed at the
+ // page tail belongs to the last column's last fragment, not to whichever
+ // fragment set maxCursorY. Subtracting it unconditionally would clip the
+ // band up into the body of an earlier, taller column.
+ for (let i = 0; i < pages.length && i < paginator.states.length; i++) {
+ const s = paginator.states[i];
+ const maxY = s.maxCursorY ?? 0;
+ const cursorY = s.cursorY ?? 0;
+ const trailing = s.trailingSpacing ?? 0;
+ const raw = Math.max(maxY, cursorY);
+ const trailingAttachedToMax = cursorY >= maxY;
+ const adjusted = raw - (trailingAttachedToMax ? trailing : 0);
+ (pages[i] as { bodyMaxY?: number }).bodyMaxY = Math.max(s.topMargin ?? 0, adjusted);
+ }
+
return {
pageSize,
pages,
diff --git a/packages/layout-engine/layout-engine/src/layout-paragraph.test.ts b/packages/layout-engine/layout-engine/src/layout-paragraph.test.ts
index 39220fe3cb..9070732112 100644
--- a/packages/layout-engine/layout-engine/src/layout-paragraph.test.ts
+++ b/packages/layout-engine/layout-engine/src/layout-paragraph.test.ts
@@ -61,6 +61,9 @@ const makePageState = (): PageState => ({
lastParagraphStyleId: undefined,
lastParagraphContextualSpacing: false,
maxCursorY: 50,
+ pageFootnoteReserve: 0,
+ footnoteDemandThisPage: 0,
+ footnoteRefsThisPage: 0,
});
/**
@@ -1444,3 +1447,58 @@ describe('layoutParagraphBlock - keepLines', () => {
expect(advanceColumn).not.toHaveBeenCalled();
});
});
+
+describe('SD-3049: footnote demand survives advanceColumn within one iteration', () => {
+ it('charges the block demand onto the page advanceColumn lands on', () => {
+ const block: ParagraphBlock = {
+ kind: 'paragraph',
+ id: 'block-x',
+ runs: [{ text: 'Spilled block.', fontFamily: 'Arial', fontSize: 12 }],
+ };
+ // 3 lines that easily fit on the next page; the block only spills because
+ // the starting cursor is near the page bottom on P.
+ const measure = makeMeasure([
+ { width: 100, lineHeight: 20, maxWidth: 200 },
+ { width: 100, lineHeight: 20, maxWidth: 200 },
+ { width: 100, lineHeight: 20, maxWidth: 200 },
+ ]);
+
+ // P starts near the bottom so the first break decision must advance.
+ const pageP: PageState = {
+ ...makePageState(),
+ page: { number: 1, fragments: [] },
+ cursorY: 600,
+ contentBottom: 620,
+ };
+
+ // Mirror the paginator: a fresh page Q with demand reset to 0 and cursor
+ // back at topMargin. Hold a reference so the test can read final state.
+ const pageQ: PageState = {
+ ...makePageState(),
+ page: { number: 2, fragments: [] },
+ cursorY: 50,
+ contentBottom: 620,
+ };
+
+ const BLOCK_DEMAND = 100;
+
+ layoutParagraphBlock({
+ block,
+ measure,
+ columnWidth: 200,
+ ensurePage: mock(() => pageP),
+ advanceColumn: mock(() => pageQ),
+ columnX: mock(() => 50),
+ floatManager: makeFloatManager(),
+ // Phase 1 (SD-2656): body uses ORDERED minimum from anchors, not the
+ // legacy block-demand getter. Demand transfer on spill must still hold
+ // — express it via anchors whose ordered-minimum equals BLOCK_DEMAND.
+ getFootnoteAnchorsForBlockId: (blockId) =>
+ blockId === 'block-x'
+ ? [{ pmPos: 0, refId: 'r1', fullHeight: BLOCK_DEMAND, firstLineHeight: BLOCK_DEMAND }]
+ : [],
+ });
+
+ expect(pageQ.footnoteDemandThisPage).toBe(BLOCK_DEMAND);
+ });
+});
diff --git a/packages/layout-engine/layout-engine/src/layout-paragraph.ts b/packages/layout-engine/layout-engine/src/layout-paragraph.ts
index ca29187c9c..cbcf546492 100644
--- a/packages/layout-engine/layout-engine/src/layout-paragraph.ts
+++ b/packages/layout-engine/layout-engine/src/layout-paragraph.ts
@@ -17,7 +17,6 @@ import type {
import {
computeFragmentPmRange,
normalizeLines,
- sliceLines,
extractBlockPmRange,
isEmptyTextParagraph,
shouldSuppressOwnSpacing,
@@ -29,6 +28,19 @@ import { getFragmentZIndex } from '@superdoc/contracts';
const PX_PER_PT = 96 / 72;
const spacingDebugEnabled = false;
+
+/**
+ * SD-2656: ordered footnote anchor entry. The body slicer reads the candidate
+ * anchors for a given PM range and pushes them onto `PageState.footnoteAnchorsThisPage`
+ * after committing the slice; the demand formula consumes the resulting list.
+ */
+export type FootnoteAnchorRef = {
+ pmPos: number;
+ refId: string;
+ fullHeight: number;
+ firstLineHeight: number;
+};
+
/**
* Type definition for Word layout attributes attached to paragraph blocks.
* This is a subset of the WordParagraphLayoutOutput from @superdoc/word-layout.
@@ -293,6 +305,54 @@ export type ParagraphLayoutContext = {
* When undefined, uses the value from block.attrs.spacing.after.
*/
overrideSpacingAfter?: number;
+ /**
+ * SD-3049 / SD-2656: footnote demand under the ordered-cluster rule.
+ *
+ * demand = sum(fullHeight of cluster[0..N-1]) + firstLineHeight(cluster[N-1])
+ *
+ * where `cluster` is the ordered list of footnote anchors on the page. The
+ * caller passes the already-committed anchors (from PageState) plus the
+ * candidate range; this returns the demand assuming the candidate range is
+ * appended to the page's cluster.
+ *
+ * With no committed list, the in-range anchors are treated as the full
+ * cluster. With no range, returns the whole-block demand.
+ */
+ getFootnoteDemandForBlockId?: (
+ blockId: string,
+ pmStart?: number,
+ pmEnd?: number,
+ committed?: ReadonlyArray,
+ ) => number;
+
+ /**
+ * SD-2656: returns the ordered anchor entries in `[pmStart, pmEnd]` so the
+ * slicer can push them onto PageState after accepting a candidate line.
+ */
+ getFootnoteAnchorsForBlockId?: (
+ blockId: string,
+ pmStart?: number,
+ pmEnd?: number,
+ ) => ReadonlyArray;
+
+ /**
+ * SD-2656: companion to getFootnoteDemandForBlockId — returns the number
+ * of footnote refs anchored in a given PM range of this block. Used to
+ * compute band overhead (separator + per-extra-ref gap + safety margin)
+ * for the candidate slice.
+ */
+ getFootnoteRefCountForBlockId?: (blockId: string, pmStart?: number, pmEnd?: number) => number;
+
+ /**
+ * SD-2656: per-page footnote-band overhead in pixels for a given number of
+ * anchored refs. The slicer's `effectiveBottom` budget must match the
+ * planner's, otherwise body packs onto a page whose band cannot fit the
+ * refs. Source of truth lives in the planner (incrementalLayout.ts) and
+ * derives from `topPadding + dividerHeight + separatorSpacingBefore +
+ * (refs-1)*gap`. When not provided, the slicer falls back to a default
+ * formula that matches the planner's default values.
+ */
+ getFootnoteBandOverhead?: (refsTotal: number) => number;
};
export type AnchoredDrawingEntry = {
@@ -818,19 +878,130 @@ export function layoutParagraphBlock(ctx: ParagraphLayoutContext, anchors?: Para
} else {
state.trailingSpacing = 0;
}
- if (state.cursorY >= state.contentBottom) {
+ // SD-2656: footnote band overhead. Source of truth is the planner
+ // (incrementalLayout.ts), which derives overhead from data-driven
+ // separator dimensions (`topPadding`, `dividerHeight`,
+ // `separatorSpacingBefore`, inter-ref `gap`). The planner threads its
+ // formula through `ctx.getFootnoteBandOverhead` so the slicer's
+ // `effectiveBottom` budget matches the planner's exactly — otherwise
+ // body packs onto a page whose band can't actually fit the refs.
+ //
+ // The fallback formula below matches the planner's *default* values
+ // (topPadding=6, dividerHeight=6, separatorSpacingBefore≈14, gap=2)
+ // and is only used when ctx doesn't supply the overhead function (e.g.
+ // tests that don't exercise footnotes).
+ const FN_SAFETY_MARGIN_PX = 1;
+ const fallbackBandOverhead = (refsTotal: number): number =>
+ refsTotal > 0 ? 22 + Math.max(0, refsTotal - 1) * 2 : 0;
+ const bandOverhead = (refsTotal: number): number => {
+ if (refsTotal <= 0) return 0;
+ const fromCtx = ctx.getFootnoteBandOverhead?.(refsTotal);
+ const base =
+ typeof fromCtx === 'number' && Number.isFinite(fromCtx) && fromCtx >= 0
+ ? fromCtx
+ : fallbackBandOverhead(refsTotal);
+ return base + FN_SAFETY_MARGIN_PX;
+ };
+
+ /**
+ * SD-2656: effective bottom for a candidate slice.
+ *
+ * Critical: we ignore `state.pageFootnoteReserve` here and use the
+ * page's raw content area (contentBottom + reserve). With range-aware
+ * demand, the slicer knows exactly which fns are anchored on this
+ * page — the planner's pre-allocated reserve is no longer needed and
+ * actively harmful when it over-allocates. Body shrinkage is driven
+ * entirely by what THIS page's slices have charged so far + what the
+ * candidate slice would charge.
+ *
+ * `extraDemand` IS the total ordered-cluster demand for the page after
+ * the candidate slice is committed (i.e., the demand function already
+ * received state.footnoteAnchorsThisPage as `committed` and returned the
+ * full cluster demand). Do NOT add state.footnoteDemandThisPage — that
+ * would double-count the already-committed anchors (e.g. fn4 contributes
+ * `firstLine(fn4)` to state.footnoteDemandThisPage when first committed,
+ * then `full(fn4)` to extraDemand when fn5 arrives and upgrades fn4 from
+ * "last" to "non-last"). Trust extraDemand as the total.
+ */
+ const rawContentBottom = state.contentBottom + state.pageFootnoteReserve;
+ const computeEffectiveBottom = (extraDemand: number, extraRefs: number): number => {
+ const totalDemand = extraDemand;
+ const totalRefs = state.footnoteRefsThisPage + extraRefs;
+ const demandWithOverhead = totalDemand > 0 ? totalDemand + bandOverhead(totalRefs) : 0;
+ // SD-2656: respect the planner's per-page reserve as a floor. The
+ // convergence loop sets `state.pageFootnoteReserve` to communicate
+ // continuation demand from prior pages (fn body content that was
+ // deferred because it didn't fit on its anchor page). Range-aware
+ // demand alone misses this — the slicer only knows about fns anchored
+ // in THIS page's body, not about fn bodies migrating in from previous
+ // pages. Taking the max of (continuation-reserve, anchored-demand+
+ // overhead) ensures body leaves room for whichever is larger.
+ const reservedSpace = Math.max(state.pageFootnoteReserve, demandWithOverhead);
+ const minBodyLineHeight = lines[fromLine]?.lineHeight ?? 0;
+ const maxAdditional = Math.max(0, rawContentBottom - state.topMargin - minBodyLineHeight);
+ return rawContentBottom - Math.min(reservedSpace, maxAdditional);
+ };
+
+ // SD-2656: pre-slicer advance check must preview the FIRST candidate
+ // line's footnote demand. Without this preview, the in-slicer force-
+ // commit-first-line rule would unconditionally place line 0 even when
+ // its fn anchors push the band off the page. This was the band-overflow
+ // bug seen on the reference fixture's p19 (two fns ended up in the band
+ // on top of a prior fn, pushing the band ~140 px past pageH).
+ //
+ // The pre-slicer check is allowed to defer the entire block to next
+ // page only when the page already has body content (otherwise we'd
+ // deadlock on oversized fns). On an empty page, the slicer's force-
+ // commit-first-line rule keeps making progress and the band may end
+ // up clipped — but that case is handled by the planner's continuation
+ // split (separate fix path).
+ // Reserve the full footnote cluster height up front, so the body slicer
+ // backs off enough lines that every anchored footnote fits whole on its
+ // own page. This matches Word's pagination, which knows each footnote's
+ // full demand at every line decision rather than reserving a minimum
+ // and patching later. Cost: bodies that previously packed to the brink
+ // grow ≤ 1–4 pages per fixture; gain: footnote splits drop to ~0 on
+ // fixtures we measured (Carlsbad, IRA, SPA, IT-923 COI, MRL).
+ const computeFootnoteClusterDemand = (pmStart: number, pmEnd: number): number => {
+ const candidate = ctx.getFootnoteAnchorsForBlockId
+ ? ctx.getFootnoteAnchorsForBlockId(block.id, pmStart, pmEnd)
+ : [];
+ const committed = state.footnoteAnchorsThisPage ?? [];
+ if (candidate.length === 0 && committed.length === 0) return 0;
+ let demand = 0;
+ for (const anchor of committed) demand += anchor.fullHeight;
+ for (const anchor of candidate) demand += anchor.fullHeight;
+ return demand;
+ };
+
+ const previewRange = computeFragmentPmRange(block, lines, fromLine, fromLine + 1);
+ const previewRefs = ctx.getFootnoteRefCountForBlockId
+ ? ctx.getFootnoteRefCountForBlockId(block.id, previewRange.pmStart, previewRange.pmEnd)
+ : 0;
+ // Re-evaluates against current state after advanceColumn (footnoteAnchorsThisPage
+ // resets on a fresh page, so demand can shrink).
+ const computePreviewBottom = () => {
+ const demand = computeFootnoteClusterDemand(previewRange.pmStart ?? 0, previewRange.pmEnd ?? 0);
+ return computeEffectiveBottom(demand, previewRefs);
+ };
+ let effectiveBottom = computePreviewBottom();
+
+ if (state.cursorY >= effectiveBottom) {
state = advanceColumn(state);
+ effectiveBottom = computePreviewBottom();
}
- const availableHeight = state.contentBottom - state.cursorY;
+ const availableHeight = effectiveBottom - state.cursorY;
if (availableHeight <= 0) {
state = advanceColumn(state);
+ effectiveBottom = computePreviewBottom();
}
const nextLineHeight = lines[fromLine].lineHeight || 0;
- const remainingHeight = state.contentBottom - state.cursorY;
+ const remainingHeight = effectiveBottom - state.cursorY;
if (state.page.fragments.length > 0 && remainingHeight < nextLineHeight) {
state = advanceColumn(state);
+ effectiveBottom = computePreviewBottom();
}
// Use the narrowest width and offset if we remeasured
@@ -841,13 +1012,81 @@ export function layoutParagraphBlock(ctx: ParagraphLayoutContext, anchors?: Para
offsetX = narrowestOffsetX;
}
- // Reserve border expansion from available height so sliceLines doesn't accept
+ // Reserve border expansion from available height so the slicer doesn't accept
// lines that would overflow the page once border space is added.
+ // SD-3049: use `effectiveBottom` (which already accounts for any
+ // additional footnote demand above the page-level reserve) so we don't
+ // greedily add a line that would push body content into the footnote area.
const borderVertical = borderExpansion.top + borderExpansion.bottom;
- const availableForSlice = Math.max(0, state.contentBottom - state.cursorY - borderVertical);
- const slice = sliceLines(lines, fromLine, availableForSlice);
+ // SD-2656: range-aware slicer. Commit lines one at a time, charging the
+ // fn refs each line anchors. The first line always commits (otherwise
+ // a paragraph with oversized fns could deadlock); subsequent lines must
+ // pass the fit check (cursor + cumulative height + border + cumulative
+ // demand + band overhead ≤ contentBottom). When the next line would
+ // overflow, stop — the rest spills to the next page.
+ let toLine = fromLine;
+ let height = 0;
+ let sliceDemand = 0;
+ let sliceRefs = 0;
+ while (toLine < lines.length) {
+ const lineHeight = lines[toLine].lineHeight || 0;
+ const range = computeFragmentPmRange(block, lines, fromLine, toLine + 1);
+ // SD-2656 Phase 1: ordered-minimum acceptance. The body accepts a
+ // line if ordered demand (full of non-last + firstLine of last)
+ // still fits. The planner uses any leftover capacity opportunistically
+ // (continuations, extending the last anchor).
+ const orderedDemand = computeFootnoteClusterDemand(range.pmStart ?? 0, range.pmEnd ?? 0);
+ const nextRefs = ctx.getFootnoteRefCountForBlockId
+ ? ctx.getFootnoteRefCountForBlockId(block.id, range.pmStart, range.pmEnd)
+ : 0;
+
+ if (toLine === fromLine) {
+ // First line: commit unconditionally. The pre-slicer checks above
+ // already advanced the column if even a single line couldn't fit.
+ height = lineHeight;
+ sliceDemand = orderedDemand;
+ sliceRefs = nextRefs;
+ toLine = fromLine + 1;
+ continue;
+ }
+
+ const candidateBottom = state.cursorY + height + lineHeight + borderVertical;
+ const effBot = computeEffectiveBottom(orderedDemand, nextRefs);
+ if (candidateBottom > effBot) break;
+ height += lineHeight;
+ sliceDemand = orderedDemand;
+ sliceRefs = nextRefs;
+ toLine += 1;
+ }
+
+ const slice = { toLine, height };
const fragmentHeight = slice.height;
+ // Commit demand from this slice into page state. sliceDemand is the
+ // ordered-cluster TOTAL for the page (it already accounts for committed
+ // anchors), so the page-level tracker is replaced, not accumulated. The
+ // ref count is additive (each slice's refs are new).
+ if (sliceDemand > 0 || sliceRefs > 0) {
+ state.footnoteDemandThisPage = sliceDemand;
+ state.footnoteRefsThisPage = (state.footnoteRefsThisPage ?? 0) + sliceRefs;
+ }
+ // SD-2656: push the anchors actually introduced by this slice onto the
+ // page's ordered cluster. The demand for the NEXT slice/block will then
+ // see them as committed (so the current cluster's last anchor upgrades
+ // from firstLine to fullHeight when a new anchor is added later).
+ if (ctx.getFootnoteAnchorsForBlockId) {
+ const committedRange = computeFragmentPmRange(block, lines, fromLine, toLine);
+ const newAnchors = ctx.getFootnoteAnchorsForBlockId(block.id, committedRange.pmStart, committedRange.pmEnd);
+ if (newAnchors.length > 0) {
+ if (!state.footnoteAnchorsThisPage) state.footnoteAnchorsThisPage = [];
+ const seen = new Set(state.footnoteAnchorsThisPage.map((a) => a.refId));
+ for (const a of newAnchors) {
+ if (!seen.has(a.refId)) state.footnoteAnchorsThisPage.push(a);
+ }
+ }
+ }
+ void effectiveBottom;
+
// Apply negative indent adjustment to fragment position and width (similar to table indent handling).
// Negative left indent shifts content left into page margin; negative right indent extends into right margin.
// This matches Word's behavior where paragraphs with negative indents extend beyond the content area.
diff --git a/packages/layout-engine/layout-engine/src/paginator.ts b/packages/layout-engine/layout-engine/src/paginator.ts
index f09597f3ad..ffa75aad49 100644
--- a/packages/layout-engine/layout-engine/src/paginator.ts
+++ b/packages/layout-engine/layout-engine/src/paginator.ts
@@ -24,6 +24,35 @@ export type PageState = {
* Used when starting a mid-page region so the new section begins below
* all column content, not just the current column's cursor. */
maxCursorY: number;
+ /**
+ * SD-3049: Page-level footnote reserve already baked into `contentBottom`
+ * via `getActiveBottomMargin`. The block-aware break decision compares
+ * `footnoteDemandThisPage` against this; only the excess shrinks the body.
+ */
+ pageFootnoteReserve: number;
+ /**
+ * SD-3049: Accumulated measured body height of footnote refs anchored on
+ * fragments already committed to this page (and column-wide). Used by the
+ * paragraph break decision so the body packs tight to footnote demand
+ * instead of relying solely on the post-hoc page-level reserve.
+ */
+ footnoteDemandThisPage: number;
+ /**
+ * SD-2656: Number of distinct footnote refs anchored on this page so far.
+ * Drives the slicer's band-overhead computation (separator + per-extra-ref
+ * gap + safety margin), which must match the planner's reserve formula.
+ */
+ footnoteRefsThisPage: number;
+ /**
+ * SD-2656: ordered list of footnote anchors committed to this page (by
+ * document/PM order). The body slicer pushes a new entry when it accepts a
+ * candidate line that introduces a new anchor. The list drives the ordered-
+ * cluster demand formula:
+ * demand = sum(fullHeight of cluster[0..N-1]) + firstLineHeight(cluster[N-1])
+ * i.e. all anchors except the last must fit fully; only the last may split.
+ * Identified by refId so callers can dedupe and walk in document order.
+ */
+ footnoteAnchorsThisPage: Array<{ pmPos: number; refId: string; fullHeight: number; firstLineHeight: number }>;
};
export type PaginatorOptions = {
@@ -38,6 +67,12 @@ export type PaginatorOptions = {
getCurrentColumns(): NormalizedColumns;
createPage(number: number, pageMargins: PageMargins, pageSizeOverride?: { w: number; h: number }): Page;
onNewPage?: (state: PageState) => void;
+ /**
+ * SD-3049: per-page footnote reserve (the value already added to
+ * `getActiveBottomMargin`). Returned by index for the page about to be
+ * created. Defaults to 0 when not provided.
+ */
+ getFootnoteReserveForPage?: (pageIndex: number) => number;
};
export function createPaginator(opts: PaginatorOptions) {
@@ -100,8 +135,10 @@ export function createPaginator(opts: PaginatorOptions) {
const pageSizeOverride =
currentPageSize.w !== defaultPageSize.w || currentPageSize.h !== defaultPageSize.h ? currentPageSize : undefined;
+ const pageIndex = pages.length;
+ const pageFootnoteReserve = opts.getFootnoteReserveForPage?.(pageIndex) ?? 0;
const state: PageState = {
- page: opts.createPage(pages.length + 1, pageMargins, pageSizeOverride),
+ page: opts.createPage(pageIndex + 1, pageMargins, pageSizeOverride),
cursorY: topMargin,
columnIndex: 0,
topMargin,
@@ -112,6 +149,10 @@ export function createPaginator(opts: PaginatorOptions) {
lastParagraphStyleId: undefined,
lastParagraphContextualSpacing: false,
maxCursorY: topMargin,
+ pageFootnoteReserve,
+ footnoteDemandThisPage: 0,
+ footnoteRefsThisPage: 0,
+ footnoteAnchorsThisPage: [],
};
states.push(state);
pages.push(state.page);
@@ -139,6 +180,10 @@ export function createPaginator(opts: PaginatorOptions) {
state.trailingSpacing = 0;
state.lastParagraphStyleId = undefined;
state.lastParagraphContextualSpacing = false;
+ // Footnotes are reserved per-column; the body slicer's demand formula
+ // must reset per-column. Field names retain "ThisPage" for back-compat.
+ state.footnoteAnchorsThisPage = [];
+ state.footnoteRefsThisPage = 0;
return state;
}
return startNewPage();
diff --git a/packages/layout-engine/layout-resolved/src/resolveParagraph.ts b/packages/layout-engine/layout-resolved/src/resolveParagraph.ts
index de829837d8..9d221b7d04 100644
--- a/packages/layout-engine/layout-resolved/src/resolveParagraph.ts
+++ b/packages/layout-engine/layout-resolved/src/resolveParagraph.ts
@@ -22,7 +22,7 @@ import {
/**
* Resolves marker width using the already-measured glyph width from layout whenever possible.
- * Mirrors resolvePainterMarkerTextWidth from painters/dom/src/utils/marker-helpers.ts.
+ * Mirrors resolvePainterMarkerTextWidth from painters/dom/src/paragraph/list-marker.ts.
*/
function resolveMarkerTextWidth(
markerTextWidthPx: number | undefined,
@@ -205,6 +205,13 @@ export function resolveParagraphContent(
italic: m.run?.italic,
color: m.run?.color,
letterSpacing: m.run?.letterSpacing,
+ // SD-2656: preserve caps marks ( w:caps / w:smallCaps ) so the
+ // painter can apply text-transform: uppercase or font-variant:
+ // small-caps to the marker text. Word's legal/contract list styles
+ // ("FIRST:", "SECOND:") rely on this — without it the marker renders
+ // as "First", "Second" (verbatim from the ordinal-text numbering).
+ allCaps: m.run?.allCaps,
+ smallCaps: m.run?.smallCaps,
},
sourceAnchor: block.sourceAnchor,
};
diff --git a/packages/layout-engine/package.json b/packages/layout-engine/package.json
index 95f75bdb19..fe563b8d38 100644
--- a/packages/layout-engine/package.json
+++ b/packages/layout-engine/package.json
@@ -4,7 +4,7 @@
"type": "module",
"description": "Layout engine POC - manages layout, pagination, and rendering for SuperDoc",
"scripts": {
- "build": "pnpm run --filter=@superdoc/contracts --filter=@superdoc/dom-contract --filter=@superdoc/geometry-utils --filter=@superdoc/pm-adapter --filter=@superdoc/measuring-dom --filter=@superdoc/layout-engine --filter=@superdoc/layout-bridge --filter=@superdoc/painter-dom build",
- "test": "pnpm run --filter=@superdoc/contracts --filter=@superdoc/dom-contract --filter=@superdoc/geometry-utils --filter=@superdoc/pm-adapter --filter=@superdoc/measuring-dom --filter=@superdoc/layout-engine --filter=@superdoc/layout-bridge --filter=@superdoc/painter-dom test"
+ "build": "pnpm run --filter=@superdoc/contracts --filter=@superdoc/dom-contract --filter=@superdoc/geometry-utils --filter=@superdoc/measuring-dom --filter=@superdoc/layout-engine --filter=@superdoc/layout-bridge --filter=@superdoc/painter-dom build",
+ "test": "pnpm run --filter=@superdoc/contracts --filter=@superdoc/dom-contract --filter=@superdoc/geometry-utils --filter=@superdoc/measuring-dom --filter=@superdoc/layout-engine --filter=@superdoc/layout-bridge --filter=@superdoc/painter-dom test"
}
}
diff --git a/packages/layout-engine/painters/dom/src/index.test.ts b/packages/layout-engine/painters/dom/src/index.test.ts
index ce7f7bb813..de1a88bfda 100644
--- a/packages/layout-engine/painters/dom/src/index.test.ts
+++ b/packages/layout-engine/painters/dom/src/index.test.ts
@@ -5159,6 +5159,7 @@ describe('DomPainter', () => {
id: 'change-1',
author: 'Reviewer 1',
authorEmail: 'reviewer@example.com',
+ color: '#123456',
},
},
],
@@ -5183,6 +5184,9 @@ describe('DomPainter', () => {
expect(span.dataset.trackChangeKind).toBe('insert');
expect(span.dataset.trackChangeAuthor).toBe('Reviewer 1');
expect(span.dataset.trackChangeAuthorEmail).toBe('reviewer@example.com');
+ expect(span.style.getPropertyValue('--sd-tracked-changes-insert-border')).toBe('#123456');
+ expect(span.style.getPropertyValue('--sd-tracked-changes-insert-background')).toBe('#12345622');
+ expect(span.style.getPropertyValue('--sd-tracked-changes-insert-background-focused')).toBe('#12345644');
});
it('renders overlapping parent insert and child delete as an insertion with delete strikethrough metadata', () => {
diff --git a/packages/layout-engine/painters/dom/src/paragraph/list-marker.ts b/packages/layout-engine/painters/dom/src/paragraph/list-marker.ts
index 221550e8e8..f7878954f0 100644
--- a/packages/layout-engine/painters/dom/src/paragraph/list-marker.ts
+++ b/packages/layout-engine/painters/dom/src/paragraph/list-marker.ts
@@ -73,6 +73,11 @@ type MarkerRunStyle = {
color?: string | null;
letterSpacing?: number | null;
vanish?: boolean | null;
+ // SD-2656: caps marks from the level rPr. allCaps -> "FIRST" (uppercase);
+ // smallCaps -> small-caps. Without these the legal list markers render as
+ // plain "First" / "Second" / "Third" instead of Word's "FIRST" / "SECOND".
+ allCaps?: boolean | null;
+ smallCaps?: boolean | null;
};
const isMarkerSuffix = (suffix: unknown): suffix is 'tab' | 'space' | 'nothing' =>
@@ -107,6 +112,14 @@ export const createListMarkerElement = (
if (run.letterSpacing != null) {
markerEl.style.letterSpacing = `${run.letterSpacing}px`;
}
+ // SD-2656: caps marks on the level rPr — uppercase for w:caps,
+ // small-caps for w:smallCaps. Without these legal/contract markers
+ // ("FIRST:", "SECOND:") would render verbatim as "First", "Second".
+ if (run.allCaps) {
+ markerEl.style.textTransform = 'uppercase';
+ } else if (run.smallCaps) {
+ markerEl.style.fontVariant = 'small-caps';
+ }
markerContainer.appendChild(markerEl);
if (sourceAnchor) {
@@ -225,7 +238,13 @@ export const renderLegacyListMarker = (params: {
}
}
- prependMarkerSuffix(doc, lineEl, isMarkerSuffix(suffix) ? suffix : undefined, suffixWidthPx, markerLayout?.run?.fontSize);
+ prependMarkerSuffix(
+ doc,
+ lineEl,
+ isMarkerSuffix(suffix) ? suffix : undefined,
+ suffixWidthPx,
+ markerLayout?.run?.fontSize,
+ );
lineEl.prepend(markerContainer);
};
diff --git a/packages/layout-engine/painters/dom/src/runs/text-run.ts b/packages/layout-engine/painters/dom/src/runs/text-run.ts
index 25ac8c50f9..d9927998c1 100644
--- a/packages/layout-engine/painters/dom/src/runs/text-run.ts
+++ b/packages/layout-engine/painters/dom/src/runs/text-run.ts
@@ -7,7 +7,10 @@ import type { RunRenderContext, TrackedChangesRenderConfig } from './types.js';
import { applyRunDataAttributes } from './hash.js';
import { applyLinkAttributes, applyLinkDataset, buildLinkRenderData, enhanceAccessibility } from './links.js';
import { setTextContentWithFormattingSpaceMarks } from './formatting-marks.js';
-import { normalizeRtlDateTokenForWordParity, resolveRunDirectionAttribute } from '../features/inline-direction/index.js';
+import {
+ normalizeRtlDateTokenForWordParity,
+ resolveRunDirectionAttribute,
+} from '../features/inline-direction/index.js';
const DEFAULT_SUPERSCRIPT_RAISE_RATIO = 0.33;
const DEFAULT_SUBSCRIPT_LOWER_RATIO = 0.14;
diff --git a/packages/layout-engine/painters/dom/src/runs/tracked-changes.ts b/packages/layout-engine/painters/dom/src/runs/tracked-changes.ts
index d808dee9ff..2453cf7932 100644
--- a/packages/layout-engine/painters/dom/src/runs/tracked-changes.ts
+++ b/packages/layout-engine/painters/dom/src/runs/tracked-changes.ts
@@ -16,6 +16,75 @@ const TRACK_CHANGE_BASE_CLASS: Record = {
};
const TRACK_CHANGE_OVERLAP_INSERT_DELETE_CLASS = 'track-overlap-insert-delete-dec';
+/** Alpha (0-255) applied to an author color to derive the resting background. */
+const TRACK_CHANGE_BACKGROUND_ALPHA = 0x22;
+/** Alpha (0-255) applied to an author color to derive the focused background. */
+const TRACK_CHANGE_BACKGROUND_FOCUSED_ALPHA = 0x44;
+
+const expandHexColor = (hex: string): string | null => {
+ const normalized = hex.replace('#', '');
+ if (normalized.length === 3) {
+ return normalized
+ .split('')
+ .map((char) => char + char)
+ .join('');
+ }
+ if (normalized.length === 6 || normalized.length === 8) {
+ return normalized.slice(0, 6);
+ }
+ return null;
+};
+
+/**
+ * Derives a translucent background from a base color by appending an 8-digit
+ * hex alpha. Falls back to the base color unchanged when it is not a hex string
+ * the painter can extend (e.g. `rgb(...)`, named colors) — the border/text
+ * still carry the author color in that case.
+ */
+const colorWithAlpha = (color: string, alpha: number): string => {
+ const expanded = color.trim().startsWith('#') ? expandHexColor(color.trim()) : null;
+ if (!expanded) return color;
+ const alphaHex = Math.max(0, Math.min(255, alpha)).toString(16).padStart(2, '0');
+ return `#${expanded}${alphaHex}`;
+};
+
+const setColorVar = (elem: HTMLElement, name: string, value: string): void => {
+ elem.style.setProperty(name, value);
+};
+
+/**
+ * Stamps the element-scoped CSS variable family for a single tracked-change
+ * layer from its resolved `meta.color`. The painter reads only `meta.color`;
+ * color resolution (overrides / resolver / fallback) happened upstream in
+ * pm-adapter. Backgrounds are derived from the base color with alpha.
+ */
+const applyAuthorColorVariables = (elem: HTMLElement, layer: TrackedChangeMeta): void => {
+ const color = layer.color;
+ if (!color) return;
+ const background = colorWithAlpha(color, TRACK_CHANGE_BACKGROUND_ALPHA);
+ const backgroundFocused = colorWithAlpha(color, TRACK_CHANGE_BACKGROUND_FOCUSED_ALPHA);
+ switch (layer.kind) {
+ case 'insert':
+ setColorVar(elem, '--sd-tracked-changes-insert-border', color);
+ setColorVar(elem, '--sd-tracked-changes-insert-background', background);
+ setColorVar(elem, '--sd-tracked-changes-insert-background-focused', backgroundFocused);
+ break;
+ case 'delete':
+ setColorVar(elem, '--sd-tracked-changes-delete-border', color);
+ setColorVar(elem, '--sd-tracked-changes-delete-background', background);
+ setColorVar(elem, '--sd-tracked-changes-delete-background-focused', backgroundFocused);
+ setColorVar(elem, '--sd-tracked-changes-delete-text', color);
+ break;
+ case 'format':
+ setColorVar(elem, '--sd-tracked-changes-format-border', color);
+ setColorVar(elem, '--sd-tracked-changes-format-background', background);
+ setColorVar(elem, '--sd-tracked-changes-format-background-focused', backgroundFocused);
+ break;
+ default:
+ break;
+ }
+};
+
const TRACK_CHANGE_MODIFIER_CLASS: Record> = {
insert: {
review: 'highlighted',
@@ -96,6 +165,10 @@ export const applyTrackedChangeDecorations = (
if (modifier) {
elem.classList.add(modifier);
}
+
+ // Stamp the per-author CSS variable family for this layer's kind from the
+ // resolved color. Overlapping layers each contribute their own kind family.
+ applyAuthorColorVariables(elem, layer);
});
if (overlap) {
diff --git a/packages/layout-engine/painters/dom/src/styles.test.ts b/packages/layout-engine/painters/dom/src/styles.test.ts
index fec200adcd..b8eb27442e 100644
--- a/packages/layout-engine/painters/dom/src/styles.test.ts
+++ b/packages/layout-engine/painters/dom/src/styles.test.ts
@@ -322,6 +322,60 @@ describe('ensureSdtContainerStyles', () => {
expect(lastChromeShowing).toBeGreaterThan(-1);
expect(chromeNoneSuppression).toBeGreaterThan(lastChromeShowing);
});
+
+ it('exposes a --sd-content-controls-custom-* styling surface under chrome-none (SD-3322)', () => {
+ ensureSdtContainerStyles(document);
+ const styleEl = document.querySelector('[data-superdoc-sdt-container-styles="true"]');
+ const cssText = styleEl?.textContent ?? '';
+
+ // Inline rest reads the custom vars; the default-preserving fallbacks
+ // (0-width transparent border, no background/radius/padding) keep
+ // chrome-none visually empty when no variable is set.
+ expect(cssText).toContain('background: var(--sd-content-controls-custom-inline-bg, none);');
+ expect(cssText).toContain('border: var(--sd-content-controls-custom-inline-border, 0 solid transparent);');
+ expect(cssText).toContain('padding: var(--sd-content-controls-custom-inline-padding, 0);');
+ expect(cssText).toContain('border-radius: var(--sd-content-controls-custom-inline-radius, 0);');
+
+ // Hover and selected re-assert the SAME border var (constant box, no jitter)
+ // and read the background vars, which cascade from the rest background.
+ expect(cssText).toContain(
+ 'background: var(--sd-content-controls-custom-inline-hover-bg, var(--sd-content-controls-custom-inline-bg, none));',
+ );
+ expect(cssText).toContain(
+ 'background: var(--sd-content-controls-custom-inline-selected-bg, var(--sd-content-controls-custom-inline-hover-bg, var(--sd-content-controls-custom-inline-bg, none)));',
+ );
+
+ // Block exposes the same set plus an accent rail (-border-left) that falls
+ // back to the regular border.
+ expect(cssText).toContain('background: var(--sd-content-controls-custom-block-bg, none);');
+ expect(cssText).toContain(
+ 'border-left: var(--sd-content-controls-custom-block-border-left, var(--sd-content-controls-custom-block-border, 0 solid transparent));',
+ );
+ });
+
+ it('locked-hover under chrome-none follows the custom hover background, not the built-in lock-hover (SD-3322)', () => {
+ ensureSdtContainerStyles(document);
+ const styleEl = document.querySelector('[data-superdoc-sdt-container-styles="true"]');
+ const cssText = styleEl?.textContent ?? '';
+
+ // The base lock-hover rules (built-in tint on inline, transparent on block)
+ // come first and have equal specificity to the plain custom hover rules, so
+ // they would otherwise win for locked controls.
+ const baseInlineLockHover = cssText.indexOf('background-color: var(--sd-content-controls-lock-hover-bg');
+ const baseBlockLockHover = cssText.indexOf(
+ '.superdoc-structured-content-block[data-lock-mode].sdt-group-hover:not(.ProseMirror-selectednode) {',
+ );
+ expect(baseInlineLockHover).toBeGreaterThan(-1);
+ expect(baseBlockLockHover).toBeGreaterThan(-1);
+
+ // The chrome-none lock-hover reset re-asserts the custom hover background
+ // AFTER them (extra .superdoc-cc-chrome-none class + later source order wins),
+ // so a locked control under chrome:'none' uses the custom variable.
+ const customInlineHoverReassert = cssText.lastIndexOf('--sd-content-controls-custom-inline-hover-bg');
+ const customBlockHoverReassert = cssText.lastIndexOf('--sd-content-controls-custom-block-hover-bg');
+ expect(customInlineHoverReassert).toBeGreaterThan(baseInlineLockHover);
+ expect(customBlockHoverReassert).toBeGreaterThan(baseBlockLockHover);
+ });
});
describe('ensureTrackChangeStyles', () => {
diff --git a/packages/layout-engine/painters/dom/src/styles.ts b/packages/layout-engine/painters/dom/src/styles.ts
index e86fb474a0..0a6198befc 100644
--- a/packages/layout-engine/painters/dom/src/styles.ts
+++ b/packages/layout-engine/painters/dom/src/styles.ts
@@ -787,30 +787,56 @@ const SDT_CONTAINER_STYLES = `
/* Global content-control chrome opt-out: preserve SDT wrappers/datasets while
* suppressing built-in visual chrome on structured-content controls. Their
* label elements are not emitted by renderer/helpers when this class is
- * present (DOM non-emission), and these rules neutralize
- * border/padding/hover/selection visuals. documentSection chrome (e.g. the
- * locked-section tooltip) is intentionally preserved and not in scope. */
-.superdoc-cc-chrome-none .superdoc-structured-content-inline,
+ * present (DOM non-emission). documentSection chrome (e.g. the locked-section
+ * tooltip) is intentionally preserved and not in scope.
+ *
+ * Custom styling surface (SD-3322): instead of fully erasing the look, these
+ * rules read --sd-content-controls-custom-* variables whose defaults reproduce
+ * the empty look (0-width transparent border, no background, no radius/padding).
+ * So chrome:'none' stays visually empty by default, but a consumer can paint
+ * their own field/clause look by setting those variables on the painted wrapper
+ * (target it via data-sdt-* attributes) - no !important, and no need to fight
+ * the .ProseMirror-selectednode / .sdt-group-hover state classes, because the
+ * painter reads the variables across rest, hover, and selected. The border is a
+ * full shorthand (e.g. "1px solid #1355ff"); its default "0 solid transparent"
+ * is identical in layout to no border. It's re-asserted in every state so the
+ * box never shifts (no jitter); only the background changes on hover/selected.
+ * Block controls add a -border-left override for an accent rail. */
+.superdoc-cc-chrome-none .superdoc-structured-content-inline {
+ padding: var(--sd-content-controls-custom-inline-padding, 0);
+ border: var(--sd-content-controls-custom-inline-border, 0 solid transparent);
+ border-radius: var(--sd-content-controls-custom-inline-radius, 0);
+ background: var(--sd-content-controls-custom-inline-bg, none);
+}
.superdoc-cc-chrome-none .superdoc-structured-content-block {
- border: none;
- padding: 0;
- border-radius: 0;
- background: none;
+ padding: var(--sd-content-controls-custom-block-padding, 0);
+ border: var(--sd-content-controls-custom-block-border, 0 solid transparent);
+ border-left: var(--sd-content-controls-custom-block-border-left, var(--sd-content-controls-custom-block-border, 0 solid transparent));
+ border-radius: var(--sd-content-controls-custom-block-radius, 0);
+ background: var(--sd-content-controls-custom-block-bg, none);
}
.superdoc-cc-chrome-none .superdoc-structured-content-inline:hover,
+.superdoc-cc-chrome-none .superdoc-structured-content-inline[data-lock-mode]:hover {
+ border: var(--sd-content-controls-custom-inline-border, 0 solid transparent);
+ background: var(--sd-content-controls-custom-inline-hover-bg, var(--sd-content-controls-custom-inline-bg, none));
+}
.superdoc-cc-chrome-none .superdoc-structured-content-block:hover,
.superdoc-cc-chrome-none .superdoc-structured-content-block.sdt-group-hover,
-.superdoc-cc-chrome-none .superdoc-structured-content-block[data-lock-mode].sdt-group-hover,
-.superdoc-cc-chrome-none .superdoc-structured-content-inline[data-lock-mode]:hover {
- border: none;
- background: none;
+.superdoc-cc-chrome-none .superdoc-structured-content-block[data-lock-mode].sdt-group-hover {
+ border: var(--sd-content-controls-custom-block-border, 0 solid transparent);
+ border-left: var(--sd-content-controls-custom-block-border-left, var(--sd-content-controls-custom-block-border, 0 solid transparent));
+ background: var(--sd-content-controls-custom-block-hover-bg, var(--sd-content-controls-custom-block-bg, none));
}
-.superdoc-cc-chrome-none .superdoc-structured-content-inline.ProseMirror-selectednode,
+.superdoc-cc-chrome-none .superdoc-structured-content-inline.ProseMirror-selectednode {
+ border: var(--sd-content-controls-custom-inline-border, 0 solid transparent);
+ background: var(--sd-content-controls-custom-inline-selected-bg, var(--sd-content-controls-custom-inline-hover-bg, var(--sd-content-controls-custom-inline-bg, none)));
+}
.superdoc-cc-chrome-none .superdoc-structured-content-block.ProseMirror-selectednode {
- border-color: transparent;
- background: none;
+ border: var(--sd-content-controls-custom-block-border, 0 solid transparent);
+ border-left: var(--sd-content-controls-custom-block-border-left, var(--sd-content-controls-custom-block-border, 0 solid transparent));
+ background: var(--sd-content-controls-custom-block-selected-bg, var(--sd-content-controls-custom-block-hover-bg, var(--sd-content-controls-custom-block-bg, none)));
}
/* Hover highlight for SDT containers.
@@ -859,11 +885,20 @@ const SDT_CONTAINER_STYLES = `
border: none;
}
-/* Reset the lock-hover z-index boost so a suppressed SDT does not stack
- * above host-attached custom UI. Mirrors the base lock-hover selectors with
- * the chrome-none prefix so specificity stays above the boost rule. */
-.superdoc-cc-chrome-none .superdoc-structured-content-block[data-lock-mode].sdt-group-hover:not(.ProseMirror-selectednode),
+/* Chrome opt-out for the lock-hover affordance. The base lock-hover rules above
+ * paint a built-in tint and boost z-index on hovered locked controls; under
+ * chrome:'none' that would override the custom hover background and stack above
+ * host-attached UI. Re-assert the custom hover background (so a locked control
+ * follows --sd-content-controls-custom-*-hover-bg, defaulting to empty - no tint
+ * leaks) and reset the z-index. Mirrors the base lock-hover selectors with the
+ * chrome-none prefix, so the extra class wins over the base rules. Split inline
+ * vs block because each reads its own hover variable. */
.superdoc-cc-chrome-none .superdoc-structured-content-inline[data-lock-mode]:hover:not(.ProseMirror-selectednode, [data-appearance='hidden']) {
+ background: var(--sd-content-controls-custom-inline-hover-bg, var(--sd-content-controls-custom-inline-bg, none));
+ z-index: auto;
+}
+.superdoc-cc-chrome-none .superdoc-structured-content-block[data-lock-mode].sdt-group-hover:not(.ProseMirror-selectednode) {
+ background: var(--sd-content-controls-custom-block-hover-bg, var(--sd-content-controls-custom-block-bg, none));
z-index: auto;
}
diff --git a/packages/layout-engine/pm-adapter/__mocks__/@converter/styles.d.ts b/packages/layout-engine/pm-adapter/__mocks__/@converter/styles.d.ts
deleted file mode 100644
index a497db5ef3..0000000000
--- a/packages/layout-engine/pm-adapter/__mocks__/@converter/styles.d.ts
+++ /dev/null
@@ -1,19 +0,0 @@
-export function resolveParagraphProperties(
- docxContext: unknown,
- inlineProps: unknown,
-): ResolvedParagraphPropertiesExtended;
-export function resolveRunProperties(styleId: unknown, context: unknown): Record;
-/**
- * Mock for @superdoc/converter/internal/styles resolveParagraphProperties
- */
-export type ResolvedParagraphPropertiesExtended = {
- spacing: unknown;
- indent: unknown;
- borders: unknown;
- shading: unknown;
- justification: unknown;
- tabStops: unknown;
- keepLines: boolean;
- keepNext: boolean;
- numberingProperties: unknown;
-};
diff --git a/packages/layout-engine/pm-adapter/__mocks__/@converter/styles.js b/packages/layout-engine/pm-adapter/__mocks__/@converter/styles.js
deleted file mode 100644
index aade0753d2..0000000000
--- a/packages/layout-engine/pm-adapter/__mocks__/@converter/styles.js
+++ /dev/null
@@ -1,34 +0,0 @@
-/**
- * Mock for @superdoc/converter/internal/styles.js
- * This module is part of super-editor and not available in pm-adapter tests
- *
- * @typedef {Object} ResolvedParagraphPropertiesExtended
- * @property {unknown} spacing
- * @property {unknown} indent
- * @property {unknown} borders
- * @property {unknown} shading
- * @property {unknown} justification
- * @property {unknown} tabStops
- * @property {boolean} keepLines
- * @property {boolean} keepNext
- * @property {unknown} numberingProperties
- */
-
-/**
- * @param {unknown} _docxContext
- * @param {unknown} _inlineProps
- * @returns {ResolvedParagraphPropertiesExtended}
- */
-export const resolveParagraphProperties = (_docxContext, _inlineProps) => ({
- spacing: null,
- indent: null,
- borders: null,
- shading: null,
- justification: null,
- tabStops: null,
- keepLines: false,
- keepNext: false,
- numberingProperties: null,
-});
-
-export const resolveRunProperties = (_styleId, _context) => ({});
diff --git a/packages/layout-engine/pm-adapter/debug-sections.js b/packages/layout-engine/pm-adapter/debug-sections.js
deleted file mode 100644
index c69e4e8724..0000000000
--- a/packages/layout-engine/pm-adapter/debug-sections.js
+++ /dev/null
@@ -1,42 +0,0 @@
-/**
- * Debug script to analyze section break emission in multi-section document
- */
-
-console.log('\n=== MULTI-SECTION DOCUMENT ANALYSIS ===\n');
-console.log('Expected sections:');
-console.log(' Section 0: paras 0-2 (portrait, ends at para 2 sectPr)');
-console.log(' Section 1: paras 3-5 (portrait + 2 cols, ends at para 5 sectPr)');
-console.log(' Section 2: paras 6-8 (portrait, ends at para 8 sectPr)');
-console.log(' Section 3: paras 9-10 (landscape, uses body sectPr)');
-
-console.log('\n=== CURRENT EMISSION LOGIC ===\n');
-console.log('1. Emit FIRST section break BEFORE content (line 510-533)');
-console.log(' - Type: continuous');
-console.log(' - isFirstSection: true');
-console.log('2. For each paragraph (line 562-589):');
-console.log(' - IF currentSectionIndex > 0: emit section break AFTER paragraph');
-console.log(' - SKIP if currentSectionIndex === 0');
-
-console.log('\n=== PROBLEMS ===\n');
-console.log('Issue 1: Page 4 not landscape');
-console.log(' - Section 3 should use body sectPr (landscape)');
-console.log(' - Check if 4th section range created for body sectPr');
-
-console.log('\nIssue 2: Page 1 has sections 1 AND 2 content');
-console.log(' - Section 0 ends at para 2');
-console.log(' - Skip logic prevents emit at para 2');
-console.log(' - First break is continuous (no page break)');
-console.log(' - Result: no page break between sections 0 and 1!');
-
-console.log('\n=== ROOT CAUSE ===\n');
-console.log('Line 563: if (currentSectionIndex > 0)');
-console.log(' - Skips section 0 end emission');
-console.log(' - But section 0 has type=nextPage - should force break!');
-
-console.log('\n=== FIX ===\n');
-console.log('Remove skip logic - emit ALL section breaks at paragraph end');
-console.log(' - First break (at start): continuous, sets properties');
-console.log(' - Section 0 (at para 2): nextPage, forces break');
-console.log(' - Section 1 (at para 5): nextPage, forces break');
-console.log(' - Section 2 (at para 8): nextPage, forces break');
-console.log(' - Total: 4 breaks');
diff --git a/packages/layout-engine/pm-adapter/package.json b/packages/layout-engine/pm-adapter/package.json
deleted file mode 100644
index 0a8744c986..0000000000
--- a/packages/layout-engine/pm-adapter/package.json
+++ /dev/null
@@ -1,53 +0,0 @@
-{
- "name": "@superdoc/pm-adapter",
- "version": "0.0.0",
- "description": "ProseMirror to FlowBlocks adapter for the SuperDoc layout pipeline.",
- "type": "module",
- "private": true,
- "main": "./src/index.ts",
- "types": "./src/index.ts",
- "exports": {
- ".": {
- "types": "./src/index.ts",
- "default": "./src/index.ts"
- },
- "./*.js": {
- "types": "./src/*.ts",
- "source": "./src/*.ts",
- "default": "./src/*.ts"
- },
- "./*": {
- "types": "./src/*",
- "source": "./src/*",
- "default": "./src/*"
- }
- },
- "scripts": {
- "build": "tsc --project tsconfig.json --noEmit",
- "test": "vitest run",
- "test:debug": "vitest --inspect-brk --pool threads --poolOptions.threads.singleThread",
- "extract:docx": "vite-node --config ../../super-editor/vite.config.js --mode test scripts/extract-pm-json.mjs",
- "format": "prettier --write \"src/**/*.{ts,tsx}\"",
- "format:check": "prettier --check \"src/**/*.{ts,tsx}\"",
- "lint": "eslint \"src/**/*.{ts,tsx}\"",
- "lint:fix": "eslint \"src/**/*.{ts,tsx}\" --fix",
- "type-check": "tsc --noEmit"
- },
- "devDependencies": {
- "vitest": "catalog:",
- "@superdoc/layout-engine": "workspace:*",
- "@superdoc/layout-resolved": "workspace:*",
- "@superdoc/painter-dom": "workspace:*"
- },
- "dependencies": {
- "@superdoc/super-editor": "workspace:*",
- "@superdoc/common": "workspace:*",
- "@superdoc/contracts": "workspace:*",
- "@superdoc/locale-utils": "workspace:*",
- "@superdoc/measuring-dom": "workspace:*",
- "@superdoc/style-engine": "workspace:*",
- "@superdoc/word-layout": "workspace:*",
- "@superdoc/url-validation": "workspace:*",
- "@superdoc/font-utils": "workspace:*"
- }
-}
diff --git a/packages/layout-engine/pm-adapter/src/converters/inline-converters/endnote-reference.ts b/packages/layout-engine/pm-adapter/src/converters/inline-converters/endnote-reference.ts
deleted file mode 100644
index 09cc97eeef..0000000000
--- a/packages/layout-engine/pm-adapter/src/converters/inline-converters/endnote-reference.ts
+++ /dev/null
@@ -1,18 +0,0 @@
-import type { TextRun } from '@superdoc/contracts';
-import { buildReferenceMarkerRun } from './reference-marker.js';
-import type { InlineConverterParams } from './common.js';
-
-export function endnoteReferenceToBlock(params: InlineConverterParams): TextRun {
- const { node, converterContext } = params;
- const id = (node.attrs as Record | undefined)?.id;
- const displayId = resolveEndnoteDisplayNumber(id, converterContext.endnoteNumberById) ?? id ?? '*';
-
- return buildReferenceMarkerRun(String(displayId), params);
-}
-
-const resolveEndnoteDisplayNumber = (id: unknown, endnoteNumberById: Record | undefined): unknown => {
- const key = id == null ? null : String(id);
- if (!key) return null;
- const mapped = endnoteNumberById?.[key];
- return typeof mapped === 'number' && Number.isFinite(mapped) && mapped > 0 ? mapped : null;
-};
diff --git a/packages/layout-engine/pm-adapter/src/converters/inline-converters/footnote-reference.test.ts b/packages/layout-engine/pm-adapter/src/converters/inline-converters/footnote-reference.test.ts
deleted file mode 100644
index 07bc1a6500..0000000000
--- a/packages/layout-engine/pm-adapter/src/converters/inline-converters/footnote-reference.test.ts
+++ /dev/null
@@ -1,97 +0,0 @@
-import { describe, it, expect, vi } from 'vitest';
-import type { TextRun } from '@superdoc/contracts';
-import type { PMNode, PositionMap } from '../../types.js';
-import type { InlineConverterParams } from './common.js';
-import { SUBSCRIPT_SUPERSCRIPT_SCALE } from '../../constants.js';
-
-vi.mock('./text-run.js', () => ({
- textNodeToRun: vi.fn(
- (params: InlineConverterParams): TextRun => ({
- text: params.node.text || '',
- fontFamily: params.defaultFont,
- fontSize: params.defaultSize,
- }),
- ),
-}));
-
-import { footnoteReferenceToBlock } from './footnote-reference.js';
-
-function makeParams(overrides: Partial = {}): InlineConverterParams {
- const node: PMNode = { type: 'footnoteReference', attrs: { id: '1' } };
- return {
- node,
- positions: new WeakMap(),
- defaultFont: 'Calibri',
- defaultSize: 16,
- inheritedMarks: [],
- sdtMetadata: undefined,
- hyperlinkConfig: { enableRichHyperlinks: false },
- themeColors: undefined,
- runProperties: undefined,
- paragraphProperties: undefined,
- converterContext: {
- footnoteNumberById: { '1': 1, '2': 2, '10': 10 },
- } as unknown as InlineConverterParams['converterContext'],
- enableComments: false,
- visitNode: vi.fn(),
- bookmarks: undefined,
- tabOrdinal: 0,
- paragraphAttrs: {},
- nextBlockId: vi.fn(),
- ...overrides,
- } as InlineConverterParams;
-}
-
-describe('footnoteReferenceToBlock', () => {
- it('emits plain digit text for a footnote marker', () => {
- const run = footnoteReferenceToBlock(makeParams());
-
- expect(run.text).toBe('1');
- });
-
- it('does not emit Unicode superscript glyphs', () => {
- const run = footnoteReferenceToBlock(makeParams());
-
- expect(run.text).not.toMatch(/[⁰¹²³⁴⁵⁶⁷⁸⁹]/);
- });
-
- it('resolves the display number from footnoteNumberById', () => {
- const node: PMNode = { type: 'footnoteReference', attrs: { id: '2' } };
- const run = footnoteReferenceToBlock(makeParams({ node }));
-
- expect(run.text).toBe('2');
- });
-
- it('resolves multi-digit display numbers', () => {
- const node: PMNode = { type: 'footnoteReference', attrs: { id: '10' } };
- const run = footnoteReferenceToBlock(makeParams({ node }));
-
- expect(run.text).toBe('10');
- });
-
- it('falls back to raw id when footnoteNumberById has no mapping', () => {
- const node: PMNode = { type: 'footnoteReference', attrs: { id: '99' } };
- const run = footnoteReferenceToBlock(makeParams({ node }));
-
- expect(run.text).toBe('99');
- });
-
- it('falls back to asterisk when id is missing', () => {
- const node: PMNode = { type: 'footnoteReference', attrs: {} };
- const run = footnoteReferenceToBlock(makeParams({ node }));
-
- expect(run.text).toBe('*');
- });
-
- it('sets vertAlign to superscript', () => {
- const run = footnoteReferenceToBlock(makeParams());
-
- expect(run.vertAlign).toBe('superscript');
- });
-
- it('scales fontSize from the paragraph base', () => {
- const run = footnoteReferenceToBlock(makeParams({ defaultSize: 16 }));
-
- expect(run.fontSize).toBe(16 * SUBSCRIPT_SUPERSCRIPT_SCALE);
- });
-});
diff --git a/packages/layout-engine/pm-adapter/src/converters/inline-converters/footnote-reference.ts b/packages/layout-engine/pm-adapter/src/converters/inline-converters/footnote-reference.ts
deleted file mode 100644
index f7810dff0a..0000000000
--- a/packages/layout-engine/pm-adapter/src/converters/inline-converters/footnote-reference.ts
+++ /dev/null
@@ -1,18 +0,0 @@
-import type { TextRun } from '@superdoc/contracts';
-import { buildReferenceMarkerRun } from './reference-marker.js';
-import type { InlineConverterParams } from './common.js';
-
-export function footnoteReferenceToBlock(params: InlineConverterParams): TextRun {
- const { node, converterContext } = params;
- const id = (node.attrs as Record | undefined)?.id;
- const displayId = resolveFootnoteDisplayNumber(id, converterContext.footnoteNumberById) ?? id ?? '*';
-
- return buildReferenceMarkerRun(String(displayId), params);
-}
-
-const resolveFootnoteDisplayNumber = (id: unknown, footnoteNumberById: Record | undefined): unknown => {
- const key = id == null ? null : String(id);
- if (!key) return null;
- const mapped = footnoteNumberById?.[key];
- return typeof mapped === 'number' && Number.isFinite(mapped) && mapped > 0 ? mapped : null;
-};
diff --git a/packages/layout-engine/pm-adapter/src/sdt/bibliography.ts b/packages/layout-engine/pm-adapter/src/sdt/bibliography.ts
deleted file mode 100644
index 57a1cee22b..0000000000
--- a/packages/layout-engine/pm-adapter/src/sdt/bibliography.ts
+++ /dev/null
@@ -1,79 +0,0 @@
-/**
- * Bibliography Processing Module
- *
- * Handles bibliography field containers by converting child paragraphs to flow blocks.
- * Follows the same pattern as document-index.ts.
- */
-
-import type { PMNode, NodeHandlerContext } from '../types.js';
-import { createSectionBreakBlock, hasIntrinsicBoundarySignals, shouldRequirePageBoundary } from '../sections/index.js';
-
-const getChildren = (node: PMNode): PMNode[] => {
- if (Array.isArray(node.content)) return node.content;
- const content = node.content as { forEach?: (cb: (child: PMNode) => void) => void } | undefined;
- if (content && typeof content.forEach === 'function') {
- const children: PMNode[] = [];
- content.forEach((child) => children.push(child));
- return children;
- }
- return [];
-};
-
-export function handleBibliographyNode(node: PMNode, context: NodeHandlerContext): void {
- const children = getChildren(node);
- if (children.length === 0) return;
-
- const {
- blocks,
- recordBlockKind,
- nextBlockId,
- positions,
- trackedChangesConfig,
- bookmarks,
- hyperlinkConfig,
- sectionState,
- converters,
- themeColors,
- enableComments,
- } = context;
-
- const paragraphToFlowBlocks = converters.paragraphToFlowBlocks;
-
- children.forEach((child) => {
- if (child.type !== 'paragraph') return;
-
- if ((sectionState?.ranges?.length ?? 0) > 0) {
- const nextSection = sectionState!.ranges[sectionState!.currentSectionIndex + 1];
- if (nextSection && sectionState!.currentParagraphIndex === nextSection.startParagraphIndex) {
- const currentSection = sectionState!.ranges[sectionState!.currentSectionIndex];
- const requiresPageBoundary =
- shouldRequirePageBoundary(currentSection, nextSection) || hasIntrinsicBoundarySignals(nextSection);
- const extraAttrs = requiresPageBoundary ? { requirePageBoundary: true } : undefined;
- const sectionBreak = createSectionBreakBlock(nextSection, nextBlockId, extraAttrs);
- blocks.push(sectionBreak);
- recordBlockKind?.(sectionBreak.kind);
- sectionState!.currentSectionIndex++;
- }
- }
-
- const paragraphBlocks = paragraphToFlowBlocks({
- para: child,
- nextBlockId,
- positions,
- trackedChangesConfig,
- bookmarks,
- hyperlinkConfig,
- themeColors,
- converterContext: context.converterContext,
- enableComments,
- converters,
- });
-
- paragraphBlocks.forEach((block) => {
- blocks.push(block);
- recordBlockKind?.(block.kind);
- });
-
- sectionState!.currentParagraphIndex++;
- });
-}
diff --git a/packages/layout-engine/pm-adapter/src/sdt/table-of-authorities.ts b/packages/layout-engine/pm-adapter/src/sdt/table-of-authorities.ts
deleted file mode 100644
index dd4e162a4f..0000000000
--- a/packages/layout-engine/pm-adapter/src/sdt/table-of-authorities.ts
+++ /dev/null
@@ -1,79 +0,0 @@
-/**
- * Table of Authorities Processing Module
- *
- * Handles TOA field containers by converting child paragraphs to flow blocks.
- * Follows the same pattern as document-index.ts.
- */
-
-import type { PMNode, NodeHandlerContext } from '../types.js';
-import { createSectionBreakBlock, hasIntrinsicBoundarySignals, shouldRequirePageBoundary } from '../sections/index.js';
-
-const getChildren = (node: PMNode): PMNode[] => {
- if (Array.isArray(node.content)) return node.content;
- const content = node.content as { forEach?: (cb: (child: PMNode) => void) => void } | undefined;
- if (content && typeof content.forEach === 'function') {
- const children: PMNode[] = [];
- content.forEach((child) => children.push(child));
- return children;
- }
- return [];
-};
-
-export function handleTableOfAuthoritiesNode(node: PMNode, context: NodeHandlerContext): void {
- const children = getChildren(node);
- if (children.length === 0) return;
-
- const {
- blocks,
- recordBlockKind,
- nextBlockId,
- positions,
- trackedChangesConfig,
- bookmarks,
- hyperlinkConfig,
- sectionState,
- converters,
- themeColors,
- enableComments,
- } = context;
-
- const paragraphToFlowBlocks = converters.paragraphToFlowBlocks;
-
- children.forEach((child) => {
- if (child.type !== 'paragraph') return;
-
- if ((sectionState?.ranges?.length ?? 0) > 0) {
- const nextSection = sectionState!.ranges[sectionState!.currentSectionIndex + 1];
- if (nextSection && sectionState!.currentParagraphIndex === nextSection.startParagraphIndex) {
- const currentSection = sectionState!.ranges[sectionState!.currentSectionIndex];
- const requiresPageBoundary =
- shouldRequirePageBoundary(currentSection, nextSection) || hasIntrinsicBoundarySignals(nextSection);
- const extraAttrs = requiresPageBoundary ? { requirePageBoundary: true } : undefined;
- const sectionBreak = createSectionBreakBlock(nextSection, nextBlockId, extraAttrs);
- blocks.push(sectionBreak);
- recordBlockKind?.(sectionBreak.kind);
- sectionState!.currentSectionIndex++;
- }
- }
-
- const paragraphBlocks = paragraphToFlowBlocks({
- para: child,
- nextBlockId,
- positions,
- trackedChangesConfig,
- bookmarks,
- hyperlinkConfig,
- themeColors,
- converterContext: context.converterContext,
- enableComments,
- converters,
- });
-
- paragraphBlocks.forEach((block) => {
- blocks.push(block);
- recordBlockKind?.(block.kind);
- });
-
- sectionState!.currentParagraphIndex++;
- });
-}
diff --git a/packages/layout-engine/pm-adapter/tsconfig.json b/packages/layout-engine/pm-adapter/tsconfig.json
deleted file mode 100644
index 31fdb8ae79..0000000000
--- a/packages/layout-engine/pm-adapter/tsconfig.json
+++ /dev/null
@@ -1,17 +0,0 @@
-{
- "extends": "../tsconfig.base.json",
- "compilerOptions": {
- "composite": true,
- "declaration": true,
- "declarationMap": true,
- "outDir": "dist",
- "baseUrl": ".",
- "paths": {
- "@superdoc/super-editor/converter/internal/*.js": [
- "../../super-editor/dist/src/editors/v1/core/super-converter/*.d.ts"
- ],
- "@translator": ["../../super-editor/dist/src/editors/v1/core/super-converter/v3/node-translator/index.d.ts"]
- }
- },
- "include": ["src/**/*.ts", "src/fixtures/**/*.json"]
-}
diff --git a/packages/layout-engine/pm-adapter/vitest.config.mjs b/packages/layout-engine/pm-adapter/vitest.config.mjs
deleted file mode 100644
index 09c648b909..0000000000
--- a/packages/layout-engine/pm-adapter/vitest.config.mjs
+++ /dev/null
@@ -1,13 +0,0 @@
-import { defineConfig } from 'vitest/config';
-import { resolve } from 'node:path';
-import baseConfig from '../../../vitest.baseConfig';
-
-export default defineConfig({
- ...baseConfig,
- test: {
- // Use happy-dom for faster tests (set VITEST_DOM=jsdom to use jsdom)
- environment: process.env.VITEST_DOM || 'happy-dom',
- include: ['src/**/*.test.ts'],
- setupFiles: [resolve(__dirname, './vitest.setup.ts')],
- },
-});
diff --git a/packages/layout-engine/pm-adapter/vitest.setup.ts b/packages/layout-engine/pm-adapter/vitest.setup.ts
deleted file mode 100644
index a9985c2ba7..0000000000
--- a/packages/layout-engine/pm-adapter/vitest.setup.ts
+++ /dev/null
@@ -1,9 +0,0 @@
-import { resolveCanvas } from '@superdoc/measuring-dom/canvas-resolver';
-import { installNodeCanvasPolyfill } from '@superdoc/measuring-dom';
-
-const { Canvas } = resolveCanvas();
-
-installNodeCanvasPolyfill({
- document,
- Canvas,
-});
diff --git a/packages/layout-engine/tests/README.md b/packages/layout-engine/tests/README.md
index e801419a10..1ebf00ab87 100644
--- a/packages/layout-engine/tests/README.md
+++ b/packages/layout-engine/tests/README.md
@@ -54,7 +54,7 @@ Key settings:
## Dependencies
-- Relies on `@superdoc/pm-adapter`, `@superdoc/style-engine`, `@superdoc/layout-engine`, `@superdoc/painter-dom`.
+- Relies on `@core/layout-adapter`, `@superdoc/style-engine`, `@superdoc/layout-engine`, `@superdoc/painter-dom`.
- Runner: Vitest (`happy-dom` by default).
## Debugging
@@ -63,12 +63,12 @@ If tests fail after SDT schema changes:
1. **Check contracts** (`@superdoc/contracts`) - ensure `SdtMetadata` union types are up to date
2. **Check style-engine** (`@superdoc/style-engine/src/index.ts`) - verify normalization helpers match new attrs
-3. **Check PM adapter** (`@superdoc/pm-adapter/src/index.ts`) - confirm SDT unwrapping assigns metadata to blocks/runs
+3. **Check v1 layout adapter** (`super-editor`'s layout-adapter index) - confirm SDT unwrapping assigns metadata to blocks/runs
4. **Inspect snapshot diffs** - Vitest will show what changed in the summarized output
## Related Documentation
- Layout engine contracts: `packages/layout-engine/contracts/src/index.ts`
- Style engine SDT parsing: `packages/layout-engine/style-engine/src/index.ts`
-- PM adapter SDT handling: `packages/layout-engine/pm-adapter/src/index.ts` (search for `resolveNodeSdtMetadata`)
+- v1 layout adapter SDT handling: `packages/super-editor/src/editors/v1/core/layout-adapter/index.ts` (search for `resolveNodeSdtMetadata`)
- Planning docs: `packages/layout-engine/plan/fields-annotations-*.md`
diff --git a/packages/layout-engine/tests/package.json b/packages/layout-engine/tests/package.json
index 369d53a672..b8b4206739 100644
--- a/packages/layout-engine/tests/package.json
+++ b/packages/layout-engine/tests/package.json
@@ -10,7 +10,6 @@
"test:integration": "vitest run --grep 'Integration'"
},
"dependencies": {
- "@superdoc/pm-adapter": "workspace:*",
"@superdoc/layout-engine": "workspace:*",
"@superdoc/measuring-dom": "workspace:*",
"@superdoc/contracts": "workspace:*",
diff --git a/packages/layout-engine/tests/src/architecture-boundaries.test.ts b/packages/layout-engine/tests/src/architecture-boundaries.test.ts
index c5d797fcf7..f5eeb83803 100644
--- a/packages/layout-engine/tests/src/architecture-boundaries.test.ts
+++ b/packages/layout-engine/tests/src/architecture-boundaries.test.ts
@@ -2,9 +2,9 @@
* Architecture boundary guardrails.
*
* These tests enforce the one-way import flow of the layout-engine pipeline:
- * super-converter → pm-adapter → layout-engine / layout-bridge → painter-dom
- * ↑
- * style-engine (consumed ONLY by pm-adapter at runtime)
+ * super-converter → v1 layout-adapter (super-editor) → FlowBlock[]
+ * ↓
+ * layout-engine / layout-bridge → painter-dom
*
* Violations mean the pipeline has become circular or rendering logic has
* leaked into data preparation (or vice versa).
@@ -15,6 +15,10 @@ import fs from 'node:fs';
import path from 'node:path';
const LAYOUT_ENGINE_ROOT = path.resolve(__dirname, '../../');
+// SD-3222: the v1 ProseMirror adapter now lives inside @superdoc/super-editor
+// (it is v1 SuperEditor's projection from hidden PM state into FlowBlock[]),
+// not in a standalone layout-engine package.
+const V1_ADAPTER_ROOT = path.resolve(__dirname, '../../../super-editor/src/editors/v1/core/layout-adapter');
// ---------------------------------------------------------------------------
// Helpers
@@ -121,7 +125,12 @@ function expectNoViolations(violations: { file: string; line: string }[]) {
// ---------------------------------------------------------------------------
describe('architecture boundaries', () => {
- describe('Guard A: style-engine is only consumed by pm-adapter', () => {
+ it('sanity check: architecture guard source roots exist', () => {
+ expect(fs.existsSync(LAYOUT_ENGINE_ROOT)).toBe(true);
+ expect(fs.existsSync(V1_ADAPTER_ROOT)).toBe(true);
+ });
+
+ describe('Guard A: style-engine does not leak into layout runtime packages', () => {
it('painter-dom runtime src does not import @superdoc/style-engine', () => {
const srcDir = path.join(LAYOUT_ENGINE_ROOT, 'painters/dom/src');
expectNoViolations(findImportViolations(srcDir, '@superdoc/style-engine'));
@@ -153,45 +162,39 @@ describe('architecture boundaries', () => {
});
});
- describe('Guard B: painter-dom internals are not imported by pm-adapter', () => {
- it('pm-adapter runtime src does not import @superdoc/painter-dom', () => {
- const srcDir = path.join(LAYOUT_ENGINE_ROOT, 'pm-adapter/src');
- expectNoViolations(findImportViolations(srcDir, '@superdoc/painter-dom'));
+ describe('Guard B: painter-dom internals are not imported by the v1 adapter', () => {
+ it('v1 adapter runtime src does not import @superdoc/painter-dom', () => {
+ expectNoViolations(findImportViolations(V1_ADAPTER_ROOT, '@superdoc/painter-dom'));
});
- it('pm-adapter runtime src does not import relative painter paths', () => {
- const srcDir = path.join(LAYOUT_ENGINE_ROOT, 'pm-adapter/src');
+ it('v1 adapter runtime src does not import relative painter paths', () => {
// Catch any relative import reaching into painters/ directory
- expectNoViolations(findRelativeImportViolations(srcDir, /from\s+['"].*painters\//));
+ expectNoViolations(findRelativeImportViolations(V1_ADAPTER_ROOT, /from\s+['"].*painters\//));
});
});
- describe('Guard C: data flows one direction — pm-adapter does not import downstream', () => {
- it('pm-adapter runtime src does not import @superdoc/layout-bridge', () => {
- const srcDir = path.join(LAYOUT_ENGINE_ROOT, 'pm-adapter/src');
- expectNoViolations(findImportViolations(srcDir, '@superdoc/layout-bridge'));
+ describe('Guard C: data flows one direction — the v1 adapter does not import downstream', () => {
+ it('v1 adapter runtime src does not import @superdoc/layout-bridge', () => {
+ expectNoViolations(findImportViolations(V1_ADAPTER_ROOT, '@superdoc/layout-bridge'));
});
- it('pm-adapter runtime src does not import @superdoc/layout-engine', () => {
- const srcDir = path.join(LAYOUT_ENGINE_ROOT, 'pm-adapter/src');
- expectNoViolations(findImportViolations(srcDir, '@superdoc/layout-engine'));
+ it('v1 adapter runtime src does not import @superdoc/layout-engine', () => {
+ expectNoViolations(findImportViolations(V1_ADAPTER_ROOT, '@superdoc/layout-engine'));
});
- it('pm-adapter runtime src does not import relative layout-bridge paths', () => {
- const srcDir = path.join(LAYOUT_ENGINE_ROOT, 'pm-adapter/src');
- expectNoViolations(findRelativeImportViolations(srcDir, /from\s+['"].*layout-bridge\//));
+ it('v1 adapter runtime src does not import relative layout-bridge paths', () => {
+ expectNoViolations(findRelativeImportViolations(V1_ADAPTER_ROOT, /from\s+['"].*layout-bridge\//));
});
- it('pm-adapter runtime src does not import relative layout-engine paths', () => {
- const srcDir = path.join(LAYOUT_ENGINE_ROOT, 'pm-adapter/src');
- expectNoViolations(findRelativeImportViolations(srcDir, /from\s+['"].*layout-engine\//));
+ it('v1 adapter runtime src does not import relative layout-engine paths', () => {
+ expectNoViolations(findRelativeImportViolations(V1_ADAPTER_ROOT, /from\s+['"].*layout-engine\//));
});
});
describe('Guard D: painter-dom is a dumb final renderer with no upstream dependencies', () => {
- it('painter-dom runtime src does not import @superdoc/pm-adapter', () => {
+ it('painter-dom runtime src does not import @superdoc/super-editor', () => {
const srcDir = path.join(LAYOUT_ENGINE_ROOT, 'painters/dom/src');
- expectNoViolations(findImportViolations(srcDir, '@superdoc/pm-adapter'));
+ expectNoViolations(findImportViolations(srcDir, '@superdoc/super-editor'));
});
it('painter-dom runtime src does not import @superdoc/layout-bridge', () => {
@@ -220,9 +223,9 @@ describe('architecture boundaries', () => {
expectNoViolations(violations);
});
- it('painter-dom runtime src does not import relative pm-adapter paths', () => {
+ it('painter-dom runtime src does not import the relative v1 layout-adapter path', () => {
const srcDir = path.join(LAYOUT_ENGINE_ROOT, 'painters/dom/src');
- expectNoViolations(findRelativeImportViolations(srcDir, /from\s+['"].*pm-adapter\//));
+ expectNoViolations(findRelativeImportViolations(srcDir, /from\s+['"].*super-editor\/.*layout-adapter/));
});
it('painter-dom runtime src does not import relative layout-bridge paths', () => {
@@ -353,4 +356,37 @@ describe('architecture boundaries', () => {
}
});
});
+
+ describe('Guard H: layout runtime packages do not import concrete adapters (SD-3222)', () => {
+ const LAYOUT_RUNTIME_DIRS = [
+ 'layout-engine/src',
+ 'layout-bridge/src',
+ 'painters/dom/src',
+ 'contracts/src',
+ 'dom-contract/src',
+ 'layout-resolved/src',
+ ];
+
+ for (const dir of LAYOUT_RUNTIME_DIRS) {
+ // The v1 ProseMirror adapter is owned by @superdoc/super-editor. Layout
+ // runtime packages consume FlowBlock[] and layout contracts only — they
+ // must never reach back into the concrete editor adapter, whether via the
+ // package specifier, source alias, or a relative path into super-editor's
+ // adapter source.
+ it(`${dir} does not import @superdoc/super-editor`, () => {
+ const srcDir = path.join(LAYOUT_ENGINE_ROOT, dir);
+ expectNoViolations(findImportViolations(srcDir, '@superdoc/super-editor'));
+ });
+
+ it(`${dir} does not import @core/layout-adapter`, () => {
+ const srcDir = path.join(LAYOUT_ENGINE_ROOT, dir);
+ expectNoViolations(findImportViolations(srcDir, '@core/layout-adapter'));
+ });
+
+ it(`${dir} does not import the relative v1 super-editor layout-adapter path`, () => {
+ const srcDir = path.join(LAYOUT_ENGINE_ROOT, dir);
+ expectNoViolations(findRelativeImportViolations(srcDir, /from\s+['"].*super-editor\/.*layout-adapter/));
+ });
+ }
+ });
});
diff --git a/packages/layout-engine/tests/src/collaboration-stress.test.ts b/packages/layout-engine/tests/src/collaboration-stress.test.ts
index eff7abe997..f449771b57 100644
--- a/packages/layout-engine/tests/src/collaboration-stress.test.ts
+++ b/packages/layout-engine/tests/src/collaboration-stress.test.ts
@@ -13,7 +13,7 @@
*/
import { describe, it, expect, beforeEach } from 'vitest';
-import { toFlowBlocks } from '@superdoc/pm-adapter';
+import { toFlowBlocks } from './test-helpers/to-flow-blocks.js';
import type { FlowBlock, PMNode, TrackedChangesMode } from '@superdoc/contracts';
import fs from 'fs';
import path from 'path';
diff --git a/packages/layout-engine/tests/src/comments-integration.test.ts b/packages/layout-engine/tests/src/comments-integration.test.ts
index 43c4b61da3..6957194a7e 100644
--- a/packages/layout-engine/tests/src/comments-integration.test.ts
+++ b/packages/layout-engine/tests/src/comments-integration.test.ts
@@ -8,7 +8,7 @@
*/
import { describe, it, expect } from 'vitest';
-import { toFlowBlocks } from '@superdoc/pm-adapter';
+import { toFlowBlocks } from './test-helpers/to-flow-blocks.js';
import type { FlowBlock, PMNode } from '@superdoc/contracts';
import fs from 'fs';
import path from 'path';
diff --git a/packages/layout-engine/tests/src/editor-parity.test.ts b/packages/layout-engine/tests/src/editor-parity.test.ts
index 416351b39b..b8cfe24fa7 100644
--- a/packages/layout-engine/tests/src/editor-parity.test.ts
+++ b/packages/layout-engine/tests/src/editor-parity.test.ts
@@ -16,7 +16,7 @@
*/
import { describe, it, expect, beforeEach } from 'vitest';
-import { toFlowBlocks } from '@superdoc/pm-adapter';
+import { toFlowBlocks } from './test-helpers/to-flow-blocks.js';
import type { FlowBlock, PMNode } from '@superdoc/contracts';
import fs from 'fs';
import path from 'path';
diff --git a/packages/layout-engine/tests/src/footnote-formatter-parity.test.ts b/packages/layout-engine/tests/src/footnote-formatter-parity.test.ts
new file mode 100644
index 0000000000..05630084c2
--- /dev/null
+++ b/packages/layout-engine/tests/src/footnote-formatter-parity.test.ts
@@ -0,0 +1,88 @@
+/**
+ * SD-2986/B1: drift-detection parity test.
+ *
+ * `v1 layout-adapter/footnote-formatting.ts` deliberately inlines its number-format
+ * switch instead of reusing layout-engine's `formatPageNumber` — the package
+ * graph forbids the adapter from importing layout-engine at runtime (Guard C in
+ * `architecture-boundaries.test.ts`). To keep the two implementations in sync
+ * we assert here that they agree on every supported format for cardinals 1..100.
+ *
+ * If you add a new format to one helper, this test will fail until you add the
+ * matching case in the other helper. That is the intended behavior.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { formatPageNumber } from '@superdoc/layout-engine';
+import { formatFootnoteCardinal } from '@core/layout-adapter/footnote-formatting.js';
+
+const FORMATS = ['decimal', 'upperRoman', 'lowerRoman', 'upperLetter', 'lowerLetter', 'numberInDash'] as const;
+
+describe('SD-2986/B1: footnote formatter parity with formatPageNumber', () => {
+ for (const fmt of FORMATS) {
+ it(`agrees with formatPageNumber for ${fmt} on 1..100`, () => {
+ for (let n = 1; n <= 100; n += 1) {
+ expect(formatFootnoteCardinal(n, fmt)).toBe(formatPageNumber(n, fmt));
+ }
+ });
+ }
+
+ it('falls back to decimal for an unknown format string (matches expectations only — formatPageNumber rejects unknowns at the type level)', () => {
+ expect(formatFootnoteCardinal(7, 'chickenLetters')).toBe('7');
+ expect(formatFootnoteCardinal(7, undefined)).toBe('7');
+ });
+
+ it('clamps cardinals < 1 to 1 in both helpers', () => {
+ expect(formatFootnoteCardinal(0, 'decimal')).toBe(formatPageNumber(0, 'decimal'));
+ expect(formatFootnoteCardinal(-3, 'upperRoman')).toBe(formatPageNumber(-3, 'upperRoman'));
+ });
+
+ // Direct-string assertions: parity-only tests close the loop only if both
+ // helpers are correct. Pin the expected output for the less-obvious formats
+ // so a regression in BOTH helpers (e.g. someone "fixing" the inlined
+ // numberInDash to ` ${num} ` style) fails here rather than silently passing.
+ it('formats numberInDash as -n- in both helpers', () => {
+ for (const n of [1, 5, 12, 99]) {
+ const expected = `-${n}-`;
+ expect(formatFootnoteCardinal(n, 'numberInDash')).toBe(expected);
+ expect(formatPageNumber(n, 'numberInDash')).toBe(expected);
+ }
+ });
+
+ it('formats upperRoman correctly in both helpers', () => {
+ // Roman numerals are a common source of off-by-one or 9-vs-IX style bugs.
+ expect(formatFootnoteCardinal(1, 'upperRoman')).toBe('I');
+ expect(formatFootnoteCardinal(4, 'upperRoman')).toBe('IV');
+ expect(formatFootnoteCardinal(9, 'upperRoman')).toBe('IX');
+ expect(formatFootnoteCardinal(40, 'upperRoman')).toBe('XL');
+ expect(formatFootnoteCardinal(90, 'upperRoman')).toBe('XC');
+ expect(formatPageNumber(1, 'upperRoman')).toBe('I');
+ expect(formatPageNumber(4, 'upperRoman')).toBe('IV');
+ expect(formatPageNumber(9, 'upperRoman')).toBe('IX');
+ expect(formatPageNumber(40, 'upperRoman')).toBe('XL');
+ expect(formatPageNumber(90, 'upperRoman')).toBe('XC');
+ });
+
+ it('formats lowerRoman correctly in both helpers', () => {
+ expect(formatFootnoteCardinal(1, 'lowerRoman')).toBe('i');
+ expect(formatFootnoteCardinal(4, 'lowerRoman')).toBe('iv');
+ expect(formatFootnoteCardinal(9, 'lowerRoman')).toBe('ix');
+ expect(formatPageNumber(1, 'lowerRoman')).toBe('i');
+ expect(formatPageNumber(4, 'lowerRoman')).toBe('iv');
+ expect(formatPageNumber(9, 'lowerRoman')).toBe('ix');
+ });
+
+ it('formats upperLetter / lowerLetter using base-26 cycle (a, b, ..., z, aa)', () => {
+ expect(formatFootnoteCardinal(1, 'upperLetter')).toBe('A');
+ expect(formatFootnoteCardinal(26, 'upperLetter')).toBe('Z');
+ expect(formatFootnoteCardinal(27, 'upperLetter')).toBe('AA');
+ expect(formatFootnoteCardinal(1, 'lowerLetter')).toBe('a');
+ expect(formatFootnoteCardinal(26, 'lowerLetter')).toBe('z');
+ expect(formatFootnoteCardinal(27, 'lowerLetter')).toBe('aa');
+ expect(formatPageNumber(1, 'upperLetter')).toBe('A');
+ expect(formatPageNumber(26, 'upperLetter')).toBe('Z');
+ expect(formatPageNumber(27, 'upperLetter')).toBe('AA');
+ expect(formatPageNumber(1, 'lowerLetter')).toBe('a');
+ expect(formatPageNumber(26, 'lowerLetter')).toBe('z');
+ expect(formatPageNumber(27, 'lowerLetter')).toBe('aa');
+ });
+});
diff --git a/packages/layout-engine/tests/src/header-footer-integration.test.ts b/packages/layout-engine/tests/src/header-footer-integration.test.ts
index c1201b8b6b..c97b310b79 100644
--- a/packages/layout-engine/tests/src/header-footer-integration.test.ts
+++ b/packages/layout-engine/tests/src/header-footer-integration.test.ts
@@ -8,7 +8,7 @@
*/
import { describe, it, expect } from 'vitest';
-import { toFlowBlocks } from '@superdoc/pm-adapter';
+import { toFlowBlocks } from './test-helpers/to-flow-blocks.js';
import type { FlowBlock, PMNode } from '@superdoc/contracts';
import fs from 'fs';
import path from 'path';
diff --git a/packages/layout-engine/tests/src/memory-profile.test.ts b/packages/layout-engine/tests/src/memory-profile.test.ts
index 9afcd6d754..cd3fa0ca93 100644
--- a/packages/layout-engine/tests/src/memory-profile.test.ts
+++ b/packages/layout-engine/tests/src/memory-profile.test.ts
@@ -11,7 +11,7 @@
*/
import { describe, it, expect, beforeEach } from 'vitest';
-import { toFlowBlocks } from '@superdoc/pm-adapter';
+import { toFlowBlocks } from './test-helpers/to-flow-blocks.js';
import type { FlowBlock, PMNode } from '@superdoc/contracts';
import fs from 'fs';
import path from 'path';
diff --git a/packages/layout-engine/tests/src/multi-section-page-count-simple.test.ts b/packages/layout-engine/tests/src/multi-section-page-count-simple.test.ts
index aae464740a..6d8d13eb45 100644
--- a/packages/layout-engine/tests/src/multi-section-page-count-simple.test.ts
+++ b/packages/layout-engine/tests/src/multi-section-page-count-simple.test.ts
@@ -15,7 +15,7 @@
*/
import { describe, it, expect } from 'vitest';
-import { toFlowBlocks } from '@superdoc/pm-adapter';
+import { toFlowBlocks } from './test-helpers/to-flow-blocks.js';
import { layoutDocument } from '@superdoc/layout-engine';
import { measureBlock } from '@superdoc/measuring-dom';
import type { FlowBlock, PMNode, SectionBreakBlock, Measure } from '@superdoc/contracts';
@@ -33,7 +33,11 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
* @returns ProseMirror document
*/
function loadPMJsonFixture(fixtureName: string): PMNode {
- const fixturePath = path.join(__dirname, '../../pm-adapter/src/fixtures', fixtureName);
+ const fixturePath = path.join(
+ __dirname,
+ '../../../super-editor/src/editors/v1/core/layout-adapter/fixtures',
+ fixtureName,
+ );
if (!fs.existsSync(fixturePath)) {
throw new Error(`Fixture not found: ${fixturePath}`);
diff --git a/packages/layout-engine/tests/src/multi-section-page-count.test.ts b/packages/layout-engine/tests/src/multi-section-page-count.test.ts
index 22a90b5d8d..36956be0c4 100644
--- a/packages/layout-engine/tests/src/multi-section-page-count.test.ts
+++ b/packages/layout-engine/tests/src/multi-section-page-count.test.ts
@@ -15,7 +15,7 @@
*/
import { describe, it, expect, beforeAll } from 'vitest';
-import { toFlowBlocks } from '@superdoc/pm-adapter';
+import { toFlowBlocks } from './test-helpers/to-flow-blocks.js';
import { layoutDocument } from '@superdoc/layout-engine';
import { measureBlocks } from './test-helpers/section-test-utils.js';
import type { FlowBlock, PMNode, SectionBreakBlock } from '@superdoc/contracts';
diff --git a/packages/layout-engine/tests/src/performance.bench.ts b/packages/layout-engine/tests/src/performance.bench.ts
index 0ffc371f91..6b28afe399 100644
--- a/packages/layout-engine/tests/src/performance.bench.ts
+++ b/packages/layout-engine/tests/src/performance.bench.ts
@@ -12,8 +12,8 @@
import { describe, it, expect, beforeEach } from 'vitest';
import { performance } from 'perf_hooks';
-import { toFlowBlocks } from '@superdoc/pm-adapter';
-import type { PMNode } from '../../pm-adapter/src/index.js';
+import { toFlowBlocks } from './test-helpers/to-flow-blocks.js';
+import type { PMNode } from '@core/layout-adapter';
import type { FlowBlock, Measure, Layout } from '@superdoc/contracts';
import fs from 'fs';
import path from 'path';
diff --git a/packages/layout-engine/tests/src/sd-1495-auto-page-break.test.ts b/packages/layout-engine/tests/src/sd-1495-auto-page-break.test.ts
index 9bb5bf6d3f..b51f8b20f6 100644
--- a/packages/layout-engine/tests/src/sd-1495-auto-page-break.test.ts
+++ b/packages/layout-engine/tests/src/sd-1495-auto-page-break.test.ts
@@ -1,6 +1,7 @@
import { beforeAll, describe, expect, it } from 'vitest';
import { layoutDocument } from '@superdoc/layout-engine';
-import { toFlowBlocks, type ConverterContext } from '@superdoc/pm-adapter';
+import type { ConverterContext } from '@core/layout-adapter';
+import { toFlowBlocks } from './test-helpers/to-flow-blocks.js';
import { measureBlock } from '@superdoc/measuring-dom';
import type { FlowBlock, PMNode } from '@superdoc/contracts';
import fs from 'fs';
diff --git a/packages/layout-engine/tests/src/sdt-metadata.test.ts b/packages/layout-engine/tests/src/sdt-metadata.test.ts
index 01bdb657de..d5213d5bef 100644
--- a/packages/layout-engine/tests/src/sdt-metadata.test.ts
+++ b/packages/layout-engine/tests/src/sdt-metadata.test.ts
@@ -1,5 +1,5 @@
import { describe, expect, it } from 'vitest';
-import { toFlowBlocks } from '@superdoc/pm-adapter';
+import { toFlowBlocks } from './test-helpers/to-flow-blocks.js';
import type { FlowBlock, SdtMetadata } from '@superdoc/contracts';
import docFixture from '../fixtures/sdt-flow-input.json' assert { type: 'json' };
diff --git a/packages/layout-engine/tests/src/section-breaks-regression.test.ts b/packages/layout-engine/tests/src/section-breaks-regression.test.ts
index cbf7427b97..a795c28f50 100644
--- a/packages/layout-engine/tests/src/section-breaks-regression.test.ts
+++ b/packages/layout-engine/tests/src/section-breaks-regression.test.ts
@@ -461,7 +461,10 @@ describe('Section Breaks - Regression Tests', () => {
describe('Verification against real DOCX fixture', () => {
it('should match expected output for multi_section_doc.json fixture', () => {
// Load the actual fixture
- const fixturePath = path.join(__dirname, '../../pm-adapter/src/fixtures/multi_section_doc.json');
+ const fixturePath = path.join(
+ __dirname,
+ '../../../super-editor/src/editors/v1/core/layout-adapter/fixtures/multi_section_doc.json',
+ );
if (!fs.existsSync(fixturePath)) {
console.warn(`Fixture not found: ${fixturePath}, skipping test`);
diff --git a/packages/layout-engine/tests/src/section-refs-merging.test.ts b/packages/layout-engine/tests/src/section-refs-merging.test.ts
index 83f1b67625..0325f9b8a2 100644
--- a/packages/layout-engine/tests/src/section-refs-merging.test.ts
+++ b/packages/layout-engine/tests/src/section-refs-merging.test.ts
@@ -13,7 +13,7 @@
import { describe, it, expect, beforeEach } from 'vitest';
import type { PMNode, FlowBlock, SectionBreakBlock } from '@superdoc/contracts';
-import { toFlowBlocks } from '@superdoc/pm-adapter';
+import { toFlowBlocks } from './test-helpers/to-flow-blocks.js';
import { layoutDocument } from '@superdoc/layout-engine';
import { measureBlock } from '@superdoc/measuring-dom';
import { DEFAULT_CONVERTER_CONTEXT, resetBlockIdCounter, PAGE_SIZES } from './test-helpers/section-test-utils.js';
diff --git a/packages/layout-engine/tests/src/test-helpers/section-test-utils.ts b/packages/layout-engine/tests/src/test-helpers/section-test-utils.ts
index 12be635f46..d52cf554ca 100644
--- a/packages/layout-engine/tests/src/test-helpers/section-test-utils.ts
+++ b/packages/layout-engine/tests/src/test-helpers/section-test-utils.ts
@@ -8,7 +8,7 @@
*/
import type { PMNode, FlowBlock, SectionBreakBlock, Measure, Layout, Page } from '@superdoc/contracts';
-import { toFlowBlocks } from '@superdoc/pm-adapter';
+import { toFlowBlocks } from './to-flow-blocks.js';
import { layoutDocument } from '@superdoc/layout-engine';
import { measureBlock } from '@superdoc/measuring-dom';
import type { NumberingProperties, StylesDocumentProperties } from '@superdoc/style-engine/ooxml';
diff --git a/packages/layout-engine/tests/src/test-helpers/to-flow-blocks.ts b/packages/layout-engine/tests/src/test-helpers/to-flow-blocks.ts
new file mode 100644
index 0000000000..85b3076108
--- /dev/null
+++ b/packages/layout-engine/tests/src/test-helpers/to-flow-blocks.ts
@@ -0,0 +1,6 @@
+import { toFlowBlocks as adapterToFlowBlocks } from '@core/layout-adapter';
+import type { AdapterOptions, FlowBlocksResult, PMNode } from '@core/layout-adapter';
+
+export function toFlowBlocks(input: PMNode | object, options?: AdapterOptions): FlowBlocksResult {
+ return adapterToFlowBlocks(input, options);
+}
diff --git a/packages/layout-engine/tests/src/toolbar-integration.test.ts b/packages/layout-engine/tests/src/toolbar-integration.test.ts
index c950ec260a..aa362f4e3f 100644
--- a/packages/layout-engine/tests/src/toolbar-integration.test.ts
+++ b/packages/layout-engine/tests/src/toolbar-integration.test.ts
@@ -8,7 +8,7 @@
*/
import { describe, it, expect } from 'vitest';
-import { toFlowBlocks } from '@superdoc/pm-adapter';
+import { toFlowBlocks } from './test-helpers/to-flow-blocks.js';
import type { FlowBlock, PMNode } from '@superdoc/contracts';
import fs from 'fs';
import path from 'path';
diff --git a/packages/sdk/codegen/src/__tests__/cross-lang-parity.test.ts b/packages/sdk/codegen/src/__tests__/cross-lang-parity.test.ts
index 203d7ef5dc..dcd13528ae 100644
--- a/packages/sdk/codegen/src/__tests__/cross-lang-parity.test.ts
+++ b/packages/sdk/codegen/src/__tests__/cross-lang-parity.test.ts
@@ -54,7 +54,7 @@ function callPython(command: Record): Promise {
/** Import Node SDK chooseTools (cached). */
let _nodeTools: typeof import('../../../langs/node/src/tools.js') | null = null;
-async function nodeTools() {
+async function nodeTools(): Promise {
if (!_nodeTools) {
_nodeTools = await import(path.join(REPO_ROOT, 'packages/sdk/langs/node/src/tools.ts'));
}
@@ -78,6 +78,43 @@ describe('chooseTools parity', () => {
expect(pyResult.meta.toolCount).toBe(nodeResult.meta.toolCount);
expect(nodeResult.meta.toolCount).toBeGreaterThan(0);
});
+
+ test('returns same tool count when preset: legacy is explicit (parity)', async () => {
+ const input = { provider: 'generic' as const, preset: 'legacy' };
+
+ const { chooseTools } = await nodeTools();
+ const nodeResult = await chooseTools(input);
+
+ const pyResult = (await callPython({ action: 'chooseTools', input })) as ChooseResult & {
+ meta: { preset?: string };
+ };
+
+ expect(pyResult.meta.provider).toBe(nodeResult.meta.provider);
+ expect(pyResult.meta.toolCount).toBe(nodeResult.meta.toolCount);
+ expect(pyResult.meta.preset).toBe('legacy');
+ expect(nodeResult.meta.preset).toBe('legacy');
+ });
+});
+
+// --------------------------------------------------------------------------
+// Preset registry parity
+// --------------------------------------------------------------------------
+
+describe('Preset registry parity', () => {
+ test('Node and Python expose the same DEFAULT_PRESET and registered ids', async () => {
+ const { DEFAULT_PRESET: nodeDefault, listPresets: nodeList } = await nodeTools();
+ const nodePresets = nodeList();
+
+ const pyResult = (await callPython({ action: 'listPresets' })) as {
+ defaultPreset: string;
+ presets: string[];
+ };
+
+ expect(pyResult.defaultPreset).toBe(nodeDefault);
+ expect(nodeDefault).toBe('legacy');
+ // Both runtimes register the same preset set (order-agnostic).
+ expect([...pyResult.presets].sort()).toEqual([...nodePresets].sort());
+ });
});
// --------------------------------------------------------------------------
diff --git a/packages/sdk/langs/node/src/__tests__/presets.test.ts b/packages/sdk/langs/node/src/__tests__/presets.test.ts
new file mode 100644
index 0000000000..28f17a1be3
--- /dev/null
+++ b/packages/sdk/langs/node/src/__tests__/presets.test.ts
@@ -0,0 +1,179 @@
+import { describe, expect, test } from 'bun:test';
+import {
+ chooseTools,
+ DEFAULT_PRESET,
+ getPreset,
+ getMcpPrompt,
+ getSystemPrompt,
+ getSystemPromptForProvider,
+ getToolCatalog,
+ listPresets,
+ listTools,
+} from '../tools.ts';
+import { SuperDocCliError } from '../runtime/errors.js';
+
+const PROVIDERS = ['openai', 'anthropic', 'vercel', 'generic'] as const;
+
+describe('preset registry', () => {
+ test('DEFAULT_PRESET is "legacy"', () => {
+ expect(DEFAULT_PRESET).toBe('legacy');
+ });
+
+ test('listPresets() includes "legacy"', () => {
+ const presets = listPresets();
+ expect(presets).toContain('legacy');
+ });
+
+ test('getPreset() (no arg) returns the legacy preset', () => {
+ const preset = getPreset();
+ expect(preset.id).toBe('legacy');
+ });
+
+ test('getPreset("legacy") returns the legacy preset', () => {
+ const preset = getPreset('legacy');
+ expect(preset.id).toBe('legacy');
+ expect(preset.description).toBeDefined();
+ expect(preset.supportsCacheControl).toBe(true);
+ });
+
+ test('getPreset("nonexistent") throws PRESET_NOT_FOUND', () => {
+ try {
+ getPreset('nonexistent-preset');
+ throw new Error('Expected getPreset to throw.');
+ } catch (error) {
+ expect(error).toBeInstanceOf(SuperDocCliError);
+ const cliError = error as SuperDocCliError;
+ expect(cliError.code).toBe('PRESET_NOT_FOUND');
+ expect(cliError.message).toContain('nonexistent-preset');
+ const details = cliError.details as { id: string; availablePresets: string[] };
+ expect(details.id).toBe('nonexistent-preset');
+ expect(details.availablePresets).toContain('legacy');
+ }
+ });
+
+ test('getPreset("") throws PRESET_NOT_FOUND (empty string is not the default)', () => {
+ try {
+ getPreset('');
+ throw new Error('Expected getPreset("") to throw.');
+ } catch (error) {
+ expect(error).toBeInstanceOf(SuperDocCliError);
+ expect((error as SuperDocCliError).code).toBe('PRESET_NOT_FOUND');
+ }
+ });
+
+ test('chooseTools({preset: ""}) throws PRESET_NOT_FOUND (cross-lang parity)', async () => {
+ await expect(chooseTools({ provider: 'openai', preset: '' })).rejects.toMatchObject({
+ code: 'PRESET_NOT_FOUND',
+ });
+ });
+});
+
+describe('public ToolCatalog type — structural access', () => {
+ test('getToolCatalog().tools entries expose typed properties', async () => {
+ const catalog = await getToolCatalog();
+ expect(catalog.tools.length).toBeGreaterThan(0);
+ const first = catalog.tools[0]!;
+ // These property accesses validate that ToolCatalog.tools is structurally
+ // typed (ToolCatalogEntry[]) — not unknown[]. Compile failure here means
+ // the public catalog row type regressed.
+ expect(typeof first.toolName).toBe('string');
+ expect(typeof first.description).toBe('string');
+ expect(typeof first.mutates).toBe('boolean');
+ expect(Array.isArray(first.operations)).toBe(true);
+ expect(typeof first.operations[0]?.operationId).toBe('string');
+ expect(typeof first.operations[0]?.intentAction).toBe('string');
+ });
+});
+
+describe('chooseTools — default preset equivalence', () => {
+ for (const provider of PROVIDERS) {
+ test(`omitting preset equals preset: 'legacy' (${provider})`, async () => {
+ const implicit = await chooseTools({ provider });
+ const explicit = await chooseTools({ provider, preset: 'legacy' });
+ // Tools content identical
+ expect(implicit.tools).toEqual(explicit.tools);
+ // Same tool count
+ expect(implicit.meta.toolCount).toBe(explicit.meta.toolCount);
+ // Same provider, same cache strategy
+ expect(implicit.meta.provider).toBe(explicit.meta.provider);
+ expect(implicit.meta.cacheStrategy).toBe(explicit.meta.cacheStrategy);
+ // Both echo legacy as resolved preset
+ expect(implicit.meta.preset).toBe('legacy');
+ expect(explicit.meta.preset).toBe('legacy');
+ });
+ }
+
+ test(`chooseTools(provider, preset: 'nonexistent') throws PRESET_NOT_FOUND`, async () => {
+ await expect(chooseTools({ provider: 'openai', preset: 'nonexistent-preset' })).rejects.toMatchObject({
+ code: 'PRESET_NOT_FOUND',
+ });
+ });
+
+ test('meta.preset field is included', async () => {
+ const { meta } = await chooseTools({ provider: 'openai' });
+ expect(meta.preset).toBe('legacy');
+ });
+});
+
+describe('catalog + listings — default preset equivalence', () => {
+ test(`getToolCatalog() equals getToolCatalog('legacy')`, async () => {
+ const implicit = await getToolCatalog();
+ const explicit = await getToolCatalog('legacy');
+ expect(implicit).toEqual(explicit);
+ });
+
+ for (const provider of PROVIDERS) {
+ test(`listTools(${provider}) equals listTools(${provider}, 'legacy')`, async () => {
+ const implicit = await listTools(provider);
+ const explicit = await listTools(provider, 'legacy');
+ expect(implicit).toEqual(explicit);
+ });
+ }
+
+ test(`getToolCatalog('nonexistent') throws PRESET_NOT_FOUND`, async () => {
+ await expect(getToolCatalog('nonexistent-preset')).rejects.toMatchObject({
+ code: 'PRESET_NOT_FOUND',
+ });
+ });
+});
+
+describe('system prompts — default preset equivalence', () => {
+ test(`getSystemPrompt() equals getSystemPrompt('legacy')`, async () => {
+ const implicit = await getSystemPrompt();
+ const explicit = await getSystemPrompt('legacy');
+ expect(implicit).toBe(explicit);
+ });
+
+ test(`getMcpPrompt() equals getMcpPrompt('legacy')`, async () => {
+ const implicit = await getMcpPrompt();
+ const explicit = await getMcpPrompt('legacy');
+ expect(implicit).toBe(explicit);
+ });
+
+ test(`getSystemPromptForProvider({provider}) equals preset: 'legacy'`, async () => {
+ const implicit = await getSystemPromptForProvider({ provider: 'anthropic', cache: true });
+ const explicit = await getSystemPromptForProvider({
+ provider: 'anthropic',
+ preset: 'legacy',
+ cache: true,
+ });
+ expect(implicit).toEqual(explicit);
+ });
+});
+
+describe('legacy preset direct access', () => {
+ test('getPreset("legacy").getCatalog() matches getToolCatalog()', async () => {
+ const direct = await getPreset('legacy').getCatalog();
+ const viaTopLevel = await getToolCatalog();
+ expect(direct).toEqual(viaTopLevel);
+ });
+
+ for (const provider of PROVIDERS) {
+ test(`getPreset("legacy").getTools(${provider}) matches chooseTools({provider}).tools`, async () => {
+ const direct = await getPreset('legacy').getTools(provider);
+ const viaTopLevel = await chooseTools({ provider });
+ expect(direct.tools).toEqual(viaTopLevel.tools);
+ expect(direct.cacheStrategy).toBe(viaTopLevel.meta.cacheStrategy);
+ });
+ }
+});
diff --git a/packages/sdk/langs/node/src/index.ts b/packages/sdk/langs/node/src/index.ts
index b3e1e8b25a..86ba0123b9 100644
--- a/packages/sdk/langs/node/src/index.ts
+++ b/packages/sdk/langs/node/src/index.ts
@@ -253,11 +253,17 @@ export {
getSystemPromptForProvider,
getToolCatalog,
listTools,
+ DEFAULT_PRESET,
+ getPreset,
+ listPresets,
} from './tools.js';
export type {
AnthropicSystemPrompt,
CacheStrategy,
SystemPromptForProviderResult,
+ ToolCatalog,
+ ToolCatalogEntry,
+ ToolCatalogOperation,
ToolChooserInput,
ToolProvider,
} from './tools.js';
diff --git a/packages/sdk/langs/node/src/presets.ts b/packages/sdk/langs/node/src/presets.ts
new file mode 100644
index 0000000000..460dea6e88
--- /dev/null
+++ b/packages/sdk/langs/node/src/presets.ts
@@ -0,0 +1,185 @@
+/**
+ * Preset registry for SuperDoc LLM tools.
+ *
+ * A preset is a self-contained collection of LLM tools — provider catalogs
+ * (openai / anthropic / vercel / generic), a system prompt, and a dispatcher.
+ * Multiple presets can coexist in the SDK; consumers select one at runtime via
+ * `chooseTools({ preset })`.
+ *
+ * const { tools, meta } = await chooseTools({ provider: 'vercel', preset: 'legacy' });
+ *
+ * v1 ships a single preset: `'legacy'` — a thin wrapper around today's
+ * codegen-emitted intent tools. When callers omit `preset`, `legacy` is used.
+ * The default may move once a replacement preset reaches parity; bumping it is
+ * a coordinated change in this file alone.
+ *
+ * Presets are NOT versioned. The preset id encodes the variant; a new shape
+ * ships as a new id, not a new version of an existing one.
+ *
+ * @internal
+ */
+
+import type { BoundDocApi } from './generated/client.js';
+import type { InvokeOptions } from './runtime/process.js';
+import { SuperDocCliError } from './runtime/errors.js';
+import { legacyPreset } from './presets/legacy.js';
+
+/**
+ * Wire format the tools are emitted in.
+ *
+ * - `openai` — OpenAI Chat Completions / Responses
+ * - `anthropic` — Anthropic Messages API
+ * - `vercel` — Vercel AI SDK (provider-agnostic adapter)
+ * - `generic` — vendor-neutral JSON Schema shape
+ */
+export type ToolProvider = 'openai' | 'anthropic' | 'vercel' | 'generic';
+
+/**
+ * Prompt-cache strategy returned by `chooseTools.meta.cacheStrategy`.
+ *
+ * - `explicit` — preset emitted provider-specific cache markers (Anthropic `cache_control`)
+ * - `automatic` — provider caches automatically (OpenAI ≥ 1024 prompt tokens)
+ * - `unsupported` — pass-through; caching depends on the underlying model (vercel/generic)
+ * - `disabled` — caller passed `cache: false` or omitted the flag
+ */
+export type CacheStrategy = 'explicit' | 'automatic' | 'unsupported' | 'disabled';
+
+/**
+ * One operation row in a {@link ToolCatalogEntry}. Each catalog entry can
+ * dispatch to one or more operations (e.g. multi-action intent tools), so
+ * the catalog records the operation id and the action discriminator that
+ * routes to it.
+ */
+export type ToolCatalogOperation = {
+ operationId: string;
+ intentAction: string;
+ required?: string[];
+ requiredOneOf?: string[][];
+};
+
+/**
+ * One entry in the {@link ToolCatalog}. Matches the shape of the catalog
+ * emitted by the legacy preset's codegen — kept stable as the public
+ * catalog row shape so TypeScript consumers can introspect `tools[i]`
+ * without losing property typing.
+ */
+export type ToolCatalogEntry = {
+ toolName: string;
+ description: string;
+ inputSchema: Record;
+ mutates: boolean;
+ operations: ToolCatalogOperation[];
+};
+
+/**
+ * Full tool catalog shape. The legacy preset returns the existing codegen
+ * catalog with `contractVersion`, `generatedAt`, `toolCount`, `tools`.
+ */
+export type ToolCatalog = {
+ contractVersion: string;
+ generatedAt: string | null;
+ toolCount: number;
+ tools: ToolCatalogEntry[];
+};
+
+export interface GetToolsOptions {
+ /**
+ * When `true`, the preset applies provider-specific prompt-cache markers
+ * (Anthropic `cache_control: { type: "ephemeral" }` on the last tool,
+ * for example). When omitted or `false`, no markers are added.
+ */
+ cache?: boolean;
+}
+
+export interface GetToolsResult {
+ tools: unknown[];
+ cacheStrategy: CacheStrategy;
+}
+
+/**
+ * Self-contained preset of LLM tools.
+ *
+ * Each preset owns:
+ * - its tool catalogs per provider format
+ * - its system prompt (and MCP-flavored variant)
+ * - its dispatcher (how a named tool call routes against a doc handle)
+ *
+ * Presets are stateless; the same descriptor handles every call.
+ *
+ * @internal
+ */
+export interface PresetDescriptor {
+ /** Stable identifier — used as the preset's only "version" reference. */
+ readonly id: string;
+
+ /** Human-readable description shown by `listPresets()`. */
+ readonly description: string;
+
+ /**
+ * Whether this preset's provider adapters emit Anthropic prompt-cache
+ * markers when called with `cache: true`. Informational; per-provider
+ * behavior is reported via `GetToolsResult.cacheStrategy`.
+ */
+ readonly supportsCacheControl: boolean;
+
+ /** Tool definitions for the requested provider format. */
+ getTools(provider: ToolProvider, options?: GetToolsOptions): Promise;
+
+ /** Full tool catalog with metadata (contract version, tool count, etc.). */
+ getCatalog(): Promise;
+
+ /** System prompt for embedded LLM usage (OpenAI/Anthropic/Vercel APIs). */
+ getSystemPrompt(): Promise;
+
+ /** System prompt for MCP server `instructions`. */
+ getMcpPrompt(): Promise;
+
+ /**
+ * Dispatch a tool call against a bound document handle.
+ *
+ * The handle injects session targeting; `args` must NOT carry `doc` or
+ * `sessionId`. Returns whatever the underlying operation produces.
+ */
+ dispatch(
+ documentHandle: BoundDocApi,
+ toolName: string,
+ args: Record,
+ invokeOptions?: InvokeOptions,
+ ): Promise;
+}
+
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+
+/**
+ * The default preset returned when callers omit `preset`. Set to `'legacy'`
+ * so consumers built before presets existed (today's intent-tool path) keep
+ * working without changes.
+ */
+export const DEFAULT_PRESET = 'legacy';
+
+const PRESETS: Record = {
+ legacy: legacyPreset,
+};
+
+/** List the IDs of all registered presets. */
+export function listPresets(): readonly string[] {
+ return Object.keys(PRESETS);
+}
+
+/**
+ * Resolve a preset by ID. Throws {@link SuperDocCliError} with code
+ * `PRESET_NOT_FOUND` if the ID is not registered. Omit the argument to
+ * get the default preset.
+ */
+export function getPreset(id: string = DEFAULT_PRESET): PresetDescriptor {
+ const preset = PRESETS[id];
+ if (preset == null) {
+ throw new SuperDocCliError(`Unknown LLM-tools preset: "${id}"`, {
+ code: 'PRESET_NOT_FOUND',
+ details: { id, availablePresets: Object.keys(PRESETS) },
+ });
+ }
+ return preset;
+}
diff --git a/packages/sdk/langs/node/src/presets/legacy.ts b/packages/sdk/langs/node/src/presets/legacy.ts
new file mode 100644
index 0000000000..7351ee893b
--- /dev/null
+++ b/packages/sdk/langs/node/src/presets/legacy.ts
@@ -0,0 +1,351 @@
+/**
+ * Legacy preset — wraps the existing codegen-emitted intent tools verbatim.
+ *
+ * The legacy preset is a read-through over the packaged tool artifacts in
+ * `packages/sdk/tools/` (catalog, per-provider tool JSON, system prompts) and
+ * delegates dispatch to the codegen-emitted `dispatchIntentTool`. It is the
+ * default preset returned by `chooseTools()` when callers omit `preset`.
+ *
+ * Nothing in this file relocates or rewrites the packaged artifacts. The whole
+ * point of the read-through wrapper is that running `generate:all` continues
+ * to refresh `packages/sdk/tools/*.json` in place; the legacy preset picks up
+ * the new files on the next call.
+ *
+ * @internal
+ */
+
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { BoundDocApi } from '../generated/client.js';
+import type { InvokeOptions } from '../runtime/process.js';
+import { SuperDocCliError } from '../runtime/errors.js';
+import { dispatchIntentTool } from '../generated/intent-dispatch.generated.js';
+import type {
+ GetToolsOptions,
+ GetToolsResult,
+ PresetDescriptor,
+ ToolCatalog,
+ ToolCatalogEntry,
+ ToolCatalogOperation,
+ ToolProvider,
+} from '../presets.js';
+
+// Resolve tools directory relative to package root (works from both src/ and dist/)
+const toolsDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'tools');
+
+const providerFileByName: Record = {
+ openai: 'tools.openai.json',
+ anthropic: 'tools.anthropic.json',
+ vercel: 'tools.vercel.json',
+ generic: 'tools.generic.json',
+};
+
+const STRIP_EMPTY_OPTIONAL_ARGS = new Set(['parentId', 'parentCommentId', 'id', 'status']);
+
+function isRecord(value: unknown): value is Record {
+ return typeof value === 'object' && value != null && !Array.isArray(value);
+}
+
+function isObviouslyCorruptedToolArgKey(key: string): boolean {
+ const trimmed = key.trim();
+ return trimmed.length === 0 || !/[\p{L}\p{N}]/u.test(trimmed);
+}
+
+function stripCorruptedToolArgKeys(value: unknown): unknown {
+ if (Array.isArray(value)) {
+ return value.map((item) => stripCorruptedToolArgKeys(item));
+ }
+ if (!isRecord(value)) return value;
+ const clean: Record = {};
+ for (const [key, entryValue] of Object.entries(value)) {
+ if (isObviouslyCorruptedToolArgKey(key)) continue;
+ clean[key] = stripCorruptedToolArgKeys(entryValue);
+ }
+ return clean;
+}
+
+async function readJson(fileName: string): Promise {
+ const filePath = path.join(toolsDir, fileName);
+ let raw = '';
+ try {
+ raw = await readFile(filePath, 'utf8');
+ } catch (error) {
+ throw new SuperDocCliError('Unable to load packaged tool artifact.', {
+ code: 'TOOLS_ASSET_NOT_FOUND',
+ details: { filePath, message: error instanceof Error ? error.message : String(error) },
+ });
+ }
+ try {
+ return JSON.parse(raw) as T;
+ } catch (error) {
+ throw new SuperDocCliError('Packaged tool artifact is invalid JSON.', {
+ code: 'TOOLS_ASSET_INVALID',
+ details: { filePath, message: error instanceof Error ? error.message : String(error) },
+ });
+ }
+}
+
+async function readProviderTools(provider: ToolProvider): Promise<{
+ contractVersion: string;
+ tools: unknown[];
+}> {
+ return readJson(providerFileByName[provider]);
+}
+
+// Cached catalog instance — loaded once per process.
+let _catalogCache: ToolCatalog | null = null;
+
+async function getCachedCatalog(): Promise {
+ if (_catalogCache == null) {
+ _catalogCache = await readJson('catalog.json');
+ }
+ return _catalogCache;
+}
+
+/**
+ * Apply provider-specific caching markers to the tools array. Clones the last
+ * entry instead of mutating the input. Anthropic gets an explicit
+ * `cache_control` on the last tool; other providers pass through.
+ */
+function applyCacheMarkers(tools: unknown[], provider: ToolProvider, cacheRequested: boolean): GetToolsResult {
+ if (!cacheRequested) {
+ return { tools, cacheStrategy: 'disabled' };
+ }
+
+ if (provider === 'anthropic') {
+ if (tools.length === 0) return { tools, cacheStrategy: 'explicit' };
+ // Anthropic: marking the LAST tool with cache_control caches the entire
+ // tools block (and everything before it in the request — system prompt
+ // first if it also has cache_control). Shallow-spread the last entry so we
+ // don't mutate the cached tool list in place.
+ const next = tools.slice(0, -1);
+ const last = {
+ ...(tools[tools.length - 1] as Record),
+ cache_control: { type: 'ephemeral' },
+ };
+ next.push(last);
+ return { tools: next, cacheStrategy: 'explicit' };
+ }
+
+ if (provider === 'openai') {
+ // OpenAI caches prompts ≥ 1024 tokens automatically. No marker needed,
+ // but we still report cacheStrategy:'automatic' so callers can branch on
+ // it (e.g. for measurement).
+ return { tools, cacheStrategy: 'automatic' };
+ }
+
+ // vercel / generic — depends on underlying model.
+ return { tools, cacheStrategy: 'unsupported' };
+}
+
+function resolveDocApiMethod(
+ documentHandle: BoundDocApi,
+ operationId: string,
+): (args: unknown, options?: InvokeOptions) => Promise {
+ const tokens = operationId.split('.').slice(1);
+ let cursor: unknown = documentHandle;
+
+ for (const token of tokens) {
+ if (!isRecord(cursor) || !(token in cursor)) {
+ throw new SuperDocCliError(`No SDK doc method found for operation ${operationId}.`, {
+ code: 'TOOL_DISPATCH_NOT_FOUND',
+ details: { operationId, token },
+ });
+ }
+ cursor = cursor[token];
+ }
+
+ if (typeof cursor !== 'function') {
+ throw new SuperDocCliError(`Resolved member for ${operationId} is not callable.`, {
+ code: 'TOOL_DISPATCH_NOT_FOUND',
+ details: { operationId },
+ });
+ }
+
+ return cursor as (args: unknown, options?: InvokeOptions) => Promise;
+}
+
+/**
+ * Validate tool arguments against the catalog schema.
+ *
+ * Checks three things in order:
+ * 1. No unknown keys (additionalProperties: false in merged schema)
+ * 2. All universally-required keys present (merged schema `required`)
+ * 3. All action-specific required keys present (per-operation `required`)
+ */
+function validateToolArgs(toolName: string, args: Record, tool: ToolCatalogEntry): void {
+ const schema = tool.inputSchema;
+ const properties = isRecord(schema.properties) ? schema.properties : {};
+ const required: string[] = Array.isArray(schema.required) ? (schema.required as string[]) : [];
+
+ // 1. Reject unknown keys (additionalProperties: false in merged schema)
+ const knownKeys = new Set(Object.keys(properties));
+ const unknownKeys = Object.keys(args).filter((k) => !knownKeys.has(k));
+ if (unknownKeys.length > 0) {
+ throw new SuperDocCliError(`Unknown argument(s) for ${toolName}: ${unknownKeys.join(', ')}`, {
+ code: 'INVALID_ARGUMENT',
+ details: { toolName, unknownKeys, knownKeys: [...knownKeys] },
+ });
+ }
+
+ // 2. Reject missing universally-required keys (merged schema `required`)
+ const missingKeys = required.filter((k) => args[k] == null);
+ if (missingKeys.length > 0) {
+ throw new SuperDocCliError(`Missing required argument(s) for ${toolName}: ${missingKeys.join(', ')}`, {
+ code: 'INVALID_ARGUMENT',
+ details: { toolName, missingKeys },
+ });
+ }
+
+ // 3. Reject missing per-operation required keys. For multi-action tools,
+ // resolve the operation by action; for single-op tools, use the sole entry.
+ const action = args.action;
+ let op: ToolCatalogOperation | undefined;
+ if (typeof action === 'string' && tool.operations.length > 1) {
+ op = tool.operations.find((o) => o.intentAction === action);
+ } else if (tool.operations.length === 1) {
+ op = tool.operations[0];
+ }
+
+ if (op) {
+ validateOperationRequired(toolName, action, args, op);
+ }
+}
+
+/**
+ * Check per-operation required constraints. Handles both flat `required: string[]`
+ * and discriminated `requiredOneOf: string[][]` shapes emitted by codegen.
+ */
+function validateOperationRequired(
+ toolName: string,
+ action: unknown,
+ args: Record,
+ op: ToolCatalogOperation,
+): void {
+ const actionLabel = typeof action === 'string' ? ` action "${action}"` : '';
+
+ if (op.requiredOneOf && op.requiredOneOf.length > 0) {
+ const satisfied = op.requiredOneOf.some((branch) => branch.every((k) => args[k] != null));
+ if (!satisfied) {
+ const options = op.requiredOneOf.map((b) => b.join(' + ')).join(' | ');
+ throw new SuperDocCliError(
+ `Missing required argument(s) for ${toolName}${actionLabel}: must provide one of: ${options}`,
+ {
+ code: 'INVALID_ARGUMENT',
+ details: { toolName, action, requiredOneOf: op.requiredOneOf },
+ },
+ );
+ }
+ } else if (op.required && op.required.length > 0) {
+ const missingActionKeys = op.required.filter((k) => args[k] == null);
+ if (missingActionKeys.length > 0) {
+ throw new SuperDocCliError(
+ `Missing required argument(s) for ${toolName}${actionLabel}: ${missingActionKeys.join(', ')}`,
+ {
+ code: 'INVALID_ARGUMENT',
+ details: { toolName, action, missingKeys: missingActionKeys },
+ },
+ );
+ }
+ }
+}
+
+async function legacyGetTools(provider: ToolProvider, options?: GetToolsOptions): Promise {
+ const { tools } = await readProviderTools(provider);
+ // Fail fast on malformed provider artifacts so agents don't silently boot
+ // with zero tools. Matches the pre-presets behavior of the public
+ // `listTools` path (TOOLS_ASSET_INVALID).
+ if (!Array.isArray(tools)) {
+ throw new SuperDocCliError('Tool provider bundle is missing tools array.', {
+ code: 'TOOLS_ASSET_INVALID',
+ details: { provider },
+ });
+ }
+ return applyCacheMarkers(tools, provider, options?.cache === true);
+}
+
+async function legacyGetCatalog(): Promise {
+ return getCachedCatalog();
+}
+
+async function legacyGetSystemPrompt(): Promise {
+ const promptPath = path.join(toolsDir, 'system-prompt.md');
+ try {
+ return await readFile(promptPath, 'utf8');
+ } catch {
+ throw new SuperDocCliError('System prompt not found.', {
+ code: 'TOOLS_ASSET_NOT_FOUND',
+ details: { filePath: promptPath },
+ });
+ }
+}
+
+async function legacyGetMcpPrompt(): Promise {
+ const promptPath = path.join(toolsDir, 'system-prompt-mcp.md');
+ try {
+ return await readFile(promptPath, 'utf8');
+ } catch {
+ throw new SuperDocCliError('MCP system prompt not found.', {
+ code: 'TOOLS_ASSET_NOT_FOUND',
+ details: { filePath: promptPath },
+ });
+ }
+}
+
+async function legacyDispatch(
+ documentHandle: BoundDocApi,
+ toolName: string,
+ args: Record,
+ invokeOptions?: InvokeOptions,
+): Promise {
+ if (!isRecord(args)) {
+ throw new SuperDocCliError(`Tool arguments for ${toolName} must be an object.`, {
+ code: 'INVALID_ARGUMENT',
+ details: { toolName },
+ });
+ }
+
+ const sanitizedArgs = stripCorruptedToolArgKeys(args);
+ if (!isRecord(sanitizedArgs)) {
+ throw new SuperDocCliError(`Tool arguments for ${toolName} must be an object.`, {
+ code: 'INVALID_ARGUMENT',
+ details: { toolName },
+ });
+ }
+
+ const catalog = await getCachedCatalog();
+ const tool = catalog.tools.find((t) => t.toolName === toolName);
+ if (tool == null) {
+ throw new SuperDocCliError(`Unknown tool: ${toolName}`, {
+ code: 'TOOL_DISPATCH_NOT_FOUND',
+ details: { toolName },
+ });
+ }
+ validateToolArgs(toolName, sanitizedArgs, tool);
+
+ // Strip empty strings for known optional ID/enum params that LLMs fill with ""
+ // instead of omitting. Only target params where "" is never a valid value.
+ const cleanArgs: Record = {};
+ for (const [key, value] of Object.entries(sanitizedArgs)) {
+ if (value === '' && STRIP_EMPTY_OPTIONAL_ARGS.has(key)) continue;
+ cleanArgs[key] = value;
+ }
+
+ return dispatchIntentTool(toolName, cleanArgs, (operationId, input) => {
+ const method = resolveDocApiMethod(documentHandle, operationId);
+ return method(input, invokeOptions);
+ });
+}
+
+export const legacyPreset: PresetDescriptor = {
+ id: 'legacy',
+ description: 'Codegen-emitted intent tools (default). Wraps packages/sdk/tools/ artifacts verbatim.',
+ supportsCacheControl: true,
+
+ getTools: legacyGetTools,
+ getCatalog: legacyGetCatalog,
+ getSystemPrompt: legacyGetSystemPrompt,
+ getMcpPrompt: legacyGetMcpPrompt,
+ dispatch: legacyDispatch,
+};
diff --git a/packages/sdk/langs/node/src/tools.ts b/packages/sdk/langs/node/src/tools.ts
index a7b80acd63..68fea3a78f 100644
--- a/packages/sdk/langs/node/src/tools.ts
+++ b/packages/sdk/langs/node/src/tools.ts
@@ -1,127 +1,41 @@
-import { readFile } from 'node:fs/promises';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
+/**
+ * Public LLM-tools API. Thin layer over the preset registry — every call here
+ * resolves a preset (defaulting to `legacy` for backwards compat) and delegates
+ * to it.
+ *
+ * Presets are the unit of swapping. To add a new tool surface (e.g. handwritten
+ * "core" tools, prompt-caching variant, lazy-load experiment), register a new
+ * descriptor in `presets.ts` — no changes here required.
+ */
+
import type { BoundDocApi } from './generated/client.js';
import type { InvokeOptions } from './runtime/process.js';
-import { SuperDocCliError } from './runtime/errors.js';
-import { dispatchIntentTool } from './generated/intent-dispatch.generated.js';
-
-export type ToolProvider = 'openai' | 'anthropic' | 'vercel' | 'generic';
-
-// Resolve tools directory relative to package root (works from both src/ and dist/)
-const toolsDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'tools');
-const providerFileByName: Record = {
- openai: 'tools.openai.json',
- anthropic: 'tools.anthropic.json',
- vercel: 'tools.vercel.json',
- generic: 'tools.generic.json',
-};
-
-export type ToolCatalog = {
- contractVersion: string;
- generatedAt: string | null;
- toolCount: number;
- tools: ToolCatalogEntry[];
-};
-
-type OperationEntry = {
- operationId: string;
- intentAction: string;
- required?: string[];
- requiredOneOf?: string[][];
-};
-
-type ToolCatalogEntry = {
- toolName: string;
- description: string;
- inputSchema: Record;
- mutates: boolean;
- operations: OperationEntry[];
-};
-
-const STRIP_EMPTY_OPTIONAL_ARGS = new Set(['parentId', 'parentCommentId', 'id', 'status']);
+import {
+ DEFAULT_PRESET,
+ getPreset,
+ listPresets,
+ type CacheStrategy,
+ type ToolCatalog,
+ type ToolCatalogEntry,
+ type ToolCatalogOperation,
+ type ToolProvider,
+} from './presets.js';
+
+export { DEFAULT_PRESET, getPreset, listPresets };
+export type { CacheStrategy, ToolCatalog, ToolCatalogEntry, ToolCatalogOperation, ToolProvider };
-function isRecord(value: unknown): value is Record {
- return typeof value === 'object' && value != null && !Array.isArray(value);
-}
-
-function isObviouslyCorruptedToolArgKey(key: string): boolean {
- const trimmed = key.trim();
- return trimmed.length === 0 || !/[\p{L}\p{N}]/u.test(trimmed);
-}
-
-function stripCorruptedToolArgKeys(value: unknown): unknown {
- if (Array.isArray(value)) {
- return value.map((item) => stripCorruptedToolArgKeys(item));
- }
-
- if (!isRecord(value)) return value;
-
- const clean: Record = {};
- for (const [key, entryValue] of Object.entries(value)) {
- if (isObviouslyCorruptedToolArgKey(key)) continue;
- clean[key] = stripCorruptedToolArgKeys(entryValue);
- }
- return clean;
-}
-
-async function readJson(fileName: string): Promise {
- const filePath = path.join(toolsDir, fileName);
- let raw = '';
- try {
- raw = await readFile(filePath, 'utf8');
- } catch (error) {
- throw new SuperDocCliError('Unable to load packaged tool artifact.', {
- code: 'TOOLS_ASSET_NOT_FOUND',
- details: {
- filePath,
- message: error instanceof Error ? error.message : String(error),
- },
- });
- }
-
- try {
- return JSON.parse(raw) as T;
- } catch (error) {
- throw new SuperDocCliError('Packaged tool artifact is invalid JSON.', {
- code: 'TOOLS_ASSET_INVALID',
- details: {
- filePath,
- message: error instanceof Error ? error.message : String(error),
- },
- });
- }
-}
-
-async function loadProviderBundle(provider: ToolProvider): Promise<{
- contractVersion: string;
- tools: unknown[];
-}> {
- return readJson(providerFileByName[provider]);
-}
-
-async function loadCatalog(): Promise {
- return readJson('catalog.json');
-}
-
-export async function getToolCatalog(): Promise {
- return getCachedCatalog();
-}
-
-export async function listTools(provider: ToolProvider): Promise {
- const bundle = await loadProviderBundle(provider);
- const tools = bundle.tools;
- if (!Array.isArray(tools)) {
- throw new SuperDocCliError('Tool provider bundle is missing tools array.', {
- code: 'TOOLS_ASSET_INVALID',
- details: { provider },
- });
- }
- return tools;
-}
+// ---------------------------------------------------------------------------
+// chooseTools — provider-shaped tool list with optional cache markers
+// ---------------------------------------------------------------------------
export type ToolChooserInput = {
provider: ToolProvider;
+ /**
+ * Preset ID to load tools from. Defaults to {@link DEFAULT_PRESET}
+ * (`'legacy'`) for backwards compatibility. Use {@link listPresets} to
+ * discover available presets.
+ */
+ preset?: string;
/**
* When `true`, applies provider-specific prompt-caching markers to the
* returned tools so subsequent identical requests reuse the cached prefix.
@@ -139,220 +53,79 @@ export type ToolChooserInput = {
cache?: boolean;
};
-export type CacheStrategy = 'explicit' | 'automatic' | 'unsupported' | 'disabled';
-
/**
- * Select all intent tools for a specific provider.
- *
- * Returns all intent tools in the requested provider format. Pass
- * `cache: true` to apply provider-specific caching markers (see
- * {@link ToolChooserInput.cache}).
+ * Select tools for a specific provider from a preset.
*
* @example
* ```ts
+ * // Default — legacy preset, no cache markers.
+ * const { tools, meta } = await chooseTools({ provider: 'vercel' });
+ *
* // Anthropic — last tool gets cache_control automatically.
* const { tools, meta } = await chooseTools({ provider: 'anthropic', cache: true });
*
- * // OpenAI — caching is automatic when prompts exceed 1024 tokens.
- * const { tools } = await chooseTools({ provider: 'openai', cache: true });
+ * // Pick a specific preset by ID.
+ * const { tools, meta } = await chooseTools({ provider: 'openai', preset: 'legacy' });
* ```
*/
export async function chooseTools(input: ToolChooserInput): Promise<{
tools: unknown[];
meta: {
provider: ToolProvider;
+ preset: string;
toolCount: number;
cacheStrategy: CacheStrategy;
};
}> {
- const bundle = await loadProviderBundle(input.provider);
- const rawTools = Array.isArray(bundle.tools) ? bundle.tools : [];
- const cacheRequested = input.cache === true;
-
- const { tools, cacheStrategy } = applyCacheMarkers(rawTools, input.provider, cacheRequested);
-
+ const presetId = input.preset ?? DEFAULT_PRESET;
+ const preset = getPreset(presetId);
+ const { tools, cacheStrategy } = await preset.getTools(input.provider, {
+ cache: input.cache === true,
+ });
return {
tools,
meta: {
provider: input.provider,
+ preset: presetId,
toolCount: tools.length,
cacheStrategy,
},
};
}
-/**
- * Apply provider-specific caching markers to the tools array. Mutates a clone,
- * never the input. Anthropic gets an explicit `cache_control` on the last
- * tool; other providers pass through.
- */
-function applyCacheMarkers(
- tools: unknown[],
- provider: ToolProvider,
- cacheRequested: boolean,
-): { tools: unknown[]; cacheStrategy: CacheStrategy } {
- if (!cacheRequested) {
- return { tools, cacheStrategy: 'disabled' };
- }
-
- if (provider === 'anthropic') {
- if (tools.length === 0) return { tools, cacheStrategy: 'explicit' };
- // Anthropic: marking the LAST tool with cache_control caches the entire
- // tools block (and everything before it in the request — system prompt
- // first if it also has cache_control). Shallow-spread the last entry so we
- // don't mutate the cached bundle in place.
- const next = tools.slice(0, -1);
- const last = {
- ...(tools[tools.length - 1] as Record),
- cache_control: { type: 'ephemeral' },
- };
- next.push(last);
- return { tools: next, cacheStrategy: 'explicit' };
- }
-
- if (provider === 'openai') {
- // OpenAI caches prompts ≥ 1024 tokens automatically. No marker needed,
- // but we still report cacheStrategy:'automatic' so callers can branch on
- // it (e.g. for measurement).
- return { tools, cacheStrategy: 'automatic' };
- }
-
- // vercel / generic — depends on underlying model.
- return { tools, cacheStrategy: 'unsupported' };
-}
-
-function resolveDocApiMethod(
- documentHandle: BoundDocApi,
- operationId: string,
-): (args: unknown, options?: InvokeOptions) => Promise {
- const tokens = operationId.split('.').slice(1);
- let cursor: unknown = documentHandle;
-
- for (const token of tokens) {
- if (!isRecord(cursor) || !(token in cursor)) {
- throw new SuperDocCliError(`No SDK doc method found for operation ${operationId}.`, {
- code: 'TOOL_DISPATCH_NOT_FOUND',
- details: { operationId, token },
- });
- }
- cursor = cursor[token];
- }
-
- if (typeof cursor !== 'function') {
- throw new SuperDocCliError(`Resolved member for ${operationId} is not callable.`, {
- code: 'TOOL_DISPATCH_NOT_FOUND',
- details: { operationId },
- });
- }
-
- return cursor as (args: unknown, options?: InvokeOptions) => Promise;
-}
-
-// Cached catalog instance — loaded once per process.
-let _catalogCache: ToolCatalog | null = null;
+// ---------------------------------------------------------------------------
+// Catalog + listings (preset-scoped; default to legacy)
+// ---------------------------------------------------------------------------
-async function getCachedCatalog(): Promise {
- if (_catalogCache == null) {
- _catalogCache = await loadCatalog();
- }
- return _catalogCache;
+/** Return the full tool catalog for a preset (default: legacy). */
+export async function getToolCatalog(preset?: string): Promise {
+ return getPreset(preset ?? DEFAULT_PRESET).getCatalog();
}
/**
- * Validate tool arguments against the catalog schema.
+ * Return the raw tool array for a provider from a preset (default: legacy).
*
- * Checks three things in order:
- * 1. No unknown keys (additionalProperties: false in merged schema)
- * 2. All universally-required keys present (merged schema `required`)
- * 3. All action-specific required keys present (per-operation `required`)
+ * No cache markers are applied. Use {@link chooseTools} when you need cache
+ * markers and metadata.
*/
-function validateToolArgs(toolName: string, args: Record, tool: ToolCatalogEntry): void {
- const schema = tool.inputSchema;
- const properties = isRecord(schema.properties) ? schema.properties : {};
- const required: string[] = Array.isArray(schema.required) ? (schema.required as string[]) : [];
-
- // 1. Reject unknown keys
- const knownKeys = new Set(Object.keys(properties));
- const unknownKeys = Object.keys(args).filter((k) => !knownKeys.has(k));
- if (unknownKeys.length > 0) {
- throw new SuperDocCliError(`Unknown argument(s) for ${toolName}: ${unknownKeys.join(', ')}`, {
- code: 'INVALID_ARGUMENT',
- details: { toolName, unknownKeys, knownKeys: [...knownKeys] },
- });
- }
-
- // 2. Reject missing universally-required keys
- const missingKeys = required.filter((k) => args[k] == null);
- if (missingKeys.length > 0) {
- throw new SuperDocCliError(`Missing required argument(s) for ${toolName}: ${missingKeys.join(', ')}`, {
- code: 'INVALID_ARGUMENT',
- details: { toolName, missingKeys },
- });
- }
-
- // 3. Reject missing per-operation required keys.
- // For multi-action tools, resolve the operation by action; for single-op
- // tools, use the sole operation entry.
- const action = args.action;
- let op: OperationEntry | undefined;
- if (typeof action === 'string' && tool.operations.length > 1) {
- op = tool.operations.find((o) => o.intentAction === action);
- } else if (tool.operations.length === 1) {
- op = tool.operations[0];
- }
-
- if (op) {
- validateOperationRequired(toolName, action, args, op);
- }
+export async function listTools(provider: ToolProvider, preset?: string): Promise {
+ const { tools } = await getPreset(preset ?? DEFAULT_PRESET).getTools(provider, { cache: false });
+ return tools;
}
-/**
- * Check per-operation required constraints.
- *
- * Handles two shapes emitted by the codegen:
- * - `required: string[]` — all listed keys must be present
- * - `requiredOneOf: string[][]` — at least one branch must be fully satisfied
- * (mirrors JSON Schema `oneOf` with per-branch `required` arrays)
- */
-function validateOperationRequired(
- toolName: string,
- action: unknown,
- args: Record,
- op: OperationEntry,
-): void {
- const actionLabel = typeof action === 'string' ? ` action "${action}"` : '';
-
- if (op.requiredOneOf && op.requiredOneOf.length > 0) {
- const satisfied = op.requiredOneOf.some((branch) => branch.every((k) => args[k] != null));
- if (!satisfied) {
- const options = op.requiredOneOf.map((b) => b.join(' + ')).join(' | ');
- throw new SuperDocCliError(
- `Missing required argument(s) for ${toolName}${actionLabel}: must provide one of: ${options}`,
- {
- code: 'INVALID_ARGUMENT',
- details: { toolName, action, requiredOneOf: op.requiredOneOf },
- },
- );
- }
- } else if (op.required && op.required.length > 0) {
- const missingActionKeys = op.required.filter((k) => args[k] == null);
- if (missingActionKeys.length > 0) {
- throw new SuperDocCliError(
- `Missing required argument(s) for ${toolName}${actionLabel}: ${missingActionKeys.join(', ')}`,
- {
- code: 'INVALID_ARGUMENT',
- details: { toolName, action, missingKeys: missingActionKeys },
- },
- );
- }
- }
-}
+// ---------------------------------------------------------------------------
+// Dispatch
+// ---------------------------------------------------------------------------
/**
- * Dispatch a tool call against a bound document handle.
+ * Dispatch a tool call against a bound document handle using the default
+ * preset (`legacy`).
+ *
+ * The document handle injects session targeting automatically; tool arguments
+ * should not contain `doc` or `sessionId`.
*
- * The document handle injects session targeting automatically.
- * Tool arguments should not contain `doc` or `sessionId`.
+ * For preset-aware dispatch — e.g. when comparing two presets — call
+ * `getPreset('id').dispatch(...)` directly.
*/
export async function dispatchSuperDocTool(
documentHandle: BoundDocApi,
@@ -360,81 +133,32 @@ export async function dispatchSuperDocTool(
args: Record = {},
invokeOptions?: InvokeOptions,
): Promise {
- if (!isRecord(args)) {
- throw new SuperDocCliError(`Tool arguments for ${toolName} must be an object.`, {
- code: 'INVALID_ARGUMENT',
- details: { toolName },
- });
- }
-
- const sanitizedArgs = stripCorruptedToolArgKeys(args);
- if (!isRecord(sanitizedArgs)) {
- throw new SuperDocCliError(`Tool arguments for ${toolName} must be an object.`, {
- code: 'INVALID_ARGUMENT',
- details: { toolName },
- });
- }
-
- // Validate against the tool schema before dispatch.
- const catalog = await getCachedCatalog();
- const tool = catalog.tools.find((t) => t.toolName === toolName);
- if (tool == null) {
- throw new SuperDocCliError(`Unknown tool: ${toolName}`, {
- code: 'TOOL_DISPATCH_NOT_FOUND',
- details: { toolName },
- });
- }
- validateToolArgs(toolName, sanitizedArgs, tool);
-
- // Strip empty strings for known optional ID/enum params that LLMs fill with ""
- // instead of omitting. Only target params where "" is never a valid value.
- const cleanArgs: Record = {};
- for (const [key, value] of Object.entries(sanitizedArgs)) {
- if (value === '' && STRIP_EMPTY_OPTIONAL_ARGS.has(key)) continue;
- cleanArgs[key] = value;
- }
-
- return dispatchIntentTool(toolName, cleanArgs, (operationId, input) => {
- const method = resolveDocApiMethod(documentHandle, operationId);
- return method(input, invokeOptions);
- });
+ return getPreset(DEFAULT_PRESET).dispatch(documentHandle, toolName, args, invokeOptions);
}
+// ---------------------------------------------------------------------------
+// System prompts (preset-scoped; default to legacy)
+// ---------------------------------------------------------------------------
+
/**
- * Read the bundled SDK system prompt for intent tools.
+ * Read the packaged SDK system prompt (default preset: legacy).
*
- * This prompt includes a persona preamble ("You are a document editing assistant…")
- * suitable for embedded LLM usage (OpenAI, Anthropic, Vercel APIs).
- * For MCP server instructions, use {@link getMcpPrompt} instead.
+ * Includes a persona preamble ("You are a document editing assistant…")
+ * suitable for embedded LLM usage (OpenAI, Anthropic, Vercel APIs). For MCP
+ * server instructions, use {@link getMcpPrompt} instead.
*/
-export async function getSystemPrompt(): Promise {
- const promptPath = path.join(toolsDir, 'system-prompt.md');
- try {
- return await readFile(promptPath, 'utf8');
- } catch {
- throw new SuperDocCliError('System prompt not found.', {
- code: 'TOOLS_ASSET_NOT_FOUND',
- details: { filePath: promptPath },
- });
- }
+export async function getSystemPrompt(preset?: string): Promise {
+ return getPreset(preset ?? DEFAULT_PRESET).getSystemPrompt();
}
/**
- * Read the bundled MCP system prompt for intent tools.
+ * Read the packaged MCP system prompt for intent tools (default preset: legacy).
*
- * This prompt omits the persona preamble and includes session lifecycle
- * instructions (open/save/close) suitable for MCP server `instructions`.
+ * Omits the persona preamble and includes session lifecycle instructions
+ * (open/save/close) suitable for MCP server `instructions`.
*/
-export async function getMcpPrompt(): Promise {
- const promptPath = path.join(toolsDir, 'system-prompt-mcp.md');
- try {
- return await readFile(promptPath, 'utf8');
- } catch {
- throw new SuperDocCliError('MCP system prompt not found.', {
- code: 'TOOLS_ASSET_NOT_FOUND',
- details: { filePath: promptPath },
- });
- }
+export async function getMcpPrompt(preset?: string): Promise {
+ return getPreset(preset ?? DEFAULT_PRESET).getMcpPrompt();
}
// ---------------------------------------------------------------------------
@@ -481,9 +205,10 @@ export type SystemPromptForProviderResult =
*/
export async function getSystemPromptForProvider(input: {
provider: ToolProvider;
+ preset?: string;
cache?: boolean;
}): Promise {
- const text = await getSystemPrompt();
+ const text = await getSystemPrompt(input.preset);
const cacheRequested = input.cache === true;
if (input.provider === 'anthropic') {
diff --git a/packages/sdk/langs/python/pyproject.toml b/packages/sdk/langs/python/pyproject.toml
index bfeee6b86f..ade7157fc3 100644
--- a/packages/sdk/langs/python/pyproject.toml
+++ b/packages/sdk/langs/python/pyproject.toml
@@ -22,6 +22,7 @@ dependencies = [
packages = [
"superdoc",
"superdoc.generated",
+ "superdoc.presets",
"superdoc.skills",
"superdoc.tools",
]
diff --git a/packages/sdk/langs/python/superdoc/__init__.py b/packages/sdk/langs/python/superdoc/__init__.py
index fa0b628a52..40ddf0e273 100644
--- a/packages/sdk/langs/python/superdoc/__init__.py
+++ b/packages/sdk/langs/python/superdoc/__init__.py
@@ -1,3 +1,4 @@
+from .presets import DEFAULT_PRESET, get_preset, list_presets
from .client import AsyncSuperDocClient, AsyncSuperDocDocument, SuperDocClient, SuperDocDocument
from .errors import SuperDocError
from .skill_api import get_skill, install_skill, list_skills
@@ -29,4 +30,7 @@
"dispatch_superdoc_tool_async",
"get_mcp_prompt",
"get_system_prompt",
+ "DEFAULT_PRESET",
+ "get_preset",
+ "list_presets",
]
diff --git a/packages/sdk/langs/python/superdoc/presets/__init__.py b/packages/sdk/langs/python/superdoc/presets/__init__.py
new file mode 100644
index 0000000000..3cb8c6cc29
--- /dev/null
+++ b/packages/sdk/langs/python/superdoc/presets/__init__.py
@@ -0,0 +1,102 @@
+"""Preset registry for SuperDoc LLM tools (Python).
+
+Mirrors the Node SDK preset registry (see ``packages/sdk/langs/node/src/presets.ts``).
+A preset is a self-contained collection of LLM tools — provider catalogs
+(openai / anthropic / vercel / generic), a system prompt, and a dispatcher.
+Multiple presets can coexist; consumers select one at runtime via
+``choose_tools({'preset': ...})``.
+
+v1 ships a single preset: ``'legacy'`` — a thin wrapper around today's
+codegen-emitted intent tools. When callers omit ``preset``, ``legacy`` is used.
+
+Presets are NOT versioned. The preset id encodes the variant; a new shape
+ships as a new id, not a new version of an existing one.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Awaitable, Dict, List, Literal, Optional, Protocol
+
+from ..errors import SuperDocError
+
+ToolProvider = Literal['openai', 'anthropic', 'vercel', 'generic']
+
+
+class PresetDescriptor(Protocol):
+ """Self-contained preset of LLM tools.
+
+ Mirrors the Node SDK PresetDescriptor interface 1:1. Each preset owns
+ its tool catalogs per provider, its system prompts, and its dispatcher.
+ """
+
+ id: str
+ description: str
+ supports_cache_control: bool
+
+ def get_tools(self, provider: ToolProvider, *, cache: bool = False) -> Dict[str, Any]: ...
+ def get_catalog(self) -> Dict[str, Any]: ...
+ def get_system_prompt(self) -> str: ...
+ def get_mcp_prompt(self) -> str: ...
+ def dispatch(
+ self,
+ document_handle: Any,
+ tool_name: str,
+ args: Optional[Dict[str, Any]] = None,
+ invoke_options: Optional[Dict[str, Any]] = None,
+ ) -> Any: ...
+ def dispatch_async(
+ self,
+ document_handle: Any,
+ tool_name: str,
+ args: Optional[Dict[str, Any]] = None,
+ invoke_options: Optional[Dict[str, Any]] = None,
+ ) -> Awaitable[Any]: ...
+
+
+# Lazy import to avoid the registry pulling in heavy modules at package load.
+def _build_registry() -> Dict[str, PresetDescriptor]:
+ from .legacy import legacy_preset # noqa: WPS433 — intentional lazy import
+ return {'legacy': legacy_preset}
+
+
+DEFAULT_PRESET: str = 'legacy'
+_PRESETS: Optional[Dict[str, PresetDescriptor]] = None
+
+
+def _registry() -> Dict[str, PresetDescriptor]:
+ global _PRESETS
+ if _PRESETS is None:
+ _PRESETS = _build_registry()
+ return _PRESETS
+
+
+def list_presets() -> List[str]:
+ """List the IDs of all registered presets."""
+ return list(_registry().keys())
+
+
+def get_preset(preset_id: Optional[str] = None) -> PresetDescriptor:
+ """Resolve a preset by ID.
+
+ Raises :class:`SuperDocError` with code ``PRESET_NOT_FOUND`` if the ID is
+ not registered. Omit the argument to get the default preset.
+ """
+ resolved = preset_id if preset_id is not None else DEFAULT_PRESET
+ registry = _registry()
+ preset = registry.get(resolved)
+ if preset is None:
+ raise SuperDocError(
+ f'Unknown LLM-tools preset: "{resolved}"',
+ code='PRESET_NOT_FOUND',
+ details={'id': resolved, 'availablePresets': list(registry.keys())},
+ )
+ return preset
+
+
+__all__ = [
+ 'PresetDescriptor',
+ 'DEFAULT_PRESET',
+ 'ToolProvider',
+ 'get_preset',
+ 'list_presets',
+]
diff --git a/packages/sdk/langs/python/superdoc/presets/legacy.py b/packages/sdk/langs/python/superdoc/presets/legacy.py
new file mode 100644
index 0000000000..33647150eb
--- /dev/null
+++ b/packages/sdk/langs/python/superdoc/presets/legacy.py
@@ -0,0 +1,286 @@
+"""Legacy preset — wraps the existing codegen-emitted intent tools verbatim.
+
+Mirrors ``packages/sdk/langs/node/src/presets/legacy.ts``. The legacy preset is
+a read-through over the packaged tool artifacts in ``superdoc/tools/`` (catalog,
+per-provider tool JSON, system prompts) and delegates dispatch to the
+codegen-emitted ``dispatch_intent_tool``. It is the default preset returned
+by ``choose_tools()`` when callers omit ``preset``.
+
+Nothing in this file relocates or rewrites the packaged artifacts. The whole
+point of the read-through wrapper is that running ``generate:all`` continues
+to refresh the package assets in place; the legacy preset picks up the new
+files on the next call.
+"""
+
+from __future__ import annotations
+
+import inspect
+import json
+import re
+from dataclasses import dataclass
+from importlib import resources
+from typing import Any, Awaitable, Dict, List, Optional, cast
+
+from ..errors import SuperDocError
+from ..tools.intent_dispatch_generated import dispatch_intent_tool
+from . import ToolProvider
+
+_PROVIDER_FILE: Dict[ToolProvider, str] = {
+ 'openai': 'tools.openai.json',
+ 'anthropic': 'tools.anthropic.json',
+ 'vercel': 'tools.vercel.json',
+ 'generic': 'tools.generic.json',
+}
+
+
+def _read_json_asset(name: str) -> Dict[str, Any]:
+ resource = resources.files('superdoc').joinpath('tools', name)
+ try:
+ raw = resource.read_text(encoding='utf-8')
+ except FileNotFoundError as error:
+ raise SuperDocError(
+ 'Unable to load packaged tool artifact.',
+ code='TOOLS_ASSET_NOT_FOUND',
+ details={'file': name},
+ ) from error
+ except Exception as error:
+ raise SuperDocError(
+ 'Unable to read packaged tool artifact.',
+ code='TOOLS_ASSET_NOT_FOUND',
+ details={'file': name, 'message': str(error)},
+ ) from error
+
+ try:
+ parsed = json.loads(raw)
+ except Exception as error:
+ raise SuperDocError(
+ 'Packaged tool artifact is invalid JSON.',
+ code='TOOLS_ASSET_INVALID',
+ details={'file': name, 'message': str(error)},
+ ) from error
+
+ if not isinstance(parsed, dict):
+ raise SuperDocError(
+ 'Packaged tool artifact root must be an object.',
+ code='TOOLS_ASSET_INVALID',
+ details={'file': name},
+ )
+
+ return cast(Dict[str, Any], parsed)
+
+
+_catalog_cache: Optional[Dict[str, Any]] = None
+
+
+def _get_catalog_cached() -> Dict[str, Any]:
+ global _catalog_cache
+ if _catalog_cache is None:
+ _catalog_cache = _read_json_asset('catalog.json')
+ return _catalog_cache
+
+
+def _apply_cache_markers(
+ tools: List[Any],
+ provider: ToolProvider,
+ cache_requested: bool,
+) -> Dict[str, Any]:
+ if not cache_requested:
+ return {'tools': tools, 'cacheStrategy': 'disabled'}
+
+ if provider == 'anthropic':
+ if not tools:
+ return {'tools': tools, 'cacheStrategy': 'explicit'}
+ # Mark the LAST tool with cache_control — caches the entire tools block.
+ next_tools = list(tools[:-1])
+ last = dict(tools[-1]) if isinstance(tools[-1], dict) else tools[-1]
+ if isinstance(last, dict):
+ last['cache_control'] = {'type': 'ephemeral'}
+ next_tools.append(last)
+ return {'tools': next_tools, 'cacheStrategy': 'explicit'}
+
+ if provider == 'openai':
+ return {'tools': tools, 'cacheStrategy': 'automatic'}
+
+ return {'tools': tools, 'cacheStrategy': 'unsupported'}
+
+
+def _snake_case(token: str) -> str:
+ token = re.sub(r'([A-Z]+)([A-Z][a-z])', r'\1_\2', token)
+ token = re.sub(r'([a-z0-9])([A-Z])', r'\1_\2', token)
+ return token.replace('-', '_').lower()
+
+
+def _resolve_doc_method(document_handle: Any, operation_id: str) -> Any:
+ cursor = document_handle
+ for token in operation_id.split('.')[1:]:
+ candidates = [token]
+ snake_token = _snake_case(token)
+ if snake_token != token:
+ candidates.append(snake_token)
+
+ resolved = None
+ for candidate in candidates:
+ if hasattr(cursor, candidate):
+ resolved = getattr(cursor, candidate)
+ break
+
+ if resolved is None:
+ raise SuperDocError(
+ 'No SDK doc method found for operation.',
+ code='TOOL_DISPATCH_NOT_FOUND',
+ details={'operationId': operation_id, 'token': token},
+ )
+ cursor = resolved
+
+ if not callable(cursor):
+ raise SuperDocError(
+ 'Resolved SDK doc member is not callable.',
+ code='TOOL_DISPATCH_NOT_FOUND',
+ details={'operationId': operation_id},
+ )
+
+ return cursor
+
+
+def _legacy_get_tools(provider: ToolProvider, *, cache: bool = False) -> Dict[str, Any]:
+ if provider not in ('openai', 'anthropic', 'vercel', 'generic'):
+ raise SuperDocError('provider is required.', code='INVALID_ARGUMENT', details={'provider': provider})
+ provider_file = _read_json_asset(_PROVIDER_FILE[provider])
+ tools = provider_file.get('tools')
+ # Fail fast on malformed provider artifacts so agents don't silently boot
+ # with zero tools. Matches the Node legacy preset's behavior and the
+ # pre-presets contract of the public list_tools path.
+ if not isinstance(tools, list):
+ raise SuperDocError(
+ 'Tool provider bundle is missing tools array.',
+ code='TOOLS_ASSET_INVALID',
+ details={'provider': provider},
+ )
+ return _apply_cache_markers(cast(List[Any], tools), provider, cache)
+
+
+def _legacy_get_catalog() -> Dict[str, Any]:
+ return _get_catalog_cached()
+
+
+def _legacy_get_system_prompt() -> str:
+ resource = resources.files('superdoc').joinpath('tools', 'system-prompt.md')
+ try:
+ return resource.read_text(encoding='utf-8')
+ except FileNotFoundError as error:
+ raise SuperDocError(
+ 'System prompt not found.',
+ code='TOOLS_ASSET_NOT_FOUND',
+ details={'file': 'system-prompt.md'},
+ ) from error
+
+
+def _legacy_get_mcp_prompt() -> str:
+ resource = resources.files('superdoc').joinpath('tools', 'system-prompt-mcp.md')
+ try:
+ return resource.read_text(encoding='utf-8')
+ except FileNotFoundError as error:
+ raise SuperDocError(
+ 'MCP system prompt not found.',
+ code='TOOLS_ASSET_NOT_FOUND',
+ details={'file': 'system-prompt-mcp.md'},
+ ) from error
+
+
+def _legacy_dispatch(
+ document_handle: Any,
+ tool_name: str,
+ args: Optional[Dict[str, Any]] = None,
+ invoke_options: Optional[Dict[str, Any]] = None,
+) -> Any:
+ payload = args or {}
+ if not isinstance(payload, dict):
+ raise SuperDocError(
+ 'Tool arguments must be an object.',
+ code='INVALID_ARGUMENT',
+ details={'toolName': tool_name},
+ )
+
+ payload = {k: v for k, v in payload.items() if k not in ('doc', 'sessionId')}
+
+ def execute(operation_id: str, input_args: Dict[str, Any]) -> Any:
+ method = _resolve_doc_method(document_handle, operation_id)
+ if inspect.iscoroutinefunction(method):
+ raise SuperDocError(
+ 'legacy.dispatch cannot call async methods. Use dispatch_async.',
+ code='INVALID_ARGUMENT',
+ details={'toolName': tool_name, 'operationId': operation_id},
+ )
+ kwargs = dict(invoke_options or {})
+ return method(input_args, **kwargs)
+
+ return dispatch_intent_tool(tool_name, payload, execute)
+
+
+async def _legacy_dispatch_async(
+ document_handle: Any,
+ tool_name: str,
+ args: Optional[Dict[str, Any]] = None,
+ invoke_options: Optional[Dict[str, Any]] = None,
+) -> Any:
+ payload = args or {}
+ if not isinstance(payload, dict):
+ raise SuperDocError(
+ 'Tool arguments must be an object.',
+ code='INVALID_ARGUMENT',
+ details={'toolName': tool_name},
+ )
+
+ payload = {k: v for k, v in payload.items() if k not in ('doc', 'sessionId')}
+
+ def execute(operation_id: str, input_args: Dict[str, Any]) -> Any:
+ method = _resolve_doc_method(document_handle, operation_id)
+ kwargs = dict(invoke_options or {})
+ return method(input_args, **kwargs)
+
+ result = dispatch_intent_tool(tool_name, payload, execute)
+ if inspect.isawaitable(result):
+ return await result
+ return result
+
+
+@dataclass(frozen=True)
+class _LegacyPreset:
+ id: str = 'legacy'
+ description: str = (
+ 'Codegen-emitted intent tools (default). Wraps superdoc/tools/ artifacts verbatim.'
+ )
+ supports_cache_control: bool = True
+
+ def get_tools(self, provider: ToolProvider, *, cache: bool = False) -> Dict[str, Any]:
+ return _legacy_get_tools(provider, cache=cache)
+
+ def get_catalog(self) -> Dict[str, Any]:
+ return _legacy_get_catalog()
+
+ def get_system_prompt(self) -> str:
+ return _legacy_get_system_prompt()
+
+ def get_mcp_prompt(self) -> str:
+ return _legacy_get_mcp_prompt()
+
+ def dispatch(
+ self,
+ document_handle: Any,
+ tool_name: str,
+ args: Optional[Dict[str, Any]] = None,
+ invoke_options: Optional[Dict[str, Any]] = None,
+ ) -> Any:
+ return _legacy_dispatch(document_handle, tool_name, args, invoke_options)
+
+ def dispatch_async(
+ self,
+ document_handle: Any,
+ tool_name: str,
+ args: Optional[Dict[str, Any]] = None,
+ invoke_options: Optional[Dict[str, Any]] = None,
+ ) -> Awaitable[Any]:
+ return _legacy_dispatch_async(document_handle, tool_name, args, invoke_options)
+
+
+legacy_preset: _LegacyPreset = _LegacyPreset()
diff --git a/packages/sdk/langs/python/superdoc/test_parity_helper.py b/packages/sdk/langs/python/superdoc/test_parity_helper.py
index 08fbd86f93..92f1560ddc 100644
--- a/packages/sdk/langs/python/superdoc/test_parity_helper.py
+++ b/packages/sdk/langs/python/superdoc/test_parity_helper.py
@@ -26,6 +26,13 @@ def main() -> None:
result.pop('tools', None)
print(json.dumps({'ok': True, 'result': result}))
+ elif action == 'listPresets':
+ from superdoc import DEFAULT_PRESET, list_presets
+ print(json.dumps({'ok': True, 'result': {
+ 'defaultPreset': DEFAULT_PRESET,
+ 'presets': list_presets(),
+ }}))
+
elif action == 'resolveIntentDispatch':
from superdoc.tools.intent_dispatch_generated import dispatch_intent_tool
tool_name = command['toolName']
diff --git a/packages/sdk/langs/python/superdoc/tools_api.py b/packages/sdk/langs/python/superdoc/tools_api.py
index 12ed092873..87847c16a2 100644
--- a/packages/sdk/langs/python/superdoc/tools_api.py
+++ b/packages/sdk/langs/python/superdoc/tools_api.py
@@ -1,174 +1,118 @@
+"""Public LLM-tools API (Python SDK). Thin layer over the preset registry.
+
+Every call here resolves a preset (defaulting to ``legacy`` for backwards
+compat) and delegates to it. Mirrors ``packages/sdk/langs/node/src/tools.ts``.
+"""
+
from __future__ import annotations
-import inspect
-import json
-import re
-from importlib import resources
-from typing import Any, Dict, List, Literal, Optional, TypedDict, cast
+from typing import Any, Dict, List, Optional, TypedDict, cast
+from .presets import DEFAULT_PRESET, ToolProvider, get_preset, list_presets
from .errors import SuperDocError
-from .tools.intent_dispatch_generated import dispatch_intent_tool
-ToolProvider = Literal['openai', 'anthropic', 'vercel', 'generic']
+__all__ = [
+ 'DEFAULT_PRESET',
+ 'ToolChooserInput',
+ 'ToolProvider',
+ 'choose_tools',
+ 'dispatch_superdoc_tool',
+ 'dispatch_superdoc_tool_async',
+ 'get_preset',
+ 'get_mcp_prompt',
+ 'get_system_prompt',
+ 'get_tool_catalog',
+ 'list_presets',
+ 'list_tools',
+]
class ToolChooserInput(TypedDict, total=False):
provider: ToolProvider
+ # Preset ID to load tools from. Defaults to DEFAULT_PRESET ('legacy')
+ # for backwards compatibility. Use list_presets() to discover presets.
+ preset: str
+ # When True, applies provider-specific prompt-cache markers (Anthropic
+ # ``cache_control: { type: "ephemeral" }`` on the last tool, etc).
+ cache: bool
-PROVIDER_FILE: Dict[ToolProvider, str] = {
- 'openai': 'tools.openai.json',
- 'anthropic': 'tools.anthropic.json',
- 'vercel': 'tools.vercel.json',
- 'generic': 'tools.generic.json',
-}
-
+def get_tool_catalog(preset: Optional[str] = None) -> Dict[str, Any]:
+ """Return the full tool catalog for a preset (default: legacy)."""
+ return get_preset(preset).get_catalog()
-def _read_json_asset(name: str) -> Dict[str, Any]:
- resource = resources.files('superdoc').joinpath('tools', name)
- try:
- raw = resource.read_text(encoding='utf-8')
- except FileNotFoundError as error:
- raise SuperDocError(
- 'Unable to load packaged tool artifact.',
- code='TOOLS_ASSET_NOT_FOUND',
- details={'file': name},
- ) from error
- except Exception as error:
- raise SuperDocError(
- 'Unable to read packaged tool artifact.',
- code='TOOLS_ASSET_NOT_FOUND',
- details={'file': name, 'message': str(error)},
- ) from error
-
- try:
- parsed = json.loads(raw)
- except Exception as error:
- raise SuperDocError(
- 'Packaged tool artifact is invalid JSON.',
- code='TOOLS_ASSET_INVALID',
- details={'file': name, 'message': str(error)},
- ) from error
-
- if not isinstance(parsed, dict):
- raise SuperDocError(
- 'Packaged tool artifact root must be an object.',
- code='TOOLS_ASSET_INVALID',
- details={'file': name},
- )
- return cast(Dict[str, Any], parsed)
+def list_tools(provider: ToolProvider, preset: Optional[str] = None) -> List[Dict[str, Any]]:
+ """Return the raw tool array for a provider from a preset (default: legacy).
-
-def get_tool_catalog() -> Dict[str, Any]:
- return _read_json_asset('catalog.json')
-
-
-def list_tools(provider: ToolProvider) -> List[Dict[str, Any]]:
- bundle = _read_json_asset(PROVIDER_FILE[provider])
- tools = bundle.get('tools')
- if not isinstance(tools, list):
+ No cache markers applied. Use :func:`choose_tools` for cache markers and metadata.
+ """
+ if provider not in ('openai', 'anthropic', 'vercel', 'generic'):
raise SuperDocError(
- 'Tool provider bundle is missing tools array.',
- code='TOOLS_ASSET_INVALID',
+ 'provider is required.',
+ code='INVALID_ARGUMENT',
details={'provider': provider},
)
+ result = get_preset(preset).get_tools(provider, cache=False)
+ tools = result.get('tools') if isinstance(result.get('tools'), list) else []
return cast(List[Dict[str, Any]], tools)
def choose_tools(input: ToolChooserInput) -> Dict[str, Any]:
- """Select all intent tools for a specific provider.
-
- Returns all intent tools in the requested provider format.
+ """Select tools for a specific provider from a preset.
Example::
+ # Default — legacy preset.
result = choose_tools({'provider': 'openai'})
+
+ # Pick a specific preset.
+ result = choose_tools({'provider': 'anthropic', 'preset': 'legacy', 'cache': True})
"""
provider = input.get('provider')
if provider not in ('openai', 'anthropic', 'vercel', 'generic'):
- raise SuperDocError('provider is required.', code='INVALID_ARGUMENT', details={'provider': provider})
+ raise SuperDocError(
+ 'provider is required.',
+ code='INVALID_ARGUMENT',
+ details={'provider': provider},
+ )
- bundle = _read_json_asset(PROVIDER_FILE[provider])
- tools = bundle.get('tools') if isinstance(bundle.get('tools'), list) else []
+ # Default only when `preset` is absent. An explicit empty string is passed
+ # through to get_preset() so it raises PRESET_NOT_FOUND, matching Node/MCP
+ # fail-fast behavior. Using `or DEFAULT_PRESET` would silently treat
+ # `preset: ''` as legacy and hide misconfiguration.
+ preset_arg = input.get('preset')
+ preset_id = preset_arg if preset_arg is not None else DEFAULT_PRESET
+ cache_requested = bool(input.get('cache'))
+
+ preset = get_preset(preset_id)
+ result = preset.get_tools(cast(ToolProvider, provider), cache=cache_requested)
+ tools = result.get('tools') if isinstance(result.get('tools'), list) else []
+ cache_strategy = result.get('cacheStrategy', 'disabled')
return {
'tools': tools,
'meta': {
'provider': provider,
- 'toolCount': len(tools),
+ 'preset': preset_id,
+ 'toolCount': len(tools) if isinstance(tools, list) else 0,
+ 'cacheStrategy': cache_strategy,
},
}
-def _resolve_doc_method(document_handle: Any, operation_id: str) -> Any:
- def _snake_case(token: str) -> str:
- token = re.sub(r'([A-Z]+)([A-Z][a-z])', r'\1_\2', token)
- token = re.sub(r'([a-z0-9])([A-Z])', r'\1_\2', token)
- return token.replace('-', '_').lower()
-
- cursor = document_handle
- for token in operation_id.split('.')[1:]:
- candidates = [token]
- snake_token = _snake_case(token)
- if snake_token != token:
- candidates.append(snake_token)
-
- resolved = None
- for candidate in candidates:
- if hasattr(cursor, candidate):
- resolved = getattr(cursor, candidate)
- break
-
- if resolved is None:
- raise SuperDocError(
- 'No SDK doc method found for operation.',
- code='TOOL_DISPATCH_NOT_FOUND',
- details={'operationId': operation_id, 'token': token},
- )
- cursor = resolved
-
- if not callable(cursor):
- raise SuperDocError(
- 'Resolved SDK doc member is not callable.',
- code='TOOL_DISPATCH_NOT_FOUND',
- details={'operationId': operation_id},
- )
-
- return cursor
-
-
def dispatch_superdoc_tool(
document_handle: Any,
tool_name: str,
args: Optional[Dict[str, Any]] = None,
invoke_options: Optional[Dict[str, Any]] = None,
) -> Any:
- """Dispatch a tool call against a bound document handle.
+ """Dispatch a tool call against a bound document handle using the default preset.
- The document handle injects session targeting automatically.
- Tool arguments should not contain doc or sessionId — those are
- stripped if present for backwards compatibility with older tool schemas.
+ The handle injects session targeting automatically; arguments should not
+ contain ``doc`` or ``sessionId`` — those are stripped if present.
"""
- payload = args or {}
- if not isinstance(payload, dict):
- raise SuperDocError('Tool arguments must be an object.', code='INVALID_ARGUMENT', details={'toolName': tool_name})
-
- # Strip doc/sessionId if present — the document handle manages targeting.
- payload = {k: v for k, v in payload.items() if k not in ('doc', 'sessionId')}
-
- def execute(operation_id: str, input_args: Dict[str, Any]) -> Any:
- method = _resolve_doc_method(document_handle, operation_id)
- if inspect.iscoroutinefunction(method):
- raise SuperDocError(
- 'dispatch_superdoc_tool cannot call async methods. Use dispatch_superdoc_tool_async.',
- code='INVALID_ARGUMENT',
- details={'toolName': tool_name, 'operationId': operation_id},
- )
- kwargs = dict(invoke_options or {})
- return method(input_args, **kwargs)
-
- return dispatch_intent_tool(tool_name, payload, execute)
+ return get_preset(DEFAULT_PRESET).dispatch(document_handle, tool_name, args, invoke_options)
async def dispatch_superdoc_tool_async(
@@ -177,55 +121,25 @@ async def dispatch_superdoc_tool_async(
args: Optional[Dict[str, Any]] = None,
invoke_options: Optional[Dict[str, Any]] = None,
) -> Any:
- """Async version of dispatch_superdoc_tool. Dispatches against a bound document handle."""
- payload = args or {}
- if not isinstance(payload, dict):
- raise SuperDocError('Tool arguments must be an object.', code='INVALID_ARGUMENT', details={'toolName': tool_name})
-
- # Strip doc/sessionId if present — the document handle manages targeting.
- payload = {k: v for k, v in payload.items() if k not in ('doc', 'sessionId')}
+ """Async version of :func:`dispatch_superdoc_tool`."""
+ return await get_preset(DEFAULT_PRESET).dispatch_async(
+ document_handle, tool_name, args, invoke_options,
+ )
- def execute(operation_id: str, input_args: Dict[str, Any]) -> Any:
- method = _resolve_doc_method(document_handle, operation_id)
- kwargs = dict(invoke_options or {})
- return method(input_args, **kwargs)
- result = dispatch_intent_tool(tool_name, payload, execute)
- if inspect.isawaitable(result):
- return await result
- return result
+def get_system_prompt(preset: Optional[str] = None) -> str:
+ """Read the packaged SDK system prompt (default preset: legacy).
-
-def get_system_prompt() -> str:
- """Read the bundled SDK system prompt for intent tools.
-
- This prompt includes a persona preamble suitable for embedded LLM usage
- (OpenAI, Anthropic APIs). For MCP server instructions, use
- :func:`get_mcp_prompt` instead.
+ Includes a persona preamble suitable for embedded LLM usage. For MCP
+ server instructions, use :func:`get_mcp_prompt` instead.
"""
- resource = resources.files('superdoc').joinpath('tools', 'system-prompt.md')
- try:
- return resource.read_text(encoding='utf-8')
- except FileNotFoundError as error:
- raise SuperDocError(
- 'System prompt not found.',
- code='TOOLS_ASSET_NOT_FOUND',
- details={'file': 'system-prompt.md'},
- ) from error
+ return get_preset(preset).get_system_prompt()
-def get_mcp_prompt() -> str:
- """Read the bundled MCP system prompt for intent tools.
+def get_mcp_prompt(preset: Optional[str] = None) -> str:
+ """Read the packaged MCP system prompt for intent tools (default preset: legacy).
- This prompt omits the persona preamble and includes session lifecycle
- instructions (open/save/close) suitable for MCP server ``instructions``.
+ Omits the persona preamble and includes session lifecycle instructions
+ (open/save/close) suitable for MCP server ``instructions``.
"""
- resource = resources.files('superdoc').joinpath('tools', 'system-prompt-mcp.md')
- try:
- return resource.read_text(encoding='utf-8')
- except FileNotFoundError as error:
- raise SuperDocError(
- 'MCP system prompt not found.',
- code='TOOLS_ASSET_NOT_FOUND',
- details={'file': 'system-prompt-mcp.md'},
- ) from error
+ return get_preset(preset).get_mcp_prompt()
diff --git a/packages/sdk/langs/python/tests/test_presets.py b/packages/sdk/langs/python/tests/test_presets.py
new file mode 100644
index 0000000000..7178496b37
--- /dev/null
+++ b/packages/sdk/langs/python/tests/test_presets.py
@@ -0,0 +1,152 @@
+"""Preset registry tests (Python SDK) — mirrors Node SDK presets.test.ts."""
+
+import os
+import sys
+
+import pytest
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from superdoc import ( # noqa: E402
+ DEFAULT_PRESET,
+ SuperDocError,
+ choose_tools,
+ get_preset,
+ get_mcp_prompt,
+ get_system_prompt,
+ get_tool_catalog,
+ list_presets,
+ list_tools,
+)
+
+
+PROVIDERS = ('openai', 'anthropic', 'vercel', 'generic')
+
+
+# ---------------------------------------------------------------------------
+# Registry
+# ---------------------------------------------------------------------------
+
+def test_default_preset_is_legacy():
+ assert DEFAULT_PRESET == 'legacy'
+
+
+def test_list_presets_includes_legacy():
+ presets = list_presets()
+ assert 'legacy' in presets
+
+
+def test_get_preset_no_arg_returns_legacy():
+ preset = get_preset()
+ assert preset.id == 'legacy'
+
+
+def test_get_preset_explicit_returns_legacy():
+ preset = get_preset('legacy')
+ assert preset.id == 'legacy'
+ assert preset.description
+ assert preset.supports_cache_control is True
+
+
+def test_get_preset_nonexistent_raises_preset_not_found():
+ with pytest.raises(SuperDocError) as excinfo:
+ get_preset('nonexistent-preset')
+ assert excinfo.value.code == 'PRESET_NOT_FOUND'
+ assert 'nonexistent-preset' in str(excinfo.value)
+ assert excinfo.value.details['id'] == 'nonexistent-preset'
+ assert 'legacy' in excinfo.value.details['availablePresets']
+
+
+def test_get_preset_empty_string_raises_preset_not_found():
+ """Empty string is NOT the default — it must fail fast like Node."""
+ with pytest.raises(SuperDocError) as excinfo:
+ get_preset('')
+ assert excinfo.value.code == 'PRESET_NOT_FOUND'
+
+
+def test_choose_tools_empty_preset_raises_preset_not_found():
+ """Cross-lang parity with Node: chooseTools({preset: ''}) must throw, not
+ silently use legacy."""
+ with pytest.raises(SuperDocError) as excinfo:
+ choose_tools({'provider': 'openai', 'preset': ''})
+ assert excinfo.value.code == 'PRESET_NOT_FOUND'
+
+
+# ---------------------------------------------------------------------------
+# choose_tools — default preset equivalence
+# ---------------------------------------------------------------------------
+
+@pytest.mark.parametrize('provider', PROVIDERS)
+def test_choose_tools_omit_preset_equals_legacy(provider):
+ implicit = choose_tools({'provider': provider})
+ explicit = choose_tools({'provider': provider, 'preset': 'legacy'})
+ assert implicit['tools'] == explicit['tools']
+ assert implicit['meta']['toolCount'] == explicit['meta']['toolCount']
+ assert implicit['meta']['provider'] == explicit['meta']['provider']
+ assert implicit['meta']['cacheStrategy'] == explicit['meta']['cacheStrategy']
+ assert implicit['meta']['preset'] == 'legacy'
+ assert explicit['meta']['preset'] == 'legacy'
+
+
+def test_choose_tools_nonexistent_preset_raises():
+ with pytest.raises(SuperDocError) as excinfo:
+ choose_tools({'provider': 'openai', 'preset': 'nonexistent-preset'})
+ assert excinfo.value.code == 'PRESET_NOT_FOUND'
+
+
+def test_choose_tools_meta_preset_field_present():
+ result = choose_tools({'provider': 'openai'})
+ assert result['meta']['preset'] == 'legacy'
+
+
+# ---------------------------------------------------------------------------
+# Catalog + listings — default preset equivalence
+# ---------------------------------------------------------------------------
+
+def test_get_tool_catalog_default_equals_legacy():
+ implicit = get_tool_catalog()
+ explicit = get_tool_catalog('legacy')
+ assert implicit == explicit
+
+
+@pytest.mark.parametrize('provider', PROVIDERS)
+def test_list_tools_default_equals_legacy(provider):
+ implicit = list_tools(provider)
+ explicit = list_tools(provider, 'legacy')
+ assert implicit == explicit
+
+
+def test_get_tool_catalog_nonexistent_preset_raises():
+ with pytest.raises(SuperDocError) as excinfo:
+ get_tool_catalog('nonexistent-preset')
+ assert excinfo.value.code == 'PRESET_NOT_FOUND'
+
+
+# ---------------------------------------------------------------------------
+# System prompts — default preset equivalence
+# ---------------------------------------------------------------------------
+
+def test_get_system_prompt_default_equals_legacy():
+ assert get_system_prompt() == get_system_prompt('legacy')
+
+
+def test_get_mcp_prompt_default_equals_legacy():
+ assert get_mcp_prompt() == get_mcp_prompt('legacy')
+
+
+# ---------------------------------------------------------------------------
+# Direct preset access
+# ---------------------------------------------------------------------------
+
+def test_preset_get_catalog_matches_top_level():
+ direct = get_preset('legacy').get_catalog()
+ via_top_level = get_tool_catalog()
+ assert direct == via_top_level
+
+
+@pytest.mark.parametrize('provider', PROVIDERS)
+def test_preset_get_tools_matches_choose_tools(provider):
+ direct = get_preset('legacy').get_tools(provider)
+ via_top_level = choose_tools({'provider': provider})
+ assert direct['tools'] == via_top_level['tools']
+ assert direct['cacheStrategy'] == via_top_level['meta']['cacheStrategy']
diff --git a/packages/super-editor/package.json b/packages/super-editor/package.json
index d5ce53bfa6..d7b820bbc2 100644
--- a/packages/super-editor/package.json
+++ b/packages/super-editor/package.json
@@ -103,6 +103,7 @@
"dev": "vite",
"build": "vite build",
"build:watch": "vite build --watch",
+ "extract:docx": "tsx src/editors/v1/core/layout-adapter/scripts/extract-pm-json.mjs",
"types:check": "tsc --noEmit",
"types:build": "tsc -p tsconfig.build.json",
"test": "vitest",
@@ -118,11 +119,11 @@
"@superdoc/contracts": "workspace:*",
"@superdoc/dom-contract": "workspace:*",
"@superdoc/document-api": "workspace:*",
+ "@superdoc/font-utils": "workspace:*",
"@superdoc/layout-bridge": "workspace:*",
"@superdoc/layout-resolved": "workspace:*",
"@superdoc/measuring-dom": "workspace:*",
"@superdoc/painter-dom": "workspace:*",
- "@superdoc/pm-adapter": "workspace:*",
"@superdoc/preset-geometry": "workspace:*",
"@superdoc/style-engine": "workspace:*",
"@superdoc/url-validation": "workspace:*",
@@ -171,6 +172,7 @@
},
"devDependencies": {
"@floating-ui/dom": "catalog:",
+ "@superdoc/layout-engine": "workspace:*",
"@testing-library/react": "catalog:",
"@types/mdast": "catalog:",
"@types/react": "catalog:",
diff --git a/packages/super-editor/src/editors/v1/assets/styles/elements/ai.css b/packages/super-editor/src/editors/v1/assets/styles/elements/ai.css
index b4cabe4eeb..b7d42effe2 100644
--- a/packages/super-editor/src/editors/v1/assets/styles/elements/ai.css
+++ b/packages/super-editor/src/editors/v1/assets/styles/elements/ai.css
@@ -1,16 +1,16 @@
/* Custom toolbar styling */
/* AI button icon styling with gradient */
-.super-editor .toolbar-icon__icon--ai {
+.super-editor .sd-toolbar-icon__icon--ai {
position: relative;
z-index: 1;
}
-.super-editor .toolbar-icon__icon--ai svg {
+.super-editor .sd-toolbar-icon__icon--ai svg {
fill: transparent;
}
-.super-editor .toolbar-icon__icon--ai::before {
+.super-editor .sd-toolbar-icon__icon--ai::before {
content: '';
position: absolute;
top: 0;
@@ -33,7 +33,7 @@
transition: filter 0.2s ease;
}
-.super-editor .toolbar-icon__icon--ai:hover::before {
+.super-editor .sd-toolbar-icon__icon--ai:hover::before {
filter: brightness(1.3);
}
diff --git a/packages/super-editor/src/editors/v1/components/SuperEditor.vue b/packages/super-editor/src/editors/v1/components/SuperEditor.vue
index 9ef3822539..84c3827a6a 100644
--- a/packages/super-editor/src/editors/v1/components/SuperEditor.vue
+++ b/packages/super-editor/src/editors/v1/components/SuperEditor.vue
@@ -1293,6 +1293,7 @@ onBeforeUnmount(() => {
class="super-editor-container"
:class="{ 'web-layout': isWebLayout, contained: isContained }"
:style="containerStyle"
+ data-sd-part="editor-root"
>
{