FA: format audit for 0.14 (FA-01…FA-17)

[michaeljgrimm]

Depends-On: OpenPresentation/opf-render#151
Depends-On: OpenPresentation/opf-pptx#197
Depends-On: OpenPresentation/opf-editor#112

One integration PR for the whole format audit (FA-01 to FA-17), shipping together in breaking 0.14.0. Each item is merged with git merge --no-ff in the program's order (C:\opf-work\fa-program\integration-branches.md), then one regeneration pass.

Items

Item	Ref merged	Original core PR
FA-03 chart-type and audience catalogs	origin e0f09fbe	#414
FA-01 layout records, content-kind vocabulary	origin cccb1e25	#409
FA-02 narrative pointer	origin acfb922e	#412
FA-07 validation tightening, dead keys	origin 90a25071	#413
FA-04 built-in variables	origin fe2fa4e5	#411
FA-06 metric sentiment	origin daa744b1	#415
FA-09 chart alt	origin f9d3d7d5	#410
FA-08 CLI hidden slides, file names	origin 729c0e55	#417
FA-05 preview color roles	origin 917adb2a	#416
FA-12 quote role and photo	origin a03a14eb	#420
FA-14 chart highlight	origin 76bb92ef	#421
FA-11 timeline status	local 696fa017 (native-verified fix, ahead of origin)	#419
FA-13 conveniences (code highlight, inline code, lang, text watermark, aspect presets)	local e6ee1722	none (local only)
FA-15 combo charts	local 6fb2e32d (stacked on FA-03)	none (local only)
FA-17 layout design applied	origin 8ef4c239 (stacked on FA-01)	#422
FA-10 rich headings and quote text	local 366ca5af	none (local only)
FA-16 catalog content	local 317a9d00 (stacked on FA-01)	none (local only)

