# Deterministic layout and repair

This work implements the [ecosystem objective](ecosystem-objective-2026-09-09.md) in reviewable increments. It does not introduce a model, account, key, network or paid-service dependency into OPF. Proprietary applications remain optional compatibility-test environments.

## Current checkpoint — chart visibility and workbook data preservation

The [integration checkpoint](shared-metric-integration.md) now shares an inherited series-to-panel contrast rule and resolves chart panel/text colors in SVG and PPTX. Actual workbook category headings survive supported import/export, including current edits, Unicode and whitespace. [Separate evidence](../evidence/chart-colors-workbook/README.md) records passing core/PPTX/browser checks on Node 20/24, reviewed chart raster changes and 942 remaining conservative contrast findings. Geometry and authored content were preserved; chart semantics, palette identity, internal label layout and general theme resolution still require shared-model work.

Real PowerPoint verification of these chart changes remains open because the current COM connection failed before opening the fixture. Existing metric native tab/portrait-ink findings and the unpromoted corpus gate remain visible. No release or public deployment advances. Continue native recovery, corpus quality and coordinated source/candidate CI/review within the full deterministic repair/Auto arrange/font objective.

## Previous checkpoint — table colors and measured gallery contrast findings

The [integration checkpoint](shared-metric-integration.md) now shares inherited table text colors across SVG and editable PPTX and corrects authored colors in 96 gallery decks without altering content or geometry. Both supported Node runtimes pass the core/PPTX checks and real PowerPoint table color/save/reopen assertions. [New evidence](../evidence/table-colors-gallery-contrast/README.md) keeps the renderer golden gate, 656 changed raster reviews and 962 conservative contrast findings open. An actual browser glyph-mask counterexample separates an unrelated panel border from metric text ink; it does not dismiss other findings. Confirmed dark-chart label/background mismatch and unresolved placeholders remain quality work.

No baseline, release or public deployment advances. Existing native metric tab-position and portrait-label pixel counterexamples remain open. Continue quality fixes, coordinated source/candidate CI and PR review before release preparation; the broader deterministic repair/Auto arrange/font objective remains active.

## Previous checkpoint — metric native anchors and visual corpus review

The [metric integration checkpoint](shared-metric-integration.md) now includes a native paragraph-anchor fix and isolated field raster checks. Both Node 20/24 runs preserve 144 original/saved/edited imports from 48 real PowerPoint fixtures, with no character-bound overrun or inter-field pixel-mask collision. Eight tab-position outliers and one raster-edge outlier keep native comparisons failing. The affected PPTX checks, actual metric editor browser workflows and remaining post-golden renderer commands pass separately.

All 85 changed corpus slides were visually reviewed; 40 fictional gallery metrics and their generator were corrected to consistent units/deltas. The revised corpus validates, but pale/gradient contrast and compact hierarchy remain quality findings. No baseline, package, registry dependency or public deployment has advanced. [Separate new evidence](../evidence/shared-metric-native-anchor/summary.json) preserves the previous checkpoint and its failures. Continue resolving these gates before coordinated CI/review and release preparation. The full deterministic repair/Auto arrange/font objective remains active.

## Previous checkpoint — metric consumers and source recovery; raster gates open

The [metric integration checkpoint](shared-metric-integration.md) includes accepted alignment/line origins, SVG/native export, guarded source/type recovery and actual editor/undo/pagination/export workflows. Core passes 466 tests on Node 20/24; focused consumer and browser checks pass. Real PowerPoint preserves tested fields/types in 108 original/saved/edited imports. Corpus review remains open for 85 changed rasters, and the native raster gate fails on one portrait/right fixture. Nine native advance-bound differences are recorded separately. No release or registry/public dependency changed. Continue this source branch and resolve its gates before release preparation; the larger deterministic repair/font objective remains active.

## Previous checkpoint — metric primitive merged; composition/pagination integration underway

