@openpresentation/opf 0.22.0 → 0.22.1

package/dist/{chunk-DY7H4RG6.js → chunk-LKMR3OLD.js}

@@ -117,7 +117,7 @@ function localAssetProblems(deck, root) {
 }
 var RENDER_PACKAGE = "@openpresentation/opf-render";
 var PPTX_PACKAGE = "@openpresentation/opf-pptx";
-var PEER_RANGES = { [RENDER_PACKAGE]: "^0.20.0", [PPTX_PACKAGE]: "^0.20.0" };
+var PEER_RANGES = { [RENDER_PACKAGE]: "^0.22.0", [PPTX_PACKAGE]: "^0.22.0" };
 var RENDER_EXTRAS = {
   /** The faces of the office pack, which the CLI and `convert` always load (every format). */
   fonts: ["@expo-google-fonts/roboto@0.4.3", "@expo-google-fonts/roboto-mono@0.4.2", "@expo-google-fonts/caladea@0.4.2", "@expo-google-fonts/arimo@0.4.3", "@expo-google-fonts/tinos@0.4.2", "@expo-google-fonts/cousine@0.4.3", "@expo-google-fonts/gelasio@0.4.1", "@expo-google-fonts/noto-sans@0.4.2"],

package/dist/{conversion-DS4OiVls.d.ts → conversion-CSD65VLi.d.ts}

@@ -43,8 +43,8 @@ declare const RENDER_PACKAGE = "@openpresentation/opf-render";
 declare const PPTX_PACKAGE = "@openpresentation/opf-pptx";
 /** Peer ranges. The CLI checks the features it calls rather than the version, so a newer release in range keeps working. */
 declare const PEER_RANGES: {
-    readonly "@openpresentation/opf-render": "^0.20.0";
-    readonly "@openpresentation/opf-pptx": "^0.20.0";
+    readonly "@openpresentation/opf-render": "^0.22.0";
+    readonly "@openpresentation/opf-pptx": "^0.22.0";
 };
 interface Diagnostic {
     code: string;

package/dist/{conversion-3TTBY7OY.js → conversion-JDFXRXTK.js}

@@ -1,4 +1,4 @@
-export { convertFiles, deckFileFormat, exportFormatOf, openDeck, planConversion, readInput, saveDeck, writePlanned } from './chunk-DY7H4RG6.js';
+export { convertFiles, deckFileFormat, exportFormatOf, openDeck, planConversion, readInput, saveDeck, writePlanned } from './chunk-LKMR3OLD.js';
 import './chunk-MG34DCDB.js';
 import './chunk-MAJHCGOW.js';
 import './chunk-UJSAR6GF.js';

package/dist/docs.js

@@ -15,14 +15,14 @@ var docsData = Object.freeze([
   {
     "slug": "chart-options",
     "file": "docs/chart-options.md",
-    "title": "Chart options: axis titles, legend position, data labels and highlight",
-    "markdown": '# Chart options: axis titles, legend position, data labels and highlight\n\nStatus: RR-35 (release readiness) for axis titles, legend and data labels, FA-14 (format audit) for `highlight`. These shipped fields change geometry only for charts that use the first three fields, and colors only for charts that use `highlight`. Use the coordinated package set in the [compatibility matrix](compatibility-matrix.md); schema support alone does not establish native visual fidelity.\n\n## The fields\n\nFour optional fields on the `Chart` object (the fourth, `highlight`, has [its own section](#chart-emphasis-highlight) below):\n\n```json\n{\n  "chart": {\n    "type": "column",\n    "data": { "columns": ["Quarter", "Revenue"], "rows": [["Q1", 12], ["Q2", 18]] },\n    "axisTitles": { "category": "Quarter", "value": "Revenue ($M)" },\n    "legend": "bottom",\n    "dataLabels": { "content": ["value"], "position": "outside-end" }\n  }\n}\n```\n\n| Field | Values | Absent means |\n| --- | --- | --- |\n| `axisTitles` | `{ category?: string, value?: string, secondary?: string }` (`secondary`: combo charts) | no axis titles (today) |\n| `legend` | `none`, `top`, `bottom`, `left`, `right` | today\'s behaviour exactly: a legend at the right of multi-series charts and of pie and doughnut charts, none for a single-series chart |\n| `dataLabels` | `true`, `false` or `{ content?, position?, separator? }` | no data labels (today); the funnel and treemap constructs keep the labels they draw by default (values, category names) |\n\n`axisTitles.category` titles the axis that carries the row labels: the horizontal axis of a column, line, area, histogram, pareto, waterfall and box-and-whisker chart, the **vertical** axis of a bar chart and the X axis of a scatter chart. `axisTitles.value` titles the other one. A named `legend` position shows the legend there even for a single-series chart; `none` hides it.\n\n`dataLabels: true` is `{ "content": ["value"], "position": "auto" }`. `dataLabels: false` is the same as leaving the field out, except on the funnel and treemap constructs, which label their marks by default: there `false` removes those labels (`resolveChartOptions` reports `dataLabelsOff`). In the object form:\n\n- `content`: any of `category`, `value`, `percent` (default `["value"]`). A label shows the selected parts in the fixed order category, value, percent, joined by `separator` (default `", "`). Values print in the General number format (twelve significant digits), `percent` as the integer share of the total (`0%`), `category` as the category name (the X value on a scatter chart).\n- `position`: `auto` (default), `center`, `inside-end`, `inside-base`, `outside-end`, `above`, `below`, `left`, `right`. `auto` is the type\'s default in the table below; the engines write that concrete position, so the preview and PowerPoint do not each pick their own.\n- `separator`: text between the parts.\n\n## Chart emphasis: `highlight`\n\nHighlighting the one series or category that carries the message, and muting the rest, is the main data-storytelling technique. The content stays semantic: `highlight` names series and categories, and the engines pick the colors from the theme. There is no color field.\n\n```json\n{\n  "chart": {\n    "type": "column",\n    "data": { "columns": ["Quarter", "Revenue", "Costs"], "rows": [["Q1", 12, 8], ["Q2", 18, 11], ["Q3", 24, 15]] },\n    "highlight": { "series": ["Revenue"], "categories": ["Q3"] }\n  }\n}\n```\n\n| Field | Meaning |\n| --- | --- |\n| `highlight.series` | Value columns (series) whose marks are highlighted: every mark of each named series. Names match the data column names after any `fields` selection; a series is a plotted value column. |\n| `highlight.categories` | Row labels (the category column, or `mapping.category`) whose marks are highlighted: a column or bar of every series, a line\'s points, a pie or doughnut slice. Labels match as text (the number `2024` as `"2024"`) and a label shared by several rows highlights each of them. |\n\n**The rule.** When `highlight` is present, a mark is highlighted if its series OR its category is listed. Highlighted marks take the deck\'s primary (accent) color; every other mark takes a muted neutral derived from the theme. With both lists given, a bar of series `Revenue` in any category is highlighted, and so is a bar of category `Q3` in any series. A chart without `highlight` keeps its colors, byte for byte. A highlight that names nothing the chart plots (for example a column that is the category column) leaves the chart as if it had none.\n\n**The colors** come from core\'s `chartHighlightColors(surface, primary, text)`, which the preview and the PPTX export both call with the chart panel, the deck primary and the chart text color:\n\n- the accent is the primary color, kept at 3:1 contrast against the panel by `chartColorForFill` (a primary that already has that contrast is used unchanged);\n- the muted color is the panel mixed 30% of the way toward the text color: a light grey on a light panel and a dim grey on a dark one, in the panel\'s own hue. If that is under 1.6:1 against the panel, the mix moves toward the text color until it holds, so a muted mark is always visible and always quieter than the text.\n\nData labels stay readable: a label inside a mark takes the text color that contrasts with that mark\'s own color (core `textColorForFill`), so a label on a muted bar contrasts with the muted fill, as one on an accent bar does with the accent. Labels outside marks keep the chart text color. The legend shows each series in the color its marks have: accent for a highlighted series, muted otherwise. (A multi-series chart that highlights only categories mutes every series alike, so its legend keys look the same; name the series too when the legend matters.)\n\n**Validation.** A name that matches no data column (`series`) or no row label (`categories`) is a `chart-highlight-unknown-name` **error**, found by `resolveChartData` like `chart-mapping-unknown-column`. A series name that is a column but not plotted as a series (the category or X column, or a column `mapping.series` leaves out) is a `chart-highlight-adapted` warning and highlights nothing. A part the chart type cannot highlight is dropped with a `chart-option-adapted` diagnostic (option `highlight.series` or `highlight.categories`). `highlight` must name at least one series or category, and each list has no duplicates.\n\n### What each chart type highlights\n\n`chartOptionSupport(target).highlight` returns `{ series, categories }`; the validator, the preview, the exporter and the editor all follow it.\n\n| Type (catalog ids) | Series | Categories | What is drawn |\n| --- | --- | --- | --- |\n| clustered column, bar | yes | yes | the series\' columns or bars; a category\'s column or bar in every series |\n| stacked and 100% stacked column, bar | yes | yes | the same, per segment |\n| line, stacked line, with markers | yes | yes | a series\' line and markers; a category highlight draws a marker on each series at that category (on a line without markers, only there) |\n| area, stacked area, 100% stacked area | yes | no | the series\' area |\n| scatter | yes | no | the series\' markers (a scatter point label is not a category) |\n| radar, with markers, filled | yes | no | the series\' line (or fill) and markers |\n| pie, doughnut | no | yes | the slice of each named category (a pie plots one series, so a series name is meaningless) |\n| histogram, pareto, waterfall, funnel, treemap, box and whisker, world, combo | no | no | not supported: dropped with `chart-option-adapted` |\n\nThe Office 2016 (chartex) constructs are left out on purpose. Their marks take their colors from the construct\'s chart style, and a per-point color (`cx:dataPt`) would need native verification this change does not have; the waterfall also already colors its marks by increase, decrease and total. They draw and export as before.\n\n## Series colors\n\nSeries colors follow the deck\'s color scheme. They are not a field of the chart: the same chart takes the colors of whichever scheme the deck uses (`design.colorScheme`, the theme\'s scheme, a catalog record, a built-in such as `vibes`, or an inline scheme with slot overrides).\n\nCore\'s `chartSeriesPalette(colorScheme)` (on `@openpresentation/opf/composition`) returns the twelve colors the preview, the PPTX export and the `chart-color-only` accessibility rule all use, in this order:\n\n| Series | Color |\n| --- | --- |\n| 1 to 6 | `accent1` to `accent6` of the resolved color scheme (a slot the scheme leaves out takes the engine default scheme\'s slot) |\n| 7 to 12 | the same six accents mixed 40% toward white, in the same order (series 7 is a tint of `accent1`) |\n\nSeries `i` takes color `i`; a pie, doughnut, treemap or funnel colors category `i` with color `i`. A chart with more than twelve series repeats the list (and `chart-color-only` says so). The `primary`, `secondary` and `accent` role overrides do not reorder the list: series 1 to 3 are always `accent1` to `accent3`, the slots the PPTX export writes as theme colors.\n\nBoth engines then pass the list through `chartPaletteForFill(panel, palette)`, which keeps every series at 3:1 contrast against the chart panel (the card surface) and apart from its neighbours, so on a dark panel the colors are lightened, never merged. The palette is read in tiers of six (series 1 to 6, then 7 to 12): a color is kept apart from the colors of its own and earlier tiers only, so the tints never pull the six accents towards each other. Plan a chart\'s series order for the scheme: put the series that carries the message first (accent1 is the deck\'s primary), and keep a chart to six series or fewer so no tint is needed. The `highlight` colors above are separate: they come from the primary and the panel, not from this list.\n\nA host that validates with its own palette passes `ValidateOptions.chartPalette`; without it the rule judges each slide\'s own scheme.\n\n### Setting colors: `chart.colors`\n\n`colors` lists colors by position and replaces the palette color of that position; the rest of the palette is unchanged.\n\n```json\n{\n  "chart": {\n    "type": "column",\n    "data": { "columns": ["Quarter", "Revenue", "Costs"], "rows": [["Q1", 12, 8], ["Q2", 18, 11]] },\n    "colors": ["accent3", "#7B241C"]\n  }\n}\n```\n\n- **Position.** Entry `i` is the color of series `i` (the `i`-th plotted value column), of slice or category `i` on a pie, doughnut, treemap or funnel chart, and of the `i`-th color a histogram, pareto, waterfall or box-and-whisker chart draws with (the first color for its bars, the second for its line or negative bars). Up to 24 entries; positions past the last entry keep the deck palette.\n- **Values.** Any `ColorRef`: a hex color, a color-scheme slot or role (`accent3`, `secondary`), or a `var:<id>` color variable. A scheme name follows the deck if its scheme changes and is written to PowerPoint as a theme color; a hex color stays as written. Alpha is dropped. An entry that cannot be resolved is ignored (the palette color of its position is used) and `opf/chart-colors-adjusted` says so.\n- **Contrast.** Colors still pass through `chartPaletteForFill`: one with under 3:1 contrast against the chart panel is drawn lighter or darker, and series are kept apart. `opf/chart-colors-adjusted` warns when that happens to an authored color, and `opf/chart-color-only` judges the authored colors for colour-blind and greyscale collisions.\n- **Highlight wins.** With `chart.highlight`, highlighted marks take the primary color and every other mark the muted neutral, whatever `colors` says.\n- **Engines.** Core resolves the list with `chartSeriesPalette(colorScheme, chart.colors, { roles, variables })` (and `resolveChartColors` for the entries alone); the preview and the PPTX export pass the result to `chartPaletteForFill` as before.\n\n## Value axis\n\nA column, bar, line or area chart (standard, stacked and 100% stacked) has one value axis, and composition computes it: `composeSlide` puts `{ min, max, majorUnit }` on the composed chart item as `chart.valueAxis`. The preview draws that axis and the PPTX export writes it as `c:min`, `c:max` and `c:majorUnit`, so PowerPoint and Keynote show the same gridlines as the preview instead of choosing their own major unit. A 100% stacked chart\'s axis is a fraction (`max: 1` is 100%) and carries `percent: true`. Combo, scatter, radar, pie and the Office 2016 constructs have no computed axis (`chart` is absent); each engine keeps drawing them as before.\n\nThe scale is core\'s `niceScale(dataMin, dataMax, maxIntervals, { percent })`: zero is on the axis (always for bars and areas; for a line only when the data does not sit in the top sixth of its range), the data gets 5% headroom, and the major unit is the smallest 1, 2 or 5 times a power of ten that fits `maxIntervals` intervals. `maxIntervals` is `maxIntervalsFor(length, labelExtent)`, at most 10, where `length` is the plot\'s extent along the value axis estimated from the chart box (without measuring text) and `labelExtent` is the space one tick label needs: a column, line or area chart has `box height - 2 x pad - 1.5 x line height` (less a line for a category axis title, and a line plus a pad for a top or bottom legend) over 1.2 line heights, a bar chart `70% of the box width - 2 x pad - text size` over 4 text sizes. Here pad is `10 x scale`, text size is `chartTextSize(...) x scale` px and line height is 1.5 text sizes. `chartTextSize({ width, height, scale, minFontSize })` is the chart text size the preview draws: `CHART_TEXT_PX` (20 px at the 1280 x 720 reference, 15 pt), shrunk only when the box is small (at most 1/18 of the box height and 1/30 of its width, whole pixels) and never below `minFontSize` (default 16), with `scale = min(slide width, slide height) / 720`. A chart in a short box therefore has fewer, larger intervals (0 to 800 in steps of 100 in a tall box, steps of 200 in a short one); a tall box always gets ten at most.\n\n## What each chart type supports (axis titles, legend, data labels)\n\n`chartOptionSupport(target)` in `@openpresentation/opf/composition` returns this table; the validator, the preview, the exporter and the importer all follow it. An option a type cannot show is **adapted** (dropped, or reset to the default) and reported as a `chart-option-adapted` diagnostic by the validator (a warning), the renderer and the exporter (`onDiagnostic`). It is never silently lost and never fails the render.\n\n| Type (catalog ids) | Axis titles | Legend | Data label content | Data label positions (default) |\n| --- | --- | --- | --- | --- |\n| clustered column, bar (`column`, `bar`) | category, value | yes | category, value | center, inside-end, inside-base, outside-end (outside-end) |\n| stacked and 100% stacked column, bar | category, value | yes | category, value | center, inside-end, inside-base (center) |\n| line, stacked line, with markers | category, value | yes | category, value | above, below, left, right, center (above) |\n| area, stacked area, 100% stacked area | category, value | yes | category, value | none: the label sits in the area at each category |\n| scatter | category (X), value (Y) | yes | category (X value), value (Y) | above, below, left, right, center (above) |\n| pie | none | yes | category, value, percent | center, inside-end, outside-end (outside-end) |\n| doughnut | none | yes | category, value, percent | none: labels sit in the ring |\n| radar, with markers, filled | none | yes | category, value | none |\n| histogram, pareto | category, value | none | category, value | center, inside-end, inside-base, outside-end (outside-end) |\n| waterfall | category, value | none | category, value | center, inside-end, inside-base, outside-end (outside-end) |\n| funnel | category | none | category, value | none (center) |\n| treemap | none | none | category, value | none (center) |\n| box and whisker | category, value | yes | none | none |\n| combo (`combo`) | category, value, secondary | yes | category, value | columns: center, inside-end, inside-base, outside-end (outside-end); lines: above, below, left, right, center (above) |\n| world (region map) | none | none | none | none |\n\nA chart type outside the catalog is never adapted.\n\n## Combo charts\n\nStatus: FA-15 (format audit). A `combo` chart draws clustered columns and line series in one plot, for an amount beside a rate such as revenue and margin %:\n\n```json\n{\n  "chart": {\n    "type": "combo",\n    "data": {\n      "columns": ["Quarter", { "name": "Revenue", "format": "$#,##0.0" }, { "name": "Margin", "format": "0%" }],\n      "rows": [["Q1", 12.4, 0.31], ["Q2", 18.1, 0.34], ["Q3", 21.7, 0.29], ["Q4", 26.3, 0.37]]\n    },\n    "line": ["Margin"],\n    "secondaryAxis": ["Margin"],\n    "axisTitles": { "category": "Quarter", "value": "Revenue ($M)", "secondary": "Margin" }\n  }\n}\n```\n\n| Field | Values | Absent means |\n| --- | --- | --- |\n| `line` | plotted series names, at least one | the last plotted series is the line |\n| `secondaryAxis` | line series names | every series uses the primary (left) value axis |\n| `axisTitles.secondary` | string | no secondary axis title |\n\n- **The plan.** Every plotted series (the `mapping.series` or the positional rule) is drawn as clustered columns, except the ones `line` names, which are lines with markers. At least one series stays columns, so a `line` that names every series draws the first as columns. A one-series combo chart is drawn as columns. Core\'s `resolveChartData` returns the plan as `combo` (`{ role: "bar" | "line", axis: "primary" | "secondary" }` per series) and orders the series columns first, then the primary-axis lines, then the secondary-axis lines, so the preview, the PPTX series order and the legend agree.\n- **The secondary axis.** `secondaryAxis` puts line series on a value axis at the right (at the left right to left). It has its own automatic scale and its tick labels use the number format of its first series\' column (`DataColumn.format`, for example `0%`); the primary axis uses the first column series\' format. Gridlines follow the primary axis. `axisTitles.secondary` titles it, rotated like the primary value title.\n- **Labels.** One `dataLabels` applies to both parts: column labels sit outside the end and line labels above the points by default; `center` applies to both; a position only one part takes (`inside-end`, `inside-base`, `outside-end` for columns; `above`, `below`, `left`, `right` for lines) applies to that part and the other keeps its default, with a `chart-option-adapted` note. `resolveChartOptions` returns the column position as `dataLabels.position` and the line position as `dataLabels.linePosition`.\n- **Legend.** As for other multi-series charts (right by default, or `legend`); a column series has a square key and a line series a line with a marker.\n- **Validation.** A `line` or `secondaryAxis` name that is not a column of the data is a `chart-mapping-unknown-column` error. A name that is not plotted, a `secondaryAxis` name that is not a line, a `line` that names every series and a one-series combo chart are `chart-mapping-adapted` warnings. `line`, `secondaryAxis` and `axisTitles.secondary` on any other chart type, and `axisTitles.secondary` on a combo chart without `secondaryAxis`, are `chart-option-adapted` warnings.\n- **PPTX.** One `c:plotArea` holds a clustered column `c:barChart` (primary axes) and a `c:lineChart` with markers. Secondary-axis lines form a second `c:lineChart` on a second `c:valAx` (`axPos r`, `crosses max`) and a deleted second `c:catAx`; the embedded workbook holds every series. Import reads such a plot area (one clustered column group, one or two line groups) back as `combo` with `line` (when it is not the default), `secondaryAxis`, the secondary title and the label position.\n- **Editor.** The chart type picker offers `combo` for data with two or more series, the chart options panel sets which series are lines and which lines use the secondary axis, and switching to another type removes the three fields.\n\n## How the engines draw and write them\n\nThe preview (opf-render) and the PPTX export (opf-pptx) both read `resolveChartOptions(chart, chartOptionTarget(chart.type))`, so they agree on which options apply and with which content and position. The highlight adds `resolveChartOptions(...).highlight` (the names that survive the type\'s support table), `chartHighlightMarks(highlight, resolvedData)` (which series and which rows are named) and `chartHighlightColors` (the two colors).\n\n- **Preview.** A legend, and the axis titles, are carved from the chart box before the plot is laid out: the legend at its edge, then the titles next to the axes. Only a chart that uses a field changes; a chart without them draws the same SVG as before. A vertical axis title is rotated 270 degrees, as PowerPoint draws it.\n- **PPTX, classic charts** (column, bar, line, area, pie, doughnut, scatter, radar): `c:catAx/c:title` and `c:valAx/c:title` (rich text, `c:overlay val="0"`), `c:legend/c:legendPos` (`t`, `b`, `l`, `r`; no `c:legend` for `none`) and a `c:dLbls` per series with `c:dLblPos`, `c:showVal`, `c:showCatName`, `c:showPercent` and an explicit `c:separator`, number format `General` (RR-54: the series column format, as `toExcelNumberFormat` writes it, when its `DataColumn` has one; see [chart-table-data.md](chart-table-data.md)).\n- **PPTX, chartex** (histogram, pareto, waterfall, funnel, treemap, box and whisker): `cx:axis/cx:title`, `cx:legend pos`, and `cx:dataLabels pos` with `cx:visibility` and `cx:separator`. The classic fallback chart that precedes every chartex part carries the same classic options.\n- **Highlight (FA-14), preview.** A highlighted mark is filled with the accent color, every other mark with the muted color; series keep their order (the highlighted one is not moved on top), as PowerPoint draws them. A chart without a highlight never calls the highlight code.\n- **Highlight (FA-14), PPTX.** Series colors go into `c:ser/c:spPr` (and `c:marker/c:spPr` on line, scatter and radar series); a per-point color is a `c:dPt` with `c:idx`: `c:dPt/c:spPr` on a column or bar, a circular `c:dPt/c:marker` on a line, the slice fill on a pie or doughnut. The accent is `a:schemeClr val="accent1"` when the deck theme holds the primary exactly (so re-theming in PowerPoint recolors it) and an `a:srgbClr` literal when the contrast adjustment moved it; the muted color is always an `a:srgbClr` literal, because a mix of two theme colors is not one scheme color with `lumMod`/`lumOff`. Data labels inside a mark are written per point where the mark colors differ. Chartex constructs are unchanged.\n- **Import.** `fromPptx` reads the same parts back into `axisTitles`, `legend` and `dataLabels`. A legend equal to the default for that chart (right for multi-series, pie and doughnut; none otherwise) is not recorded, so decks that never set the field import unchanged. Anything the three fields cannot express (per-series label overrides, number formats, rich-text titles, manual layouts) is reported with a diagnostic and not invented. The highlight is not inferred from the colors (a native chart\'s fills do not say which names were highlighted, and a hand-colored chart must not turn into a highlight): in `full` provenance mode the exporter records the authored `highlight` in the chart\'s `OPF_DATA_V1` data record, and `fromPptx` restores it while the chart\'s cached data is unchanged. With `provenance: false` or `\'references-only\'`, or after the data was edited in PowerPoint (`chart-data-provenance-changed`), the chart imports without a highlight and keeps the colors it shows.\n\n## Text alternative\n\n`Chart.alt` (FA-09) is a string: what the chart shows, in a sentence or two (the point and the key numbers), not "a chart". Unlike the three options above it changes no geometry.\n\n- **Preview.** The chart\'s SVG group carries `role="img"` and `aria-label`; the role makes the drawn marks inside presentational, so the label is the chart\'s one announcement. The text beside the chart stays reachable: the slide is a labelled group, not an image (see [Accessibility of the preview](content-payloads.md#accessibility-of-the-preview)).\n- **PPTX.** The value is the chart frame\'s `p:nvGraphicFramePr/p:cNvPr/@descr`, the same attribute pictures use, on classic charts and on chartex (Office 2016) frames. `fromPptx` reads it back into `alt`.\n- **Empty string.** `""` marks the chart decorative, like an empty `Asset.alt`: the preview writes no label and hides the group (`aria-hidden`), and the PPTX frame carries PowerPoint\'s own "Mark as decorative" marker (the `adec:decorative` extension of `p:cNvPr`), not `descr=""`, which PowerPoint writes for any shape without alt text. Import reads the marker back as `alt: ""`. A chart nearly always carries a message, so `opf/chart-text-alternative` reports it as info.\n- **Validate.** `opf/chart-text-alternative` passes a chart with a non-blank `alt`. Without `alt` it still passes when text, a table or a subtitle sits beside the chart; otherwise it reports the chart and offers a quick fix that focuses the `alt` field. `opf/poor-alt-text` flags a bare "chart", a URL, a leading "chart of" and alt text over 250 characters.\n\n## Defaults and geometry\n\nA chart that sets none of the four fields renders and exports byte-for-byte as before; the preview tests and the PPTX goldens assert it. A chart with options reserves space for its legend and titles, so its geometry differs from a chart without them. The implementations require coordinated Core, renderer, PPTX and editor versions; use the [compatibility matrix](compatibility-matrix.md).\n\n## Not in this change\n\nPer-series data label overrides (column number formats are RR-54, [chart-table-data.md](chart-table-data.md)), a rotated or rich-text axis title, a chart title, a legend that overlays the plot, manual plot-area layout, secondary axes outside combo charts, and trendlines. Charts from external spreadsheets stay descoped (the `ChartDataSource` form was removed from the schema).\n'
+    "title": "Chart options: axis titles, legend, data labels, highlight, series colors and the value axis",
+    "markdown": '# Chart options: axis titles, legend, data labels, highlight, series colors and the value axis\n\nStatus: RR-35 (release readiness) for axis titles, legend and data labels, FA-14 (format audit) for `highlight`, and RR-89 and RR-92 (core 0.21.0) for series colors (`chart.colors`) and the computed value axis. The first four fields change geometry only for charts that use the first three fields, and colors only for charts that use `highlight`. Use the coordinated package set in the [compatibility matrix](compatibility-matrix.md); schema support alone does not establish native visual fidelity.\n\n## The fields\n\nFour optional fields on the `Chart` object (the fourth, `highlight`, has [its own section](#chart-emphasis-highlight) below):\n\n```json\n{\n  "chart": {\n    "type": "column",\n    "data": { "columns": ["Quarter", "Revenue"], "rows": [["Q1", 12], ["Q2", 18]] },\n    "axisTitles": { "category": "Quarter", "value": "Revenue ($M)" },\n    "legend": "bottom",\n    "dataLabels": { "content": ["value"], "position": "outside-end" }\n  }\n}\n```\n\n| Field | Values | Absent means |\n| --- | --- | --- |\n| `axisTitles` | `{ category?: string, value?: string, secondary?: string }` (`secondary`: combo charts) | no axis titles (today) |\n| `legend` | `none`, `top`, `bottom`, `left`, `right` | today\'s behaviour exactly: a legend at the right of multi-series charts and of pie and doughnut charts, none for a single-series chart |\n| `dataLabels` | `true`, `false` or `{ content?, position?, separator? }` | no data labels (today); the funnel and treemap constructs keep the labels they draw by default (values, category names) |\n\n`axisTitles.category` titles the axis that carries the row labels: the horizontal axis of a column, line, area, histogram, pareto, waterfall and box-and-whisker chart, the **vertical** axis of a bar chart and the X axis of a scatter chart. `axisTitles.value` titles the other one. A named `legend` position shows the legend there even for a single-series chart; `none` hides it.\n\n`dataLabels: true` is `{ "content": ["value"], "position": "auto" }`. `dataLabels: false` is the same as leaving the field out, except on the funnel and treemap constructs, which label their marks by default: there `false` removes those labels (`resolveChartOptions` reports `dataLabelsOff`). In the object form:\n\n- `content`: any of `category`, `value`, `percent` (default `["value"]`). A label shows the selected parts in the fixed order category, value, percent, joined by `separator` (default `", "`). Values print in the General number format (twelve significant digits), `percent` as the integer share of the total (`0%`), `category` as the category name (the X value on a scatter chart).\n- `position`: `auto` (default), `center`, `inside-end`, `inside-base`, `outside-end`, `above`, `below`, `left`, `right`. `auto` is the type\'s default in the table below; the engines write that concrete position, so the preview and PowerPoint do not each pick their own.\n- `separator`: text between the parts.\n\n## Chart emphasis: `highlight`\n\nHighlighting the one series or category that carries the message, and muting the rest, is the main data-storytelling technique. The content stays semantic: `highlight` names series and categories, and the engines pick the colors from the theme. There is no color field.\n\n```json\n{\n  "chart": {\n    "type": "column",\n    "data": { "columns": ["Quarter", "Revenue", "Costs"], "rows": [["Q1", 12, 8], ["Q2", 18, 11], ["Q3", 24, 15]] },\n    "highlight": { "series": ["Revenue"], "categories": ["Q3"] }\n  }\n}\n```\n\n| Field | Meaning |\n| --- | --- |\n| `highlight.series` | Value columns (series) whose marks are highlighted: every mark of each named series. Names match the data column names after any `fields` selection; a series is a plotted value column. |\n| `highlight.categories` | Row labels (the category column, or `mapping.category`) whose marks are highlighted: a column or bar of every series, a line\'s points, a pie or doughnut slice. Labels match as text (the number `2024` as `"2024"`) and a label shared by several rows highlights each of them. |\n\n**The rule.** When `highlight` is present, a mark is highlighted if its series OR its category is listed. Highlighted marks take the deck\'s primary (accent) color; every other mark takes a muted neutral derived from the theme. With both lists given, a bar of series `Revenue` in any category is highlighted, and so is a bar of category `Q3` in any series. A chart without `highlight` keeps its colors, byte for byte. A highlight that names nothing the chart plots (for example a column that is the category column) leaves the chart as if it had none.\n\n**The colors** come from core\'s `chartHighlightColors(surface, primary, text)`, which the preview and the PPTX export both call with the chart panel, the deck primary and the chart text color:\n\n- the accent is the primary color, kept at 3:1 contrast against the panel by `chartColorForFill` (a primary that already has that contrast is used unchanged);\n- the muted color is the panel mixed 30% of the way toward the text color: a light grey on a light panel and a dim grey on a dark one, in the panel\'s own hue. If that is under 1.6:1 against the panel, the mix moves toward the text color until it holds, so a muted mark is always visible and always quieter than the text.\n\nData labels stay readable: a label inside a mark takes the text color that contrasts with that mark\'s own color (core `textColorForFill`), so a label on a muted bar contrasts with the muted fill, as one on an accent bar does with the accent. Labels outside marks keep the chart text color. The legend shows each series in the color its marks have: accent for a highlighted series, muted otherwise. (A multi-series chart that highlights only categories mutes every series alike, so its legend keys look the same; name the series too when the legend matters.)\n\n**Validation.** A name that matches no data column (`series`) or no row label (`categories`) is a `chart-highlight-unknown-name` **error**, found by `resolveChartData` like `chart-mapping-unknown-column`. A series name that is a column but not plotted as a series (the category or X column, or a column `mapping.series` leaves out) is a `chart-highlight-adapted` warning and highlights nothing. A part the chart type cannot highlight is dropped with a `chart-option-adapted` diagnostic (option `highlight.series` or `highlight.categories`). `highlight` must name at least one series or category, and each list has no duplicates.\n\n### What each chart type highlights\n\n`chartOptionSupport(target).highlight` returns `{ series, categories }`; the validator, the preview, the exporter and the editor all follow it.\n\n| Type (catalog ids) | Series | Categories | What is drawn |\n| --- | --- | --- | --- |\n| clustered column, bar | yes | yes | the series\' columns or bars; a category\'s column or bar in every series |\n| stacked and 100% stacked column, bar | yes | yes | the same, per segment |\n| line, stacked line, with markers | yes | yes | a series\' line and markers; a category highlight draws a marker on each series at that category (on a line without markers, only there) |\n| area, stacked area, 100% stacked area | yes | no | the series\' area |\n| scatter | yes | no | the series\' markers (a scatter point label is not a category) |\n| radar, with markers, filled | yes | no | the series\' line (or fill) and markers |\n| pie, doughnut | no | yes | the slice of each named category (a pie plots one series, so a series name is meaningless) |\n| histogram, pareto, waterfall, funnel, treemap, box and whisker, world, combo | no | no | not supported: dropped with `chart-option-adapted` |\n\nThe Office 2016 (chartex) constructs are left out on purpose. Their marks take their colors from the construct\'s chart style, and a per-point color (`cx:dataPt`) would need native verification this change does not have; the waterfall also already colors its marks by increase, decrease and total. They draw and export as before.\n\n## Series colors\n\nSeries colors follow the deck\'s color scheme by default: the same chart takes the colors of whichever scheme the deck uses (`design.colorScheme`, the theme\'s scheme, a catalog record, a built-in such as `vibes`, or an inline scheme with slot overrides). To set the color of one series, slice or category, list colors in [`chart.colors`](#setting-colors-chartcolors); a position it does not list keeps the deck palette.\n\nCore\'s `chartSeriesPalette(colorScheme)` (on `@openpresentation/opf/composition`) returns the twelve colors the preview, the PPTX export and the `chart-color-only` accessibility rule all use, in this order:\n\n| Series | Color |\n| --- | --- |\n| 1 to 6 | `accent1` to `accent6` of the resolved color scheme (a slot the scheme leaves out takes the engine default scheme\'s slot) |\n| 7 to 12 | the same six accents mixed 40% toward white, in the same order (series 7 is a tint of `accent1`) |\n\nSeries `i` takes color `i`; a pie, doughnut, treemap or funnel colors category `i` with color `i`. A chart with more than twelve series repeats the list (and `chart-color-only` says so). The `primary`, `secondary` and `accent` role overrides do not reorder the list: series 1 to 3 are always `accent1` to `accent3`, the slots the PPTX export writes as theme colors.\n\nBoth engines then pass the list through `chartPaletteForFill(panel, palette)`, which keeps every series at 3:1 contrast against the chart panel (the card surface) and apart from its neighbours, so on a dark panel the colors are lightened, never merged. The palette is read in tiers of six (series 1 to 6, then 7 to 12): a color is kept apart from the colors of its own and earlier tiers only, so the tints never pull the six accents towards each other. Plan a chart\'s series order for the scheme: put the series that carries the message first (accent1 is the deck\'s primary), and keep a chart to six series or fewer so no tint is needed. The `highlight` colors above are separate: they come from the primary and the panel, not from this list.\n\nA host that validates with its own palette passes `ValidateOptions.chartPalette`; without it the rule judges each slide\'s own scheme.\n\n### Setting colors: `chart.colors`\n\n`colors` lists colors by position and replaces the palette color of that position; the rest of the palette is unchanged.\n\n```json\n{\n  "chart": {\n    "type": "column",\n    "data": { "columns": ["Quarter", "Revenue", "Costs"], "rows": [["Q1", 12, 8], ["Q2", 18, 11]] },\n    "colors": ["accent3", "#7B241C"]\n  }\n}\n```\n\n- **Position.** Entry `i` is the color of series `i` (the `i`-th plotted value column), of slice or category `i` on a pie, doughnut, treemap or funnel chart, and of the `i`-th color a histogram, pareto, waterfall or box-and-whisker chart draws with (the first color for its bars, the second for its line or negative bars). Up to 24 entries; positions past the last entry keep the deck palette.\n- **Values.** Any `ColorRef`: a hex color, a color-scheme slot or role (`accent3`, `secondary`), or a `var:<id>` color variable. A scheme name follows the deck if its scheme changes and is written to PowerPoint as a theme color; a hex color stays as written. Alpha is dropped. An entry that cannot be resolved is ignored (the palette color of its position is used) and `opf/chart-colors-adjusted` says so.\n- **Contrast.** Colors still pass through `chartPaletteForFill`: one with under 3:1 contrast against the chart panel is drawn lighter or darker, and series are kept apart. `opf/chart-colors-adjusted` warns when that happens to an authored color, and `opf/chart-color-only` judges the authored colors for colour-blind and greyscale collisions.\n- **Highlight wins.** With `chart.highlight`, highlighted marks take the primary color and every other mark the muted neutral, whatever `colors` says.\n- **Engines.** Core resolves the list with `chartSeriesPalette(colorScheme, chart.colors, { roles, variables })` (and `resolveChartColors` for the entries alone); the preview and the PPTX export pass the result to `chartPaletteForFill` as before.\n\n## Value axis\n\nA column, bar, line or area chart (standard, stacked and 100% stacked) has one value axis, and composition computes it: `composeSlide` puts `{ min, max, majorUnit }` on the composed chart item as `chart.valueAxis`. The preview draws that axis and the PPTX export writes it as `c:min`, `c:max` and `c:majorUnit`, so PowerPoint and Keynote show the same gridlines as the preview instead of choosing their own major unit. A 100% stacked chart\'s axis is a fraction (`max: 1` is 100%) and carries `percent: true`. Combo, scatter, radar, pie and the Office 2016 constructs have no computed axis (`chart` is absent); each engine keeps drawing them as before.\n\nThe scale is core\'s `niceScale(dataMin, dataMax, maxIntervals, { percent })`: zero is on the axis (always for bars and areas; for a line only when the data does not sit in the top sixth of its range), the data gets 5% headroom, and the major unit is the smallest 1, 2 or 5 times a power of ten that fits `maxIntervals` intervals. `maxIntervals` is `maxIntervalsFor(length, labelExtent)`, at most 10, where `length` is the plot\'s extent along the value axis estimated from the chart box (without measuring text) and `labelExtent` is the space one tick label needs: a column, line or area chart has `box height - 2 x pad - 1.5 x line height` (less a line for a category axis title, and a line plus a pad for a top or bottom legend) over 1.2 line heights, a bar chart `70% of the box width - 2 x pad - text size` over 4 text sizes. Here pad is `10 x scale`, text size is `chartTextSize(...) x scale` px and line height is 1.5 text sizes. `chartTextSize({ width, height, scale, minFontSize })` is the chart text size the preview draws: `CHART_TEXT_PX` (20 px at the 1280 x 720 reference, 15 pt), shrunk only when the box is small (at most 1/18 of the box height and 1/30 of its width, whole pixels) and never below `minFontSize` (default 16), with `scale = min(slide width, slide height) / 720`. A chart in a short box therefore has fewer, larger intervals (0 to 800 in steps of 100 in a tall box, steps of 200 in a short one); a tall box always gets ten at most.\n\n## What each chart type supports (axis titles, legend, data labels)\n\n`chartOptionSupport(target)` in `@openpresentation/opf/composition` returns this table; the validator, the preview, the exporter and the importer all follow it. An option a type cannot show is **adapted** (dropped, or reset to the default) and reported as a `chart-option-adapted` diagnostic by the validator (a warning), the renderer and the exporter (`onDiagnostic`). It is never silently lost and never fails the render.\n\n| Type (catalog ids) | Axis titles | Legend | Data label content | Data label positions (default) |\n| --- | --- | --- | --- | --- |\n| clustered column, bar (`column`, `bar`) | category, value | yes | category, value | center, inside-end, inside-base, outside-end (outside-end) |\n| stacked and 100% stacked column, bar | category, value | yes | category, value | center, inside-end, inside-base (center) |\n| line, stacked line, with markers | category, value | yes | category, value | above, below, left, right, center (above) |\n| area, stacked area, 100% stacked area | category, value | yes | category, value | none: the label sits in the area at each category |\n| scatter | category (X), value (Y) | yes | category (X value), value (Y) | above, below, left, right, center (above) |\n| pie | none | yes | category, value, percent | center, inside-end, outside-end (outside-end) |\n| doughnut | none | yes | category, value, percent | none: labels sit in the ring |\n| radar, with markers, filled | none | yes | category, value | none |\n| histogram, pareto | category, value | none | category, value | center, inside-end, inside-base, outside-end (outside-end) |\n| waterfall | category, value | none | category, value | center, inside-end, inside-base, outside-end (outside-end) |\n| funnel | category | none | category, value | none (center) |\n| treemap | none | none | category, value | none (center) |\n| box and whisker | category, value | yes | none | none |\n| combo (`combo`) | category, value, secondary | yes | category, value | columns: center, inside-end, inside-base, outside-end (outside-end); lines: above, below, left, right, center (above) |\n| world (region map) | none | none | none | none |\n\nA chart type outside the catalog is never adapted.\n\n## Combo charts\n\nStatus: FA-15 (format audit). A `combo` chart draws clustered columns and line series in one plot, for an amount beside a rate such as revenue and margin %:\n\n```json\n{\n  "chart": {\n    "type": "combo",\n    "data": {\n      "columns": ["Quarter", { "name": "Revenue", "format": "$#,##0.0" }, { "name": "Margin", "format": "0%" }],\n      "rows": [["Q1", 12.4, 0.31], ["Q2", 18.1, 0.34], ["Q3", 21.7, 0.29], ["Q4", 26.3, 0.37]]\n    },\n    "line": ["Margin"],\n    "secondaryAxis": ["Margin"],\n    "axisTitles": { "category": "Quarter", "value": "Revenue ($M)", "secondary": "Margin" }\n  }\n}\n```\n\n| Field | Values | Absent means |\n| --- | --- | --- |\n| `line` | plotted series names, at least one | the last plotted series is the line |\n| `secondaryAxis` | line series names | every series uses the primary (left) value axis |\n| `axisTitles.secondary` | string | no secondary axis title |\n\n- **The plan.** Every plotted series (the `mapping.series` or the positional rule) is drawn as clustered columns, except the ones `line` names, which are lines with markers. At least one series stays columns, so a `line` that names every series draws the first as columns. A one-series combo chart is drawn as columns. Core\'s `resolveChartData` returns the plan as `combo` (`{ role: "bar" | "line", axis: "primary" | "secondary" }` per series) and orders the series columns first, then the primary-axis lines, then the secondary-axis lines, so the preview, the PPTX series order and the legend agree.\n- **The secondary axis.** `secondaryAxis` puts line series on a value axis at the right (at the left right to left). It has its own automatic scale and its tick labels use the number format of its first series\' column (`DataColumn.format`, for example `0%`); the primary axis uses the first column series\' format. Gridlines follow the primary axis. `axisTitles.secondary` titles it, rotated like the primary value title.\n- **Labels.** One `dataLabels` applies to both parts: column labels sit outside the end and line labels above the points by default; `center` applies to both; a position only one part takes (`inside-end`, `inside-base`, `outside-end` for columns; `above`, `below`, `left`, `right` for lines) applies to that part and the other keeps its default, with a `chart-option-adapted` note. `resolveChartOptions` returns the column position as `dataLabels.position` and the line position as `dataLabels.linePosition`.\n- **Legend.** As for other multi-series charts (right by default, or `legend`); a column series has a square key and a line series a line with a marker.\n- **Validation.** A `line` or `secondaryAxis` name that is not a column of the data is a `chart-mapping-unknown-column` error. A name that is not plotted, a `secondaryAxis` name that is not a line, a `line` that names every series and a one-series combo chart are `chart-mapping-adapted` warnings. `line`, `secondaryAxis` and `axisTitles.secondary` on any other chart type, and `axisTitles.secondary` on a combo chart without `secondaryAxis`, are `chart-option-adapted` warnings.\n- **PPTX.** One `c:plotArea` holds a clustered column `c:barChart` (primary axes) and a `c:lineChart` with markers. Secondary-axis lines form a second `c:lineChart` on a second `c:valAx` (`axPos r`, `crosses max`) and a deleted second `c:catAx`; the embedded workbook holds every series. Import reads such a plot area (one clustered column group, one or two line groups) back as `combo` with `line` (when it is not the default), `secondaryAxis`, the secondary title and the label position.\n- **Editor.** The chart type picker offers `combo` for data with two or more series, the chart options panel sets which series are lines and which lines use the secondary axis, and switching to another type removes the three fields.\n\n## How the engines draw and write them\n\nThe preview (opf-render) and the PPTX export (opf-pptx) both read `resolveChartOptions(chart, chartOptionTarget(chart.type))`, so they agree on which options apply and with which content and position. The highlight adds `resolveChartOptions(...).highlight` (the names that survive the type\'s support table), `chartHighlightMarks(highlight, resolvedData)` (which series and which rows are named) and `chartHighlightColors` (the two colors).\n\n- **Preview.** A legend, and the axis titles, are carved from the chart box before the plot is laid out: the legend at its edge, then the titles next to the axes. Only a chart that uses a field changes; a chart without them draws the same SVG as before. A vertical axis title is rotated 270 degrees, as PowerPoint draws it.\n- **PPTX, classic charts** (column, bar, line, area, pie, doughnut, scatter, radar): `c:catAx/c:title` and `c:valAx/c:title` (rich text, `c:overlay val="0"`), `c:legend/c:legendPos` (`t`, `b`, `l`, `r`; no `c:legend` for `none`) and a `c:dLbls` per series with `c:dLblPos`, `c:showVal`, `c:showCatName`, `c:showPercent` and an explicit `c:separator`, number format `General` (RR-54: the series column format, as `toExcelNumberFormat` writes it, when its `DataColumn` has one; see [chart-table-data.md](chart-table-data.md)).\n- **PPTX, chartex** (histogram, pareto, waterfall, funnel, treemap, box and whisker): `cx:axis/cx:title`, `cx:legend pos`, and `cx:dataLabels pos` with `cx:visibility` and `cx:separator`. The classic fallback chart that precedes every chartex part carries the same classic options.\n- **Highlight (FA-14), preview.** A highlighted mark is filled with the accent color, every other mark with the muted color; series keep their order (the highlighted one is not moved on top), as PowerPoint draws them. A chart without a highlight never calls the highlight code.\n- **Highlight (FA-14), PPTX.** Series colors go into `c:ser/c:spPr` (and `c:marker/c:spPr` on line, scatter and radar series); a per-point color is a `c:dPt` with `c:idx`: `c:dPt/c:spPr` on a column or bar, a circular `c:dPt/c:marker` on a line, the slice fill on a pie or doughnut. The accent is `a:schemeClr val="accent1"` when the deck theme holds the primary exactly (so re-theming in PowerPoint recolors it) and an `a:srgbClr` literal when the contrast adjustment moved it; the muted color is always an `a:srgbClr` literal, because a mix of two theme colors is not one scheme color with `lumMod`/`lumOff`. Data labels inside a mark are written per point where the mark colors differ. Chartex constructs are unchanged.\n- **Import.** `fromPptx` reads the same parts back into `axisTitles`, `legend` and `dataLabels`. A legend equal to the default for that chart (right for multi-series, pie and doughnut; none otherwise) is not recorded, so decks that never set the field import unchanged. Anything the three fields cannot express (per-series label overrides, number formats, rich-text titles, manual layouts) is reported with a diagnostic and not invented. The highlight is not inferred from the colors (a native chart\'s fills do not say which names were highlighted, and a hand-colored chart must not turn into a highlight): in `full` provenance mode the exporter records the authored `highlight` in the chart\'s `OPF_DATA_V1` data record, and `fromPptx` restores it while the chart\'s cached data is unchanged. With `provenance: false` or `\'references-only\'`, or after the data was edited in PowerPoint (`chart-data-provenance-changed`), the chart imports without a highlight and keeps the colors it shows.\n\n## Text alternative\n\n`Chart.alt` (FA-09) is a string: what the chart shows, in a sentence or two (the point and the key numbers), not "a chart". Unlike the three options above it changes no geometry.\n\n- **Preview.** The chart\'s SVG group carries `role="img"` and `aria-label`; the role makes the drawn marks inside presentational, so the label is the chart\'s one announcement. The text beside the chart stays reachable: the slide is a labelled group, not an image (see [Accessibility of the preview](content-payloads.md#accessibility-of-the-preview)).\n- **PPTX.** The value is the chart frame\'s `p:nvGraphicFramePr/p:cNvPr/@descr`, the same attribute pictures use, on classic charts and on chartex (Office 2016) frames. `fromPptx` reads it back into `alt`.\n- **Empty string.** `""` marks the chart decorative, like an empty `Asset.alt`: the preview writes no label and hides the group (`aria-hidden`), and the PPTX frame carries PowerPoint\'s own "Mark as decorative" marker (the `adec:decorative` extension of `p:cNvPr`), not `descr=""`, which PowerPoint writes for any shape without alt text. Import reads the marker back as `alt: ""`. A chart nearly always carries a message, so `opf/chart-text-alternative` reports it as info.\n- **Validate.** `opf/chart-text-alternative` passes a chart with a non-blank `alt`. Without `alt` it still passes when text, a table or a subtitle sits beside the chart; otherwise it reports the chart and offers a quick fix that focuses the `alt` field. `opf/poor-alt-text` flags a bare "chart", a URL, a leading "chart of" and alt text over 250 characters.\n\n## Defaults and geometry\n\nA chart that sets none of the four fields renders and exports byte-for-byte as before; the preview tests and the PPTX goldens assert it. A chart with options reserves space for its legend and titles, so its geometry differs from a chart without them. The implementations require coordinated Core, renderer, PPTX and editor versions; use the [compatibility matrix](compatibility-matrix.md).\n\n## Not in this change\n\nPer-series data label overrides (column number formats are RR-54, [chart-table-data.md](chart-table-data.md)), a rotated or rich-text axis title, a chart title, a legend that overlays the plot, manual plot-area layout, secondary axes outside combo charts, and trendlines. Charts from external spreadsheets stay descoped (the `ChartDataSource` form was removed from the schema).\n'
   },
   {
     "slug": "chart-table-data",
     "file": "docs/chart-table-data.md",
     "title": "Chart and table data: numbers, formats, datasets and series mapping",
-    "markdown": '# Chart and table data: numbers, formats, datasets and series mapping\n\nStatus: RR-54 (release readiness). Additive schema plus one behaviour fix (strict chart numbers). These features are shipped in the coordinated package line; use the [compatibility matrix](compatibility-matrix.md) for the verified set. This page is the contract the four packages implement; change it here first.\n\n## Decisions (vetoable)\n\nRecorded 2026-10-05 for the owner, who asked for all five recommendations of the chart/table data review at once:\n\n1. **One strict chart number rule in core.** The preview read `"12%"` as a gap and `"1e6"` as 1000000; the exporter stripped every non-numeric character (`"1e6"` became 16, `"(5)"` became 5, `"Q1"` became 1). Both engines now call core `chartNumber`, which follows the existing data-import rule. A string that is not a strict decimal number is a gap in both engines and a `chart-value-not-numeric` warning, never a guessed value. Decks whose chart cells held `"12%"` or `"$5"` export a gap where they used to export 12 or 5.\n2. **`ChartDataSource` is removed from the schema.** No engine resolved it ([opf#240](https://github.com/OpenPresentation/opf/issues/240), descoped), so the format-audit program (FA-07, 2026-10-06) deleted it, with its `chart-data-source-unresolved` warning. A future data-resolver design re-adds it when it is built. Inline data records where it came from with `data.source`, which engines never read.\n3. **Number formats use the variables syntax.** One pattern language for `NumberVariable.format`, column formats and cell formats. Core converts it to an Excel format code for the PPTX export and back on import.\n4. **Datasets are top-level and shared.** A chart or a table references one with `{ "dataset": "<id>" }`. Core inlines references before composition, so the engines keep plotting and laying out inline data.\n5. **Series mapping is by column name.** `chart.mapping` picks the category, X and series columns. Absent keeps today\'s positional rule exactly.\n\nA document that uses none of the new fields validates, previews and exports byte-for-byte as before, except for decision 1 on non-numeric strings.\n\n## Schema\n\n### Number formats\n\n`NumberFormat` is a string with the `NumberVariable.format` syntax: an optional literal prefix, a numeric part made of `#`, `0`, `,` (grouping) and `.` (decimals), and an optional literal suffix. A `%` in the prefix or suffix multiplies the value by 100. Examples: `#,##0`, `0.0%`, `$#,##0.00`, `#,##0 units`. An invalid pattern is a `number-format-invalid` error. A format applies only to number values; strings, booleans, `null` and rich runs display unchanged.\n\nTwo spellings display differently in Excel, so prefer the alternatives in charts that are exported: optional decimals only (`0.##`) show a whole number as `5` in core and the preview but as `5.` (with a trailing point) in Excel, and an all-`#` integer part (`#`, `#,###`) shows zero as `0` in core but as nothing in Excel. Use `0.0#`-style decimals with at least one `0`, or a whole-number format, and an integer part that ends in `0`.\n\n### Columns\n\n`DataColumn` is `{ "name": string, "format"?: NumberFormat }`. Anywhere a chart or dataset column is a string, it may be a `DataColumn`; the string form is `{ "name": value }` with no format.\n\n```json\n"chart": {\n  "type": "column",\n  "data": {\n    "columns": ["Quarter", { "name": "Revenue", "format": "$#,##0.0" }, { "name": "Margin", "format": "0%" }],\n    "rows": [["Q1", 12.4, 0.31], ["Q2", 18.1, 0.34]]\n  }\n}\n```\n\nA table column header may also be a `DataColumn`. A `StyledTableCell` gains an optional `format`:\n- on a body cell, it formats that cell\'s number value;\n- on a header cell (in `columns`), it is the column\'s format, the same as a `DataColumn` header.\n\nA body cell\'s own format wins over the column\'s.\n\n```json\n"table": {\n  "columns": ["Region", { "name": "Revenue", "format": "$#,##0.0" }, { "value": "Growth", "style": { "align": "right" }, "format": "0%" }],\n  "rows": [["EMEA", 8.2, 0.4], ["APAC", 6.1, { "value": 0.52, "format": "0.0%" }]]\n}\n```\n\n### Data source provenance\n\n`DataSourceRef` is `{ "src": string, "sheet"?, "range"?, "fields"?: string[], "retrieved"?: string (ISO date or date-time), "description"?: string }`. It records where inline data or a dataset came from. Engines never read, fetch or refresh it; they keep it through editing, export and re-import. It may appear as `ChartData.source` and `Dataset.source`.\n\nThere is no chart data source by file or asset (`chart.data` with `src`, `sheet`, `range`, `columns`): that form is removed (opf#240, descoped) and is a schema error. Import the data inline with `columns`/`rows` and record its origin in `source`.\n\n### Datasets\n\nTop-level `datasets` maps ids (the `assets` id pattern) to a `Dataset`:\n\n```json\n{\n  "datasets": {\n    "revenue": {\n      "title": "Revenue by quarter",\n      "columns": ["Quarter", { "name": "Revenue", "format": "$#,##0.0" }, "Costs"],\n      "rows": [["Q1", 12, 8], ["Q2", 18, 11], ["Q3", 24, 15]],\n      "source": { "src": "./data/revenue.csv", "retrieved": "2026-10-05" }\n    }\n  }\n}\n```\n\nRows hold `ChartDataCell` scalars (string, number, boolean, null). A `DatasetRef` is `{ "dataset": "<id>", "fields"?: string[] }`; `fields` selects and orders columns by name, each at most once (a repeated name is a schema error).\n- **Chart:** `chart.data` may be a `DatasetRef`. It is the second `oneOf` branch beside `ChartData`.\n- **Table:** a table is either inline (`rows` required, optional `columns`) or dataset-backed (`dataset` required, optional `fields`, and no `rows` or `columns`). Dataset tables take their headers and column formats from the dataset; per-cell styles need an inline table.\n\nValidation:\n- an unknown dataset id is a `dataset-unknown` error;\n- an unknown field is a `dataset-field-unknown` error;\n- duplicate column names in a dataset, or in chart data that a `mapping` or `fields` addresses, are a `data-column-duplicate` error;\n- a dataset nothing references is the warning `opf/unused-dataset` (category `references`).\n\n### Series mapping\n\n`chart.mapping` is `{ "category"?: string, "x"?: string, "series"?: string[] }`, naming columns after any `fields` selection:\n- `category`: the label column. Default: the first column.\n- `x`: the X column of an XY (scatter) chart. Default, today\'s rule: the second column (the first when `category` names the second), and only when the chart has three or more columns. With two columns there is no X column: the second column is the one series, plotted against row numbers. An `x` that leaves no series (two columns, or every series dropped) is a `chart-mapping-adapted` warning and that column is plotted as the series. A chart is XY when its type resolves (deprecated ids through their replacement) to the scatter construct of `chartOptionTarget`. An `x` equal to the category is a `chart-mapping-adapted` warning and the default is used. On a chart type without an X axis it is dropped with a `chart-mapping-adapted` warning.\n- `series`: the plotted columns, in order. Default: every column that is not `category` or `x`.\n\nAn unknown name is a `chart-mapping-unknown-column` error. A series that repeats the category or X column is a `chart-mapping-adapted` warning and is dropped. Mapping only reorders and selects columns; pie, doughnut and single-series constructs still plot one series (`series-dropped`, as today).\n\n## Core runtime API\n\nExported from `@openpresentation/opf` and `@openpresentation/opf/data` (module `src/chart-data.ts`; the resolvers are also on `@openpresentation/opf/composition`). Inputs are typed `unknown` so engines can pass any parsed chart, table or document; the result types are exported (`ResolvedChartData`, `ResolvedTableData`, `DataDiagnostic`, `DataColumn`, `DataSourceRef`, `Dataset`, `DatasetRef`, `ChartMapping`, `DataCellValue`, `DataTableCell`, `DataTableHeader`, `DataStyledCell`).\n\n```ts\n/** Strict chart number: finite numbers, and strings in strict decimal syntax (trimmed). Everything else is null (a gap), including "+5", ".5", "5.", "007" and plain digit strings beyond the safe integer range (usually identifiers that would lose digits); a decimal or exponent form such as "1e20" is a number. */\nexport function chartNumber(value: unknown): number | null;\n/** Format a number with a NumberFormat; an absent or invalid format prints the General form (String(value)). */\nexport function formatDataNumber(value: number, format?: string): string;\n/** Why a NumberFormat is invalid (the number-format-invalid message), or undefined when it is valid or absent. */\nexport function numberFormatError(format: unknown): string | undefined;\n/** NumberFormat -> Excel format code ("General" when absent or invalid). Literal prefix/suffix text is quoted as one run ("0.0 m/s" -> \'0.0 "m/s"\'), so \'/\' (Excel\'s fraction bar), \'E+\', \'@\', \'*\', \'_\' and \'?\' are never bare (native check opf#387); placeholders are written \'#\' before \'0\' ("0#" -> "#0"). */\nexport function toExcelNumberFormat(format?: string): string;\n/** Excel format code -> NumberFormat, or undefined when the code has no exact NumberFormat equivalent (General, sections, scaling commas, and placeholder orders Excel reads by position such as "0#" or "0.#0"). */\nexport function fromExcelNumberFormat(code: string): string | undefined;\n/** Pure: a copy of the document where every chart and table DatasetRef is replaced by inline data (columns as DataColumn when a format applies, rows copied; a chart also takes the dataset\'s `source`). `datasets` stays in place. Unknown ids, and references naming an unknown field, are left as they are. */\nexport function inlineDatasets<T>(document: T): T;\n/** One table or chart in inline form (a dataset reference copied from document.datasets); anything else is returned as is. */\nexport function inlineTableData<T>(table: T, document?: unknown): T;\nexport function inlineChartData<T>(chart: T, document?: unknown): T;\n/**\n * Resolve a chart\'s data to the canonical positional table: [category, (x,) ...series]. hasX is true when columns[1] is the X\n * column: an XY chart with three or more resolved columns (with two, the second column is the series against row numbers).\n * Category cells are kept as authored; X and series cells pass through chartNumber. Data with a single column has no\n * category: that column is the chart\'s values and passes through chartNumber too (with chart-value-not-numeric per cell).\n * Inline ChartData, a DatasetRef (needs the document) and mapping are resolved here.\n * options.path is the chart\'s JSON Pointer, the base of diagnostic paths (dataset cells report at /datasets/<id>/...).\n */\nexport function resolveChartData(chart: unknown, document?: unknown, options?: { path?: string }):\n  | { ok: true; columns: string[]; hasX: boolean; formats: (string | undefined)[]; rows: (string | number | boolean | null)[][]; source?: DataSourceRef; dataset?: string; diagnostics: DataDiagnostic[] }\n  | { ok: false; reason: "dataset-unknown" | "no-rows" | "no-columns"; message: string; diagnostics: DataDiagnostic[] };\n/** Resolve a table (inline or dataset-backed) to headers, rows and per-column formats. */\nexport function resolveTableData(table: unknown, document?: unknown, options?: { path?: string }):\n  { columns?: DataTableHeader[]; rows: DataTableCell[][]; formats: (string | undefined)[]; dataset?: string; diagnostics: DataDiagnostic[] };\n/** Display value of a table cell: a number with a valid format (cell, else column) becomes formatted text (a styled cell keeps its style with the text as value); anything else is returned unchanged. */\nexport function tableCellDisplayValue(cell: DataTableCell, columnFormat?: string): DataTableCell;\n/** Migration help (see below): the patch that stores one chart value column\'s text as numbers with the format that shows the same text, or undefined. */\nexport function suggestChartNumberFix(chart: unknown, document?: unknown, options?: { path?: string; column?: number | string }):\n  { patches: { op: "replace"; path: string; value: unknown }[]; column: number; name: string; format: string } | undefined;\n/** Helpers: dataset-level diagnostics (duplicate names, invalid formats), unreferenced dataset ids, the XY test, the DatasetRef test. */\nexport function datasetDiagnostics(document: unknown): DataDiagnostic[];\nexport function unusedDatasets(document: unknown): string[];\nexport function isXYChartType(type: unknown): boolean;\nexport function isDatasetRef(value: unknown): value is DatasetRef;\n```\n\n`DataDiagnostic` is `{ code, severity: "error" | "warning", path, message }`, with the codes above plus `chart-value-not-numeric`. `chartNumber` runs after variables are filled. Before filling, the validator does not warn on a `var:<id>` cell whose variable is a number. `chart-value-not-numeric` is reported for any value cell that `chartNumber` rejects (strings and booleans), never for `null` or `""`. An unknown `fields` entry is a `dataset-field-unknown` error and `resolveChartData`/`resolveTableData` leave that column out. `number-format-invalid` applies to `DataColumn.format` and `StyledTableCell.format`; `NumberVariable.format` keeps its existing check (`variable-format` where it is used), so no existing document gains an error.\n\n`validate` reports the codes as `opf/<code>` rule ids: the errors are `format` findings, `opf/chart-value-not-numeric` and `opf/chart-mapping-adapted` are `content` warnings, `opf/chart-data-source-unresolved` is a `references` warning, and `references` adds `opf/unused-dataset`. The raw schema issue of a finding is in its `validation` field (`validation.params.code`).\n\n### Migration help\n\nDecks written before the strict rule often hold display text in chart cells. When every text cell of a value column (an X or series column, or a lone column) is written in one display style that a NumberFormat reproduces exactly, `suggestChartNumberFix` returns the fix, and `validate` attaches it to each of the column\'s `opf/chart-value-not-numeric` warnings as `fixes: [{ id: "store-chart-numbers", title, kind: "patch", safe: false, patch }]` (a [finding fix](finding-schema-reference.md); core never applies it):\n\n- `"12%"`, `"8.5%"` become 0.12 and 0.085 with the column format `0.#%`;\n- `"$1,234"`, `"$56"` become 1234 and 56 with `$#,##0` (also `\u20AC`, `\xA3`, `\xA5`);\n- `"1,234.5"`, `"999"` become 1234.5 (the plain number stays) with `#,##0.##`.\n\nThe patch replaces each text cell with its number and the column with a `DataColumn` that has the format; a dataset column is fixed in the dataset, so every chart and table that uses it changes, and its tables show the same text. A style is one optional leading minus, one optional currency symbol, digits (grouped in threes or plain), optional decimals and an optional `%`. There is no fix when the column already has a format, when styles are mixed (`"12%"` beside `"$5"` or beside the number 0.5), for accounting negatives `"(5)"`, `"$-5"`, a decimal comma (`"1.234,5"`), units (`"5 units"`), `".5"` or `"007"`, for mixed grouping (`"1,234"` beside `"5678"`), or when one format cannot show every value as written (`"$5"` beside `"$5.50"`). Every fixed value is checked: `formatDataNumber(value, format)` equals the text as written.\n\nCore composition, table layout and pagination accept dataset-backed tables and charts by inlining first. Table layout measures the formatted text. Markdown conversion, diff, merge, patch, validate and format keep the new fields. In detail:\n\n- `composeSlide` inlines a dataset-backed `table` or `chart` from `options.presentation.datasets`, so the composed item\'s `value` (and `payload`) is the inline copy; the item `path` still points at the authored field. `layoutTable(value, box, { presentation })` does the same, and each body cell\'s `TableCellLayout.value` is its display value (`tableCellDisplayValue`); `input` stays the authored cell. A DataColumn header shows its `name` (`path` ends in `.name`).\n- `paginateSlide`/`paginate` validate a slide with the deck\'s `datasets` (and `references`). A dataset table that has to be split is written to the continuation slides as inline tables (the slide that fits is returned unchanged, with its reference).\n- `convertContent` keeps a dataset reference between chart and table (`fields` too; `mapping` is reported as lost) and needs `options.presentation` to convert a dataset table to any other kind. Inline conversions keep DataColumn formats and report lost number formats and `source`. Slide-level conversions validate with the document\'s datasets; slide-only structure edits skip the dataset checks they cannot make.\n- Markdown writes the new fields in its embedded YAML form (lossless); `datasets` go to the front matter. `format` orders `datasets`, `mapping`, `source` and `DataColumn` keys by the schema. `diff` reports changes under `datasets` in their own category. The chart rules of `validate` read resolved chart data (DataColumn names, dataset charts).\n- Variables: `resolveVariables` walks `datasets` like any other content, so `{{id}}` tokens and whole `var:<id>` cells in dataset rows are filled before engines inline the reference.\n- `opf ingest --dataset <id>` (CLI) writes the imported columns and rows into `datasets.<id>` and references it. Re-importing into an existing dataset keeps its title, description and the format of each column whose name is unchanged; `source.src` names the imported file relative to the deck file\'s folder with `/` separators (stdin: no source), and `source.retrieved` is set only by `--date YYYY-MM-DD`; the command never reads the clock.\n- The generated `Table` type now has `rows?` (a dataset table has none) and `dataset?`/`fields?`; TypeScript callers that read `table.rows` handle the dataset form (or call `resolveTableData`).\n\n## Engines\n\nAll three engines read core\'s functions when they exist and fall back to their previous behaviour on a core without RR-54, so each can ship before or after core. A document that uses none of the new fields renders, exports and edits byte for byte as before (renderer: all 805 slides of the core examples; PPTX: 21 golden digests; editor: identical patches).\n\n### Preview (opf-render, [opf-render#127](https://github.com/OpenPresentation/opf-render/pull/127))\n\n- **Data:** every chart path reads `resolveChartData`: the catalog charts, the chartex constructs, scatter, pie and doughnut, single-column charts, and the legacy sketch. Its own `chartNumber` delegates to core\'s, so `"0x10"` is now a gap too. Data that does not resolve keeps the "No chart data" placeholder. A document with an unknown dataset or mapping column fails validation (`invalid-opf`) like any other invalid document.\n- **Formats:**\n  - Data labels use their series\' format, through `formatDataNumber`.\n  - Value-axis ticks use the first plotted series\' format, as Excel does for a source-linked axis.\n  - The scatter X axis and X labels use the X column\'s format.\n  - Percent axes (100% stacked, pareto) and pie percent labels stay percent.\n  - A histogram of a lone column plots counts and takes no format.\n- **Tables:** cells draw core layout\'s display text, so a body cell\'s own `format` wins over its column\'s.\n- **Tracing:** the editor relies on each drawn part\'s authored path.\n  - Every part of a dataset-backed chart or table traces to its authored `slides.N.chart` or `slides.N.table` path, because it has no rows of its own.\n  - A chart with `mapping` traces each part to the authored column index.\n\n### PPTX export (opf-pptx, [opf-pptx#171](https://github.com/OpenPresentation/opf-pptx/pull/171))\n\n- **Numbers:** the export resolves data through `resolveChartData`, and the lenient `parsedNumber`/`numericValue` are removed. Non-numeric strings export as gaps, with one `chart-value-not-numeric` diagnostic per chart that carries a `count`.\n- **Classic charts:** `toExcelNumberFormat` codes are written as:\n  - the series `c:numCache/c:formatCode` (added where PptxGenJS writes none, such as pie and doughnut);\n  - the series and chart-group data-label `c:numFmt sourceLinked="0"`;\n  - the value-axis `c:numFmt`. The first plotted series\' format is used, a scatter X axis takes the X column\'s, and a 100% stacked axis keeps `0%`.\n  - Labels that show percentages keep PowerPoint\'s percent form.\n- **Chartex:** `cx:lvl formatCode` and the value-label and value-axis `cx:numFmt`, except on binned constructs.\n- **Embedded workbook:** custom `numFmt` entries from id 164, with cell styles on every value cell, so Edit Data shows the formats.\n- **Tables:** tables export core layout\'s display text.\n- **Datasets and mapping:** a chart that uses them exports exactly like its inline equivalent.\n- **Provenance:** in `full` mode, `OPF_DATASETS_V1` holds the `datasets` map. `OPF_DATA_V1` sits on each chart or table frame that uses a new field and holds the authored `data`, `mapping` and table form (and, FA-14, a chart\'s `highlight`, which then also records its inline `data`; see [chart-options.md](chart-options.md)), plus a hash of the cached names, values and format codes. `references-only` mode and `provenance: false` write neither tag.\n\n### PPTX import (opf-pptx)\n\n- **With provenance:** `datasets` is restored before document provenance validates. A frame\'s dataset reference, `mapping`, formats and `source` are restored only while the cache hash still matches. If PowerPoint (or a person) changed the values, the native values import and a diagnostic says why, such as `chart-data-provenance-changed` or `table-dataset-unavailable`. The hash compares format codes in core\'s canonical form (`fromExcelNumberFormat`), so PowerPoint\'s re-spellings on save (`\\$#,##0.0` for `$#,##0.0`, `#,##0\\ "units"` for `#,##0 "units"`, native check [opf#385](https://github.com/OpenPresentation/opf/pull/385)) still match; a General code counts as no code.\n- **Without provenance:** a cache `formatCode` that `fromExcelNumberFormat` maps back becomes that column\'s `{ name, format }`, for both classic and chartex charts. Core returns the canonical spelling, such as `#,##0 units` for `#,##0 "units"`. Other codes are reported as `chart-number-format-adapted` and never invented.\n- **Cached values:** these follow the strict rule as well. XML decimal forms (`+5`, `.5`, `007`) are numbers; anything else is a gap with a diagnostic, never a stripped number or 0.\n\n### Editor (opf-editor, [opf-editor#92](https://github.com/OpenPresentation/opf-editor/pull/92))\n\n- **DataColumn headers:** the data grid shows a `DataColumn` header\'s `name`. Rename, insert, delete, move and paste keep each column\'s format.\n- **Chart cells:** they follow `chartNumber`. Text that is not a number is refused with the reason, and a stored string read as a gap is flagged.\n- **Shared datasets:** a dataset-backed chart or table is edited at `/datasets/<id>` through `fields`.\n  - Hidden columns keep their data.\n  - A column added while `fields` is set goes to both the dataset and `fields`.\n  - A rename updates every `fields` and `mapping` that names the column, in the same patch.\n  - Deleting a column another item uses is refused with `dataset-column-in-use`.\n  - The status line says how many items share the dataset, and "Use a copy of the data" (`detachGridDataset`) inlines one item\'s data.\n- **Format and mapping:**\n  - A per-column format field (`setGridColumnFormat`) is checked with `numberFormatError`.\n  - A "Chart columns" panel (`setChartMapping`) sets the category, the X column (XY charts only) and the series, and writes only what differs from the default.\n- **Import:** "Store as a shared dataset" (`prepareDatasetImport`) imports into `datasets.<id>`, as `opf ingest --dataset` does.\n- **Other panels:** the table style panel and `table-options` refuse a dataset table with `table-dataset-backed`. Find and replace also searches dataset text.\n- **Undo:** each edit is one undoable patch.\n\n### Native PowerPoint checks\n\nWanted before release:\n- formatted data labels and value axes;\n- Edit Data shows the workbook cell formats with no repair prompt;\n- no repair prompt for the frame `custDataLst`;\n- after a plain save in PowerPoint, the data tags and cache hash survive;\n- the two spellings above (`0.##` on a whole number, `#` on zero) show as described.\n\nSample decks are written by the PPTX branch under `artifacts/rr-54-native/`.\n\n## Not in this change\n\n- Resolving a data source by file or asset, or refreshing `source` ([opf#240](https://github.com/OpenPresentation/opf/issues/240)).\n- Date axes and date formats.\n- Per-series colours. (Columns with line series, optionally on a secondary axis, are the `combo` chart type: [chart-options.md](chart-options.md#combo-charts).)\n- Formulas.\n- Rich text in dataset cells.\n'
+    "markdown": '# Chart and table data: numbers, formats, datasets and series mapping\n\nStatus: RR-54 (release readiness). Additive schema plus one behaviour fix (strict chart numbers). These features are shipped in the coordinated package line; use the [compatibility matrix](compatibility-matrix.md) for the verified set. This page is the contract the four packages implement; change it here first.\n\n## Decisions (vetoable)\n\nRecorded 2026-10-05 for the owner, who asked for all five recommendations of the chart/table data review at once:\n\n1. **One strict chart number rule in core.** The preview read `"12%"` as a gap and `"1e6"` as 1000000; the exporter stripped every non-numeric character (`"1e6"` became 16, `"(5)"` became 5, `"Q1"` became 1). Both engines now call core `chartNumber`, which follows the existing data-import rule. A string that is not a strict decimal number is a gap in both engines and a `chart-value-not-numeric` warning, never a guessed value. Decks whose chart cells held `"12%"` or `"$5"` export a gap where they used to export 12 or 5.\n2. **`ChartDataSource` is removed from the schema.** No engine resolved it ([opf#240](https://github.com/OpenPresentation/opf/issues/240), descoped), so the format-audit program (FA-07, 2026-10-06) deleted it, with its `chart-data-source-unresolved` warning. A future data-resolver design re-adds it when it is built. Inline data records where it came from with `data.source`, which engines never read.\n3. **Number formats use the variables syntax.** One pattern language for `NumberVariable.format`, column formats and cell formats. Core converts it to an Excel format code for the PPTX export and back on import.\n4. **Datasets are top-level and shared.** A chart or a table references one with `{ "dataset": "<id>" }`. Core inlines references before composition, so the engines keep plotting and laying out inline data.\n5. **Series mapping is by column name.** `chart.mapping` picks the category, X and series columns. Absent keeps today\'s positional rule exactly.\n\nA document that uses none of the new fields validates, previews and exports byte-for-byte as before, except for decision 1 on non-numeric strings.\n\n## Schema\n\n### Number formats\n\n`NumberFormat` is a string with the `NumberVariable.format` syntax: an optional literal prefix, a numeric part made of `#`, `0`, `,` (grouping) and `.` (decimals), and an optional literal suffix. A `%` in the prefix or suffix multiplies the value by 100. Examples: `#,##0`, `0.0%`, `$#,##0.00`, `#,##0 units`. An invalid pattern is a `number-format-invalid` error. A format applies only to number values; strings, booleans, `null` and rich runs display unchanged.\n\nTwo spellings display differently in Excel, so prefer the alternatives in charts that are exported: optional decimals only (`0.##`) show a whole number as `5` in core and the preview but as `5.` (with a trailing point) in Excel, and an all-`#` integer part (`#`, `#,###`) shows zero as `0` in core but as nothing in Excel. Use `0.0#`-style decimals with at least one `0`, or a whole-number format, and an integer part that ends in `0`.\n\n### Columns\n\n`DataColumn` is `{ "name": string, "format"?: NumberFormat }`. Anywhere a chart or dataset column is a string, it may be a `DataColumn`; the string form is `{ "name": value }` with no format.\n\n```json\n"chart": {\n  "type": "column",\n  "data": {\n    "columns": ["Quarter", { "name": "Revenue", "format": "$#,##0.0" }, { "name": "Margin", "format": "0%" }],\n    "rows": [["Q1", 12.4, 0.31], ["Q2", 18.1, 0.34]]\n  }\n}\n```\n\nA table column header may also be a `DataColumn`. A `StyledTableCell` gains an optional `format`:\n- on a body cell, it formats that cell\'s number value;\n- on a header cell (in `columns`), it is the column\'s format, the same as a `DataColumn` header.\n\nA body cell\'s own format wins over the column\'s.\n\n```json\n"table": {\n  "columns": ["Region", { "name": "Revenue", "format": "$#,##0.0" }, { "value": "Growth", "style": { "align": "right" }, "format": "0%" }],\n  "rows": [["EMEA", 8.2, 0.4], ["APAC", 6.1, { "value": 0.52, "format": "0.0%" }]]\n}\n```\n\n### Data source provenance\n\n`DataSourceRef` is `{ "src": string, "sheet"?, "range"?, "fields"?: string[], "retrieved"?: string (ISO date or date-time), "description"?: string }`. It records where inline data or a dataset came from. Engines never read, fetch or refresh it; they keep it through editing, export and re-import. It may appear as `ChartData.source` and `Dataset.source`.\n\nThere is no chart data source by file or asset (`chart.data` with `src`, `sheet`, `range`, `columns`): that form is removed (opf#240, descoped) and is a schema error. Import the data inline with `columns`/`rows` and record its origin in `source`.\n\n### Datasets\n\nTop-level `datasets` maps ids (the `assets` id pattern) to a `Dataset`:\n\n```json\n{\n  "datasets": {\n    "revenue": {\n      "title": "Revenue by quarter",\n      "columns": ["Quarter", { "name": "Revenue", "format": "$#,##0.0" }, "Costs"],\n      "rows": [["Q1", 12, 8], ["Q2", 18, 11], ["Q3", 24, 15]],\n      "source": { "src": "./data/revenue.csv", "retrieved": "2026-10-05" }\n    }\n  }\n}\n```\n\nRows hold `ChartDataCell` scalars (string, number, boolean, null). A `DatasetRef` is `{ "dataset": "<id>", "fields"?: string[] }`; `fields` selects and orders columns by name, each at most once (a repeated name is a schema error).\n- **Chart:** `chart.data` may be a `DatasetRef`. It is the second `oneOf` branch beside `ChartData`.\n- **Table:** a table is either inline (`rows` required, optional `columns`) or dataset-backed (`dataset` required, optional `fields`, and no `rows` or `columns`). Dataset tables take their headers and column formats from the dataset; per-cell styles need an inline table.\n\nValidation:\n- an unknown dataset id is a `dataset-unknown` error;\n- an unknown field is a `dataset-field-unknown` error;\n- duplicate column names in a dataset, or in chart data that a `mapping` or `fields` addresses, are a `data-column-duplicate` error;\n- a dataset nothing references is the warning `opf/unused-dataset` (category `references`).\n\n### Series mapping\n\n`chart.mapping` is `{ "category"?: string, "x"?: string, "series"?: string[] }`, naming columns after any `fields` selection:\n- `category`: the label column. Default: the first column.\n- `x`: the X column of an XY (scatter) chart. Default, today\'s rule: the second column (the first when `category` names the second), and only when the chart has three or more columns. With two columns there is no X column: the second column is the one series, plotted against row numbers. An `x` that leaves no series (two columns, or every series dropped) is a `chart-mapping-adapted` warning and that column is plotted as the series. A chart is XY when its type resolves (deprecated ids through their replacement) to the scatter construct of `chartOptionTarget`. An `x` equal to the category is a `chart-mapping-adapted` warning and the default is used. On a chart type without an X axis it is dropped with a `chart-mapping-adapted` warning.\n- `series`: the plotted columns, in order. Default: every column that is not `category` or `x`.\n\nAn unknown name is a `chart-mapping-unknown-column` error. A series that repeats the category or X column is a `chart-mapping-adapted` warning and is dropped. Mapping only reorders and selects columns; pie, doughnut and single-series constructs still plot one series (`series-dropped`, as today).\n\n## Core runtime API\n\nExported from `@openpresentation/opf` and `@openpresentation/opf/data` (module `src/chart-data.ts`; the resolvers are also on `@openpresentation/opf/composition`). Inputs are typed `unknown` so engines can pass any parsed chart, table or document; the result types are exported (`ResolvedChartData`, `ResolvedTableData`, `DataDiagnostic`, `DataColumn`, `DataSourceRef`, `Dataset`, `DatasetRef`, `ChartMapping`, `DataCellValue`, `DataTableCell`, `DataTableHeader`, `DataStyledCell`).\n\n```ts\n/** Strict chart number: finite numbers, and strings in strict decimal syntax (trimmed). Everything else is null (a gap), including "+5", ".5", "5.", "007" and plain digit strings beyond the safe integer range (usually identifiers that would lose digits); a decimal or exponent form such as "1e20" is a number. */\nexport function chartNumber(value: unknown): number | null;\n/** Format a number with a NumberFormat; an absent or invalid format prints the General form (String(value)). */\nexport function formatDataNumber(value: number, format?: string): string;\n/** Why a NumberFormat is invalid (the number-format-invalid message), or undefined when it is valid or absent. */\nexport function numberFormatError(format: unknown): string | undefined;\n/** NumberFormat -> Excel format code ("General" when absent or invalid). Literal prefix/suffix text is quoted as one run ("0.0 m/s" -> \'0.0 "m/s"\'), so \'/\' (Excel\'s fraction bar), \'E+\', \'@\', \'*\', \'_\' and \'?\' are never bare (native check opf#387); placeholders are written \'#\' before \'0\' ("0#" -> "#0"). */\nexport function toExcelNumberFormat(format?: string): string;\n/** Excel format code -> NumberFormat, or undefined when the code has no exact NumberFormat equivalent (General, sections, scaling commas, and placeholder orders Excel reads by position such as "0#" or "0.#0"). */\nexport function fromExcelNumberFormat(code: string): string | undefined;\n/** Pure: a copy of the document where every chart and table DatasetRef is replaced by inline data (columns as DataColumn when a format applies, rows copied; a chart also takes the dataset\'s `source`). `datasets` stays in place. Unknown ids, and references naming an unknown field, are left as they are. */\nexport function inlineDatasets<T>(document: T): T;\n/** One table or chart in inline form (a dataset reference copied from document.datasets); anything else is returned as is. */\nexport function inlineTableData<T>(table: T, document?: unknown): T;\nexport function inlineChartData<T>(chart: T, document?: unknown): T;\n/**\n * Resolve a chart\'s data to the canonical positional table: [category, (x,) ...series]. hasX is true when columns[1] is the X\n * column: an XY chart with three or more resolved columns (with two, the second column is the series against row numbers).\n * Category cells are kept as authored; X and series cells pass through chartNumber. Data with a single column has no\n * category: that column is the chart\'s values and passes through chartNumber too (with chart-value-not-numeric per cell).\n * Inline ChartData, a DatasetRef (needs the document) and mapping are resolved here.\n * options.path is the chart\'s JSON Pointer, the base of diagnostic paths (dataset cells report at /datasets/<id>/...).\n */\nexport function resolveChartData(chart: unknown, document?: unknown, options?: { path?: string }):\n  | { ok: true; columns: string[]; hasX: boolean; formats: (string | undefined)[]; rows: (string | number | boolean | null)[][]; source?: DataSourceRef; dataset?: string; diagnostics: DataDiagnostic[] }\n  | { ok: false; reason: "dataset-unknown" | "no-rows" | "no-columns"; message: string; diagnostics: DataDiagnostic[] };\n/** Resolve a table (inline or dataset-backed) to headers, rows and per-column formats. */\nexport function resolveTableData(table: unknown, document?: unknown, options?: { path?: string }):\n  { columns?: DataTableHeader[]; rows: DataTableCell[][]; formats: (string | undefined)[]; dataset?: string; diagnostics: DataDiagnostic[] };\n/** Display value of a table cell: a number with a valid format (cell, else column) becomes formatted text (a styled cell keeps its style with the text as value); anything else is returned unchanged. */\nexport function tableCellDisplayValue(cell: DataTableCell, columnFormat?: string): DataTableCell;\n/** Migration help (see below): the patch that stores one chart value column\'s text as numbers with the format that shows the same text, or undefined. */\nexport function suggestChartNumberFix(chart: unknown, document?: unknown, options?: { path?: string; column?: number | string }):\n  { patches: { op: "replace"; path: string; value: unknown }[]; column: number; name: string; format: string } | undefined;\n/** Helpers: dataset-level diagnostics (duplicate names, invalid formats), unreferenced dataset ids, the XY test, the DatasetRef test. */\nexport function datasetDiagnostics(document: unknown): DataDiagnostic[];\nexport function unusedDatasets(document: unknown): string[];\nexport function isXYChartType(type: unknown): boolean;\nexport function isDatasetRef(value: unknown): value is DatasetRef;\n```\n\n`DataDiagnostic` is `{ code, severity: "error" | "warning", path, message }`, with the codes above plus `chart-value-not-numeric`. `chartNumber` runs after variables are filled. Before filling, the validator does not warn on a `var:<id>` cell whose variable is a number. `chart-value-not-numeric` is reported for any value cell that `chartNumber` rejects (strings and booleans), never for `null` or `""`. An unknown `fields` entry is a `dataset-field-unknown` error and `resolveChartData`/`resolveTableData` leave that column out. `number-format-invalid` applies to `DataColumn.format` and `StyledTableCell.format`; `NumberVariable.format` keeps its existing check (`variable-format` where it is used), so no existing document gains an error.\n\n`validate` reports the codes as `opf/<code>` rule ids: the errors are `format` findings, `opf/chart-value-not-numeric` and `opf/chart-mapping-adapted` are `content` warnings, `opf/chart-data-source-unresolved` is a `references` warning, and `references` adds `opf/unused-dataset`. The raw schema issue of a finding is in its `validation` field (`validation.params.code`).\n\n### Migration help\n\nDecks written before the strict rule often hold display text in chart cells. When every text cell of a value column (an X or series column, or a lone column) is written in one display style that a NumberFormat reproduces exactly, `suggestChartNumberFix` returns the fix, and `validate` attaches it to each of the column\'s `opf/chart-value-not-numeric` warnings as `fixes: [{ id: "store-chart-numbers", title, kind: "patch", safe: false, patch }]` (a [finding fix](finding-schema-reference.md); core never applies it):\n\n- `"12%"`, `"8.5%"` become 0.12 and 0.085 with the column format `0.#%`;\n- `"$1,234"`, `"$56"` become 1234 and 56 with `$#,##0` (also `\u20AC`, `\xA3`, `\xA5`);\n- `"1,234.5"`, `"999"` become 1234.5 (the plain number stays) with `#,##0.##`.\n\nThe patch replaces each text cell with its number and the column with a `DataColumn` that has the format; a dataset column is fixed in the dataset, so every chart and table that uses it changes, and its tables show the same text. A style is one optional leading minus, one optional currency symbol, digits (grouped in threes or plain), optional decimals and an optional `%`. There is no fix when the column already has a format, when styles are mixed (`"12%"` beside `"$5"` or beside the number 0.5), for accounting negatives `"(5)"`, `"$-5"`, a decimal comma (`"1.234,5"`), units (`"5 units"`), `".5"` or `"007"`, for mixed grouping (`"1,234"` beside `"5678"`), or when one format cannot show every value as written (`"$5"` beside `"$5.50"`). Every fixed value is checked: `formatDataNumber(value, format)` equals the text as written.\n\nCore composition, table layout and pagination accept dataset-backed tables and charts by inlining first. Table layout measures the formatted text. Markdown conversion, diff, merge, patch, validate and format keep the new fields. In detail:\n\n- `composeSlide` inlines a dataset-backed `table` or `chart` from `options.presentation.datasets`, so the composed item\'s `value` (and `payload`) is the inline copy; the item `path` still points at the authored field. `layoutTable(value, box, { presentation })` does the same, and each body cell\'s `TableCellLayout.value` is its display value (`tableCellDisplayValue`); `input` stays the authored cell. A DataColumn header shows its `name` (`path` ends in `.name`).\n- `paginateSlide`/`paginate` validate a slide with the deck\'s `datasets` (and `references`). A dataset table that has to be split is written to the continuation slides as inline tables (the slide that fits is returned unchanged, with its reference).\n- `convertContent` keeps a dataset reference between chart and table (`fields` too; `mapping` is reported as lost) and needs `options.presentation` to convert a dataset table to any other kind. Inline conversions keep DataColumn formats and report lost number formats and `source`. Slide-level conversions validate with the document\'s datasets; slide-only structure edits skip the dataset checks they cannot make.\n- Markdown writes the new fields in its embedded YAML form (lossless); `datasets` go to the front matter. `format` orders `datasets`, `mapping`, `source` and `DataColumn` keys by the schema. `diff` reports changes under `datasets` in their own category. The chart rules of `validate` read resolved chart data (DataColumn names, dataset charts).\n- Variables: `resolveVariables` walks `datasets` like any other content, so `{{id}}` tokens and whole `var:<id>` cells in dataset rows are filled before engines inline the reference.\n- `opf ingest --dataset <id>` (CLI) writes the imported columns and rows into `datasets.<id>` and references it. Re-importing into an existing dataset keeps its title, description and the format of each column whose name is unchanged; `source.src` names the imported file relative to the deck file\'s folder with `/` separators (stdin: no source), and `source.retrieved` is set only by `--date YYYY-MM-DD`; the command never reads the clock.\n- The generated `Table` type now has `rows?` (a dataset table has none) and `dataset?`/`fields?`; TypeScript callers that read `table.rows` handle the dataset form (or call `resolveTableData`).\n\n## Engines\n\nAll three engines read core\'s functions when they exist and fall back to their previous behaviour on a core without RR-54, so each can ship before or after core. A document that uses none of the new fields renders, exports and edits byte for byte as before (renderer: all 805 slides of the core examples; PPTX: 21 golden digests; editor: identical patches).\n\n### Preview (opf-render, [opf-render#127](https://github.com/OpenPresentation/opf-render/pull/127))\n\n- **Data:** every chart path reads `resolveChartData`: the catalog charts, the chartex constructs, scatter, pie and doughnut, single-column charts, and the legacy sketch. Its own `chartNumber` delegates to core\'s, so `"0x10"` is now a gap too. Data that does not resolve keeps the "No chart data" placeholder. A document with an unknown dataset or mapping column fails validation (`invalid-opf`) like any other invalid document.\n- **Formats:**\n  - Data labels use their series\' format, through `formatDataNumber`.\n  - Value-axis ticks use the first plotted series\' format, as Excel does for a source-linked axis.\n  - The scatter X axis and X labels use the X column\'s format.\n  - Percent axes (100% stacked, pareto) and pie percent labels stay percent.\n  - A histogram of a lone column plots counts and takes no format.\n- **Tables:** cells draw core layout\'s display text, so a body cell\'s own `format` wins over its column\'s.\n- **Tracing:** the editor relies on each drawn part\'s authored path.\n  - Every part of a dataset-backed chart or table traces to its authored `slides.N.chart` or `slides.N.table` path, because it has no rows of its own.\n  - A chart with `mapping` traces each part to the authored column index.\n\n### PPTX export (opf-pptx, [opf-pptx#171](https://github.com/OpenPresentation/opf-pptx/pull/171))\n\n- **Numbers:** the export resolves data through `resolveChartData`, and the lenient `parsedNumber`/`numericValue` are removed. Non-numeric strings export as gaps, with one `chart-value-not-numeric` diagnostic per chart that carries a `count`.\n- **Classic charts:** `toExcelNumberFormat` codes are written as:\n  - the series `c:numCache/c:formatCode` (added where PptxGenJS writes none, such as pie and doughnut);\n  - the series and chart-group data-label `c:numFmt sourceLinked="0"`;\n  - the value-axis `c:numFmt`. The first plotted series\' format is used, a scatter X axis takes the X column\'s, and a 100% stacked axis keeps `0%`.\n  - Labels that show percentages keep PowerPoint\'s percent form.\n- **Chartex:** `cx:lvl formatCode` and the value-label and value-axis `cx:numFmt`, except on binned constructs.\n- **Embedded workbook:** custom `numFmt` entries from id 164, with cell styles on every value cell, so Edit Data shows the formats.\n- **Tables:** tables export core layout\'s display text.\n- **Datasets and mapping:** a chart that uses them exports exactly like its inline equivalent.\n- **Provenance:** in `full` mode, `OPF_DATASETS_V1` holds the `datasets` map. `OPF_DATA_V1` sits on each chart or table frame that uses a new field and holds the authored `data`, `mapping` and table form (and, FA-14, a chart\'s `highlight`, which then also records its inline `data`; see [chart-options.md](chart-options.md)), plus a hash of the cached names, values and format codes. `references-only` mode and `provenance: false` write neither tag.\n\n### PPTX import (opf-pptx)\n\n- **With provenance:** `datasets` is restored before document provenance validates. A frame\'s dataset reference, `mapping`, formats and `source` are restored only while the cache hash still matches. If PowerPoint (or a person) changed the values, the native values import and a diagnostic says why, such as `chart-data-provenance-changed` or `table-dataset-unavailable`. The hash compares format codes in core\'s canonical form (`fromExcelNumberFormat`), so PowerPoint\'s re-spellings on save (`\\$#,##0.0` for `$#,##0.0`, `#,##0\\ "units"` for `#,##0 "units"`, native check [opf#385](https://github.com/OpenPresentation/opf/pull/385)) still match; a General code counts as no code.\n- **Without provenance:** a cache `formatCode` that `fromExcelNumberFormat` maps back becomes that column\'s `{ name, format }`, for both classic and chartex charts. Core returns the canonical spelling, such as `#,##0 units` for `#,##0 "units"`. Other codes are reported as `chart-number-format-adapted` and never invented.\n- **Cached values:** these follow the strict rule as well. XML decimal forms (`+5`, `.5`, `007`) are numbers; anything else is a gap with a diagnostic, never a stripped number or 0.\n\n### Editor (opf-editor, [opf-editor#92](https://github.com/OpenPresentation/opf-editor/pull/92))\n\n- **DataColumn headers:** the data grid shows a `DataColumn` header\'s `name`. Rename, insert, delete, move and paste keep each column\'s format.\n- **Chart cells:** they follow `chartNumber`. Text that is not a number is refused with the reason, and a stored string read as a gap is flagged.\n- **Shared datasets:** a dataset-backed chart or table is edited at `/datasets/<id>` through `fields`.\n  - Hidden columns keep their data.\n  - A column added while `fields` is set goes to both the dataset and `fields`.\n  - A rename updates every `fields` and `mapping` that names the column, in the same patch.\n  - Deleting a column another item uses is refused with `dataset-column-in-use`.\n  - The status line says how many items share the dataset, and "Use a copy of the data" (`detachGridDataset`) inlines one item\'s data.\n- **Format and mapping:**\n  - A per-column format field (`setGridColumnFormat`) is checked with `numberFormatError`.\n  - A "Chart columns" panel (`setChartMapping`) sets the category, the X column (XY charts only) and the series, and writes only what differs from the default.\n- **Import:** "Store as a shared dataset" (`prepareDatasetImport`) imports into `datasets.<id>`, as `opf ingest --dataset` does.\n- **Other panels:** the table style panel and `table-options` refuse a dataset table with `table-dataset-backed`. Find and replace also searches dataset text.\n- **Undo:** each edit is one undoable patch.\n\n### Native PowerPoint checks\n\nWanted before release:\n- formatted data labels and value axes;\n- Edit Data shows the workbook cell formats with no repair prompt;\n- no repair prompt for the frame `custDataLst`;\n- after a plain save in PowerPoint, the data tags and cache hash survive;\n- the two spellings above (`0.##` on a whole number, `#` on zero) show as described.\n\nSample decks are written by the PPTX branch under `artifacts/rr-54-native/`.\n\n## Not in this change\n\n- Resolving a data source by file or asset, or refreshing `source` ([opf#240](https://github.com/OpenPresentation/opf/issues/240)).\n- Date axes and date formats.\n- Per-series colors: shipped later as `chart.colors`; see [chart-options.md](chart-options.md#setting-colors-chartcolors). (Columns with line series, optionally on a secondary axis, are the `combo` chart type: [chart-options.md](chart-options.md#combo-charts).)\n- Formulas.\n- Rich text in dataset cells.\n'
   },
   {
     "slug": "cli",
@@ -46,7 +46,7 @@ var docsData = Object.freeze([
     "slug": "content-payloads",
     "file": "docs/content-payloads.md",
     "title": "Content Payloads",
-    "markdown": '# Content Payloads\n\nSlide content lives directly on a slide as a full-slide payload, in layout-agnostic `blocks`, or inside a promoted region key such as `left`, `center+right`, or `top:left`.\n\nThe slide-level `title`, `subtitle` and `tag` are not payloads, but like `text` and `quote.text` they accept a string or `TextRun[]` (colored words, bold, links, `cite`/`footnote` markers); see [Rich text](rich-text.md#rich-headings-and-quotes).\n\nThe optional payload `type` can make intent explicit, but OPF should usually infer the content kind from the field present:\n\n| Field | Inferred type | Notes |\n| --- | --- | --- |\n| `text` | `text` | Plain string or `TextRun[]`. |\n| `bullets` | `text` | Prose bullets: plain talking points, usually `string[]`. |\n| `items` | `list` | Structured list: entries that share a shape or carry a `description`; `string[]` or `ListItem[]`. See [items versus bullets](#items-versus-bullets). |\n| `image` | `image` | Asset string shorthand or `Asset` object with `src` and optional metadata. |\n| `video` | `video` | Asset string shorthand or `Asset` object with `src` and optional metadata. |\n| `chart` | `chart` | Chart object with `type` and tabular `data`. |\n| `table` | `table` | Table object with optional `columns` and required `rows`. |\n| `code` | `code` | String shorthand or `Code` object with `source`, `language`, `filename`, and `highlight`. |\n| `metric` | `metric` | String/number shorthand or `Metric` object with `value`, `label`, `description`, `unit`, `delta`, `trend`, and `sentiment`. |\n| `quote` | `quote` | String shorthand or `Quote` object with `text` (string or `TextRun[]`), `attribution`, `role`, `photo`, and `source`. |\n| `timeline` | `timeline` | Array shorthand or `Timeline` object with `name`, `description`, and `events`. |\n\n## Items versus bullets\n\nBoth fields draw the same bulleted (or numbered) list: one marker, the same nesting `level`, rich-text entries and `numbering`, fitted by the same list engine. Nothing about the drawing differs. They differ in the kind they infer and in what an entry may carry:\n\n| | `bullets` | `items` |\n| --- | --- | --- |\n| Inferred kind | `text` | `list` |\n| Entry | string, `TextRun[]` or `{ text, level, start }` | string, `TextRun[]` or `{ text, description, level, start }` |\n| `description` | not allowed (a schema error) | supporting detail drawn under the entry |\n| Beside `text` in one block or region | allowed | an error (`list` and `text` are different kinds) |\n\n**The rule.** Use `bullets` for plain talking points: short lines that each stand alone. Use `items` when the entries share a shape (features, steps, options, risks) or any entry needs a `description`; never fold a heading and its detail into one string with a separator, that is what `description` is for. When in doubt, use `items`, because it can grow a `description` later without changing the payload kind. The editor helper `convertListForm` switches a payload between the two; going to `bullets` drops the descriptions.\n\nDo not give one payload both. In a block or a promoted region, `items` next to `bullets` is the error "content payload mixes fields from incompatible content types". At slide root it validates, as the shorthand for two blocks, and composes as two lists side by side; write two blocks on purpose if you want that. `numbering` applies to every list in the payload.\n\nA layout\'s placeholder kind (`list` or `text`) is what layout pickers match on (`layoutContent`), but composition does not refuse the other field and draws both the same way: the choice states what the content is, it is not a switch for the look.\n\n## Code highlight\n\n`code.highlight` marks lines of a code block: a line number or an inclusive `[start, end]` range, 1-based, for example `[3, [5, 7]]`. Lines are counted by line break in `code.source`; a line that wraps is still one line. The preview and the PPTX export draw a theme-derived band behind the marked lines and dim the others slightly; every line keeps at least 4.5:1 contrast against what it sits on (`codeHighlightColors`). The PPTX export draws one native rectangle per run of marked lines behind the per-line text boxes, and import restores `highlight` from the code provenance tag. A line past the last line, or a range written end before start, is the validation warning `code-highlight-out-of-range` or `code-highlight-range-reversed`, and engines ignore it. Pagination keeps each page\'s marked lines, renumbered from 1.\n\n## Color references\n\nEvery content color field \u2014 `TextRun.color`, styled table cell `style.fill` and `style.color`, and table cell border `color` \u2014 accepts three forms:\n\n- A literal hex color: `"#0F172A"`, `"#B42318CC"`.\n- A color-scheme slot or role name, resolved through the effective color scheme after design resolution: slots `accent1`\u2013`accent6`, `dark1`, `dark2`, `light1`, `light2`, `hyperlink`, `followedHyperlink`; roles `primary`, `secondary`, `accent`, `background`, `surface`, `surfaceAlt`, `text`, `textSecondary`. `surfaceAlt` is the alternate surface for banded table rows: core derives it from `surface` and `text` (`surfaceAltColor`), so it always differs visibly from the `surface` of the plain rows, on light and dark slides, and body text keeps 4.5:1 on it.\n- A variable reference `var:<id>` into the top-level `variables` map.\n\n```json\n{\n  "variables": { "risk": "#B42318" },\n  "slides": [\n    {\n      "title": "What Could Go Wrong",\n      "items": [\n        ["Two regions at ", { "text": "85% utilization", "color": "var:risk", "bold": true }],\n        ["Mitigations ship in ", { "text": "November", "color": "accent2" }]\n      ]\n    }\n  ]\n}\n```\n\nPrefer names and variables over literal hex: re-theming the deck updates every named reference, while a hex value stays frozen at authoring time. An unknown `var:` id is a validation warning, never an error; engines fall back to their default text color. The styled table cell and border color fields enforce the three forms at the schema level; run colors additionally accept any string so imported decks keep validating \u2014 unrecognized values warn, and renderers fall back to the theme color. See [`design-resolution.md`](./design-resolution.md) for the resolution rules.\n\n## Numbered lists\n\n`numbering` on an `items` or `bullets` payload draws numbers instead of bullets: a style name (`arabic`, `roman-upper`, `roman-lower`, `alpha-upper`, `alpha-lower`), a `{ style, start, suffix }` object, or an array with one entry per list level. PowerPoint export writes native auto-numbers and the preview draws the same numbers. See [numbered lists](numbered-lists.md).\n\n```json\n{ "items": ["Define", "Build", "Ship"], "numbering": { "style": "roman-lower", "suffix": "paren" } }\n```\n\n## Blocks\n\nUse slide-level `blocks` when a slide contains multiple content payloads, but exact placement should be inferred by the renderer. Blocks may contain a concrete content payload or a nested group with its own `blocks` and optional `composition`. Groups cannot mix child blocks with leaf payload fields. See [dynamic composition](dynamic-composition.md) for nesting and inheritance rules.\n\n```json\n{\n  "title": "Customer Feedback Summary",\n  "blocks": [\n    {\n      "table": {\n        "columns": ["Theme", "Mentions"],\n        "rows": [\n          ["Speed", 42],\n          ["Ease of use", 31]\n        ]\n      }\n    },\n    {\n      "quote": {\n        "text": "The new workflow cut review time in half.",\n        "attribution": "Operations Lead",\n        "source": "Customer interview"\n      }\n    }\n  ]\n}\n```\n\nAt slide root only, multiple content payload kinds are accepted as shorthand for the equivalent blocks form when there is no explicit `type`, no `blocks`, and no promoted region keys:\n\n```json\n{\n  "title": "Habitat & Territory",\n  "text": "Jaguars are strongly associated with presence of water and dense cover.",\n  "items": [\n    "Primary habitats include dense rainforests, swamps, and seasonally flooded wetlands.",\n    "Solitary animals that establish and defend large territories."\n  ]\n}\n```\n\nThe same shorthand works for other content kinds:\n\n```json\n{\n  "title": "Evidence Snapshot",\n  "chart": {\n    "type": "line",\n    "data": {\n      "columns": ["Quarter", "Sightings"],\n      "rows": [\n        ["Q1", 12],\n        ["Q2", 18]\n      ]\n    }\n  },\n  "quote": {\n    "text": "Jaguar conservation depends on connected habitat.",\n    "attribution": "Field researcher"\n  }\n}\n```\n\n## Chart\n\nChart-specific fields are grouped under `chart`. Do not put loose chart data directly on a slide or region.\n\n```json\n{\n  "title": "Revenue Trend",\n  "chart": {\n    "type": "line",\n    "data": {\n      "columns": ["Quarter", "Revenue", "Costs"],\n      "rows": [\n        ["Q1", 12, 8],\n        ["Q2", 18, 11],\n        ["Q3", 24, 15]\n      ]\n    }\n  }\n}\n```\n\nInline chart data is tabular by default. Renderers convert `columns` and `rows` into series, axes, legends, and workbook data internally.\n\nGive every chart an `alt`: one or two sentences that say what the data shows (the point and the key numbers), not "a chart" or "bar chart". The preview names the chart with it (`role="img"`, `aria-label`) and the PowerPoint export writes it as the chart frame\'s alternative text (`descr`), which `fromPptx` reads back. `"alt": ""` marks a chart decorative, as an empty image `alt` does; `validate` (`opf/chart-text-alternative`) still reports it as info so the choice is reviewed. Without `alt`, text beside the chart (a subtitle, text or table) satisfies the rule. See [chart options](chart-options.md#text-alternative).\n\nValue cells are numbers. A string is read only in strict decimal syntax (`"12"`, `" -3.5 "`, `"1e6"`); anything else (`"12%"`, `"$5"`, `"(5)"`, `"1,234"`, `"Q1"`) is a gap in the preview and the export and a `chart-value-not-numeric` warning, never a guessed value. `null` and `""` are gaps without a warning. Core `chartNumber` is the one rule every engine uses (RR-54; before it the PPTX exporter stripped non-numeric characters, so `"12%"` exported as 12).\n\nA column is a string or a `DataColumn` with a number format, which the data labels, the value axis and the exported workbook use:\n\n```json\n{\n  "chart": {\n    "type": "column",\n    "data": {\n      "columns": ["Quarter", { "name": "Revenue", "format": "$#,##0.0" }, { "name": "Margin", "format": "0%" }],\n      "rows": [["Q1", 12.4, 0.31], ["Q2", 18.1, 0.34]],\n      "source": { "src": "./data/revenue.csv", "retrieved": "2026-10-05" }\n    },\n    "mapping": { "category": "Quarter", "series": ["Revenue"] }\n  }\n}\n```\n\nFormats use the `NumberVariable.format` syntax (`#,##0`, `0.0%`, `$#,##0.00`, `#,##0 units`; a `%` multiplies by 100). `source` records provenance only; engines never read or refresh it. `mapping` picks the category, the X column of a scatter chart and the plotted series by column name; without it the first column is the category and every other column a series. Shared data lives in the top-level `datasets` map and a chart plots it with `"data": { "dataset": "revenue", "fields": ["Quarter", "Revenue"] }`. The full contract, with validation codes and the engine behaviour, is [Chart and table data](chart-table-data.md).\n\nChart data is inline columns and rows or a dataset. A data source by file or asset (`"data": { "src": "asset:revenue-csv", "columns": [...] }`) is not part of the format: no engine loaded it, and the validator rejects it. Import the data inline (with a `source`) or into a dataset instead.\n\n## Table\n\nTable-specific fields are grouped under `table`. Do not put loose `columns` or `rows` directly on a slide or region.\n\n```json\n{\n  "title": "Pipeline",\n  "table": {\n    "columns": ["Stage", "Count", "Value"],\n    "rows": [\n      ["Qualified", 42, "$1.2M"],\n      ["Proposal", 18, "$840K"]\n    ]\n  }\n}\n```\n\nA table may instead show a dataset: `"table": { "dataset": "revenue", "fields": ["Quarter", "Revenue"] }` (no `rows` or `columns`); it takes its headers, rows and column formats from the dataset, and per-cell styles need an inline table. A column header may be a `DataColumn` (`{ "name": "Revenue", "format": "$#,##0.0" }`) and a styled header or body cell takes a `format`; a number cell displays formatted (the body cell\'s own format wins over the column\'s), and `layoutTable` measures the formatted text. See [Chart and table data](chart-table-data.md).\n\nTable body cells accept strings, numbers, booleans, or `null`. Since core 0.5.0, a cell or column header also accepts the same `TextRun[]` used by rich text:\n\n```json\n{\n  "table": {\n    "columns": [["Quarter ", {"text": "growth", "bold": true}], "Value"],\n    "rows": [\n      [["Up ", {"text": "12%", "color": "#008800"}], 12]\n    ]\n  }\n}\n```\n\nUse the coordinated Node 24 set recorded in [release-plan.json](../release-plan.json) and the [compatibility matrix](compatibility-matrix.md) for exact pins and evidence. Core measures run styles when checking overflow and keeps each row intact when paginating. The renderer traces rich cells for the editor\'s existing formatting, typing and undo controls; the exporter emits editable native text runs. PPTX 0.4.0 introduced import of supported native character styles, paragraph defaults, theme fonts/colors, external links and significant whitespace as rich runs. Unstyled body cells remain strings, and cached display text cannot recover original scalar types or live fields. Conditional table styles, merged geometry and cell fills/borders/alignment remain limited; native PowerPoint visual parity is not yet verified.\n\nA table may carry an `alt` (FA-27), the same text alternative as `Chart.alt`: one or two sentences that say what the table shows (the point and the key numbers), not "a table". The preview names the table with it (a `role="group"` with `aria-label`; the cells stay readable) and the PowerPoint export writes it as the table frame\'s alternative text (`descr`), which `fromPptx` reads back. `"alt": ""` hides a purely decorative table, as an empty image `alt` does. Unlike a chart, a table needs no `alt`: a screen reader reads a native table cell by cell, so `validate` reports nothing when it is missing, and a table beside a chart still counts as that chart\'s text alternative. The `alt` is a summary read before the cells, which stay readable text (in PowerPoint too, where `descr` on a table frame does not hide its cells), so it is most useful for a large or dense table.\n\nCore 0.6.0 adds `layoutTable` from `@openpresentation/opf/composition`. It measures scalar and rich cells, keeps short rows compact, and gives wrapped or multiline rows the height they need. When space is constrained it reduces spare row height before shrinking text, and reports overflow when the minimum fitting size cannot fit. Pass the same `scale`, font family, measurement provider and effective `minFontSize` to each consumer. The returned row boxes, cell text boxes and fits are shared by the coordinated SVG and PPTX implementations; rich table cells use uniform line advances to match native cell paragraph spacing. Native viewer fidelity remains a separate verification boundary.\n\n## Captions\n\nAn `image`, `chart`, `table` or `video` payload takes a `caption`: a string, `TextRun[]`, or `{ "text", "position": "below" | "above", "align": "left" | "center" | "right" }` (defaults `below`, `left`). It sits beside the payload field on a block or promoted-region payload, or on the slide root when the root holds exactly one of those payloads; anywhere else it is a `caption-unsupported-payload` error.\n\n```json\n{\n  "title": "Pipeline",\n  "blocks": [\n    { "image": "asset:funnel", "caption": "Figure 1. Pipeline by stage, Q3" },\n    { "table": { "columns": ["Stage", "Count"], "rows": [["Qualified", 42]] }, "caption": { "text": "Table 1. Counts", "position": "above", "align": "center" } }\n  ]\n}\n```\n\nCore composition reserves the caption band inside the block\'s region and shrinks the media by its height (`item.caption` carries the band, `item.box` is the media box); the preview and the PPTX export draw that band in the muted text colour at the caption size (0.6 of the body size, never under the readable floor). Captioned blocks are the only ones whose geometry changes. See [footnotes, citations and captions](footnotes-citations-captions.md).\n\n## Code\n\nCode-specific fields are grouped under `code`. A string value is shorthand for `code.source`; use object form when syntax highlighting or a file label matters. In object form, `source` is required. `language` colours the code in the preview and the PowerPoint export (comments, strings, numbers, keywords, names and types, in colours from the deck theme); an unknown language stays plain and the text is never changed. See [dynamic composition](dynamic-composition.md#preview-polish-shared-by-preview-and-export-rr-07) for the supported languages.\n\n```json\n{\n  "title": "Decision Rule",\n  "code": {\n    "source": "if risk > threshold:\\n    escalate(owner)\\nelse:\\n    approve(change)",\n    "language": "python",\n    "filename": "decision.py"\n  }\n}\n```\n\n## Metric\n\nMetric-specific fields are grouped under `metric`. A string or number value is shorthand for `metric.value`; numeric values stay numeric and are formatted by renderers at display time. Use object form when labels, descriptions, units, deltas, trends, or sentiment matter. A `trend` (`up`, `down`, `flat`) draws an arrow beside its word, coloured with the delta text, in the preview and the PowerPoint export; the arrow always points the way the trend does, and its colour follows `sentiment` (`positive` green, `negative` red, `neutral` the neutral text colour). When `sentiment` is absent up is positive, down is negative and flat is neutral, so set it when the direction is not the verdict: a falling churn, cost or latency is `"trend": "down", "sentiment": "positive"`. Only the trend arrow and the trend and delta text take the colour, so `sentiment` has no visible effect on a metric without a `trend`; the word stays editable text and the arrow carries "Trend: up" as its alternative text (see [dynamic composition](dynamic-composition.md#preview-polish-shared-by-preview-and-export-rr-07)).\n\nThe `metrics` v2 layout accepts metric blocks in its body region and flows them as a grid. For several metrics, use separate `{ "metric": ... }` entries in `blocks`; the content kind and payload key are `metric`. Choosing a layout does not reinterpret existing text as numeric data.\n\n```json\n{\n  "title": "Operating Metric",\n  "metric": {\n    "value": "42%",\n    "label": "Review cycle reduction",\n    "description": "Median reduction across customer review workflows.",\n    "delta": "+11 pts",\n    "trend": "up"\n  }\n}\n```\n\nA falling value that is good news keeps its downward arrow and takes the green:\n\n```json\n{\n  "title": "Churn",\n  "metric": {\n    "value": "3.1%",\n    "label": "Monthly churn",\n    "delta": "-0.6 pts",\n    "trend": "down",\n    "sentiment": "positive"\n  }\n}\n```\n\n## Quote\n\nQuote-specific fields are grouped under `quote`. A string value is shorthand for `quote.text`; use object form when attribution or citation matters. `text` is a string or `TextRun[]` with inline formatting; `attribution`, `role` and `source` are plain strings.\n\n```json\n{\n  "title": "Customer Proof",\n  "quote": {\n    "text": "The new workflow made exceptions visible before they became escalations.",\n    "attribution": "Priya Raman",\n    "source": "Customer interview"\n  }\n}\n```\n\nA testimonial attributes the quote to a person with a title and a face. `role` is the person\'s title and organization, and `photo` is their headshot, an `Asset` (a source string or an object with `src` and `alt`):\n\n```json\n{\n  "title": "Customer Proof",\n  "quote": {\n    "text": "The new workflow made exceptions visible before they became escalations.",\n    "attribution": "Priya Raman",\n    "role": "VP Operations, Acme",\n    "photo": { "src": "asset:priya-raman", "alt": "Priya Raman" },\n    "source": "Customer interview, March 2026"\n  }\n}\n```\n\nThe footer under the quote is the attribution, then the role on its own line, then the source after ` - ` on the last line. Without a `role` it is the single line it always was (`attribution - source`). With a `photo`, the headshot is a circle at the start edge of the footer row (the left in a left-to-right deck, the right in a right-to-left one), three times the footer font size across, and the footer lines sit beside it, centered on it. The photo is cropped to fill the circle, and its size follows the footer\'s font size when the readability floor shrinks the footer. Without a `photo` nothing else changes. The preview draws it with the circular clip that an image block uses for shape `circle`, and PowerPoint export writes a native picture with the `ellipse` geometry and the alt text as its description; importing that file restores `role` and `photo`. A photo needs alt text (the `opf/missing-alt-text` rule of `validate` checks `quote.photo`); an SVG photo exports as its PNG raster. A photo with no attribution, role or source still draws, alone in the footer row. The Markdown dialect has no native form for `role` and `photo`: a quote that carries them is written as an `opf` block, which round trips exactly, and a plain `> \u2014 Name, Title` line stays an attribution.\n\n## Timeline\n\nTimeline-specific fields are grouped under `timeline`. An array value is shorthand for `timeline.events`; use object form when the timeline needs a name or description. Timeline events use `when`, `what`, `description` and `status`. `status` is `done`, `current` or `planned` and marks progress: `done` is a filled marker with normal text, `current` ("we are here") is a ringed marker with a bold label, and `planned` is a hollow outlined marker with muted text. An event without a status draws as a plain filled marker. Schedule health (at risk, blocked) is not a status; say it in the event text. See [Dynamic composition](dynamic-composition.md#timeline-internals) for the exact drawing.\n\n```json\n{\n  "title": "Rollout Plan",\n  "timeline": {\n    "name": "Regional Rollout",\n    "description": "Major milestones for the rollout.",\n    "events": [\n      {\n        "when": "Q1",\n        "what": "Pilot",\n        "description": "Launch with one operations team."\n      },\n      {\n        "when": "Q2",\n        "what": "Rollout",\n        "description": "Expand to all regions."\n      }\n    ]\n  }\n}\n```\n\nA roadmap with progress states:\n\n```json\n{\n  "title": "Product roadmap",\n  "timeline": [\n    { "when": "Q1", "what": "Discovery", "status": "done" },\n    { "when": "Q2", "what": "Pilot", "status": "current" },\n    { "when": "Q3", "what": "Rollout", "status": "planned" }\n  ]\n}\n```\n\n## Regions\n\nRegion keys address a 3\xD73 grid of rows (`top`, `middle`, `bottom`) and columns (`left`, `center`, `right`):\n\n```\n                  left                 center                 right\n         +--------------------+--------------------+--------------------+\n   top   |  top:left          |  top:center        |  top:right         |\n         +--------------------+--------------------+--------------------+\n  middle |  middle:left       |  middle:center     |  middle:right      |\n         +--------------------+--------------------+--------------------+\n  bottom |  bottom:left       |  bottom:center     |  bottom:right      |\n         +--------------------+--------------------+--------------------+\n```\n\n- A bare column key (`left`) spans all three rows; a bare row key (`top`) spans all three columns.\n- `+` spans adjacent rows or columns: `center+right`, `top+middle`.\n- `row:column` combines the two: `top:left`, `middle+bottom:center+right`.\n- Keys on one slide must not overlap, and regions cannot be mixed with root payload fields.\n\nSpans compose into common slide shapes:\n\n```\n  "left" + "center+right"             "top" + "middle+bottom"\n  (sidebar + main)                    (headline band + body)\n  +----------+------------------+     +-------------------------------+\n  |          |                  |     |              top              |\n  |          |                  |     +-------------------------------+\n  |   left   |  center+right    |     |                               |\n  |          |                  |     |         middle+bottom         |\n  |          |                  |     |                               |\n  +----------+------------------+     +-------------------------------+\n\n  "top" + "middle+bottom:left" + "middle+bottom:center+right"\n  (headline band, then sidebar + main)\n  +---------------------------------------------+\n  |                     top                     |\n  +---------------+-----------------------------+\n  |               |                             |\n  | middle+bottom | middle+bottom:center+right  |\n  | :left         |                             |\n  |               |                             |\n  +---------------+-----------------------------+\n```\n\nThe same payload objects work inside regions \u2014 here, the sidebar-plus-main shape:\n\n```json\n{\n  "title": "Operating Snapshot",\n  "left": {\n    "table": {\n      "columns": ["Metric", "Value"],\n      "rows": [\n        ["Revenue", "$4.2M"],\n        ["Gross margin", "68%"]\n      ]\n    }\n  },\n  "center+right": {\n    "chart": {\n      "type": "line",\n      "data": {\n        "columns": ["Month", "Revenue"],\n        "rows": [\n          ["Jan", 3.4],\n          ["Feb", 3.8],\n          ["Mar", 4.2]\n        ]\n      }\n    }\n  }\n}\n```\n\n## Accessibility of the preview\n\nThe SVG preview and the PowerPoint export agree on what a reader can reach. The slide root is a labelled container (`role="group"`, `aria-roledescription="slide"`, `aria-label` set to the slide title), never an image: an image makes everything inside it presentational, so a screen reader would hear only the title. Text stays reachable, in the order it is drawn: tag, title and subtitle, the content in layout order, footnotes, then header and footer. That covers body text, list entries, quotes, metric values and labels, table cells, timeline entries, captions and furniture text.\n\nA picture with `alt` is an image with that name. Purely decorative drawing is hidden (`aria-hidden`): the background and its overlay, card frames, table cell fills and borders, dividers, timeline markers, watermarks, list bullets, a picture or chart whose `alt` is `""`, and a header or footer picture without `alt` (a logo repeated on every slide). A chart with `alt` is an image with that name, and its drawn marks are not announced separately. The deck element, the player and `renderDeckHtml` in `@openpresentation/opf-render` put the one slide container (region or figure) around the drawing, so a slide is announced once.\n\nTesting status (opf-render#170): this contract is the DOM and ARIA structure. It is checked with axe-core, the browser\'s accessibility tree and focus-order assertions, and it is **not tested with assistive technology**: no screen reader (NVDA, JAWS, VoiceOver, TalkBack) has been run against the preview, the deck element or the player (owner decision 2026-10-10). Forced colors are verified with Chromium\'s emulation only, not the Windows contrast theme ([evidence](evidence/rr-59-forced-colors-emulated-20261010/README.md)).\n'
+    "markdown": '# Content Payloads\n\nSlide content lives directly on a slide as a full-slide payload, in layout-agnostic `blocks`, or inside a promoted region key such as `left`, `center+right`, or `top:left`.\n\nThe slide-level `title`, `subtitle` and `tag` are not payloads, but like `text` and `quote.text` they accept a string or `TextRun[]` (colored words, bold, links, `cite`/`footnote` markers); see [Rich text](rich-text.md#rich-headings-and-quotes).\n\nThe optional payload `type` can make intent explicit, but OPF should usually infer the content kind from the field present:\n\n| Field | Inferred type | Notes |\n| --- | --- | --- |\n| `text` | `text` | Plain string or `TextRun[]`. |\n| `bullets` | `text` | Prose bullets: plain talking points, usually `string[]`. |\n| `items` | `list` | Structured list: entries that share a shape or carry a `description`; `string[]` or `ListItem[]`. See [items versus bullets](#items-versus-bullets). |\n| `image` | `image` | Asset string shorthand or `Asset` object with `src` and optional metadata. |\n| `video` | `video` | Asset string shorthand or `Asset` object with `src` and optional metadata. |\n| `chart` | `chart` | Chart object with `type` and tabular `data`. |\n| `table` | `table` | Table object with optional `columns` and required `rows`. |\n| `code` | `code` | String shorthand or `Code` object with `source`, `language`, `filename`, and `highlight`. |\n| `metric` | `metric` | String/number shorthand or `Metric` object with `value`, `label`, `description`, `unit`, `delta`, `trend`, and `sentiment`. |\n| `quote` | `quote` | String shorthand or `Quote` object with `text` (string or `TextRun[]`), `attribution`, `role`, `photo`, and `source`. |\n| `timeline` | `timeline` | Array shorthand or `Timeline` object with `name`, `description`, and `events`. |\n\n## Items versus bullets\n\nBoth fields draw the same bulleted (or numbered) list: one marker, the same nesting `level`, rich-text entries and `numbering`, fitted by the same list engine. Nothing about the drawing differs. They differ in the kind they infer and in what an entry may carry:\n\n| | `bullets` | `items` |\n| --- | --- | --- |\n| Inferred kind | `text` | `list` |\n| Entry | string, `TextRun[]` or `{ text, level, start }` | string, `TextRun[]` or `{ text, description, level, start }` |\n| `description` | not allowed (a schema error) | supporting detail drawn under the entry |\n| Beside `text` in one block or region | allowed | an error (`list` and `text` are different kinds) |\n\n**The rule.** Use `bullets` for plain talking points: short lines that each stand alone. Use `items` when the entries share a shape (features, steps, options, risks) or any entry needs a `description`; never fold a heading and its detail into one string with a separator, that is what `description` is for. When in doubt, use `items`, because it can grow a `description` later without changing the payload kind. The editor helper `convertListForm` switches a payload between the two; going to `bullets` drops the descriptions.\n\nDo not give one payload both. In a block or a promoted region, `items` next to `bullets` is the error "content payload mixes fields from incompatible content types". At slide root it validates, as the shorthand for two blocks, and composes as two lists side by side; write two blocks on purpose if you want that. `numbering` applies to every list in the payload.\n\nA layout\'s placeholder kind (`list` or `text`) is what layout pickers match on (`layoutContent`), but composition does not refuse the other field and draws both the same way: the choice states what the content is, it is not a switch for the look.\n\n## Code highlight\n\n`code.highlight` marks lines of a code block: a line number or an inclusive `[start, end]` range, 1-based, for example `[3, [5, 7]]`. Lines are counted by line break in `code.source`; a line that wraps is still one line. The preview and the PPTX export draw a theme-derived band behind the marked lines and dim the others slightly; every line keeps at least 4.5:1 contrast against what it sits on (`codeHighlightColors`). The PPTX export draws one native rectangle per run of marked lines behind the per-line text boxes, and import restores `highlight` from the code provenance tag. A line past the last line, or a range written end before start, is the validation warning `code-highlight-out-of-range` or `code-highlight-range-reversed`, and engines ignore it. Pagination keeps each page\'s marked lines, renumbered from 1.\n\n## Color references\n\nEvery content color field \u2014 `TextRun.color`, styled table cell `style.fill` and `style.color`, and table cell border `color` \u2014 accepts three forms:\n\n- A literal hex color: `"#0F172A"`, `"#B42318CC"`.\n- A color-scheme slot or role name, resolved through the effective color scheme after design resolution: slots `accent1`\u2013`accent6`, `dark1`, `dark2`, `light1`, `light2`, `hyperlink`, `followedHyperlink`; roles `primary`, `secondary`, `accent`, `background`, `surface`, `surfaceAlt`, `text`, `textSecondary`. `surfaceAlt` is the alternate surface for banded table rows: core derives it from `surface` and `text` (`surfaceAltColor`), so it always differs visibly from the `surface` of the plain rows, on light and dark slides, and body text keeps 4.5:1 on it.\n- A variable reference `var:<id>` into the top-level `variables` map.\n\n```json\n{\n  "variables": { "risk": "#B42318" },\n  "slides": [\n    {\n      "title": "What Could Go Wrong",\n      "items": [\n        ["Two regions at ", { "text": "85% utilization", "color": "var:risk", "bold": true }],\n        ["Mitigations ship in ", { "text": "November", "color": "accent2" }]\n      ]\n    }\n  ]\n}\n```\n\nPrefer names and variables over literal hex: re-theming the deck updates every named reference, while a hex value stays frozen at authoring time. An unknown `var:` id is a validation warning, never an error; engines fall back to their default text color. The styled table cell and border color fields enforce the three forms at the schema level; run colors additionally accept any string so imported decks keep validating \u2014 unrecognized values warn, and renderers fall back to the theme color. See [`design-resolution.md`](./design-resolution.md) for the resolution rules.\n\n## Numbered lists\n\n`numbering` on an `items` or `bullets` payload draws numbers instead of bullets: a style name (`arabic`, `roman-upper`, `roman-lower`, `alpha-upper`, `alpha-lower`), a `{ style, start, suffix }` object, or an array with one entry per list level. PowerPoint export writes native auto-numbers and the preview draws the same numbers. See [numbered lists](numbered-lists.md).\n\n```json\n{ "items": ["Define", "Build", "Ship"], "numbering": { "style": "roman-lower", "suffix": "paren" } }\n```\n\n## Blocks\n\nUse slide-level `blocks` when a slide contains multiple content payloads, but exact placement should be inferred by the renderer. Blocks may contain a concrete content payload or a nested group with its own `blocks` and optional `composition`. Groups cannot mix child blocks with leaf payload fields. See [dynamic composition](dynamic-composition.md) for nesting and inheritance rules.\n\n```json\n{\n  "title": "Customer Feedback Summary",\n  "blocks": [\n    {\n      "table": {\n        "columns": ["Theme", "Mentions"],\n        "rows": [\n          ["Speed", 42],\n          ["Ease of use", 31]\n        ]\n      }\n    },\n    {\n      "quote": {\n        "text": "The new workflow cut review time in half.",\n        "attribution": "Operations Lead",\n        "source": "Customer interview"\n      }\n    }\n  ]\n}\n```\n\nAt slide root only, multiple content payload kinds are accepted as shorthand for the equivalent blocks form when there is no explicit `type`, no `blocks`, and no promoted region keys:\n\n```json\n{\n  "title": "Habitat & Territory",\n  "text": "Jaguars are strongly associated with presence of water and dense cover.",\n  "items": [\n    "Primary habitats include dense rainforests, swamps, and seasonally flooded wetlands.",\n    "Solitary animals that establish and defend large territories."\n  ]\n}\n```\n\nThe same shorthand works for other content kinds:\n\n```json\n{\n  "title": "Evidence Snapshot",\n  "chart": {\n    "type": "line",\n    "data": {\n      "columns": ["Quarter", "Sightings"],\n      "rows": [\n        ["Q1", 12],\n        ["Q2", 18]\n      ]\n    }\n  },\n  "quote": {\n    "text": "Jaguar conservation depends on connected habitat.",\n    "attribution": "Field researcher"\n  }\n}\n```\n\n## Chart\n\nChart-specific fields are grouped under `chart`. Do not put loose chart data directly on a slide or region.\n\n```json\n{\n  "title": "Revenue Trend",\n  "chart": {\n    "type": "line",\n    "data": {\n      "columns": ["Quarter", "Revenue", "Costs"],\n      "rows": [\n        ["Q1", 12, 8],\n        ["Q2", 18, 11],\n        ["Q3", 24, 15]\n      ]\n    }\n  }\n}\n```\n\nInline chart data is tabular by default. Renderers convert `columns` and `rows` into series, axes, legends, and workbook data internally.\n\nGive every chart an `alt`: one or two sentences that say what the data shows (the point and the key numbers), not "a chart" or "bar chart". The preview names the chart with it (`role="img"`, `aria-label`) and the PowerPoint export writes it as the chart frame\'s alternative text (`descr`), which `fromPptx` reads back. `"alt": ""` marks a chart decorative, as an empty image `alt` does; `validate` (`opf/chart-text-alternative`) still reports it as info so the choice is reviewed. Without `alt`, text beside the chart (a subtitle, text or table) satisfies the rule. See [chart options](chart-options.md#text-alternative).\n\nValue cells are numbers. A string is read only in strict decimal syntax (`"12"`, `" -3.5 "`, `"1e6"`); anything else (`"12%"`, `"$5"`, `"(5)"`, `"1,234"`, `"Q1"`) is a gap in the preview and the export and a `chart-value-not-numeric` warning, never a guessed value. `null` and `""` are gaps without a warning. Core `chartNumber` is the one rule every engine uses (RR-54; before it the PPTX exporter stripped non-numeric characters, so `"12%"` exported as 12).\n\nA column is a string or a `DataColumn` with a number format, which the data labels, the value axis and the exported workbook use:\n\n```json\n{\n  "chart": {\n    "type": "column",\n    "data": {\n      "columns": ["Quarter", { "name": "Revenue", "format": "$#,##0.0" }, { "name": "Margin", "format": "0%" }],\n      "rows": [["Q1", 12.4, 0.31], ["Q2", 18.1, 0.34]],\n      "source": { "src": "./data/revenue.csv", "retrieved": "2026-10-05" }\n    },\n    "mapping": { "category": "Quarter", "series": ["Revenue"] }\n  }\n}\n```\n\nFormats use the `NumberVariable.format` syntax (`#,##0`, `0.0%`, `$#,##0.00`, `#,##0 units`; a `%` multiplies by 100). `source` records provenance only; engines never read or refresh it. `mapping` picks the category, the X column of a scatter chart and the plotted series by column name; without it the first column is the category and every other column a series. Shared data lives in the top-level `datasets` map and a chart plots it with `"data": { "dataset": "revenue", "fields": ["Quarter", "Revenue"] }`. The full contract, with validation codes and the engine behaviour, is [Chart and table data](chart-table-data.md).\n\nChart data is inline columns and rows or a dataset. A data source by file or asset (`"data": { "src": "asset:revenue-csv", "columns": [...] }`) is not part of the format: no engine loaded it, and the validator rejects it. Import the data inline (with a `source`) or into a dataset instead.\n\n## Table\n\nTable-specific fields are grouped under `table`. Do not put loose `columns` or `rows` directly on a slide or region.\n\n```json\n{\n  "title": "Pipeline",\n  "table": {\n    "columns": ["Stage", "Count", "Value"],\n    "rows": [\n      ["Qualified", 42, "$1.2M"],\n      ["Proposal", 18, "$840K"]\n    ]\n  }\n}\n```\n\nA table may instead show a dataset: `"table": { "dataset": "revenue", "fields": ["Quarter", "Revenue"] }` (no `rows` or `columns`); it takes its headers, rows and column formats from the dataset, and per-cell styles need an inline table. A column header may be a `DataColumn` (`{ "name": "Revenue", "format": "$#,##0.0" }`) and a styled header or body cell takes a `format`; a number cell displays formatted (the body cell\'s own format wins over the column\'s), and `layoutTable` measures the formatted text. See [Chart and table data](chart-table-data.md).\n\nTable body cells accept strings, numbers, booleans, or `null`. Since core 0.5.0, a cell or column header also accepts the same `TextRun[]` used by rich text:\n\n```json\n{\n  "table": {\n    "columns": [["Quarter ", {"text": "growth", "bold": true}], "Value"],\n    "rows": [\n      [["Up ", {"text": "12%", "color": "#008800"}], 12]\n    ]\n  }\n}\n```\n\nUse the coordinated Node 24 set recorded in [release-plan.json](../release-plan.json) and the [compatibility matrix](compatibility-matrix.md) for exact pins and evidence. Core measures run styles when checking overflow and keeps each row intact when paginating. The renderer traces rich cells for the editor\'s existing formatting, typing and undo controls; the exporter emits editable native text runs. PPTX 0.4.0 introduced import of supported native character styles, paragraph defaults, theme fonts/colors, external links and significant whitespace as rich runs. Unstyled body cells remain strings, and cached display text cannot recover original scalar types or live fields. Conditional table styles, merged geometry and cell fills/borders/alignment remain limited; native PowerPoint visual parity is not yet verified.\n\n**Table text size and bold.** Table text draws at the body size (about 19 pt, 25 reference pixels) and the whole table shrinks together toward `composition.minFontSize` when its rows do not fit, so a table next to bullets no longer reads smaller than they do. A run\'s own `fontSize` is drawn as written. `TableCellStyle` takes `bold` to make the whole cell bold; a numeric cell can be bold and still use its number `format` (`{"value": 18.1, "style": {"bold": true}}`), and a cell written as runs in a numeric column keeps the column\'s alignment.\n\nA table may carry an `alt` (FA-27), the same text alternative as `Chart.alt`: one or two sentences that say what the table shows (the point and the key numbers), not "a table". The preview names the table with it (a `role="group"` with `aria-label`; the cells stay readable) and the PowerPoint export writes it as the table frame\'s alternative text (`descr`), which `fromPptx` reads back. `"alt": ""` hides a purely decorative table, as an empty image `alt` does. Unlike a chart, a table needs no `alt`: a screen reader reads a native table cell by cell, so `validate` reports nothing when it is missing, and a table beside a chart still counts as that chart\'s text alternative. The `alt` is a summary read before the cells, which stay readable text (in PowerPoint too, where `descr` on a table frame does not hide its cells), so it is most useful for a large or dense table.\n\nCore 0.6.0 adds `layoutTable` from `@openpresentation/opf/composition`. It measures scalar and rich cells, keeps short rows compact, and gives wrapped or multiline rows the height they need. When space is constrained it reduces spare row height before shrinking text, and reports overflow when the minimum fitting size cannot fit. Pass the same `scale`, font family, measurement provider and effective `minFontSize` to each consumer. The returned row boxes, cell text boxes and fits are shared by the coordinated SVG and PPTX implementations; rich table cells use uniform line advances to match native cell paragraph spacing. Native viewer fidelity remains a separate verification boundary.\n\n## Captions\n\nAn `image`, `chart`, `table` or `video` payload takes a `caption`: a string, `TextRun[]`, or `{ "text", "position": "below" | "above", "align": "left" | "center" | "right" }` (defaults `below`, `left`). It sits beside the payload field on a block or promoted-region payload, or on the slide root when the root holds exactly one of those payloads; anywhere else it is a `caption-unsupported-payload` error.\n\n```json\n{\n  "title": "Pipeline",\n  "blocks": [\n    { "image": "asset:funnel", "caption": "Figure 1. Pipeline by stage, Q3" },\n    { "table": { "columns": ["Stage", "Count"], "rows": [["Qualified", 42]] }, "caption": { "text": "Table 1. Counts", "position": "above", "align": "center" } }\n  ]\n}\n```\n\nCore composition reserves the caption band inside the block\'s region and shrinks the media by its height (`item.caption` carries the band, `item.box` is the media box); the preview and the PPTX export draw that band in the muted text colour at the caption size (0.6 of the body size, never under the readable floor). Captioned blocks are the only ones whose geometry changes. See [footnotes, citations and captions](footnotes-citations-captions.md).\n\n## Code\n\nCode-specific fields are grouped under `code`. A string value is shorthand for `code.source`; use object form when syntax highlighting or a file label matters. In object form, `source` is required. `language` colours the code in the preview and the PowerPoint export (comments, strings, numbers, keywords, names and types, in colours from the deck theme); an unknown language stays plain and the text is never changed. See [dynamic composition](dynamic-composition.md#preview-polish-shared-by-preview-and-export-rr-07) for the supported languages.\n\n```json\n{\n  "title": "Decision Rule",\n  "code": {\n    "source": "if risk > threshold:\\n    escalate(owner)\\nelse:\\n    approve(change)",\n    "language": "python",\n    "filename": "decision.py"\n  }\n}\n```\n\n## Metric\n\nMetric-specific fields are grouped under `metric`. A string or number value is shorthand for `metric.value`; numeric values stay numeric and are formatted by renderers at display time. Use object form when labels, descriptions, units, deltas, trends, or sentiment matter. A `trend` (`up`, `down`, `flat`) draws an arrow beside its word, coloured with the delta text, in the preview and the PowerPoint export; the arrow always points the way the trend does, and its colour follows `sentiment` (`positive` green, `negative` red, `neutral` the neutral text colour). When `sentiment` is absent up is positive, down is negative and flat is neutral, so set it when the direction is not the verdict: a falling churn, cost or latency is `"trend": "down", "sentiment": "positive"`. Only the trend arrow and the trend and delta text take the colour, so `sentiment` has no visible effect on a metric without a `trend`; the word stays editable text and the arrow carries "Trend: up" as its alternative text (see [dynamic composition](dynamic-composition.md#preview-polish-shared-by-preview-and-export-rr-07)).\n\nThe `metrics` v2 layout accepts metric blocks in its body region and flows them as a grid. For several metrics, use separate `{ "metric": ... }` entries in `blocks`; the content kind and payload key are `metric`. Choosing a layout does not reinterpret existing text as numeric data.\n\n```json\n{\n  "title": "Operating Metric",\n  "metric": {\n    "value": "42%",\n    "label": "Review cycle reduction",\n    "description": "Median reduction across customer review workflows.",\n    "delta": "+11 pts",\n    "trend": "up"\n  }\n}\n```\n\nA falling value that is good news keeps its downward arrow and takes the green:\n\n```json\n{\n  "title": "Churn",\n  "metric": {\n    "value": "3.1%",\n    "label": "Monthly churn",\n    "delta": "-0.6 pts",\n    "trend": "down",\n    "sentiment": "positive"\n  }\n}\n```\n\n## Quote\n\nQuote-specific fields are grouped under `quote`. A string value is shorthand for `quote.text`; use object form when attribution or citation matters. `text` is a string or `TextRun[]` with inline formatting; `attribution`, `role` and `source` are plain strings.\n\n```json\n{\n  "title": "Customer Proof",\n  "quote": {\n    "text": "The new workflow made exceptions visible before they became escalations.",\n    "attribution": "Priya Raman",\n    "source": "Customer interview"\n  }\n}\n```\n\nA testimonial attributes the quote to a person with a title and a face. `role` is the person\'s title and organization, and `photo` is their headshot, an `Asset` (a source string or an object with `src` and `alt`):\n\n```json\n{\n  "title": "Customer Proof",\n  "quote": {\n    "text": "The new workflow made exceptions visible before they became escalations.",\n    "attribution": "Priya Raman",\n    "role": "VP Operations, Acme",\n    "photo": { "src": "asset:priya-raman", "alt": "Priya Raman" },\n    "source": "Customer interview, March 2026"\n  }\n}\n```\n\nThe footer under the quote is the attribution, then the role on its own line, then the source after ` - ` on the last line. Without a `role` it is the single line it always was (`attribution - source`). With a `photo`, the headshot is a circle at the start edge of the footer row (the left in a left-to-right deck, the right in a right-to-left one), three times the footer font size across, and the footer lines sit beside it, centered on it. The photo is cropped to fill the circle, and its size follows the footer\'s font size when the readability floor shrinks the footer. Without a `photo` nothing else changes. The preview draws it with the circular clip that an image block uses for shape `circle`, and PowerPoint export writes a native picture with the `ellipse` geometry and the alt text as its description; importing that file restores `role` and `photo`. A photo needs alt text (the `opf/missing-alt-text` rule of `validate` checks `quote.photo`); an SVG photo exports as its PNG raster. A photo with no attribution, role or source still draws, alone in the footer row. The Markdown dialect has no native form for `role` and `photo`: a quote that carries them is written as an `opf` block, which round trips exactly, and a plain `> \u2014 Name, Title` line stays an attribution.\n\n## Timeline\n\nTimeline-specific fields are grouped under `timeline`. An array value is shorthand for `timeline.events`; use object form when the timeline needs a name or description. Timeline events use `when`, `what`, `description` and `status`. `status` is `done`, `current` or `planned` and marks progress: `done` is a filled marker with normal text, `current` ("we are here") is a ringed marker with a bold label, and `planned` is a hollow outlined marker with muted text. An event without a status draws as a plain filled marker. Schedule health (at risk, blocked) is not a status; say it in the event text. See [Dynamic composition](dynamic-composition.md#timeline-internals) for the exact drawing.\n\n```json\n{\n  "title": "Rollout Plan",\n  "timeline": {\n    "name": "Regional Rollout",\n    "description": "Major milestones for the rollout.",\n    "events": [\n      {\n        "when": "Q1",\n        "what": "Pilot",\n        "description": "Launch with one operations team."\n      },\n      {\n        "when": "Q2",\n        "what": "Rollout",\n        "description": "Expand to all regions."\n      }\n    ]\n  }\n}\n```\n\nA roadmap with progress states:\n\n```json\n{\n  "title": "Product roadmap",\n  "timeline": [\n    { "when": "Q1", "what": "Discovery", "status": "done" },\n    { "when": "Q2", "what": "Pilot", "status": "current" },\n    { "when": "Q3", "what": "Rollout", "status": "planned" }\n  ]\n}\n```\n\n## Regions\n\nRegion keys address a 3\xD73 grid of rows (`top`, `middle`, `bottom`) and columns (`left`, `center`, `right`):\n\n```\n                  left                 center                 right\n         +--------------------+--------------------+--------------------+\n   top   |  top:left          |  top:center        |  top:right         |\n         +--------------------+--------------------+--------------------+\n  middle |  middle:left       |  middle:center     |  middle:right      |\n         +--------------------+--------------------+--------------------+\n  bottom |  bottom:left       |  bottom:center     |  bottom:right      |\n         +--------------------+--------------------+--------------------+\n```\n\n- A bare column key (`left`) spans all three rows; a bare row key (`top`) spans all three columns.\n- `+` spans adjacent rows or columns: `center+right`, `top+middle`.\n- `row:column` combines the two: `top:left`, `middle+bottom:center+right`.\n- Keys on one slide must not overlap, and regions cannot be mixed with root payload fields.\n\nSpans compose into common slide shapes:\n\n```\n  "left" + "center+right"             "top" + "middle+bottom"\n  (sidebar + main)                    (headline band + body)\n  +----------+------------------+     +-------------------------------+\n  |          |                  |     |              top              |\n  |          |                  |     +-------------------------------+\n  |   left   |  center+right    |     |                               |\n  |          |                  |     |         middle+bottom         |\n  |          |                  |     |                               |\n  +----------+------------------+     +-------------------------------+\n\n  "top" + "middle+bottom:left" + "middle+bottom:center+right"\n  (headline band, then sidebar + main)\n  +---------------------------------------------+\n  |                     top                     |\n  +---------------+-----------------------------+\n  |               |                             |\n  | middle+bottom | middle+bottom:center+right  |\n  | :left         |                             |\n  |               |                             |\n  +---------------+-----------------------------+\n```\n\nThe same payload objects work inside regions \u2014 here, the sidebar-plus-main shape:\n\n```json\n{\n  "title": "Operating Snapshot",\n  "left": {\n    "table": {\n      "columns": ["Metric", "Value"],\n      "rows": [\n        ["Revenue", "$4.2M"],\n        ["Gross margin", "68%"]\n      ]\n    }\n  },\n  "center+right": {\n    "chart": {\n      "type": "line",\n      "data": {\n        "columns": ["Month", "Revenue"],\n        "rows": [\n          ["Jan", 3.4],\n          ["Feb", 3.8],\n          ["Mar", 4.2]\n        ]\n      }\n    }\n  }\n}\n```\n\n## Accessibility of the preview\n\nThe SVG preview and the PowerPoint export agree on what a reader can reach. The slide root is a labelled container (`role="group"`, `aria-roledescription="slide"`, `aria-label` set to the slide title), never an image: an image makes everything inside it presentational, so a screen reader would hear only the title. Text stays reachable, in the order it is drawn: tag, title and subtitle, the content in layout order, footnotes, then header and footer. That covers body text, list entries, quotes, metric values and labels, table cells, timeline entries, captions and furniture text.\n\nA picture with `alt` is an image with that name. Purely decorative drawing is hidden (`aria-hidden`): the background and its overlay, card frames, table cell fills and borders, dividers, timeline markers, watermarks, list bullets, a picture or chart whose `alt` is `""`, and a header or footer picture without `alt` (a logo repeated on every slide). A chart with `alt` is an image with that name, and its drawn marks are not announced separately. The deck element, the player and `renderDeckHtml` in `@openpresentation/opf-render` put the one slide container (region or figure) around the drawing, so a slide is announced once.\n\nTesting status (opf-render#170): this contract is the DOM and ARIA structure. It is checked with axe-core, the browser\'s accessibility tree and focus-order assertions, and it is **not tested with assistive technology**: no screen reader (NVDA, JAWS, VoiceOver, TalkBack) has been run against the preview, the deck element or the player (owner decision 2026-10-10). Forced colors are verified with Chromium\'s emulation only, not the Windows contrast theme ([evidence](evidence/rr-59-forced-colors-emulated-20261010/README.md)).\n'
   },
   {
     "slug": "conversions",
@@ -100,7 +100,7 @@ var docsData = Object.freeze([
     "slug": "examples",
     "file": "docs/examples.md",
     "title": "OPF Examples Guide",
-    "markdown": "# OPF Examples Guide\n\nThe `examples/` directory has two shipped layers, plus a docs fixture kept outside the catalog:\n\n- `examples/technical/` contains compact fixtures that isolate one or two schema behaviors.\n- `examples/gallery/` contains scenario-oriented decks that show OPF working across industries, functions, education, government, international, presentation-type, and design/media use cases.\n- The representative deck for [the published-package quickstart](quickstart.md) lives at [`docs/quickstart/developer-quickstart.opf.json`](quickstart/developer-quickstart.opf.json), outside the catalog, so `@openpresentation/opf/examples` stays at the published example count (currently 127 decks); the renderer golden corpus tracks that catalog on its own release cadence.\n- The runnable first deck lives at [`docs/first-deck/`](first-deck/README.md), also outside the catalog (a deck under `examples/` would change the examples corpus that the renderer golden covers): six slides (bullets, a metric, a chart, a styled table, a local image) and a README that goes from install to validate, PNG, PPTX and opening the file in PowerPoint or Keynote, with the known limits.\n- `examples/markdown/` holds decks written in the [Markdown dialect](markdown.md) (`.opf.md`, not `.opf.json`, so they are outside the catalog count): `quarterly-review.opf.md` is a Markdown deck that every command reads (`opf validate examples/markdown/quarterly-review.opf.md`); it uses every block kind and is canonical. `outline.md` is a plain outline, not a deck (a plain `.md` file is never taken for one), read with `opf convert outline.md deck.opf.json` (a plain `.md` input is OPF Markdown, and an outline with no `---` is cut at its headings). The tests convert, validate, compose and round trip them.\n- The examples root is kept as an organizing directory rather than a home for standalone OPF files.\n\n## Technical Fixtures\n\nUse `examples/technical/` when you want a small file that exercises a specific schema surface:\n\n- content payloads, rich text, blocks, charts, tables, media, metrics, quotes, and timelines\n- promoted region keys and span combinations\n- asset string/object forms and asset-backed chart data\n- design backgrounds, organization logo shapes, headers, footers, watermarks, and slide-level overrides\n- metadata array forms, language metadata, custom narrative records, and catalog overrides\n\n## Gallery Folders\n\n| Folder | What It Demonstrates |\n| --- | --- |\n| `industries/` | Vertical market decks with operating plans, investment briefs, readiness reviews, and launch coordination. |\n| `business-functions/` | Department-specific decks for sales, marketing, product, engineering, finance, HR, legal, security, support, procurement, and strategy. |\n| `education/` | K-12, higher education, research, advising, workforce, advancement, and student services scenarios. |\n| `government/` | Public health, transit, emergency management, utilities, regulators, courts, parks, workforce, tax, and civic engagement decks. |\n| `presentation-types/` | Reusable deck archetypes such as pitches, board updates, QBRs, conference talks, workshops, postmortems, launches, policy briefings, training, and research reports. |\n| `international/` | Region- or language-specific decks, including examples of language object metadata and right-to-left direction. |\n| `design-and-media/` | Decks that emphasize design controls, image/video assets, data storytelling, and self-running orientation patterns. |\n\n## Patterns To Look For\n\n- Technical fixtures that isolate validator and renderer behavior.\n- Sparse gallery documents that use shorthand catalog references and a small slide list.\n- Medium documents with schema ids, metadata, organization and speaker records, design overrides, assets, and richer slide payloads.\n- Dense documents with their own records in `catalogs.custom`, promoted region keys, `blocks`, media assets, code payloads, header/footer configuration, organization logo shapes, watermarks, and extensions.\n- Mixed content payloads across text, bullets, lists, image, video, chart, table, code, metric, quote, and timeline slides.\n- Catalog references across narratives, layouts, themes, color schemes, font schemes, audiences, purposes and tones, every record embedded under `catalogs.default` or `catalogs.custom`, so each deck validates and renders with no catalog registered; chart types, languages and social platforms as engine vocabularies.\n\n## Validation\n\nRun the example validator after changing any `*.opf.json` file:\n\n```sh\nnode scripts/validate-examples.mjs\n```\n\nThe script walks every OPF document under `examples/` and reports schema or semantic validation issues with file paths.\n"
+    "markdown": "# OPF Examples Guide\n\nThe `examples/` directory has two shipped layers, plus a docs fixture kept outside the catalog:\n\n- `examples/technical/` contains compact fixtures that isolate one or two schema behaviors.\n- `examples/gallery/` contains scenario-oriented decks that show OPF working across industries, functions, education, government, international, presentation-type, and design/media use cases.\n- The representative deck for [the published-package quickstart](quickstart.md) lives at [`docs/quickstart/developer-quickstart.opf.json`](quickstart/developer-quickstart.opf.json), outside the catalog, so `@openpresentation/opf/examples` stays at the published example count (currently 128 decks); the renderer golden corpus tracks that catalog on its own release cadence.\n- The runnable first deck lives at [`docs/first-deck/`](first-deck/README.md), also outside the catalog (a deck under `examples/` would change the examples corpus that the renderer golden covers): six slides (bullets, a metric, a chart, a styled table, a local image) and a README that goes from install to validate, PNG, PPTX and opening the file in PowerPoint or Keynote, with the known limits.\n- `examples/markdown/` holds decks written in the [Markdown dialect](markdown.md) (`.opf.md`, not `.opf.json`, so they are outside the catalog count): `quarterly-review.opf.md` is a Markdown deck that every command reads (`opf validate examples/markdown/quarterly-review.opf.md`); it uses every block kind and is canonical. `outline.md` is a plain outline, not a deck (a plain `.md` file is never taken for one), read with `opf convert outline.md deck.opf.json` (a plain `.md` input is OPF Markdown, and an outline with no `---` is cut at its headings). The tests convert, validate, compose and round trip them.\n- The examples root is kept as an organizing directory rather than a home for standalone OPF files.\n\n## Technical Fixtures\n\nUse `examples/technical/` when you want a small file that exercises a specific schema surface:\n\n- content payloads, rich text, blocks, charts, tables, media, metrics, quotes, and timelines\n- promoted region keys and span combinations\n- asset string/object forms and asset-backed chart data\n- design backgrounds, organization logo shapes, headers, footers, watermarks, and slide-level overrides\n- metadata array forms, language metadata, custom narrative records, and catalog overrides\n\n## Gallery Folders\n\n| Folder | What It Demonstrates |\n| --- | --- |\n| `industries/` | Vertical market decks with operating plans, investment briefs, readiness reviews, and launch coordination. |\n| `business-functions/` | Department-specific decks for sales, marketing, product, engineering, finance, HR, legal, security, support, procurement, and strategy. |\n| `education/` | K-12, higher education, research, advising, workforce, advancement, and student services scenarios. |\n| `government/` | Public health, transit, emergency management, utilities, regulators, courts, parks, workforce, tax, and civic engagement decks. |\n| `presentation-types/` | Reusable deck archetypes such as pitches, board updates, QBRs, conference talks, workshops, postmortems, launches, policy briefings, training, and research reports. |\n| `international/` | Region- or language-specific decks, including examples of language object metadata and right-to-left direction. |\n| `design-and-media/` | Decks that emphasize design controls, image/video assets, data storytelling, and self-running orientation patterns. |\n\n## Patterns To Look For\n\n- Technical fixtures that isolate validator and renderer behavior.\n- Sparse gallery documents that use shorthand catalog references and a small slide list.\n- Medium documents with schema ids, metadata, organization and speaker records, design overrides, assets, and richer slide payloads.\n- Dense documents with their own records in `catalogs.custom`, promoted region keys, `blocks`, media assets, code payloads, header/footer configuration, organization logo shapes, watermarks, and extensions.\n- Mixed content payloads across text, bullets, lists, image, video, chart, table, code, metric, quote, and timeline slides.\n- Catalog references across narratives, layouts, themes, color schemes, font schemes, audiences, purposes and tones, every record embedded under `catalogs.default` or `catalogs.custom`, so each deck validates and renders with no catalog registered; chart types, languages and social platforms as engine vocabularies.\n\n## Validation\n\nRun the example validator after changing any `*.opf.json` file:\n\n```sh\nnode scripts/validate-examples.mjs\n```\n\nThe script walks every OPF document under `examples/` and reports schema or semantic validation issues with file paths.\n"
   },
   {
     "slug": "finding-schema-reference",
@@ -292,7 +292,7 @@ var docsData = Object.freeze([
     "slug": "release-process",
     "file": "docs/release-process.md",
     "title": "OPF Release Process",
-    "markdown": "# OPF Release Process\n\nUse Node 24 (`24.x`) for all future source, candidate and registry verification.\nThe packages declare the open-ended `engines.node` `>=22` (RR-20, tested on Node 22, 24 and 26 by the `node-range`\nCI jobs, which run in the merge queue and on pull requests labelled `full-ci`); a closed range such as `24.x` makes npm on any other Node silently install an older release, and\n`pnpm check:engines-range` fails on one, including in a lockfile that pins a release made after the fix.\nThe next releases must document the [Node 24 migration](migrations/node24.md)\nand use new versions. Historical dual-runtime release records remain unchanged.\n\nThis document is the release runbook for the public JavaScript package,\n[`@openpresentation/opf`](https://www.npmjs.com/package/@openpresentation/opf).\n\nThe canonical release path is:\n\n1. Merge the release commit to `main`.\n2. Push a semver tag whose name matches the package version.\n3. Let GitHub Actions publish to npm through npm trusted publishing.\n4. Verify npm and the GitHub Release the publish workflow creates from the changelog section.\n\n## Agent authorization and coordinated release order\n\nThe owner authorized agents to prepare and publish npm releases on 2026-09-29\nand for future releases whenever a release is required. This does not waive any\ngate: a release still needs a merged release-prep PR, green required checks and\nthe verification below. Agents keep publishing on the trusted-publishing\nworkflows (GitHub Actions OIDC with `--provenance`). If a workflow cannot run,\nstop and repair the trusted-publishing path; do not substitute a local publish\nor an npm-token publish that omits the required provenance.\n\nThe engine packages depend on each other, so publish in this order and wait for\neach version to appear on the registry before starting the next:\n\n1. `@openpresentation/opf` (this repository, `opf-vX.Y.Z` tag).\n2. `@openpresentation/opf-render` (`opf-render-vX.Y.Z` tag) and\n   `@openpresentation/opf-pptx` (`opf-pptx-vX.Y.Z` tag). Both depend on core; PPTX\n   also devDepends on the renderer, so publish the renderer first.\n3. `@openpresentation/opf-editor` (`opf-editor-vX.Y.Z` tag), which depends on core\n   and peers/devDepends on the renderer and PPTX.\n\nEach sibling's release-prep PR raises its dependency floors to the just-published\nversions. Its lockfile can only be refreshed after the upstream version exists on\nnpm (`npm install --package-lock-only`), so merge sibling release PRs only after\nthe upstream publish. `@openpresentation/cli` depends on core (a regular dependency; its floor is raised by the release-prep PR like the others, the commands run that core's Node engine) and is released\nseparately by `cli-publish.yml` (`cli-vX.Y.Z`) when a CLI release is needed.\n\nThe CLI release gate includes the installed-package regression `packages/cli/test/installed-regression.mjs` (RR-59, [opf#476](https://github.com/OpenPresentation/opf/issues/476)). It drives the installed `opf` binary beside the published opf-render and opf-pptx, the render font packages and the Noto JP and SC script packages, with no network after the install (a preload refuses every connection and fetch, and a local server that the image URLs point at counts zero requests): `opf convert deck.opf.json deck.svg` embeds `Noto Sans JP` 400 and 700 for a `ja-JP` deck, nothing under `--text system` and no CJK face for a Latin-only deck; `opf convert deck.opf.json deck.pptx` of a deck with an `https:` content image (an image block and a quote photo) exits 0 with a `pptx/unresolved-asset` warning at the slide path and the placeholder, exits 1 and writes no file under `--fail-on warning`, and exports a native picture for an embedded or local PNG under `--fail-on warning`. It runs in `pnpm test:cli:packed:peers` (the candidate CLI and core tarballs; OPF CI, the Windows and engines-range CLI jobs, and `cli-publish.yml` before `npm publish`) and in `pnpm test:registry-ecosystem` (the published set of `release-plan.json`, from plan 0.16).\n\nA sibling pull request that needs a core that is not on npm yet (a breaking core release and its sibling PRs, `Depends-On: OpenPresentation/opf#N`) declares it in its `package.json` as `\"opf\": { \"requiresUnreleasedCore\": \"X.Y.Z\" }` (RR-55). Its CI then skips only the packed install against published dependencies (`npm run test:packed`, with a `::notice::`) while the installed published `@openpresentation/opf` is lower than `X.Y.Z`; every linked-ecosystem step still runs. The field is for pull requests only: `release-train.mjs prep` deletes it (and refuses a field above the core of the train), and `plan` flags a release commit whose `package.json` still carries it.\n\nRelease-prep PRs contain only version bumps, changelog entries, dependency ranges\nand lockfile changes (plus current-instruction docs). The changelog entries are\nnot written by hand: every change adds a fragment `changes/<slug>.md` in its own\nPR (RR-46, [changes/README.md](../changes/README.md)), and the release-prep PR\nruns the assembler, which moves the fragments into the new release section of\n`CHANGELOG.md` and deletes them. Each sibling repository has the same\n`changes/` directory and script:\n\n```sh\n# core (packages are named in each fragment: opf = CHANGELOG.md, cli = packages/cli/CHANGELOG.md)\nnode scripts/changelog-fragments.mjs assemble --version X.Y.Z --package opf --date YYYY-MM-DD\nnode scripts/changelog-fragments.mjs assemble --version A.B.C --package cli   # only when the CLI is released\n# opf-render, opf-pptx, opf-editor\nnode scripts/changelog-fragments.mjs assemble --version X.Y.Z --date YYYY-MM-DD [--summary \"Patch release: ...\"]\n```\n\nUse `--dry-run` to preview, and check that no `changes/*.md` other than\n`README.md` remains for the released package before opening the PR. After the whole set is on\nthe registry, a follow-up docs change updates `release-plan.json`, the\ncompatibility matrix and the quickstart to the published set, and the gallery\nconsumer dependencies are bumped.\n\n## Release train (scripted, RR-51)\n\n`scripts/release-train.mjs` runs the coordinated release above in lockstep order. It is run by the supervisor with\ntheir own `gh` login (or `GH_TOKEN`); every command is a dry run unless `--execute` is given. It only reads, opens\nrelease-prep pull requests and creates tags: it never merges a pull request and never publishes. Each package is still\npublished by its own repository's trusted-publishing workflow (OIDC, `--provenance`) when its tag appears.\n\nName the versions of the train, any subset: `--core X.Y.Z --render X.Y.Z --pptx X.Y.Z --editor X.Y.Z --cli X.Y.Z`.\nThe order is always core, then opf-render, then opf-pptx, then opf-editor and the CLI.\n\n```sh\n# 1. What is missing (read only; exit 1 until every package is on npm)\nnode scripts/release-train.mjs plan --core 0.12.1 --render 0.12.1 --pptx 0.12.3 --editor 0.11.3 --cli 0.10.1\n\n# 2. The release-prep PR of the next package, once its upstream is on npm (dry run first: a scratch clone and the diff)\nnode scripts/release-train.mjs prep render --core 0.12.1 --render 0.12.1 [--item RR-nn]\nnode scripts/release-train.mjs prep render --core 0.12.1 --render 0.12.1 --item RR-nn --execute\n\n# 3. After a person merged it with green CI: tag the release commit, wait for the publish run and npm, verify\nnode scripts/release-train.mjs tag render --core 0.12.1 --render 0.12.1 --execute\n\n# 4. Verify any published version (also run by `tag` and `run`)\nnode scripts/release-train.mjs verify @openpresentation/opf-render@0.12.1\n\n# Or the whole sequence: it stops at the first step that needs a person and prints the command to resume\nnode scripts/release-train.mjs run --core 0.12.1 --render 0.12.1 --pptx 0.12.3 --editor 0.11.3 --cli 0.10.1 --execute\n```\n\nWhat each step checks:\n\n- `plan` reads, per package: whether the version is already on npm (then it is only verified), the version in the\n  manifest at `main`'s head, the release commit (the commit that set the version) and its merged release-prep PR, the\n  required checks on the release commit (the `main` ruleset's required checks; for a repository without a ruleset,\n  every reported check apart from existing advisory bots and the identity-verified scheduled Editor flake measurement), the tag, whether the upstream versions of the train are on npm, and the dependency floors.\n  It flags every sibling whose `@openpresentation/opf` floor stays below a new core in the train, with hints from core's\n  fragments or changelog section: the tool cannot know whether a core release moves geometry, so the release owner\n  decides whether the lockstep rule below applies (flag, never decided).\n- `prep` refuses until every upstream version of the train is on npm. In a scratch clone of `main` it bumps the\n  version, runs `node scripts/changelog-fragments.mjs assemble --version X.Y.Z --date <today>` (with `--package opf` or\n  `--package cli` in core, `--summary` when given), raises the floors that name a package of the train (caret and\n  tilde ranges keep their operator; exact devDependency pins move to the exact version; `workspace:*` is untouched;\n  for CLI preparation, already-compatible patch peer ranges stay unchanged while development pins advance;\n  core runtime files are never edited by CLI prep) and refreshes the lockfile\n  (`npm install --package-lock-only` in the siblings, `pnpm install --lockfile-only` in core). It fails if a fragment\n  for the package is left or if anything other than the manifest, changelog, fragments, lockfile and peers file\n  changed. The PR body lists README lines that name the previous version for a person to review; prose is not\n  rewritten. It also deletes `opf.requiresUnreleasedCore` from the manifest when the sibling declares it (see above; `plan` flags a release commit that keeps it). Branch `codex/release-<package>-<x-y-z>` unless `--branch` is given. An open release-prep PR (found by\n  branch or by a \"release <package> X.Y.Z\" title) or a merged one is detected and nothing is written.\n- `tag` re-verifies right before tagging: the version at the release commit, that the commit is on `main`, green\n  required checks, every upstream of the train on npm and every runtime floor naming a version npm has. It then creates\n  `refs/tags/<prefix>X.Y.Z` (`opf-v`, `opf-render-v`, `opf-pptx-v`, `opf-editor-v`, `cli-v`) with\n  `POST /repos/{repo}/git/refs` on the release commit (checks that are still running, or not reported yet right after\n  the merge, stop it unless `--checks-wait-minutes N` is given: it then polls them every `--poll-seconds` for up to N\n  minutes, and a red check still stops it at once), polls that repository's publish workflow run for the tag\n  (default every 120 s, up to 90 min), polls npm until the version is visible, and runs `verify`. A tag that already\n  exists on the release commit is not created again; one on another commit stops the train. A failed publish run stops\n  with its link: never move or re-push the tag; re-run a transient failure (`gh run rerun <id> --failed`), fix a real\n  one on `main` with a new version.\n- `verify` checks the registry manifest, that `gitHead` equals the tagged commit (and that the commit is on `main` and\n  carries the version), `dist.attestations` with the SLSA v1 provenance predicate, the provenance statement itself\n  (built by `.github/workflows/<publish workflow>` of the package's repository on `refs/tags/<tag>` from the tagged\n  commit, subject digest equal to `dist.integrity`), `npm audit signatures --include-attestations` in a scratch\n  project that installs exactly that version (no invalid or missing signatures; the package has a verified\n  attestation), and the GitHub release for the tag (every lockstep package's publish workflow creates one from 0.18\n  on, RR-20; a gallery release has none). A release that is not \"Latest\" passes: the CLI's is created with\n  `--latest=false` because core owns \"Latest\" in `OpenPresentation/opf`. The dist-tag is reported for information.\n  - Propagation: right after a publish, npm serves the packument (with `dist.attestations.url`) minutes before the\n    attestation bundle (HTTP 404 `{\"error\":\"Not found\"}`) and before a fresh `npm install` can resolve the version\n    (`notarget`, \"No matching version found\"); the first live use, core 0.12.1, failed `verify` on exactly these two\n    for 2-4 minutes. Only those two checks wait: `tag` and `run` retry the bundle fetch and the scratch install every\n    30 s (`--attest-poll-seconds`) for up to 15 min (`--attest-wait-minutes`; 0 turns the wait off) and say what they\n    wait for in the log. Any answer that is not \"not yet there\" fails at once without waiting: a bundle that is\n    present but has no SLSA provenance or names another repository, workflow, ref, commit or digest, an invalid or\n    missing signature, any other install error. If the wait runs out, the check fails with \"still not propagated\n    after N min\". Standalone `verify` keeps failing fast; `verify <package>@X.Y.Z --wait <minutes>` gives it the same\n    retry (for example right after a publish run you started by hand).\n- `run` repeats `plan` per package in order and does the next step: verify what is on npm, stop at an open release-prep\n  PR, open a missing one (`prep`), wait for pending checks on a merged release commit, then `tag`. Re-running it after\n  a stop skips every step already done; a version already on npm is never published again.\n\nThe follow-up docs PR (`release-plan.json`, the compatibility matrix and the quickstart) and the gallery consumer bumps\nstay by hand after the train.\n\n`.github/workflows/release-train.yml` is the same script as a `workflow_dispatch` (inputs: the versions and `mode`).\nUntil the GitHub App of [opf#298](https://github.com/OpenPresentation/opf/issues/298) exists it is plan-only: tags\npushed with a workflow's `GITHUB_TOKEN` start no other workflow (so the publish workflows would never run), and\n`GITHUB_TOKEN` cannot push branches or open pull requests in the sibling repositories, so `mode: execute` fails at\nonce. With the App (`ECOSYSTEM_APP_ID` variable and `ECOSYSTEM_APP_PRIVATE_KEY` secret, the roller's App) `mode:\nexecute` runs `run --execute` with the App's token.\n\nThe steps by hand below remain the fallback when the script cannot run.\n\n## The gallery lane (RR-78)\n\n`@openpresentation/gallery` (the pptx.gallery catalog records) is released from its own repository,\n[OpenPresentation/gallery](https://github.com/OpenPresentation/gallery), on its own version line, outside the lockstep\ntrain: `release-train.mjs` has it in `INDEPENDENT_PACKAGES` (repository `gallery`, tags `vX.Y.Z`, workflow\n`gallery-publish.yml`), never in `PACKAGES`, so no train plans, preps or tags it, and `release-plan.json` lists it under\n`independentPackages`. A gallery release needs no core release, and a core release does not release the gallery.\n\n- **Versions.** New records are a minor release. Removing or renaming an id, changing how an existing record draws, or\n  a change that needs a newer record schema (`opf.catalogSchema`) is a major release. The gallery repository's\n  pixel-stability check (`npm run check:stability`, on every pull request there and before every publish) fails a\n  minor or patch release that changes an existing record's drawing or removes an id.\n- **Release and publish.** In the gallery repository: a pull request that sets the version and the `CHANGELOG.md`\n  section, then a `vX.Y.Z` tag on main. Its `gallery-publish.yml` refuses a tag that is not `v` plus the version, a\n  tag off main and a `repository` other than OpenPresentation/gallery, runs every check, and publishes with\n  `npm publish --access public --provenance` (see its CONTRIBUTING.md).\n- **Verify.** `node scripts/release-train.mjs verify gallery@X.Y.Z` here (tag `vX.Y.Z` and gitHead in\n  OpenPresentation/gallery, provenance built by `gallery-publish.yml` on `refs/tags/vX.Y.Z`, signatures). The workflow\n  creates no GitHub release.\n- **Trusted publisher on npm** (`@openpresentation/gallery`, Settings, Trusted publishing): GitHub Actions,\n  organization `OpenPresentation`, repository `gallery`, workflow filename `gallery-publish.yml`, no environment.\n- **First release.** `1.0.0` is the first version published from OpenPresentation/gallery; `0.0.1` was a placeholder\n  published by hand. Against 0.0.1 the stability check runs as a major release and reports no changed record.\n\nFrom OPF 0.19, core and the CLI consume the independently published Gallery package: their Node defaults register\n`gallery`, and core has no `/catalog` subpath. OPF 0.19 used Gallery 2; OPF 0.20 uses Gallery 3.\nThe current ranges and exact verified set are in the package manifests and [release-plan.json](../release-plan.json).\nA core or CLI release needs a Gallery version its range accepts on npm first. A reviewed registry-adoption PR\nupdates those ranges and the authentic lockfile after independent publication verification. Stable release\npreparation follows that adoption; it does not perform the source configuration transition.\n\nBefore registry adoption, explicit authenticated candidate CI can stage reviewed gallery and engine tarballs\n(`scripts/candidate-gallery-build.mjs`, `scripts/pack-cli-candidate.mjs`, `scripts/pack-ecosystem.mjs`). Its recorded\noriginal/staged metadata and runtime checks qualify development consumers; they do not prove the declared source\nranges are registry-installable or authorize publication. Ordinary registry and publication gates stay unchanged.\nCore's registry tests use the exact gallery version and integrity recorded in the workspace lockfile.\n\n## Geometry-moving core releases: lockstep floors\n\nCore composition changes that move geometry (for example opf#169 cover centering) make the preview and the PPTX export drift when `@openpresentation/opf-render` and `@openpresentation/opf-pptx` resolve different core versions (measured: 186-300 pt title offsets on covers).\n\nRule: when a core release contains composition or geometry changes, the same release train must raise BOTH the renderer's and PPTX's core floor (`dependencies` and, where present, `peerDependencies`) to that core version, publish them together, and raise the editor's floor too. Do not release core alone and leave a sibling on the older floor.\n\nThe parity harness must always run with `--import <opf>/scripts/register-local-opf.mjs` (as `run.ps1` does) so every engine shares one core.\n\n## Release Preconditions\n\nBefore tagging, confirm that the release commit on `main` already contains:\n\n- `packages/javascript/package.json` with the intended version.\n- `CHANGELOG.md` with the matching release section (assembled from `changes/`, see above).\n- Passing `OPF CI` on the release commit.\n\nThe publish workflow validates the tag name against\n`packages/javascript/package.json`, so the tag must point at the release commit.\n\n## Tag And Publish\n\nUse the `opf-vX.Y.Z` tag form for the package release:\n\n```sh\ngit checkout main\ngit pull origin main\ngrep '\"version\"' packages/javascript/package.json\ngit tag opf-vX.Y.Z\ngit push origin opf-vX.Y.Z\n```\n\nFor example, version `0.3.0` used:\n\n```sh\ngit tag opf-v0.3.0\ngit push origin opf-v0.3.0\n```\n\nPushing the tag triggers `.github/workflows/npm-publish.yml`. The workflow:\n\n- runs on tags matching `opf-v*` or `@openpresentation/opf@v*`\n- installs dependencies with pnpm on Node 24\n- verifies the tag matches `packages/javascript/package.json`\n- runs typecheck and tests\n- runs the npm package dry-run check\n- publishes from `packages/javascript` with `npm publish --access public --provenance`\n\nDo not rerun a successful publish for the same version. npm package versions are\nimmutable; a second publish for an already-published version should fail.\n\n## Trusted Publishing\n\nnpm publishing is configured to use GitHub Actions OIDC trusted publishing, not\na long-lived npm token.\n\nExpected npm package trusted-publisher settings:\n\n| Setting | Value |\n|---|---|\n| Package | `@openpresentation/opf` |\n| Publisher | GitHub Actions |\n| Organization/repository | `OpenPresentation/opf` |\n| Workflow filename | `npm-publish.yml` |\n| Environment | empty, unless the workflow is later moved behind a GitHub Environment |\n| Permission | `npm publish` |\n\nExpected workflow settings:\n\n```yaml\npermissions:\n  contents: read\n  id-token: write\n```\n\nThe publish step should not set `NODE_AUTH_TOKEN`:\n\n```yaml\n- name: Publish to npm\n  working-directory: packages/javascript\n  run: npm publish --access public\n```\n\nIf a future release fails with npm authentication errors, check the npm\ntrusted-publisher settings first and repair the OIDC workflow. Do not add an\n`NPM_TOKEN` fallback or publish locally; the required trusted-publishing and\nprovenance gates still apply.\n\n## Verify The Release\n\n`node scripts/release-train.mjs verify <package>@X.Y.Z` runs every registry check of this section and the provenance\nchecks (see \"Release train\" above). By hand, after the workflow completes, verify npm:\n\n```sh\nnpm view @openpresentation/opf version\n```\n\nThe output should equal the package version that was tagged.\n\nSpot-check the validator API from a clean project or temporary directory:\n\n```sh\nnpm install @openpresentation/opf@X.Y.Z\nnode --input-type=module -e \"import {validate} from '@openpresentation/opf'; console.log(validate({name:'t', narrative:'not-a-real-id', slides:[{title:'t'}]}, {only:['format','references']}).findings)\"\n```\n\nThe expected result is one `opf/unresolved-reference` warning for the narrative (no catalog is registered).\n\n## GitHub Release Notes\n\nFrom 0.18 on, every lockstep package's tag workflow ends in a `release` job that creates a GitHub Release after the npm\npublish (RR-20). The job holds `contents: write`; the publish job keeps only `id-token: write` for provenance. It takes\nthe notes from the matching `## X.Y.Z` section of the package's changelog and fails when the section is missing.\n\n| Package | Repository, workflow | Tag | Title | Changelog | Latest |\n| --- | --- | --- | --- | --- | --- |\n| `@openpresentation/opf` | `opf`, `npm-publish.yml` | `opf-vX.Y.Z` | `@openpresentation/opf X.Y.Z` | `CHANGELOG.md` | yes |\n| `@openpresentation/opf-render` | `opf-render`, `npm-publish.yml` | `opf-render-vX.Y.Z` | `@openpresentation/opf-render X.Y.Z` | `CHANGELOG.md` | yes |\n| `@openpresentation/opf-pptx` | `opf-pptx`, `release.yml` | `opf-pptx-vX.Y.Z` | `@openpresentation/opf-pptx X.Y.Z` | `CHANGELOG.md` | yes |\n| `@openpresentation/opf-editor` | `opf-editor`, `release.yml` | `opf-editor-vX.Y.Z` | `@openpresentation/opf-editor X.Y.Z` | `CHANGELOG.md` | yes |\n| `@openpresentation/cli` | `opf`, `cli-publish.yml` | `cli-vX.Y.Z` | `@openpresentation/cli X.Y.Z` | `packages/cli/CHANGELOG.md` | no (core owns it) |\n\nReleases before 0.18 are not backfilled. `verify` requires the release for each of these packages. If release creation\nfailed, rerun the failed `release` job (it keeps an existing release and its notes), or create the missing release for\nthe existing tag, for example:\n\n```sh\ngh release create opf-render-vX.Y.Z \\\n  --repo OpenPresentation/opf-render \\\n  --title '@openpresentation/opf-render X.Y.Z' \\\n  --notes-file /path/to/release-notes.md \\\n  --verify-tag --latest\n```\n\nUse the matching `## X.Y.Z` section of the changelog as the release notes.\n\n## Troubleshooting\n\nIf the tag/version check fails, the tag does not point at the release commit or\nthe tag name does not match `packages/javascript/package.json`. Stop and inspect\nthe exact tag and merged release source. Never move or re-push a release tag.\nFix a real source or version error on `main` through a new release-prep PR and\nuse a new version/tag after its gates pass. A transient workflow failure may be\nretried on the same unchanged tag; it does not authorize replacing the tag.\n\nIf npm publish fails with `ENEEDAUTH`, confirm:\n\n- npm has a trusted publisher for `OpenPresentation/opf`\n- the trusted publisher uses workflow filename `npm-publish.yml`\n- `.github/workflows/npm-publish.yml` has `id-token: write`\n- the publish job is running on a modern Node/npm toolchain\n\nIf npm publish fails after the version is already present on npm, do not retry\nthe same publish. Verify the package and treat the failure as a duplicate\npublish attempt.\n\n### CLI peer contracts before a new minor train\n\nA CLI release prep advances development pins, but does not define a new runtime peer contract.\nBefore a train crosses an incompatible peer minor (for example 0.18 to 0.19), the reviewed feature changes\nmust align the CLI's peer metadata with core's peer manifest and `packages/javascript/src/node/peers.ts`.\nRelease core's new contract first. Then CLI prep keeps those aligned ranges and advances its core dependency\nand development pins. If CLI metadata still names the old incompatible line, prep stops before cloning;\nmake the contract change in its own reviewed PR, rather than editing core runtime files in release prep.\n\n\n### Scheduled Editor measurement policy (RR-68)\n\nThe Editor's `.github/workflows/flake-repeat.yml` declares that its scheduled repeat measures rather than gates.\nThe fallback-all mode in `pr-gate.mjs` and `release-train.mjs` therefore treats that measurement as advisory only\nwhen authenticated workflow-run metadata verifies `OpenPresentation/opf-editor`, GitHub Actions app 15368,\nworkflow 373564717, that exact path, event `schedule`, branch `main`, the observed commit SHA and check-suite\nassociation. Both the check runs and the running suite follow this policy; advisory activity and failures remain\nvisible. Explicitly required contexts always gate, including the same job name. Commit statuses, other workflows,\nevents, repositories or apps, and missing or inaccessible identity metadata continue to gate.\n\nIdentity lookups are cached per candidate run and commit for each observer's lifetime, including failed lookups;\nthey do not poll workflow state. The policy changes no checks, thresholds, retries or workflow executions, and does\nnot authorize using an unmerged tooling change for a release.\n"
+    "markdown": "# OPF Release Process\n\nUse Node 24 (`24.x`) for all future source, candidate and registry verification.\nThe packages declare the open-ended `engines.node` `>=22` (RR-20, tested on Node 22, 24 and 26 by the `node-range`\nCI jobs, which run in the merge queue and on pull requests labelled `full-ci`); a closed range such as `24.x` makes npm on any other Node silently install an older release, and\n`pnpm check:engines-range` fails on one, including in a lockfile that pins a release made after the fix.\nThe next releases must document the [Node 24 migration](migrations/node24.md)\nand use new versions. Historical dual-runtime release records remain unchanged.\n\nThis document is the release runbook for the public JavaScript package,\n[`@openpresentation/opf`](https://www.npmjs.com/package/@openpresentation/opf).\n\nThe canonical release path is:\n\n1. Merge the release commit to `main`.\n2. Push a semver tag whose name matches the package version.\n3. Let GitHub Actions publish to npm through npm trusted publishing.\n4. Verify npm and the GitHub Release the publish workflow creates from the changelog section.\n\n## Agent authorization and coordinated release order\n\nThe owner authorized agents to prepare and publish npm releases on 2026-09-29\nand for future releases whenever a release is required. This does not waive any\ngate: a release still needs a merged release-prep PR, green required checks and\nthe verification below. Agents keep publishing on the trusted-publishing\nworkflows (GitHub Actions OIDC with `--provenance`). If a workflow cannot run,\nstop and repair the trusted-publishing path; do not substitute a local publish\nor an npm-token publish that omits the required provenance.\n\nThe engine packages depend on each other, so publish in this order and wait for\neach version to appear on the registry before starting the next:\n\n1. `@openpresentation/opf` (this repository, `opf-vX.Y.Z` tag).\n2. `@openpresentation/opf-render` (`opf-render-vX.Y.Z` tag) and\n   `@openpresentation/opf-pptx` (`opf-pptx-vX.Y.Z` tag). Both depend on core; PPTX\n   also devDepends on the renderer, so publish the renderer first.\n3. `@openpresentation/opf-editor` (`opf-editor-vX.Y.Z` tag), which depends on core\n   and peers/devDepends on the renderer and PPTX.\n\nEach sibling's release-prep PR raises its dependency floors to the just-published\nversions. Its lockfile can only be refreshed after the upstream version exists on\nnpm (`npm install --package-lock-only`), so merge sibling release PRs only after\nthe upstream publish. `@openpresentation/cli` depends on core (a regular dependency; its floor is raised by the release-prep PR like the others, the commands run that core's Node engine) and is released\nseparately by `cli-publish.yml` (`cli-vX.Y.Z`) when a CLI release is needed.\n\nThe CLI release gate includes the installed-package regression `packages/cli/test/installed-regression.mjs` (RR-59, [opf#476](https://github.com/OpenPresentation/opf/issues/476)). It drives the installed `opf` binary beside the published opf-render and opf-pptx, the render font packages and the Noto JP and SC script packages, with no network after the install (a preload refuses every connection and fetch, and a local server that the image URLs point at counts zero requests): `opf convert deck.opf.json deck.svg` embeds `Noto Sans JP` 400 and 700 for a `ja-JP` deck, nothing under `--text system` and no CJK face for a Latin-only deck; `opf convert deck.opf.json deck.pptx` of a deck with an `https:` content image (an image block and a quote photo) exits 0 with a `pptx/unresolved-asset` warning at the slide path and the placeholder, exits 1 and writes no file under `--fail-on warning`, and exports a native picture for an embedded or local PNG under `--fail-on warning`. It runs in `pnpm test:cli:packed:peers` (the candidate CLI and core tarballs; OPF CI, the Windows and engines-range CLI jobs, and `cli-publish.yml` before `npm publish`) and in `pnpm test:registry-ecosystem` (the published set of `release-plan.json`, from plan 0.16).\n\nA sibling pull request that needs a core that is not on npm yet (a breaking core release and its sibling PRs, `Depends-On: OpenPresentation/opf#N`) declares it in its `package.json` as `\"opf\": { \"requiresUnreleasedCore\": \"X.Y.Z\" }` (RR-55). Its CI then skips only the packed install against published dependencies (`npm run test:packed`, with a `::notice::`) while the installed published `@openpresentation/opf` is lower than `X.Y.Z`; every linked-ecosystem step still runs. The field is for pull requests only: `release-train.mjs prep` deletes it (and refuses a field above the core of the train), and `plan` flags a release commit whose `package.json` still carries it.\n\nRelease-prep PRs contain only version bumps, changelog entries, dependency ranges\nand lockfile changes (plus current-instruction docs). The changelog entries are\nnot written by hand: every change adds a fragment `changes/<slug>.md` in its own\nPR (RR-46, [changes/README.md](../changes/README.md)), and the release-prep PR\nruns the assembler, which moves the fragments into the new release section of\n`CHANGELOG.md` and deletes them. Each sibling repository has the same\n`changes/` directory and script:\n\n```sh\n# core (packages are named in each fragment: opf = CHANGELOG.md, cli = packages/cli/CHANGELOG.md)\nnode scripts/changelog-fragments.mjs assemble --version X.Y.Z --package opf --date YYYY-MM-DD\nnode scripts/changelog-fragments.mjs assemble --version A.B.C --package cli   # only when the CLI is released\n# opf-render, opf-pptx, opf-editor\nnode scripts/changelog-fragments.mjs assemble --version X.Y.Z --date YYYY-MM-DD [--summary \"Patch release: ...\"]\n```\n\nUse `--dry-run` to preview, and check that no `changes/*.md` other than\n`README.md` remains for the released package before opening the PR. After the whole set is on\nthe registry, a follow-up docs change updates `release-plan.json`, the\ncompatibility matrix and the quickstart to the published set, and the gallery\nconsumer dependencies are bumped.\n\n## Release train (scripted, RR-51)\n\n`scripts/release-train.mjs` runs the coordinated release above in lockstep order. It is run by the supervisor with\ntheir own `gh` login (or `GH_TOKEN`); every command is a dry run unless `--execute` is given. It only reads, opens\nrelease-prep pull requests and creates tags: it never merges a pull request and never publishes. Each package is still\npublished by its own repository's trusted-publishing workflow (OIDC, `--provenance`) when its tag appears.\n\nName the versions of the train, any subset: `--core X.Y.Z --render X.Y.Z --pptx X.Y.Z --editor X.Y.Z --cli X.Y.Z`.\nThe order is always core, then opf-render, then opf-pptx, then opf-editor and the CLI.\n\n```sh\n# 1. What is missing (read only; exit 1 until every package is on npm)\nnode scripts/release-train.mjs plan --core 0.12.1 --render 0.12.1 --pptx 0.12.3 --editor 0.11.3 --cli 0.10.1\n\n# 2. The release-prep PR of the next package, once its upstream is on npm (dry run first: a scratch clone and the diff)\nnode scripts/release-train.mjs prep render --core 0.12.1 --render 0.12.1 [--item RR-nn]\nnode scripts/release-train.mjs prep render --core 0.12.1 --render 0.12.1 --item RR-nn --execute\n\n# 3. After a person merged it with green CI: tag the release commit, wait for the publish run and npm, verify\nnode scripts/release-train.mjs tag render --core 0.12.1 --render 0.12.1 --execute\n\n# 4. Verify any published version (also run by `tag` and `run`)\nnode scripts/release-train.mjs verify @openpresentation/opf-render@0.12.1\n\n# Or the whole sequence: it stops at the first step that needs a person and prints the command to resume\nnode scripts/release-train.mjs run --core 0.12.1 --render 0.12.1 --pptx 0.12.3 --editor 0.11.3 --cli 0.10.1 --execute\n```\n\nWhat each step checks:\n\n- `plan` reads, per package: whether the version is already on npm (then it is only verified), the version in the\n  manifest at `main`'s head, the release commit (the commit that set the version) and its merged release-prep PR, the\n  required checks on the release commit (the `main` ruleset's required checks; for a repository without a ruleset,\n  every reported check apart from existing advisory bots and the identity-verified scheduled Editor flake measurement), the tag, whether the upstream versions of the train are on npm, and the dependency floors.\n  It flags every sibling whose `@openpresentation/opf` floor stays below a new core in the train, with hints from core's\n  fragments or changelog section: the tool cannot know whether a core release moves geometry, so the release owner\n  decides whether the lockstep rule below applies (flag, never decided).\n- `prep` refuses until every upstream version of the train is on npm. In a scratch clone of `main` it bumps the\n  version, runs `node scripts/changelog-fragments.mjs assemble --version X.Y.Z --date <today>` (with `--package opf` or\n  `--package cli` in core, `--summary` when given), raises the floors that name a package of the train (caret and\n  tilde ranges keep their operator; exact devDependency pins move to the exact version; `workspace:*` is untouched;\n  for CLI preparation, already-compatible patch peer ranges stay unchanged while development pins advance;\n  core runtime files are never edited by CLI prep) and refreshes the lockfile\n  (`npm install --package-lock-only` in the siblings, `pnpm install --lockfile-only` in core). It fails if a fragment\n  for the package is left or if anything other than the manifest, changelog, fragments, lockfile and peers file\n  changed. The PR body lists README lines that name the previous version for a person to review; prose is not\n  rewritten. It also deletes `opf.requiresUnreleasedCore` from the manifest when the sibling declares it (see above; `plan` flags a release commit that keeps it). Branch `codex/release-<package>-<x-y-z>` unless `--branch` is given. An open release-prep PR (found by\n  branch or by a \"release <package> X.Y.Z\" title) or a merged one is detected and nothing is written.\n- `tag` re-verifies right before tagging: the version at the release commit, that the commit is on `main`, green\n  required checks, every upstream of the train on npm and every runtime floor naming a version npm has. It then creates\n  `refs/tags/<prefix>X.Y.Z` (`opf-v`, `opf-render-v`, `opf-pptx-v`, `opf-editor-v`, `cli-v`) with\n  `POST /repos/{repo}/git/refs` on the release commit (checks that are still running, or not reported yet right after\n  the merge, stop it unless `--checks-wait-minutes N` is given: it then polls them every `--poll-seconds` for up to N\n  minutes, and a red check still stops it at once), polls that repository's publish workflow run for the tag\n  (default every 120 s, up to 90 min), polls npm until the version is visible, and runs `verify`. A tag that already\n  exists on the release commit is not created again; one on another commit stops the train. A failed publish run stops\n  with its link: never move or re-push the tag; re-run a transient failure (`gh run rerun <id> --failed`), fix a real\n  one on `main` with a new version.\n- `verify` checks the registry manifest, that `gitHead` equals the tagged commit (and that the commit is on `main` and\n  carries the version), `dist.attestations` with the SLSA v1 provenance predicate, the provenance statement itself\n  (built by `.github/workflows/<publish workflow>` of the package's repository on `refs/tags/<tag>` from the tagged\n  commit, subject digest equal to `dist.integrity`), `npm audit signatures --include-attestations` in a scratch\n  project that installs exactly that version (no invalid or missing signatures; the package has a verified\n  attestation), and the GitHub release for the tag (every lockstep package's publish workflow creates one from 0.18\n  on, RR-20; a gallery release has none). A release that is not \"Latest\" passes: the CLI's is created with\n  `--latest=false` because core owns \"Latest\" in `OpenPresentation/opf`. The dist-tag is reported for information.\n  - Propagation: right after a publish, npm serves the packument (with `dist.attestations.url`) minutes before the\n    attestation bundle (HTTP 404 `{\"error\":\"Not found\"}`) and before a fresh `npm install` can resolve the version\n    (`notarget`, \"No matching version found\"); the first live use, core 0.12.1, failed `verify` on exactly these two\n    for 2-4 minutes. Only those two checks wait: `tag` and `run` retry the bundle fetch and the scratch install every\n    30 s (`--attest-poll-seconds`) for up to 15 min (`--attest-wait-minutes`; 0 turns the wait off) and say what they\n    wait for in the log. Any answer that is not \"not yet there\" fails at once without waiting: a bundle that is\n    present but has no SLSA provenance or names another repository, workflow, ref, commit or digest, an invalid or\n    missing signature, any other install error. If the wait runs out, the check fails with \"still not propagated\n    after N min\". Standalone `verify` keeps failing fast; `verify <package>@X.Y.Z --wait <minutes>` gives it the same\n    retry (for example right after a publish run you started by hand).\n- `run` repeats `plan` per package in order and does the next step: verify what is on npm, stop at an open release-prep\n  PR, open a missing one (`prep`), wait for pending checks on a merged release commit, then `tag`. Re-running it after\n  a stop skips every step already done; a version already on npm is never published again.\n\nThe follow-up docs PR (`release-plan.json`, the compatibility matrix and the quickstart) and the gallery consumer bumps\nstay by hand after the train.\n\n`.github/workflows/release-train.yml` is the same script as a `workflow_dispatch` (inputs: the versions and `mode`).\nUntil the GitHub App of [opf#298](https://github.com/OpenPresentation/opf/issues/298) exists it is plan-only: tags\npushed with a workflow's `GITHUB_TOKEN` start no other workflow (so the publish workflows would never run), and\n`GITHUB_TOKEN` cannot push branches or open pull requests in the sibling repositories, so `mode: execute` fails at\nonce. With the App (`ECOSYSTEM_APP_ID` variable and `ECOSYSTEM_APP_PRIVATE_KEY` secret, the roller's App) `mode:\nexecute` runs `run --execute` with the App's token.\n\nThe steps by hand below remain the fallback when the script cannot run.\n\n## The gallery lane (RR-78)\n\n`@openpresentation/gallery` (the pptx.gallery catalog records) is released from its own repository,\n[OpenPresentation/gallery](https://github.com/OpenPresentation/gallery), on its own version line, outside the lockstep\ntrain: `release-train.mjs` has it in `INDEPENDENT_PACKAGES` (repository `gallery`, tags `vX.Y.Z`, workflow\n`gallery-publish.yml`), never in `PACKAGES`, so no train plans, preps or tags it, and `release-plan.json` lists it under\n`independentPackages`. A gallery release needs no core release, and a core release does not release the gallery.\n\n- **Versions.** New records are a minor release. Removing or renaming an id, changing how an existing record draws, or\n  a change that needs a newer record schema (`opf.catalogSchema`) is a major release. The gallery repository's\n  pixel-stability check (`npm run check:stability`, on every pull request there and before every publish) fails a\n  minor or patch release that changes an existing record's drawing or removes an id.\n- **Release and publish.** In the gallery repository: a pull request that sets the version and the `CHANGELOG.md`\n  section, then a `vX.Y.Z` tag on main. Its `gallery-publish.yml` refuses a tag that is not `v` plus the version, a\n  tag off main and a `repository` other than OpenPresentation/gallery, runs every check, and publishes with\n  `npm publish --access public --provenance` (see its CONTRIBUTING.md).\n- **Verify.** `node scripts/release-train.mjs verify gallery@X.Y.Z` here (tag `vX.Y.Z` and gitHead in\n  OpenPresentation/gallery, provenance built by `gallery-publish.yml` on `refs/tags/vX.Y.Z`, signatures). The workflow\n  creates no GitHub release.\n- **Trusted publisher on npm** (`@openpresentation/gallery`, Settings, Trusted publishing): GitHub Actions,\n  organization `OpenPresentation`, repository `gallery`, workflow filename `gallery-publish.yml`, no environment.\n- **First release.** `1.0.0` is the first version published from OpenPresentation/gallery; `0.0.1` was a placeholder\n  published by hand. Against 0.0.1 the stability check runs as a major release and reports no changed record.\n\nFrom OPF 0.19, core and the CLI consume the independently published Gallery package: their Node defaults register\n`gallery`, and core has no `/catalog` subpath. OPF 0.19 used Gallery 2; OPF 0.20 uses Gallery 3.\nThe current ranges and exact verified set are in the package manifests and [release-plan.json](../release-plan.json).\nA core or CLI release needs a Gallery version its range accepts on npm first. A reviewed registry-adoption PR\nupdates those ranges and the authentic lockfile after independent publication verification. Stable release\npreparation follows that adoption; it does not perform the source configuration transition.\n\nBefore registry adoption, explicit authenticated candidate CI can stage reviewed gallery and engine tarballs\n(`scripts/candidate-gallery-build.mjs`, `scripts/pack-cli-candidate.mjs`, `scripts/pack-ecosystem.mjs`). Its recorded\noriginal/staged metadata and runtime checks qualify development consumers; they do not prove the declared source\nranges are registry-installable or authorize publication. Ordinary registry and publication gates stay unchanged.\nCore's registry tests use the exact gallery version and integrity recorded in the workspace lockfile.\n\n## Geometry-moving core releases: lockstep floors\n\nCore composition changes that move geometry (for example opf#169 cover centering) make the preview and the PPTX export drift when `@openpresentation/opf-render` and `@openpresentation/opf-pptx` resolve different core versions (measured: 186-300 pt title offsets on covers).\n\nRule: when a core release contains composition or geometry changes, the same release train must raise BOTH the renderer's and PPTX's core floor (`dependencies` and, where present, `peerDependencies`) to that core version, publish them together, and raise the editor's floor too. Do not release core alone and leave a sibling on the older floor.\n\nThe parity harness must always run with `--import <opf>/scripts/register-local-opf.mjs` (as `run.ps1` does) so every engine shares one core.\n\n## Renderer font-count gate (RR-90)\n\nThe installed-consumer check (`scripts/test-packed-ecosystem.mjs`) and `test:gallery-lazy-fonts` compare the number of vendored faces a renderer lists as lazy fonts with `scripts/lazy-font-counts.mjs`. A renderer release whose fonts did not change needs no new entry. The gate hashes the renderer package's font set, which is 143 files: `dist/font-manifest.js` and every file under `fonts/` (faces, licenses, `PROVENANCE.json`, `NOTICE.md`). An unlisted stable version passes when that hash is in `REVIEWED_FONT_SETS` and its measured count equals the count recorded there.\n\nIt fails closed, with a message that says what changed, when:\n\n- the font files differ from every reviewed set (the message prints the new hashes): review what changed, then add the set to `REVIEWED_FONT_SETS` and the version's count to `LAZY_FONT_COUNTS`;\n- the font files are a reviewed set but the count differs: find out why the count moved, then add an entry;\n- the version is a prerelease: it always needs its own `LAZY_FONT_COUNTS` entry.\n\nTo review a set, pack the release (`npm pack @openpresentation/opf-render@<version>`), run `hashFontSet` from `scripts/lazy-font-counts.mjs` over the unpacked `package/` folder, and record the result with the versions you checked. Every existing `LAZY_FONT_COUNTS` entry stays and keeps its own rule.\n\n## Release Preconditions\n\nBefore tagging, confirm that the release commit on `main` already contains:\n\n- `packages/javascript/package.json` with the intended version.\n- `CHANGELOG.md` with the matching release section (assembled from `changes/`, see above).\n- Passing `OPF CI` on the release commit.\n\nThe publish workflow validates the tag name against\n`packages/javascript/package.json`, so the tag must point at the release commit.\n\n## Tag And Publish\n\nUse the `opf-vX.Y.Z` tag form for the package release:\n\n```sh\ngit checkout main\ngit pull origin main\ngrep '\"version\"' packages/javascript/package.json\ngit tag opf-vX.Y.Z\ngit push origin opf-vX.Y.Z\n```\n\nFor example, version `0.3.0` used:\n\n```sh\ngit tag opf-v0.3.0\ngit push origin opf-v0.3.0\n```\n\nPushing the tag triggers `.github/workflows/npm-publish.yml`. The workflow:\n\n- runs on tags matching `opf-v*` or `@openpresentation/opf@v*`\n- installs dependencies with pnpm on Node 24\n- verifies the tag matches `packages/javascript/package.json`\n- runs typecheck and tests\n- runs the npm package dry-run check\n- publishes from `packages/javascript` with `npm publish --access public --provenance`\n\nDo not rerun a successful publish for the same version. npm package versions are\nimmutable; a second publish for an already-published version should fail.\n\n## Trusted Publishing\n\nnpm publishing is configured to use GitHub Actions OIDC trusted publishing, not\na long-lived npm token.\n\nExpected npm package trusted-publisher settings:\n\n| Setting | Value |\n|---|---|\n| Package | `@openpresentation/opf` |\n| Publisher | GitHub Actions |\n| Organization/repository | `OpenPresentation/opf` |\n| Workflow filename | `npm-publish.yml` |\n| Environment | empty, unless the workflow is later moved behind a GitHub Environment |\n| Permission | `npm publish` |\n\nExpected workflow settings:\n\n```yaml\npermissions:\n  contents: read\n  id-token: write\n```\n\nThe publish step should not set `NODE_AUTH_TOKEN`:\n\n```yaml\n- name: Publish to npm\n  working-directory: packages/javascript\n  run: npm publish --access public\n```\n\nIf a future release fails with npm authentication errors, check the npm\ntrusted-publisher settings first and repair the OIDC workflow. Do not add an\n`NPM_TOKEN` fallback or publish locally; the required trusted-publishing and\nprovenance gates still apply.\n\n## Verify The Release\n\n`node scripts/release-train.mjs verify <package>@X.Y.Z` runs every registry check of this section and the provenance\nchecks (see \"Release train\" above). By hand, after the workflow completes, verify npm:\n\n```sh\nnpm view @openpresentation/opf version\n```\n\nThe output should equal the package version that was tagged.\n\nSpot-check the validator API from a clean project or temporary directory:\n\n```sh\nnpm install @openpresentation/opf@X.Y.Z\nnode --input-type=module -e \"import {validate} from '@openpresentation/opf'; console.log(validate({name:'t', narrative:'not-a-real-id', slides:[{title:'t'}]}, {only:['format','references']}).findings)\"\n```\n\nThe expected result is one `opf/unresolved-reference` warning for the narrative (no catalog is registered).\n\n## GitHub Release Notes\n\nFrom 0.18 on, every lockstep package's tag workflow ends in a `release` job that creates a GitHub Release after the npm\npublish (RR-20). The job holds `contents: write`; the publish job keeps only `id-token: write` for provenance. It takes\nthe notes from the matching `## X.Y.Z` section of the package's changelog and fails when the section is missing.\n\n| Package | Repository, workflow | Tag | Title | Changelog | Latest |\n| --- | --- | --- | --- | --- | --- |\n| `@openpresentation/opf` | `opf`, `npm-publish.yml` | `opf-vX.Y.Z` | `@openpresentation/opf X.Y.Z` | `CHANGELOG.md` | yes |\n| `@openpresentation/opf-render` | `opf-render`, `npm-publish.yml` | `opf-render-vX.Y.Z` | `@openpresentation/opf-render X.Y.Z` | `CHANGELOG.md` | yes |\n| `@openpresentation/opf-pptx` | `opf-pptx`, `release.yml` | `opf-pptx-vX.Y.Z` | `@openpresentation/opf-pptx X.Y.Z` | `CHANGELOG.md` | yes |\n| `@openpresentation/opf-editor` | `opf-editor`, `release.yml` | `opf-editor-vX.Y.Z` | `@openpresentation/opf-editor X.Y.Z` | `CHANGELOG.md` | yes |\n| `@openpresentation/cli` | `opf`, `cli-publish.yml` | `cli-vX.Y.Z` | `@openpresentation/cli X.Y.Z` | `packages/cli/CHANGELOG.md` | no (core owns it) |\n\nReleases before 0.18 are not backfilled. `verify` requires the release for each of these packages. If release creation\nfailed, rerun the failed `release` job (it keeps an existing release and its notes), or create the missing release for\nthe existing tag, for example:\n\n```sh\ngh release create opf-render-vX.Y.Z \\\n  --repo OpenPresentation/opf-render \\\n  --title '@openpresentation/opf-render X.Y.Z' \\\n  --notes-file /path/to/release-notes.md \\\n  --verify-tag --latest\n```\n\nUse the matching `## X.Y.Z` section of the changelog as the release notes.\n\n## Troubleshooting\n\nIf the tag/version check fails, the tag does not point at the release commit or\nthe tag name does not match `packages/javascript/package.json`. Stop and inspect\nthe exact tag and merged release source. Never move or re-push a release tag.\nFix a real source or version error on `main` through a new release-prep PR and\nuse a new version/tag after its gates pass. A transient workflow failure may be\nretried on the same unchanged tag; it does not authorize replacing the tag.\n\nIf npm publish fails with `ENEEDAUTH`, confirm:\n\n- npm has a trusted publisher for `OpenPresentation/opf`\n- the trusted publisher uses workflow filename `npm-publish.yml`\n- `.github/workflows/npm-publish.yml` has `id-token: write`\n- the publish job is running on a modern Node/npm toolchain\n\nIf npm publish fails after the version is already present on npm, do not retry\nthe same publish. Verify the package and treat the failure as a duplicate\npublish attempt.\n\n### CLI peer contracts before a new minor train\n\nA CLI release prep advances development pins, but does not define a new runtime peer contract.\nBefore a train crosses an incompatible peer minor (for example 0.18 to 0.19), the reviewed feature changes\nmust align the CLI's peer metadata with core's peer manifest and `packages/javascript/src/node/peers.ts`.\nRelease core's new contract first. Then CLI prep keeps those aligned ranges and advances its core dependency\nand development pins. If CLI metadata still names the old incompatible line, prep stops before cloning;\nmake the contract change in its own reviewed PR, rather than editing core runtime files in release prep.\n\n\n### Scheduled Editor measurement policy (RR-68)\n\nThe Editor's `.github/workflows/flake-repeat.yml` declares that its scheduled repeat measures rather than gates.\nThe fallback-all mode in `pr-gate.mjs` and `release-train.mjs` therefore treats that measurement as advisory only\nwhen authenticated workflow-run metadata verifies `OpenPresentation/opf-editor`, GitHub Actions app 15368,\nworkflow 373564717, that exact path, event `schedule`, branch `main`, the observed commit SHA and check-suite\nassociation. Both the check runs and the running suite follow this policy; advisory activity and failures remain\nvisible. Explicitly required contexts always gate, including the same job name. Commit statuses, other workflows,\nevents, repositories or apps, and missing or inaccessible identity metadata continue to gate.\n\nIdentity lookups are cached per candidate run and commit for each observer's lifetime, including failed lookups;\nthey do not poll workflow state. The policy changes no checks, thresholds, retries or workflow executions, and does\nnot authorize using an unmerged tooling change for a release.\n"
   },
   {
     "slug": "rich-text",
@@ -358,7 +358,7 @@ var docsData = Object.freeze([
     "slug": "yaml",
     "file": "docs/yaml.md",
     "title": "OPF as YAML",
-    "markdown": '# OPF as YAML\n\n`@openpresentation/opf/yaml` (RR-56) reads and writes an OPF deck as YAML, in both directions, with no renderer, fonts, network or model: the same input always gives the same output. The CLI exposes it through `opf convert` (`deck.opf.yaml` to `deck.opf.json` and back; `opf from-yaml` and `opf to-yaml` before 0.18), and every command that reads or writes a deck understands `.opf.yaml` files (and, the same way, [`.opf.md` Markdown decks](markdown.md#markdown-decks-in-every-command)); `parse` and `stringify` read and write a deck in JSON, YAML or Markdown with one call, and `open` and `save` of `@openpresentation/opf` read and write the files in Node.\n\n- **JSON stays canonical.** The schema, the interchange form and every package describe the JSON. A `.opf.yaml` file is an authoring serialization of the same data: the parsed YAML is exactly the JSON document, and the [schema](../spec/schemas/opf.schema.json) validates that parsed data.\n- **Write a deck by hand.** YAML has no braces, no quotes around keys and no trailing-comma errors, and a block scalar (`text: |`) keeps a paragraph readable. Comments are allowed in the file (they are not data).\n- **One strict dialect.** JSON-compatible YAML 1.2, core schema. Anything that could mean something else in another reader, or cannot exist in JSON, is an error with a line and a column.\n- **Round trip.** `toYaml` writes canonical text that `fromYaml` reads back to the same deck, and that converts back to itself byte for byte. Every one of the 127 example decks round-trips, JSON to YAML to JSON and YAML to JSON to YAML.\n- **Errors have places.** Findings use the shared Finding format of [validate](validate.md) and carry the source offset, length, line and column of the YAML that caused them, including the OPF findings mapped back to the YAML of the field they name.\n\n```js\nimport { fromYaml, toYaml } from "@openpresentation/opf/yaml";\n\nconst { presentation, valid, findings } = fromYaml(text);\nconst { yaml } = toYaml(presentation, { schemaComment: true });\n```\n\n```sh\nopf convert deck.opf.yaml deck.opf.json\nopf convert deck.opf.json deck.opf.yaml --schema-comment\nopf validate deck.opf.yaml\nopf convert deck.opf.yaml slides/deck.svg\n```\n\n## An example\n\n```yaml\n# yaml-language-server: $schema=https://openpresentation.org/schema/opf/v1\n$schema: https://openpresentation.org/schema/opf/v1\nname: Q3 Business Review\nlanguage: en-US\nslides:\n  - id: cover\n    layout: cover\n    title: Q3 Business Review\n    subtitle: Operations and growth\n    notes: Two minutes on the agenda, then straight into the numbers.\n  - title: Revenue grew every quarter\n    blocks:\n      - chart:\n          type: column\n          data:\n            columns:\n              - Quarter\n              - Revenue\n            rows:\n              - - Q1\n                - 12\n              - - Q2\n                - 18\n      - quote:\n          text: We would rather spend a week on capacity than a month on an outage.\n          attribution: Priya Raman, Head of Platform\n```\n\nis the same deck as the JSON it converts to: `name`, `language` and `slides` with the values above. `cover` is a 0.19 intent layout. To pin a block to a named area, write `region: <name>` on that block after reading the selected layout\'s `regions`; `layout: auto` explicitly asks for automatic composition. A comment and the first line are not data.\n\n## The dialect\n\n`fromYaml` accepts exactly this, and nothing else:\n\n| Rule | What happens otherwise |\n| --- | --- |\n| One document, with a mapping at the root | `yaml/empty` (nothing, or only comments), `yaml/multiple-documents` (a `---` separates two), `yaml/not-mapping` (a list or a bare value) |\n| YAML 1.2 core schema | `2026-10-01`, `yes`, `no`, `on`, `off` and `1_000` stay **strings**: only `true`/`false`, `null`/`~` and numbers (decimal, `0x1F`, `0o17`, exponents) are typed. Quote a value to force text |\n| No duplicate keys | `yaml/duplicate-key`, at the repeated key |\n| Keys are strings | `yaml/key` for `1:`, `true:`, `null:` or a collection used as a key. Quote it: `"1":` |\n| No custom tags | `yaml/tag` for `!custom`, `!!binary`, `!!set` and the like. The core tags `!!str`, `!!int`, `!!float`, `!!bool`, `!!null`, `!!map` and `!!seq` are allowed |\n| Finite numbers only | `yaml/number` for `.inf`, `-.inf` and `.nan`, with the hint to quote them |\n| No anchors, aliases or merge keys | `yaml/alias`, with help that points at `aliases: true` |\n| Syntax | `yaml/syntax` for anything the parser rejects, at the position it reports |\n\nA leading byte order mark and CRLF line endings are accepted. Offsets are UTF-16 units into the text you passed (a BOM counts as one); lines and columns are one-based and ignore the BOM. After the YAML parses, the deck goes through `validate` and each finding (`opf/...` rule ids) is located at the YAML node of the field it names: the value for a scalar, the key through the value for a mapping or a list, and the nearest existing ancestor for something that is missing.\n\n### `aliases: true`\n\nAnchors (`&name`), aliases (`*name`) and the `<<` merge key are valid YAML and handy for repeated values, but they are not JSON, many tools handle them differently, and an alias hides the size of what it expands to. They are refused by default. `fromYaml(text, { aliases: true })` (CLI: `opf convert deck.opf.yaml deck.opf.json --aliases`) expands them to plain data:\n\n```yaml\nslides:\n  - title: One\n    extensions:\n      owner: &owner { team: ops, oncall: true }\n  - title: Two\n    extensions:\n      owner: *owner\n      other:\n        <<: *owner\n        extra: 1\n```\n\nThe expansion is capped by the `yaml` package\'s `maxAliasCount` (100; each alias counts the nodes it expands to, so nested aliases that multiply exponentially are refused with `yaml/alias-limit`), and an alias that sits inside its own anchor is `yaml/alias-cycle`. What comes out is always finite, tree-shaped JSON data, and keys, tags and numbers are checked exactly as without the option. Writing never produces anchors or aliases.\n\n## Writing OPF as YAML\n\n`toYaml(presentation, { schemaComment })` first validates the presentation (`OPFYamlError`, `code: "invalid-document"`, when it is not valid OPF), then writes the canonical form:\n\n- keys in the order of the schema (the same order as [`opf format`](../packages/cli/README.md)): `$schema`, `name`, ..., `slides`, `assets`, ..., with keys the schema does not declare after them in their own order;\n- two-space indentation, block style throughout, no line folding (`lineWidth: 0`), a block scalar (`|`) for text with line breaks, one trailing newline, LF line endings;\n- strings that would read as another type, or as another type in a YAML 1.1 reader, are quoted: `"yes"`, `"No"`, `"on"`, `"2026-10-01"`, `"123"`, `"null"`, `"0x1F"`, `"12:30"`, and any string with leading or trailing spaces, a `#` or `: `. Mapping keys such as `"yes":` follow the same rule;\n- the text is **read back before it is returned**: it is parsed again in the strict dialect and compared with the input, key order included. If it does not read back to the same data, `toYaml` throws `OPFYamlError` with `code: "not-representable"` instead of writing something wrong (for example a lone surrogate in a string).\n\n`schemaComment: true` starts the file with `# yaml-language-server: $schema=<url>`, the deck\'s own `$schema` or else the canonical `https://openpresentation.org/schema/opf/v1`.\n\n### Editor autocomplete\n\nEditors that use the YAML language server (VS Code with the Red Hat YAML extension, Neovim, Zed, JetBrains) read the modeline on the first line and validate and complete the file against the schema:\n\n```yaml\n# yaml-language-server: $schema=https://openpresentation.org/schema/opf/v1\n```\n\n`opf convert deck.opf.json deck.opf.yaml --schema-comment` (and `opf create --schema-comment`) writes it. A command that rewrites a YAML file keeps the file\'s own first-line modeline verbatim (whatever URL it names, even a local schema path) and generates one only for `--schema-comment`. It is a comment: `fromYaml` ignores it.\n\n## Other exports\n\nThese three exports are not part of the `fromYaml`/`toYaml` pair. They exist so the CLI and other tools can reuse the reader.\n\n| Export | Purpose |\n| --- | --- |\n| `parseYamlData(yaml, options)` | The same strict dialect for any JSON-compatible root, for files that are not decks (a JSON Patch, a settings file). `{ value, valid, findings }` |\n| `scanYamlComments(yaml)` | `{ count, modeline? }`: the comments a rewrite would lose, and the editor modeline (the first-line `# yaml-language-server:` comment, verbatim) |\n| `YAML_SCHEMA_URL` | The canonical schema URL |\n\n## Findings\n\n`fromYaml(text, options)` never throws for malformed content. It returns the deck and the [validate](validate.md) report of it, `{ presentation, valid, findings, counts, schemaValid, checks }` (plus `template` and `unfilledVariables` for a deck with content variables), so a YAML file reports exactly what the same deck as JSON text does. `presentation` is a best effort when `valid` is false (an empty object after a YAML error). Each finding is a [Finding](finding-schema-reference.md) (`ruleId`, `severity`, `category`, `path`, `scope`, `message`, `help`) plus `location` (`offset`, `length`, `line`, `column`). Options: `validate` (`true`, the default, checks `format` and `references`; `validate` options pick other rules or categories, and `{}` runs every rule; `false` skips the check, so `schemaValid` is null) and `aliases` (default false).\n\nYAML errors are `format` findings: `yaml/syntax`, `yaml/empty`, `yaml/not-mapping`, `yaml/multiple-documents`, `yaml/duplicate-key`, `yaml/key`, `yaml/tag`, `yaml/number`, `yaml/alias`, `yaml/alias-limit`, `yaml/alias-cycle`. After one, no OPF check runs (`schemaValid: null`). Ids starting `opf/` are the `validate` findings of the deck, located in the YAML.\n\n## Command line\n\n```text\nopf convert <deck.opf.yaml|-> <output.opf.json|-> [--from yaml] [--to json] [--aliases] [--force] [--fail-on <level>]\nopf convert <deck.opf.json|-> <output.opf.yaml|-> [--to yaml] [--schema-comment] [--force] [--fail-on <level>]\n```\n\nOutput `-` writes stdout (with `--to`) and the JSON report goes to stderr. Exit codes: 0 success, 1 a deck that is not valid OPF, an output conflict or a finding at or above `--fail-on`, 2 usage, a YAML syntax error (with the located `findings`), a read error or I/O. Nothing is written on a failure. `--aliases` applies to a YAML input and `--schema-comment` to a YAML output; anywhere else they are usage errors. `opf from-yaml` and `opf to-yaml` were removed in 0.18.\n\n### YAML everywhere\n\nEvery command that reads a deck or a JSON Patch reads YAML too, through one reader:\n\n1. A file whose name ends `.yaml` or `.yml` is YAML, parsed in the strict dialect (no aliases). A name ending `.opf.md` is a [Markdown deck](markdown.md#markdown-decks-in-every-command), read the same way.\n2. Anything else (stdin and every other name) is JSON when the text starts with `{` or `[`; otherwise `--from yaml|md` (`--from json`) says what it is, and without it the command exits 2 and asks for it. `--from` applies to every deck input of the command and wins over a name.\n3. A YAML syntax or dialect error exits **2**, like invalid JSON, and the message carries the position: `Invalid YAML in deck.opf.yaml at line 5, column 5: Map keys must be unique [yaml/duplicate-key]`, with the located `findings` and `code: "invalid-yaml"` in the JSON error report. `opf validate` instead reports a YAML error as a `yaml/<rule>` finding and exits 1, as it does for JSON that does not parse. A deck with a syntax-valid but invalid OPF structure is reported by the command as it is for JSON (`validate` and `convert` locate their findings in the YAML).\n\nA deck is written as YAML when the output name ends `.yaml`/`.yml` or `--to yaml` is given (`--to json` forces JSON, `--to md` writes a Markdown deck). When the output is stdout or has another name, the format of the deck that was read is used (a YAML deck is edited, merged, filled, paginated and embedded back to YAML); `create` has no deck input and defaults to JSON. `opf format` canonicalizes a YAML file in place of the form it has (`-i`, `--check`); `opf convert` changes forms.\n\nThese are not deck serializations: `validate --config` and `--signals` output are JSON; `fill` data and the `ingest` source accept CSV, TSV or JSON. In `fill` and `ingest`, `--data-format csv|tsv|json` names the data format and `--to yaml` selects the output.\n\n**Comments are not preserved.** A command that rewrites a YAML file (`edit`, `format`, `merge`, `paginate`, `embed`, `fill`, `ingest --into`, `convert`) writes the canonical text of the data, so comments and the original quoting and layout are lost. The CLI prints `warning: <file> has N comments; comments are not preserved when OPF rewrites a YAML file.` on stderr, and does not fail. The `# yaml-language-server:` line is kept.\n\n## Decisions and limits\n\nThese choices are the defaults of the module and can be changed.\n\n- **JSON stays canonical and the interchange form.** The schemas, the catalogs, the reports, the renderer, the editor and the PPTX converter all take the JSON document; YAML is converted at the edge, by `fromYaml` and `toYaml`, and `opf convert deck.opf.yaml deck.opf.json` gives you the JSON. Nothing in OPF depends on a YAML library at run time except this subpath and the Markdown front matter.\n- **Comments are not preserved by commands that rewrite.** The YAML is parsed to plain data and written again from the data, which is what makes the output canonical and the same deck always the same bytes. Preserving comments would need a lossless syntax tree through every edit and would make output depend on the history of the file. Use an editor to change a file that you annotate heavily, and keep the notes in `description`, `notes` or `extensions` when they should survive.\n- **Strict by default.** Anchors, aliases, merge keys, custom tags, duplicate keys, non-string keys and non-finite numbers are where YAML readers disagree (YAML 1.1 and 1.2, `<<`, `on`/`yes`, sexagesimal numbers) or where a document stops being JSON. A deck should mean the same thing in every tool, so the reader accepts the intersection and says where the text leaves it. `aliases: true` opts into expansion for files that already use it.\n- **pptx.dev\'s playground uses `aliases: true`** so that YAML pasted into it from other sources keeps working; the default of the module and of the CLI stays strict.\n- **One YAML reader.** The `yaml` package (ISC, no dependencies) reads and writes, with the core schema. The [Markdown](markdown.md) front matter and the `opf-slide` and `opf-block` fences follow the same rules (JSON-compatible YAML 1.2 core schema: no anchors, tags or duplicate keys).\n- **Block style only.** Tables and chart data are lists of lists, which block style spreads over many lines. The text is longer than the JSON but diffs line by line, and one style means one canonical form.\n- **Quoting is conservative.** The core schema reads `yes` and `2026-10-01` as text, but a YAML 1.1 reader does not, so the writer quotes them anyway.\n- **No new fields.** YAML adds nothing to the schema: there is no YAML-only key, and a file that does not validate as JSON does not validate as YAML.\n'
+    "markdown": '# OPF as YAML\n\n`@openpresentation/opf/yaml` (RR-56) reads and writes an OPF deck as YAML, in both directions, with no renderer, fonts, network or model: the same input always gives the same output. The CLI exposes it through `opf convert` (`deck.opf.yaml` to `deck.opf.json` and back; `opf from-yaml` and `opf to-yaml` before 0.18), and every command that reads or writes a deck understands `.opf.yaml` files (and, the same way, [`.opf.md` Markdown decks](markdown.md#markdown-decks-in-every-command)); `parse` and `stringify` read and write a deck in JSON, YAML or Markdown with one call, and `open` and `save` of `@openpresentation/opf` read and write the files in Node.\n\n- **JSON stays canonical.** The schema, the interchange form and every package describe the JSON. A `.opf.yaml` file is an authoring serialization of the same data: the parsed YAML is exactly the JSON document, and the [schema](../spec/schemas/opf.schema.json) validates that parsed data.\n- **Write a deck by hand.** YAML has no braces, no quotes around keys and no trailing-comma errors, and a block scalar (`text: |`) keeps a paragraph readable. Comments are allowed in the file (they are not data).\n- **One strict dialect.** JSON-compatible YAML 1.2, core schema. Anything that could mean something else in another reader, or cannot exist in JSON, is an error with a line and a column.\n- **Round trip.** `toYaml` writes canonical text that `fromYaml` reads back to the same deck, and that converts back to itself byte for byte. Every one of the 128 example decks round-trips, JSON to YAML to JSON and YAML to JSON to YAML.\n- **Errors have places.** Findings use the shared Finding format of [validate](validate.md) and carry the source offset, length, line and column of the YAML that caused them, including the OPF findings mapped back to the YAML of the field they name.\n\n```js\nimport { fromYaml, toYaml } from "@openpresentation/opf/yaml";\n\nconst { presentation, valid, findings } = fromYaml(text);\nconst { yaml } = toYaml(presentation, { schemaComment: true });\n```\n\n```sh\nopf convert deck.opf.yaml deck.opf.json\nopf convert deck.opf.json deck.opf.yaml --schema-comment\nopf validate deck.opf.yaml\nopf convert deck.opf.yaml slides/deck.svg\n```\n\n## An example\n\n```yaml\n# yaml-language-server: $schema=https://openpresentation.org/schema/opf/v1\n$schema: https://openpresentation.org/schema/opf/v1\nname: Q3 Business Review\nlanguage: en-US\nslides:\n  - id: cover\n    layout: cover\n    title: Q3 Business Review\n    subtitle: Operations and growth\n    notes: Two minutes on the agenda, then straight into the numbers.\n  - title: Revenue grew every quarter\n    blocks:\n      - chart:\n          type: column\n          data:\n            columns:\n              - Quarter\n              - Revenue\n            rows:\n              - - Q1\n                - 12\n              - - Q2\n                - 18\n      - quote:\n          text: We would rather spend a week on capacity than a month on an outage.\n          attribution: Priya Raman, Head of Platform\n```\n\nis the same deck as the JSON it converts to: `name`, `language` and `slides` with the values above. `cover` is a 0.19 intent layout. To pin a block to a named area, write `region: <name>` on that block after reading the selected layout\'s `regions`; `layout: auto` explicitly asks for automatic composition. A comment and the first line are not data.\n\n## The dialect\n\n`fromYaml` accepts exactly this, and nothing else:\n\n| Rule | What happens otherwise |\n| --- | --- |\n| One document, with a mapping at the root | `yaml/empty` (nothing, or only comments), `yaml/multiple-documents` (a `---` separates two), `yaml/not-mapping` (a list or a bare value) |\n| YAML 1.2 core schema | `2026-10-01`, `yes`, `no`, `on`, `off` and `1_000` stay **strings**: only `true`/`false`, `null`/`~` and numbers (decimal, `0x1F`, `0o17`, exponents) are typed. Quote a value to force text |\n| No duplicate keys | `yaml/duplicate-key`, at the repeated key |\n| Keys are strings | `yaml/key` for `1:`, `true:`, `null:` or a collection used as a key. Quote it: `"1":` |\n| No custom tags | `yaml/tag` for `!custom`, `!!binary`, `!!set` and the like. The core tags `!!str`, `!!int`, `!!float`, `!!bool`, `!!null`, `!!map` and `!!seq` are allowed |\n| Finite numbers only | `yaml/number` for `.inf`, `-.inf` and `.nan`, with the hint to quote them |\n| No anchors, aliases or merge keys | `yaml/alias`, with help that points at `aliases: true` |\n| Syntax | `yaml/syntax` for anything the parser rejects, at the position it reports |\n\nA leading byte order mark and CRLF line endings are accepted. Offsets are UTF-16 units into the text you passed (a BOM counts as one); lines and columns are one-based and ignore the BOM. After the YAML parses, the deck goes through `validate` and each finding (`opf/...` rule ids) is located at the YAML node of the field it names: the value for a scalar, the key through the value for a mapping or a list, and the nearest existing ancestor for something that is missing.\n\n### `aliases: true`\n\nAnchors (`&name`), aliases (`*name`) and the `<<` merge key are valid YAML and handy for repeated values, but they are not JSON, many tools handle them differently, and an alias hides the size of what it expands to. They are refused by default. `fromYaml(text, { aliases: true })` (CLI: `opf convert deck.opf.yaml deck.opf.json --aliases`) expands them to plain data:\n\n```yaml\nslides:\n  - title: One\n    extensions:\n      owner: &owner { team: ops, oncall: true }\n  - title: Two\n    extensions:\n      owner: *owner\n      other:\n        <<: *owner\n        extra: 1\n```\n\nThe expansion is capped by the `yaml` package\'s `maxAliasCount` (100; each alias counts the nodes it expands to, so nested aliases that multiply exponentially are refused with `yaml/alias-limit`), and an alias that sits inside its own anchor is `yaml/alias-cycle`. What comes out is always finite, tree-shaped JSON data, and keys, tags and numbers are checked exactly as without the option. Writing never produces anchors or aliases.\n\n## Writing OPF as YAML\n\n`toYaml(presentation, { schemaComment })` first validates the presentation (`OPFYamlError`, `code: "invalid-document"`, when it is not valid OPF), then writes the canonical form:\n\n- keys in the order of the schema (the same order as [`opf format`](../packages/cli/README.md)): `$schema`, `name`, ..., `slides`, `assets`, ..., with keys the schema does not declare after them in their own order;\n- two-space indentation, block style throughout, no line folding (`lineWidth: 0`), a block scalar (`|`) for text with line breaks, one trailing newline, LF line endings;\n- strings that would read as another type, or as another type in a YAML 1.1 reader, are quoted: `"yes"`, `"No"`, `"on"`, `"2026-10-01"`, `"123"`, `"null"`, `"0x1F"`, `"12:30"`, and any string with leading or trailing spaces, a `#` or `: `. Mapping keys such as `"yes":` follow the same rule;\n- the text is **read back before it is returned**: it is parsed again in the strict dialect and compared with the input, key order included. If it does not read back to the same data, `toYaml` throws `OPFYamlError` with `code: "not-representable"` instead of writing something wrong (for example a lone surrogate in a string).\n\n`schemaComment: true` starts the file with `# yaml-language-server: $schema=<url>`, the deck\'s own `$schema` or else the canonical `https://openpresentation.org/schema/opf/v1`.\n\n### Editor autocomplete\n\nEditors that use the YAML language server (VS Code with the Red Hat YAML extension, Neovim, Zed, JetBrains) read the modeline on the first line and validate and complete the file against the schema:\n\n```yaml\n# yaml-language-server: $schema=https://openpresentation.org/schema/opf/v1\n```\n\n`opf convert deck.opf.json deck.opf.yaml --schema-comment` (and `opf create --schema-comment`) writes it. A command that rewrites a YAML file keeps the file\'s own first-line modeline verbatim (whatever URL it names, even a local schema path) and generates one only for `--schema-comment`. It is a comment: `fromYaml` ignores it.\n\n## Other exports\n\nThese three exports are not part of the `fromYaml`/`toYaml` pair. They exist so the CLI and other tools can reuse the reader.\n\n| Export | Purpose |\n| --- | --- |\n| `parseYamlData(yaml, options)` | The same strict dialect for any JSON-compatible root, for files that are not decks (a JSON Patch, a settings file). `{ value, valid, findings }` |\n| `scanYamlComments(yaml)` | `{ count, modeline? }`: the comments a rewrite would lose, and the editor modeline (the first-line `# yaml-language-server:` comment, verbatim) |\n| `YAML_SCHEMA_URL` | The canonical schema URL |\n\n## Findings\n\n`fromYaml(text, options)` never throws for malformed content. It returns the deck and the [validate](validate.md) report of it, `{ presentation, valid, findings, counts, schemaValid, checks }` (plus `template` and `unfilledVariables` for a deck with content variables), so a YAML file reports exactly what the same deck as JSON text does. `presentation` is a best effort when `valid` is false (an empty object after a YAML error). Each finding is a [Finding](finding-schema-reference.md) (`ruleId`, `severity`, `category`, `path`, `scope`, `message`, `help`) plus `location` (`offset`, `length`, `line`, `column`). Options: `validate` (`true`, the default, checks `format` and `references`; `validate` options pick other rules or categories, and `{}` runs every rule; `false` skips the check, so `schemaValid` is null) and `aliases` (default false).\n\nYAML errors are `format` findings: `yaml/syntax`, `yaml/empty`, `yaml/not-mapping`, `yaml/multiple-documents`, `yaml/duplicate-key`, `yaml/key`, `yaml/tag`, `yaml/number`, `yaml/alias`, `yaml/alias-limit`, `yaml/alias-cycle`. After one, no OPF check runs (`schemaValid: null`). Ids starting `opf/` are the `validate` findings of the deck, located in the YAML.\n\n## Command line\n\n```text\nopf convert <deck.opf.yaml|-> <output.opf.json|-> [--from yaml] [--to json] [--aliases] [--force] [--fail-on <level>]\nopf convert <deck.opf.json|-> <output.opf.yaml|-> [--to yaml] [--schema-comment] [--force] [--fail-on <level>]\n```\n\nOutput `-` writes stdout (with `--to`) and the JSON report goes to stderr. Exit codes: 0 success, 1 a deck that is not valid OPF, an output conflict or a finding at or above `--fail-on`, 2 usage, a YAML syntax error (with the located `findings`), a read error or I/O. Nothing is written on a failure. `--aliases` applies to a YAML input and `--schema-comment` to a YAML output; anywhere else they are usage errors. `opf from-yaml` and `opf to-yaml` were removed in 0.18.\n\n### YAML everywhere\n\nEvery command that reads a deck or a JSON Patch reads YAML too, through one reader:\n\n1. A file whose name ends `.yaml` or `.yml` is YAML, parsed in the strict dialect (no aliases). A name ending `.opf.md` is a [Markdown deck](markdown.md#markdown-decks-in-every-command), read the same way.\n2. Anything else (stdin and every other name) is JSON when the text starts with `{` or `[`; otherwise `--from yaml|md` (`--from json`) says what it is, and without it the command exits 2 and asks for it. `--from` applies to every deck input of the command and wins over a name.\n3. A YAML syntax or dialect error exits **2**, like invalid JSON, and the message carries the position: `Invalid YAML in deck.opf.yaml at line 5, column 5: Map keys must be unique [yaml/duplicate-key]`, with the located `findings` and `code: "invalid-yaml"` in the JSON error report. `opf validate` instead reports a YAML error as a `yaml/<rule>` finding and exits 1, as it does for JSON that does not parse. A deck with a syntax-valid but invalid OPF structure is reported by the command as it is for JSON (`validate` and `convert` locate their findings in the YAML).\n\nA deck is written as YAML when the output name ends `.yaml`/`.yml` or `--to yaml` is given (`--to json` forces JSON, `--to md` writes a Markdown deck). When the output is stdout or has another name, the format of the deck that was read is used (a YAML deck is edited, merged, filled, paginated and embedded back to YAML); `create` has no deck input and defaults to JSON. `opf format` canonicalizes a YAML file in place of the form it has (`-i`, `--check`); `opf convert` changes forms.\n\nThese are not deck serializations: `validate --config` and `--signals` output are JSON; `fill` data and the `ingest` source accept CSV, TSV or JSON. In `fill` and `ingest`, `--data-format csv|tsv|json` names the data format and `--to yaml` selects the output.\n\n**Comments are not preserved.** A command that rewrites a YAML file (`edit`, `format`, `merge`, `paginate`, `embed`, `fill`, `ingest --into`, `convert`) writes the canonical text of the data, so comments and the original quoting and layout are lost. The CLI prints `warning: <file> has N comments; comments are not preserved when OPF rewrites a YAML file.` on stderr, and does not fail. The `# yaml-language-server:` line is kept.\n\n## Decisions and limits\n\nThese choices are the defaults of the module and can be changed.\n\n- **JSON stays canonical and the interchange form.** The schemas, the catalogs, the reports, the renderer, the editor and the PPTX converter all take the JSON document; YAML is converted at the edge, by `fromYaml` and `toYaml`, and `opf convert deck.opf.yaml deck.opf.json` gives you the JSON. Nothing in OPF depends on a YAML library at run time except this subpath and the Markdown front matter.\n- **Comments are not preserved by commands that rewrite.** The YAML is parsed to plain data and written again from the data, which is what makes the output canonical and the same deck always the same bytes. Preserving comments would need a lossless syntax tree through every edit and would make output depend on the history of the file. Use an editor to change a file that you annotate heavily, and keep the notes in `description`, `notes` or `extensions` when they should survive.\n- **Strict by default.** Anchors, aliases, merge keys, custom tags, duplicate keys, non-string keys and non-finite numbers are where YAML readers disagree (YAML 1.1 and 1.2, `<<`, `on`/`yes`, sexagesimal numbers) or where a document stops being JSON. A deck should mean the same thing in every tool, so the reader accepts the intersection and says where the text leaves it. `aliases: true` opts into expansion for files that already use it.\n- **pptx.dev\'s playground uses `aliases: true`** so that YAML pasted into it from other sources keeps working; the default of the module and of the CLI stays strict.\n- **One YAML reader.** The `yaml` package (ISC, no dependencies) reads and writes, with the core schema. The [Markdown](markdown.md) front matter and the `opf-slide` and `opf-block` fences follow the same rules (JSON-compatible YAML 1.2 core schema: no anchors, tags or duplicate keys).\n- **Block style only.** Tables and chart data are lists of lists, which block style spreads over many lines. The text is longer than the JSON but diffs line by line, and one style means one canonical form.\n- **Quoting is conservative.** The core schema reads `yes` and `2026-10-01` as text, but a YAML 1.1 reader does not, so the writer quotes them anyway.\n- **No new fields.** YAML adds nothing to the schema: there is no YAML-only key, and a file that does not validate as JSON does not validate as YAML.\n'
   }
 ]);
 var docsRaw = docsData;

package/dist/examples.js

@@ -93973,6 +93973,147 @@ var examplesData = Object.freeze([
       }
     }
   },
+  {
+    "slug": "chart-colors",
+    "file": "examples/technical/chart-colors.opf.json",
+    "category": "technical",
+    "gallery": null,
+    "deck": {
+      "$schema": "https://openpresentation.org/schema/opf/v1",
+      "name": "Chart Colors",
+      "description": "Technical fixture for chart series colors: series follow the deck color scheme in order, chart.colors sets the first positions by ColorRef (a color-scheme slot, a hex color or a variable), and chart.highlight wins over it.",
+      "slides": [
+        {
+          "title": "Series follow the deck palette, and colors sets the first two",
+          "chart": {
+            "type": "column",
+            "alt": "Quarterly revenue, costs, services and support in $M; revenue peaks at 24 in Q3.",
+            "data": {
+              "columns": [
+                "Quarter",
+                "Revenue",
+                "Costs",
+                "Services",
+                "Support"
+              ],
+              "rows": [
+                [
+                  "Q1",
+                  12,
+                  8,
+                  5,
+                  3
+                ],
+                [
+                  "Q2",
+                  18,
+                  11,
+                  7,
+                  4
+                ],
+                [
+                  "Q3",
+                  24,
+                  15,
+                  9,
+                  6
+                ],
+                [
+                  "Q4",
+                  22,
+                  14,
+                  10,
+                  7
+                ]
+              ]
+            },
+            "axisTitles": {
+              "value": "$M"
+            },
+            "colors": [
+              "accent5",
+              "#E67E22"
+            ]
+          }
+        },
+        {
+          "title": "A pie takes one color per category",
+          "chart": {
+            "type": "pie",
+            "alt": "Share of Q3 revenue by line: product 55%, services 25%, support 15%, other 5%.",
+            "data": {
+              "columns": [
+                "Line",
+                "Share"
+              ],
+              "rows": [
+                [
+                  "Product",
+                  55
+                ],
+                [
+                  "Services",
+                  25
+                ],
+                [
+                  "Support",
+                  15
+                ],
+                [
+                  "Other",
+                  5
+                ]
+              ]
+            },
+            "colors": [
+              "#2ECC71",
+              "accent1",
+              "#E67E22"
+            ]
+          }
+        },
+        {
+          "title": "Highlight wins over colors",
+          "chart": {
+            "type": "column",
+            "alt": "Quarterly revenue in $M with Q3 highlighted at 24.",
+            "data": {
+              "columns": [
+                "Quarter",
+                "Revenue"
+              ],
+              "rows": [
+                [
+                  "Q1",
+                  12
+                ],
+                [
+                  "Q2",
+                  18
+                ],
+                [
+                  "Q3",
+                  24
+                ],
+                [
+                  "Q4",
+                  22
+                ]
+              ]
+            },
+            "colors": [
+              "#E67E22"
+            ],
+            "highlight": {
+              "categories": [
+                "Q3"
+              ]
+            }
+          }
+        }
+      ]
+    }
+  },
   {
     "slug": "chart-data-sources",
     "file": "examples/technical/chart-data-sources.opf.json",
@@ -96744,7 +96885,7 @@ var examplesData = Object.freeze([
     "deck": {
       "$schema": "https://openpresentation.org/schema/opf/v1",
       "name": "Table Cell Types",
-      "description": "Technical fixture for supported table cell scalar values.",
+      "description": "Technical fixture for supported table cell scalar values, and for a styled table: a bold cell keeps its number format, and a rich cell in a numeric column keeps the column's alignment.",
       "slides": [
         {
           "title": "Scalar Cells",
@@ -96785,6 +96926,146 @@ var examplesData = Object.freeze([
               ]
             ]
           }
+        },
+        {
+          "title": "Bold Cells And A Number Column",
+          "table": {
+            "columns": [
+              {
+                "value": "Region",
+                "style": {
+                  "bold": true,
+                  "padding": {
+                    "top": 10,
+                    "right": 14,
+                    "bottom": 10,
+                    "left": 14
+                  }
+                }
+              },
+              {
+                "value": "Q4 revenue ($M)",
+                "format": "$#,##0.0",
+                "style": {
+                  "bold": true,
+                  "padding": {
+                    "top": 10,
+                    "right": 14,
+                    "bottom": 10,
+                    "left": 14
+                  }
+                }
+              },
+              {
+                "value": "Growth",
+                "format": "0%",
+                "style": {
+                  "bold": true,
+                  "padding": {
+                    "top": 10,
+                    "right": 14,
+                    "bottom": 10,
+                    "left": 14
+                  }
+                }
+              }
+            ],
+            "rows": [
+              [
+                {
+                  "value": "North America",
+                  "style": {
+                    "padding": {
+                      "top": 10,
+                      "right": 14,
+                      "bottom": 10,
+                      "left": 14
+                    }
+                  }
+                },
+                {
+                  "value": 18.1,
+                  "style": {
+                    "bold": true,
+                    "padding": {
+                      "top": 10,
+                      "right": 14,
+                      "bottom": 10,
+                      "left": 14
+                    }
+                  }
+                },
+                {
+                  "value": [
+                    {
+                      "text": "46%",
+                      "color": "#F5B041",
+                      "bold": true
+                    }
+                  ],
+                  "style": {
+                    "padding": {
+                      "top": 10,
+                      "right": 14,
+                      "bottom": 10,
+                      "left": 14
+                    }
+                  }
+                }
+              ],
+              [
+                {
+                  "value": "EMEA",
+                  "style": {
+                    "padding": {
+                      "top": 10,
+                      "right": 14,
+                      "bottom": 10,
+                      "left": 14
+                    }
+                  }
+                },
+                {
+                  "value": 11.5,
+                  "style": {
+                    "padding": {
+                      "top": 10,
+                      "right": 14,
+                      "bottom": 10,
+                      "left": 14
+                    }
+                  }
+                },
+                0.4
+              ],
+              [
+                {
+                  "value": "Asia-Pacific",
+                  "style": {
+                    "padding": {
+                      "top": 10,
+                      "right": 14,
+                      "bottom": 10,
+                      "left": 14
+                    }
+                  }
+                },
+                {
+                  "value": 7.7,
+                  "style": {
+                    "padding": {
+                      "top": 10,
+                      "right": 14,
+                      "bottom": 10,
+                      "left": 14
+                    }
+                  }
+                },
+                0.31
+              ]
+            ],
+            "alt": "North America grew 46% to $18.1M in Q4, ahead of EMEA at 40% and Asia-Pacific at 31%."
+          }
         }
       ]
     }

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { SchemaEntry, SchemaName, audience, chartType, colorScheme, fontScheme, language, layout, narrative, presentation, purpose, schemaEntries, schemaNames, schemas, socialPlatform, theme, tone } from './schemas.js';
-import { C as ConvertInput, a as ConvertOptions, b as ConvertResult, c as ConvertFormat, O as OpenOptions, S as SaveOptions, d as SaveResult } from './conversion-DS4OiVls.js';
-export { e as ConvertedFile, E as ExportFormat, F as FontsHandle, f as OPFApiError, g as OPFExportError, h as OPFImportError, i as SlideSelection, p as parseSlideSelection } from './conversion-DS4OiVls.js';
+import { C as ConvertInput, a as ConvertOptions, b as ConvertResult, c as ConvertFormat, O as OpenOptions, S as SaveOptions, d as SaveResult } from './conversion-CSD65VLi.js';
+export { e as ConvertedFile, E as ExportFormat, F as FontsHandle, f as OPFApiError, g as OPFExportError, h as OPFImportError, i as SlideSelection, p as parseSlideSelection } from './conversion-CSD65VLi.js';
 import { v as validate$1 } from './validator-Cflv4F9e.js';
 export { C as CATALOG_SCHEMA, a as CatalogDisplayKind, b as CatalogRecordKind, D as DEFAULT_VALIDATION_THRESHOLDS, O as OPFValidationError, c as assertValid, d as assertValidCatalogRecord, e as catalogDisplayKinds, f as catalogSchemaNames, g as findValidationRule, h as validateCatalogRecord, i as validationRules } from './validator-Cflv4F9e.js';
 import { R as ResolveVariablesOptions, h as VariableDiagnostic } from './validation-types-B21fZfb2.js';

package/dist/index.js

@@ -31,7 +31,7 @@ var stats2 = (presentation2, options) => stats(presentation2, withDefaultCatalog
 var paginate2 = (input, options) => paginate(input, withDefaultCatalog(options));
 var embed2 = (document, options) => embed(document, withDefaultCatalog(options));
 var edit2 = (deck, patch, options) => edit(deck, patch, withDefaultCatalog(options));
-var engine = () => import('./conversion-3TTBY7OY.js');
+var engine = () => import('./conversion-JDFXRXTK.js');
 var rethrow = (error, fallback) => {
   if (error instanceof OPFValidationError) throw error;
   throw asApiError(OPFApiError, error, fallback);

package/dist/node-engine.d.ts

@@ -1,6 +1,6 @@
 export { b as DeckReport, c as DeckReportOptions, r as readDeckReport } from './deck-report-vnWmXBjq.js';
-import { F as FontsHandle, j as EmbeddedFace, R as Renderer, k as Reporter, P as Peer, l as PptxModule, f as OPFApiError } from './conversion-DS4OiVls.js';
-export { m as ConversionPlan, D as Diagnostic, n as EXPORT_FORMATS, o as EXPORT_TEXT, q as ExportContext, r as ExportFile, s as ExportFontSummary, E as ExportFormat, t as ExportOptions, u as ExportResult, v as ExportRun, w as ExportText, I as ImportOptions, x as ImportResult, g as OPFExportError, h as OPFImportError, y as PEER_RANGES, z as PPTX_PACKAGE, A as PreparedExport, B as RENDER_EXTRAS, G as RENDER_PACKAGE, H as ReportFinding, J as ResolvedExportOptions, i as SlideSelection, K as Source, V as VERSIONS, L as asApiError, M as assetRoot, N as checkDate, Q as checkOptions, T as checkRenamedOptions, U as checkScale, W as deckFileFormat, X as exportFormatOf, Y as finishReport, Z as importPresentation, _ as loadPptx, $ as loadRenderer, a0 as locatePackage, a1 as missingPeerFrom, p as parseSlideSelection, a2 as planConversion, a3 as prepareExport, a4 as reaches, a5 as readInput, a6 as reportThrown, a7 as resolveExportOptions, a8 as runExport, a9 as runPreparedExport, aa as writePlanned } from './conversion-DS4OiVls.js';
+import { F as FontsHandle, j as EmbeddedFace, R as Renderer, k as Reporter, P as Peer, l as PptxModule, f as OPFApiError } from './conversion-CSD65VLi.js';
+export { m as ConversionPlan, D as Diagnostic, n as EXPORT_FORMATS, o as EXPORT_TEXT, q as ExportContext, r as ExportFile, s as ExportFontSummary, E as ExportFormat, t as ExportOptions, u as ExportResult, v as ExportRun, w as ExportText, I as ImportOptions, x as ImportResult, g as OPFExportError, h as OPFImportError, y as PEER_RANGES, z as PPTX_PACKAGE, A as PreparedExport, B as RENDER_EXTRAS, G as RENDER_PACKAGE, H as ReportFinding, J as ResolvedExportOptions, i as SlideSelection, K as Source, V as VERSIONS, L as asApiError, M as assetRoot, N as checkDate, Q as checkOptions, T as checkRenamedOptions, U as checkScale, W as deckFileFormat, X as exportFormatOf, Y as finishReport, Z as importPresentation, _ as loadPptx, $ as loadRenderer, a0 as locatePackage, a1 as missingPeerFrom, p as parseSlideSelection, a2 as planConversion, a3 as prepareExport, a4 as reaches, a5 as readInput, a6 as reportThrown, a7 as resolveExportOptions, a8 as runExport, a9 as runPreparedExport, aa as writePlanned } from './conversion-CSD65VLi.js';
 import { C as Catalog } from './catalog-refs-CSHevLn1.js';
 import { e as PresentationPaginationResult } from './pagination-C4jzAtFy.js';
 import './presentation-fN6tORPZ.js';

package/dist/node-engine.js

@@ -1,5 +1,5 @@
-import { loadRenderer, listFontDirectories, leaseSharedFonts, prepareFonts } from './chunk-DY7H4RG6.js';
-export { EXPORT_FORMATS, EXPORT_TEXT, PEER_RANGES, PPTX_PACKAGE, RENDER_EXTRAS, RENDER_PACKAGE, Reporter, VERSIONS, assetRoot, checkDate, checkDestinations, checkOptions, checkOutputPattern, checkRenamedOptions, checkScale, createZip, deckFileFormat, deckStem, embeddedFor, exportFormatOf, finishReport, importPresentation, leaseSharedFonts, listFontDirectories, loadPptx, loadRenderer, localAssetProblems, locatePackage, missingPeerFrom, padNumber, planConversion, pointerOf, prepareExport, prepareFonts, publishNew, reaches, readInput, reportThrown, resolveExportOptions, runExport, runImport, runPreparedExport, stemOf, writeFiles, writePlanned } from './chunk-DY7H4RG6.js';
+import { loadRenderer, listFontDirectories, leaseSharedFonts, prepareFonts } from './chunk-LKMR3OLD.js';
+export { EXPORT_FORMATS, EXPORT_TEXT, PEER_RANGES, PPTX_PACKAGE, RENDER_EXTRAS, RENDER_PACKAGE, Reporter, VERSIONS, assetRoot, checkDate, checkDestinations, checkOptions, checkOutputPattern, checkRenamedOptions, checkScale, createZip, deckFileFormat, deckStem, embeddedFor, exportFormatOf, finishReport, importPresentation, leaseSharedFonts, listFontDirectories, loadPptx, loadRenderer, localAssetProblems, locatePackage, missingPeerFrom, padNumber, planConversion, pointerOf, prepareExport, prepareFonts, publishNew, reaches, readInput, reportThrown, resolveExportOptions, runExport, runImport, runPreparedExport, stemOf, writeFiles, writePlanned } from './chunk-LKMR3OLD.js';
 import { defaultCatalogs } from './chunk-MG34DCDB.js';
 export { defaultCatalogs, galleryMismatch } from './chunk-MG34DCDB.js';
 import { OPFApiError } from './chunk-MAJHCGOW.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpresentation/opf",
-  "version": "0.22.0",
+  "version": "0.22.1",
   "description": "Canonical Open Presentation Format schemas, TypeScript types, local validation and composition; in Node, the file API and the CLI defaults register the pptx.gallery catalog of @openpresentation/gallery.",
   "license": "MIT",
   "author": "Open Presentation",
@@ -168,8 +168,8 @@
     "typescript": "~5.9.3"
   },
   "peerDependencies": {
-    "@openpresentation/opf-pptx": "^0.20.0",
-    "@openpresentation/opf-render": "^0.20.0"
+    "@openpresentation/opf-pptx": "^0.22.0",
+    "@openpresentation/opf-render": "^0.22.0"
   },
   "peerDependenciesMeta": {
     "@openpresentation/opf-pptx": {