No item was left out. main is merged on top twice (#427, then #404 and RR-56 #406 YAML); the RR-56 merge conflicted only in docs/markdown.md (main's numbered-list wording, FA-12's quote role/photo wording) and the CLI usage (FA-08 --include-hidden beside RR-56 --format).

Resolved by hand

Generated files (schema/catalog references, docs/audit.md, catalog index.json/manifest.json hashes, golden fixture JSON, ecosystem.lock.json golden entry, gallery trackers) took one side and were regenerated below. Source conflicts, keeping both items' intent:

• spec/schemas/opf.schema.json: color-scheme roles keep FA-07's $ref HexColor with FA-05's descriptions; Chart has FA-09 alt and FA-14 highlight side by side; chart type takes FA-15's description and combo example; Watermark is required: [opacity] plus oneOf [{required:[src]},{required:[text]}] (FA-07 + FA-13), with FA-07's src wording and the string/Asset default-opacity sentence; FontScheme.code stays FA-07's family string with FA-13's inline-code wording (also in font-scheme.schema.json); design.watermark mentions both forms; Quote drops "The text is a plain string" (FA-12) because FA-10 makes it string | TextRun[]; FA-14's highlight description now lists combo among the constructs that drop it (core chartOptionSupport gives combo no highlight support).
• spec/schemas/layout.schema.json: FA-01's kind description, plus FA-06's metric sentiment.
• composition.ts: layoutQuote combines FA-12 (role, photo, photo-fit, Selection) with FA-10 (rich TextRun[] body, heightOf), including the photo-overlap check through heightOf; ComposeSlideOptions.presentation keeps FA-04 speaker and FA-17's design keys; exports keep FA-15 ChartComboSeries, FA-17 design hints and FA-01 layoutContent.
• audit-design.ts: FA-07 and FA-05 both made background colors ColorRefs; FA-05's backgroundColorRef/resolveColorRoles version is kept and FA-07's now-unused BackgroundColor helper removed.
• chart-options.ts: FA-14 highlight and FA-15 combo/secondary axis together. lint.ts/validator.ts/opf-inspect skill: data warning codes are FA-07's set (no chart-data-source-unresolved) plus FA-14 chart-highlight-adapted and FA-13 code-highlight codes.
• audit-rules-a11y.ts: FA-09 chart-alt rule with FA-10's rich-subtitle test; FA-12 quote-photo alt kind next to FA-09's chart kind.
• pagination.ts: FA-13 code-highlight slicing plus FA-10 rich quote slicing. convert/content.ts: FA-12 role/photo loss plus FA-10 rich quote runs. markdown/canon.ts: FA-09 alt without FA-07's removed src data source.
• examples/technical/chart-data-sources.opf.json: FA-07's removal of the data-source slides.
• Docs prose (markdown.md, content-payloads.md, conversions.md, llm-authoring.md, dynamic-composition.md, chart-options.md, design-resolution.md, opf-author content reference, scripts/fixtures/README.md): every item's sentences kept; docs/markdown.md no longer says a chart fence takes a src data source.
• script-fonts.test.mjs: FA-07 app: 'powerpoint' with FA-16 language ids.
• Cross-item tests: FA-13's "a code span in a title keeps its backticks" now expects a code run (FA-10 keeps title formatting, which is the later item's behavior); FA-07's "FontScheme.code names code blocks only" now expects FA-13's inline code runs; the Watermark description keeps FA-07's "fixed frame" sentence; RR-56's YAML example round trip counts 127 decks (FA-14's chart-highlight).

Cross-item fix: table banding on dark themes

Commit "FA-05: table banding stays visible on dark themes". The editor's banded rows used the background role, which FA-05 made the slide background; on a theme whose background is the dark surface (minimal: dark2) the bands vanished. New ColorRef role surfaceAlt, derived in core by surfaceAltColor(surface, text) (surface mixed 10% towards the text, further until 1.1:1 against the surface while the text keeps 4.5:1, else away from the text). resolveColorRoles returns it and resolveColorRef("surfaceAlt") derives it from the surface and text roles both engines already pass, so preview and PPTX agree with no engine change (checked: minimal rows #011842 / bands #1A2F55 in SVG and PPTX; classic #F0F0F0 / #D8D8D8). New exports: surfaceAltColor, SURFACE_ALT_MIX, SURFACE_ALT_MIN_CONTRAST. Test: test/surface-alt.test.mjs (minimal and classic, every catalog scheme on its default, dark1 and dark2 backgrounds). The editor's BAND_FILL must become surfaceAlt (opf-editor#112). No example deck uses banding, so no golden change.

Regeneration

node scripts/generate-schema-docs.mjs; node scripts/sync-gallery-catalog.mjs --rehash --match-gallery (font-schemes is a mirrored kind whose records FA-07/FA-16 changed); pnpm exec biome check --write (kept only in files this PR changes; main is not biome-clean elsewhere); pnpm build; node scripts/build-audit-docs.mjs; pnpm build:gallery-tracker (stale because FA-13 adds the 1:1, 4:5 and 9:16 presets).

Tests

Local runs on Windows, Node 24, at the head:

• pnpm typecheck is clean.
• pnpm test passes: every package and CLI test, and all root checks, including check:registry-golden against the transitional lock golden below.
• pnpm test:ecosystem passes against the linked sibling integration worktrees.
• opf-render#151's test/golden.mjs with the FA renderer passes against opf-examples-png.fa-0-14.sha256.json: 807 slides, 127 decks.

Golden: two fixtures (the release supervisor's design)

The lock's golden means what the locked renderer renders core's examples to. Main's locked renderer (opf-render 759017e) predates FA, so this PR carries two fixtures:

1. scripts/fixtures/opf-examples-png.fa-0-14-locked-render.sha256.json is TRANSITIONAL, and the lock selects it until the roll. It was produced on Linux by regenerate-core-golden.yml dry run 37554992751: the guard reproduced main byte for byte, then it rendered this branch with the locked renderer. 59 slides in 48 decks move, because the old renderer draws the renamed chart type ids the old way (40+ gallery chart slides at v0.2.0 release tracking: packed-package smoke #2 and Release @openpresentation/opf 0.3.0 #6) and ignores FA-05's text role. With this fixture, this PR's merge-group run checks exactly what main will render. It is deleted after the roll.

2. scripts/fixtures/opf-examples-png.fa-0-14.sha256.json is the true FA set, rendered with the FA renderer (opf-render#151) on this core using the opf#367 method:

   • Guard first: main, 805 slides in 126 decks, with the locked renderer, reproduced main's fixture byte for byte.
   • The candidate was rendered twice, and the two runs were identical (807 slides, 127 decks).
   • opf-render#151 selects it with golden-override in its ci.yml, so its own CI, with Depends-On this PR, verifies it on Linux. The roller adopts it as the lock's golden.

   The true set moves 22 slides in 15 decks against RR-20 (16 changed, 4 added, 2 removed):

Slides	Item	Reason
technical/design-backgrounds #0–#4	FA-05	One color-role resolution: the deck's text role now applies.
technical/chart-highlight #0–#2 (added)	FA-14	New example deck.
technical/chart-type-sampler #2 (added)	FA-15	New combo-chart slide.
technical/chart-data-sources #1–#2 (removed)	FA-07	ChartDataSource removed.
technical/asset-source-forms #3	FA-07	The asset-backed chart is now inline rows ("Pipeline Chart").
10 gallery decks at #2: compliance-readiness-review, engineering-capacity-planning, supplier-risk-heatmap, video-demo-sales-narrative, workforce-pathway-partnership, recycling-participation-campaign, wildfire-evacuation-preparedness, battery-line-supplier-readiness, boutique-hotel-revenue-recovery, manager-training-deck	FA-07 (+FA-03)	data.src replaced by inline rows. Where the deck used a removed alias, the clean id applies (dumbbell and dot-plot become scatter, canada becomes world).

The RR-20 opf-examples-png.example-decks.sha256.json is restored to main's bytes and kept in RETAINED_CORE_GOLDENS for the published core 0.13.0. The intermediate FA-03 chart-ids and FA-15 combo-chart fixtures are removed.

Tooling, so that the roller adopts a core fixture:

• scripts/ecosystem-roll.mjs accepts a renderer golden-override that names opf/scripts/fixtures/<name>.sha256.json. The path must pass isSafeRelativePath, and plan() fails the roll if the fixture is missing at the rolled core SHA.
• The lock and its provenance record "golden adopted from opf-render golden-override (core fixture)".
• The tests are in scripts/ecosystem-roll.test.mjs.
• opf-render#151's pin test accepts that override form.

Landing sequence

1. This PR goes through the merge queue. Its merge-group run checks the transitional fixture with the locked renderer.
2. opf-render#151 and opf-pptx#197 merge next. Their Depends-On then resolves to this PR's merge commit, so re-run their CI after this lands.
3. The roller is dispatched. It adopts opf-render's golden-override, so the lock ends with the FA renderer and opf-examples-png.fa-0-14.sha256.json, and the roll PR's queue run verifies that pair.
4. A tiny opf-render PR resets golden-override to ''. A stale override broke a roll once. The same step, or RR-55, deletes the transitional fa-0-14-locked-render fixture.
5. opf-editor#112 merges.

pptx-gallery#110 waits for the 0.14 release. RR-55 #423 reuses this two-fixture pattern.

🤖 Generated with Claude Code

---

Note

High Risk
Breaking pre-v1 schema, catalog, and validation changes across the whole OPF surface, plus coordinated golden/ecosystem lock behavior that gates merge-queue and sibling repos.

Overview
FA 0.14 lands as one coordinated format-audit integration: breaking schema and catalog changes (FA-01–FA-17), new composition/audit/chart APIs, and docs/changelog for each item.

Format and catalogs: Layout records use a unified design + placeholders vocabulary; narratives become catalog pointers with renamed beat fields; chart-type/audience catalogs are cleaned (deprecated ids removed, -3x suffix dropped, record shape slimmed); validation tightens colors/links/gradients and removes dead keys including ChartDataSource; additive features include built-in variables, resolveColorRoles / surfaceAlt, metric sentiment, chart alt and highlight, combo charts, rich headings, timeline status, quote role/photo, code highlight, and full layout design merge via resolveDesignHints.

CLI and tooling: opf render/export skip hidden slides by default (--include-hidden), name outputs from deck filename/name, and the published-packages matrix runs the release-tag font-switch harness so unreleased catalog shapes in the checkout do not break CI.

Ecosystem CI: Depends-On applies on merge_group (queue head PR); opf-render Depends-On can adopt that PR's golden-override; the roller can adopt a core fixture golden from renderer override (FA-19 / roller notes in changesets).

^{Reviewed by Cursor Bugbot for commit d18ddfe. Configure here.}

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: aedcb2b2-3998-4853-874b-c926b9fc1f66)

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: 82c2f1e2-5f2d-493d-bf92-b27f04a14d07)