Core PR #58 merged as `5cfc944ee7709b54bc2d1e7192cd86b7a52d6cb7`, identical to reviewed `d484a32a910cd9f0c729bcb9e5dc57f1e1cdfaa6`, after complete Node 20/24 coordinator/core, Windows/macOS CLI and Bugbot passed. Continue `codex/shared-metric-integration-20260910`: the [initial source checkpoint](shared-metric-integration.md) consumes complete metrics in composition/scoring (`grid-score-v4`) and atomic pagination. All 464 core tests and existing preservation suites pass on both supported Node runtimes. Renderer/PPTX/editor changes, actual integrated browser/native gates and review remain open. No package has been bumped or published.

## Previous checkpoint — standalone metric allocation verified; consumer integration next

The [shared metric checkpoint](shared-metric-layout.md) records an unreleased standalone `layoutMetric` API on `codex/shared-metric-layout-20260910`. Complete metadata and numeric/scalar source types, proportional-font line/segment mappings, compact inline/stacked allocation and scaled floors are implemented. Both supported Node runtimes pass 458 core tests and the existing preservation suites. Sixty real-font cases include 50 fits, six irreducible strict failures and four explicit missing-glyph cases. Fifty controlled browser cases pass exact source/advance/segment checks offline; their evidence is byte-identical across Node 20.20.2/24.20.0. Glyph overhangs remain recorded separately. Full CI/review, composition/pagination integration and actual editor/PPTX/native workflows remain gates. Do not mark metric coverage complete or bump/release versions yet.

## Previous checkpoint — published shared code complete; metric internals next

Core 0.9.0, CLI 0.7.0, renderer/PPTX 0.7.0 and editor 0.6.0 are published and adopted on all three public sites. Core PR #57 merged the [public evidence](../evidence/shared-code-public-adoption/summary.json) as `115f3e915b9b36f0518e55ac6a4f8014ac7114cc`, after complete Node 20/24 coordinator `34456846499`, core CI `34456846509` and Bugbot passed. The 21 public workflows, exact font/editor/download assets and native PowerPoint public-Author fixture supplement the earlier registry matrices. The full repair/Auto arrange/font objective remains open.

Continue `codex/shared-metric-layout-20260910`. The [published metric fixtures](../evidence/metric-layout-gap-2026-09-10.fixtures.json) reproduce identical results on [Node 20](../evidence/metric-layout-gap-2026-09-10.node20.json) and [Node 24](../evidence/metric-layout-gap-2026-09-10.node24.json):

- `value: 42`, `unit: "ms"`, `delta: 0` and `trend: "flat"` serialize only the value and label in both SVG and native PPTX XML. The input JSON remains unchanged.
- A metric label uses 23 reference pixels despite an explicit `minFontSize: 32`.
- A long label passes composition with no diagnostic, then both renderer and converter reject strict overflow. Composition explanations correctly list the metric among unmeasured payloads.

Reproduce with `node scripts/probe-metric-layout-gap.mjs <verified-registry-consumer> [output-prefix]`. The helper verifies all 555 installed core/renderer/converter files against the committed complete-set registry archive report and records actual open-font hashes. Its assertions intentionally document these versions' defects; they are not acceptable behavior for the replacement implementation. These are serialized output and font-size observations, not new browser glyph or native raster-equivalence evidence.

The next bounded implementation is a shared metric measurement/placement primitive, followed by composition/scoring/pagination and consumer integration. Preserve scalar types and every provided field, including zero; distinguish source content from generated display separators. Return requested/resolved styles, complete part boxes and source mappings. Allocate available space before shrinking, enforce the selected floor even above nominal label size, reject irreducible parts under strict policy, and reuse accepted geometry in browser and native export. Cover wide/portrait dimensions, empty and long metadata, nested strict floors, numeric zero/negative values and controlled native edit/reimport before claiming the metric gap is closed. Do not mark metric coverage complete or release a new version from an unintegrated primitive.

## Previous source checkpoint — shared code integration

The shared code integration is merged in core PR #54 (`8d9c9c80b788bbdc80e18ad2b6468f07b2e2321d`), after complete Node 20/24 coordinator/core CI, Windows/macOS CLI and review passed. It consumes complete code measurement in composition/pagination and identifies changed scoring as `grid-score-v3`. All 448 core tests and preservation suites pass on both Node versions. Coordinated consumers and fresh candidate tarballs pass actual offline code editing/export/reimport; real Windows PowerPoint preserves code/metadata through 24 original/saved/edited imports. Code characters that XML cannot represent reject explicitly, without changing schema-valid source strings. [Integration details and evidence](shared-code-integration.md) distinguish source, installed-browser and native scopes. [Release preparation](shared-code-release.md) targets core 0.9.0/CLI 0.7.0 before consumers and public adoption; publication and the full repair/Auto arrange/font objective remain unfinished.

Core 0.8.0, CLI 0.6.0, renderer/PPTX 0.6.0 and editor 0.5.0 are published and verified together through merged core PR #51. `quote-flow-v1` and `grid-score-v2` measure both quote body and footer, reuse accepted geometry in preview/export, and persist pagination readability without dropping irreducible empty-body content. The [release checkpoint](shared-quote-release.md) records exact commits and fresh source/tarball/registry, browser and Windows PowerPoint evidence. The complete deterministic repair/Auto arrange/font objective is still open. The sections below preserve the earlier increments and their evidence boundaries.

The next implementation milestone is shared code-language/body measurement. The new package set still reproduces a language label measuring 4200.68 pixels against 1128.8 available with no overflow diagnostic. A second schema-valid fixture shows that the serialized SVG omits `filename`, removes indentation/trailing whitespace and collapses even the two spaces inside a string literal. The source JSON remains unchanged. Node 20.20.2 and 24.20.0 produce identical [registry/font/source-bound reports](../evidence/code-layout-gap-2026-09-09.json) from [these fixtures](../evidence/code-layout-gap-2026-09-09.opf.json). Reproduce with `node scripts/probe-code-layout-gap.mjs <actual-registry-consumer> [output-prefix]`; the helper deliberately asserts these published defects, not acceptable future behavior. It requires core 0.8.0/renderer 0.6.0 and rejects source links/loaders. This is serialized SVG/advance evidence, not a new browser glyph or native export result.

The standalone candidate `layoutCode` API now implements complete filename/language/body allocation, exact whitespace and CRLF source ranges, measured tab/text segments, requested/resolved styles, floors and actionable failures. It leaves the composition/pagination/renderer/converter paths unchanged until integration. Nine focused tests plus all 442 core tests and existing preservation suites pass on Node 20.20.2 and 24.20.0. Eight real-font wide/portrait scenarios produce identical [source/runtime/font-bound reports](../evidence/shared-code-layout-2026-09-09.json). A controlled SVG harness preserves literal text and matches eight cases' accepted advances and segment starts/ends within 0.1 reference pixel using exact Cousine regular/bold bytes; [browser evidence](../evidence/shared-code-browser-2026-09-09.json) is identical across the two Node runtimes on Edge 152. This harness is separate from integrated OPF rendering and native export.

The browser probe caught CSS-only SVG tabs advancing by one space despite `tab-size: 4`. Accepted code lines therefore include explicit segment positions and widths. Integrating SVG should consume those positions and preserve tab text (the controlled harness uses positioned spans and an explicit tab `textLength`); native export must use matching tab stops or other verified native placement. Do not introduce a second measurement pass or convert literal tabs into stored spaces. Verify exact source/filename/language and whitespace handling, ancestor strict-fit checks, candidate scoring, accepted-cell rounding, pagination and actual browser/native edit/export/reimport behavior. Broader shaping/bidi and font mappings remain separate gates. Review the shared code integration before extending metric/timeline/chart internals and the repair operation below. Public deployment adoption does not establish that these remaining layout gaps are fixed.

Initial coordinator `34433357130` passed the source/tarball/registry suites and eight model cases, but both Linux browser jobs caught default hinting rounding advances to whole pixels (for example, 11 instead of 10.8017578125). The controlled harness now requests `text-rendering="geometricPrecision"` without changing its 0.1-pixel tolerance and preserves observations even on failure. Renewed Edge runs pass on both Node versions; Linux CI must pass before merging the primitive. Integration must carry the explicit rendering mode and verify actual output rather than assuming default platform metrics agree.

## Implemented first increment: explain existing selection

Branch `codex/layout-repair-20260909` adds opt-in `composeSlide(slide, {explain:true, ...resolvedOptions})`. The result reports the versioned `grid-score-v1` candidate costs, selected column count, fixed-mode/region reasons, measurement-provider status and incomplete payload coverage. Strict overflow errors retain the same explanation. Core 0.7.0 is already published and does not include this API; a future release is required.

The geometry and selection algorithm remain unchanged. Costs expose current heuristics; they are not a polished-layout guarantee. See [the exact rules and scope](../dynamic-composition.md#explain-automatic-selection-core-080).

Local Windows verification on Node 20 and 24: 417 core tests, composition/nesting/pagination/data/rich-text/list suites, 11 CLI unit tests and 69 command checks pass. Six new tests cover geometry/content/measurement-call preservation across dimensions and modes, component cost accounting, configured weights/regions, candidate caps, reserved slots, tied scores, unsupported payload paths and strict error explanations. Public root and focused declaration imports compile. Typecheck, lint (existing warnings), 126 example files, schema/breaking gates, six portable skills with 17 helper checks and dependency audit pass. The root dependency tree was refreshed from the merged lockfile after an initial stale generator-15 installation caused the generator-16 type-contract test to fail; the locked rerun passes. Windows still skips the file-symlink CLI case when privileges are unavailable; no OS setting was changed.

## Published payload-fit gaps

The registry-only probe `node scripts/probe-payload-fit-gaps.mjs <registry-consumer> [output-prefix]` reproduces two schema-valid counterexamples with installed core 0.7.0 and renderer 0.5.1. The [source fixture](../evidence/payload-fit-gaps-2026-09-09.opf.json) and [report](../evidence/payload-fit-gaps-2026-09-09.json) record package versions/registry lock integrities and exact font/source hashes. They use bundled Carlito/Cousine advances; neither browser glyph bounds nor native raster equivalence is asserted.

- A short quote with a long attribution receives no composition diagnostic, but the renderer reports text overflow in the footer.
- A long code language label measures 4200.68 pixels against 1128.8 available, but neither composition nor renderer reports overflow. Core estimates the code body without the real internal insets or label; the unreleased explanation now correctly lists code among incomplete payloads.

The probe deliberately asserts the published gaps. It is a historical reproduction command, not a claim that overflowing output is acceptable or a general quality gate for a future corrected release. Use the preserved fixture as an acceptance input for shared quote/code placement and diagnostics. Keep complete code coverage marked unmeasured until its label, body and internal constraints are actually shared. The coverage-only correction preserves geometry and passes all six explanation tests on Node 20/24 and all 420 core tests plus composition/pagination/data/rich-text/list suites on Node 24.

## Earlier quote checkpoints and next acceptance criteria

The following standalone checkpoints are historical; the quote integration is now published as recorded above. Their source-only evidence must not be confused with the later actual registry and native evidence.

The standalone API below is merged in core PR #46 (`6d8df02940deec8f1fa89192d10576d6048de341`) after all core/coordinated/Windows/macOS checks and review passed. Continue the [exact consumer integration plan](shared-quote-integration.md) on `codex/shared-quote-integration-20260909`; it records the important strict-path, rounding, source-mapping and measurement-reuse boundaries. The primitive remains unreleased and is not yet connected to the other engines.

Branch `codex/shared-quote-layout-20260909` starts the shared-measurement increment with an additive standalone `layoutQuote` API. It returns body/footer available boxes, complete display text, source ranges, requested/resolved styles, fits and reasoned diagnostics. It keeps the current 18-pixel insets and footer reservation for compatible readable cases, raises nominal text sizes when an explicit readability floor requires it, and leaves invalid available dimensions visible without inventing a one-pixel fit. Text-fit, out-of-cell and conservative line-box overlap failures can reject strictly. These line boxes do not establish glyph-outline or native raster equivalence.

This API alone does not connect the three engines or repair layouts. Existing `composeSlide`, preview and PowerPoint output remain unchanged and still report quote/code as incomplete coverage. Next, consume the same result in candidate scoring, accepted geometry, rendering and native export, with no independent re-fitting after acceptance; then add code internals and dynamic repair/pagination. No publication is warranted from the standalone primitive alone.

Candidate verification: all 426 core tests and composition/nesting/pagination/data/rich-text/list suites pass on Windows Node 20/24. Six quote tests cover legacy readable geometry, immutable source/mappings (including Unicode and whitespace), requested/resolved styles, strict failure, line-box overlap, invalid internal dimensions and scaled readability floors. Public root/focused declarations compile. `node scripts/test-quote-layout-geometry.mjs <registry-consumer> [report.json]` adds four actual-font wide/portrait cases against the release-plan renderer; both supported runtimes produce the same [source/runtime/font-bound report](../evidence/shared-quote-layout-2026-09-09.json). The first portrait fixture used wrong dimension fields and was rejected by the exact-dimension assertion; the final fixture uses schema-valid `widthInches`/`heightInches` and validates before measurement. Coordinated CI now executes this check after installing actual registry packages. Review and complete CI remain gates on this candidate.

1. Share payload-internal measurement and placement between core composition, renderer and converter. Start with quote body/footer and code language/body, then metric value/labels, timeline annotations and chart labels. Reuse complete payload geometry in scoring, preview and native export; do not copy formulas into another subsystem. Diagnose complete internal overflow/collisions. Preserve requested/resolved font paths and state which measurements are estimates. Add wide/portrait, oversized and mixed-style fixtures before changing selection behavior.
2. Build a bounded repair operation that generates candidate arrangements and weight allocations, enforces an explicit readability policy and evaluates measurable hierarchy, balance, whitespace, media proportions and density. Existing manual modes/weights/regions need explicit preservation or user-authorized relaxation. Include the current arrangement as a stability preference; avoid unnecessary movement after small edits. Report candidate costs, rejected constraints, reasons and the measurement scope. No content deletion, truncation, summarization or implicit undersizing is allowed.
3. When arrangement cannot fit, invoke explicit pagination only under the caller's policy. Return ordinary accepted slides, complete source mappings and diagnostics, with all-or-nothing failure for irreducible content. Preview and export must consume those same slides. Headings, rich runs, metadata, notes and every source character require preservation tests.
4. Expose one guarded operation through APIs, CLI and the six existing skills as appropriate, and add a canvas **Auto arrange** draft preview with cancel/commit and one undo step. Stale drafts must reject safely. Headless callers and human controls must use the same underlying operation and font provider.
5. Establish layout quality evidence beyond regression hashes: representative and unseen content, varied dimensions/density, malformed and valid-but-poor layouts, scripts/fonts, nested groups and impossible constraints. Track readability and visual coherence separately from geometry stability. Execute real browser edit/undo/export/reimport and native PowerPoint checks on the accepted documents. Missing macOS PowerPoint/Keynote evidence stays explicit.

## Font work continues alongside layout

The [font roadmap](font-roadmap.md) and [fidelity evidence](../font-fidelity.md) remain required. Exact font provenance/hashes, variant-specific substitution, shaping/fallback/bidirectional coverage, line breaks and native slide raster comparisons must be evaluated separately. The current Carlito Arabic error is an observed coverage gap, not a reason to remove multilingual source content. Essential bundled fonts must remain offline; proprietary reference fonts must not be redistributed. Matching widths, readable editable text or unchanged image hashes do not establish pixel equivalence.