@openpresentation/opf 0.26.3 → 0.26.5

package/dist/{chunk-34LIUOT7.js → chunk-L7YEVQHP.js}

@@ -1,8 +1,8 @@
-import { defaultCatalogs } from './chunk-2ZQBMZTZ.js';
-import { localAssetSources, OPFApiError, parseSlideSelection, OPFExportError, asApiError, OPFImportError } from './chunk-GLLR3AQ5.js';
-import { paginate } from './chunk-54OV2WQC.js';
-import { deckFormatOf, readDeckReport, stringify } from './chunk-FXNUM2PN.js';
-import { validate, OPFValidationError } from './chunk-NJWI6MPT.js';
+import { defaultCatalogs } from './chunk-K5Q3LLYK.js';
+import { localAssetSources, OPFApiError, parseSlideSelection, OPFExportError, asApiError, OPFImportError } from './chunk-UFEWQDQI.js';
+import { paginate } from './chunk-EFMR32A5.js';
+import { deckFormatOf, readDeckReport, stringify } from './chunk-STIYINEL.js';
+import { validate, OPFValidationError } from './chunk-CIWC7DRZ.js';
 import { link, stat, readdir, lstat, readFile, open, unlink, mkdir, rename } from 'fs/promises';
 import path6 from 'path';
 import { readFileSync, statSync, realpathSync } from 'fs';
@@ -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.26.3", [PPTX_PACKAGE]: "^0.26.3" };
+var PEER_RANGES = { [RENDER_PACKAGE]: "^0.26.5", [PPTX_PACKAGE]: "^0.26.5" };
 var PPTX_TEXT_OPTIONS_FROM = "0.22.0";
 var numbers = (version) => version.replace(/[-+].*$/, "").split(".").map((part) => Number.parseInt(part, 10) || 0);
 function atLeast(version, minimum) {

package/dist/chunk-MD3CJ5YJ.js

@@ -0,0 +1,452 @@
+import { SOURCE_EXPLAIN, ruleDocumentation, findValidationRule, us } from './chunk-CIWC7DRZ.js';
+
+// src/finding-text-explain-util.ts
+var ex = (fix, problem, fixed) => ({ fix, problem, fixed });
+var exampleText = (side) => typeof side === "string" ? side : JSON.stringify(side, null, 2);
+var CHART = { type: "column", alt: "Revenue by quarter", data: { columns: ["Quarter", "Revenue"], rows: [["Q1", 12], ["Q2", 15]] } };
+
+// src/finding-text-explain-audit.ts
+var WHITE = { background: { type: "solid", color: "#FFFFFF" } };
+var ROADMAP = { name: "Roadmap", regions: [{ name: "title" }, { direction: "row", regions: [{ name: "timeline", accepts: ["timeline"], max: 1 }, { name: "notes", accepts: ["text", "list"], flow: "column" }] }] };
+var TIMELINE = { timeline: { events: [{ when: "Q1", what: "Pilot" }, { when: "Q2", what: "Launch" }] } };
+var PERSON = (n) => ({ blocks: [{ image: { src: `https://example.com/${n}.png`, alt: `Person ${n}` } }, { text: `Person ${n}` }], composition: { mode: "column" } });
+var SERIES = (count) => ({ columns: ["Quarter", ...Array.from({ length: count }, (_, i) => `S${i + 1}`)], rows: [["Q1", ...Array.from({ length: count }, (_, i) => i + 1)]] });
+var AUDIT_EXPLAIN = {
+  "opf/text-contrast": ex(
+    "Pick a text color with enough contrast against the background (3:1 for large text, 4.5:1 for normal text), or remove the color override so the theme chooses a readable one.",
+    { design: WHITE, slides: [{ title: "Results", text: [{ text: "Faint note", color: "#CCCCCC" }] }] },
+    { design: WHITE, slides: [{ title: "Results", text: [{ text: "Readable note", color: "text" }] }] }
+  ),
+  "opf/text-on-image": ex(
+    "Add a full-frame overlay to the background image, or put the text on a solid or gradient background or a card, so contrast does not depend on the picture.",
+    { design: WHITE, slides: [{ title: "Welcome", design: { background: { type: "image", src: "https://example.com/hero.jpg" } } }] },
+    { design: WHITE, slides: [{ title: "Welcome", design: { background: { type: "image", src: "https://example.com/hero.jpg", overlay: { color: "#FFFFFF", opacity: 1 } } } }] }
+  ),
+  "opf/missing-alt-text": ex(
+    'Describe the picture in `alt`, or write `alt: ""` when it is only decoration.',
+    { title: "Team", image: "https://example.com/team.png" },
+    { title: "Team", image: { src: "https://example.com/team.png", alt: "The team at the 2026 offsite" } }
+  ),
+  "opf/poor-alt-text": ex(
+    'Write what a person who cannot see the picture needs to know, in plain words and without a leading "image of".',
+    { title: "Team", image: { src: "https://example.com/team.png", alt: "IMG_2041.png" } },
+    { title: "Team", image: { src: "https://example.com/team.png", alt: "Five people around a whiteboard" } }
+  ),
+  "opf/missing-slide-title": ex(
+    "Give the slide a `title`. Screen reader users find slides by title, and PowerPoint's outline uses it.",
+    { text: "Revenue grew in every quarter." },
+    { title: "Revenue grew", text: "Revenue grew in every quarter." }
+  ),
+  "opf/duplicate-slide-title": ex(
+    "Give each slide a title that tells it apart, for example by adding the part of the story it covers.",
+    { slides: [{ title: "Results", text: "Q1" }, { title: "Results", text: "Q2" }] },
+    { slides: [{ title: "Results: Q1", text: "Q1" }, { title: "Results: Q2", text: "Q2" }] }
+  ),
+  "opf/reading-order": ex(
+    "Reorder or regroup the blocks so the order they are read in follows the order they appear in, or choose a layout that puts the title first.",
+    { title: "Team", composition: { mode: "row" }, blocks: [PERSON(1), PERSON(2)] },
+    { title: "Team", composition: { mode: "column" }, blocks: [PERSON(1), PERSON(2)] }
+  ),
+  "opf/link-text": ex(
+    "Make the link text say where the link goes, for example the name of the page or file.",
+    { title: "Report", text: ["Read the report: ", { text: "click here", link: "https://example.com/report" }] },
+    { title: "Report", text: ["Read ", { text: "the 2026 annual report (PDF)", link: "https://example.com/report" }] }
+  ),
+  "opf/chart-color-only": ex(
+    "Show fewer series, choose more distinct colors, or add data labels or a direct legend so the chart does not depend on telling colors apart.",
+    { title: "Trend", chart: { type: "line", alt: "Fourteen series", data: SERIES(14) } },
+    { title: "Trend", chart: { type: "line", alt: "Two series", data: SERIES(2) } }
+  ),
+  "opf/chart-colors-adjusted": ex(
+    "Use a color that resolves (a hex color, a scheme color or a declared `var:`) and has at least 3:1 contrast against the chart panel, or remove `colors` to use the palette.",
+    { title: "Revenue", chart: { ...CHART, colors: ["var:missing"] } },
+    { title: "Revenue", chart: { ...CHART, colors: ["accent1"] } }
+  ),
+  "opf/chart-text-alternative": ex(
+    "Write the message the chart carries in `alt`, or add a subtitle, text or table beside it that states what it shows.",
+    { title: "Revenue", chart: { type: "column", data: CHART.data } },
+    { title: "Revenue", chart: { type: "column", alt: "Revenue rose from 12 to 15 million between Q1 and Q2.", data: CHART.data } }
+  ),
+  "opf/missing-language": ex(
+    "Set the deck's `language` to a BCP 47 tag such as `en-US`. It chooses fonts, text direction and the proofing language, and screen readers pronounce the text with it.",
+    { slides: [{ title: "Welcome" }] },
+    { language: "en-US", slides: [{ title: "Welcome" }] }
+  ),
+  "opf/chart-option-adapted": ex(
+    "Remove the option, or choose a chart type that can show it. Every engine draws the adapted result.",
+    { title: "Share", chart: { type: "pie", alt: "Share by region", data: { columns: ["Region", "Share"], rows: [["EMEA", 60], ["APAC", 40]] }, axisTitles: { value: "Share" } } },
+    { title: "Share", chart: { type: "pie", alt: "Share by region", data: { columns: ["Region", "Share"], rows: [["EMEA", 60], ["APAC", 40]] } } }
+  ),
+  "opf/text-overflow": ex(
+    "Shorten the text, give it more space (fewer blocks, a different composition) or split the slide. Raising the readable minimum makes it worse.",
+    { title: "Notes", composition: { minFontSize: 16 }, blocks: [{ text: "word ".repeat(600).trim() }, { text: "More" }] },
+    { title: "Notes", blocks: [{ text: "The three points that matter." }, { text: "More" }] }
+  ),
+  "opf/unresolved-content": ex(
+    "Supply what the message asks for (for example the organization logo a picture bullet needs), or remove the setting that cannot be honored.",
+    { design: { listBullet: "image" }, slides: [{ title: "Steps", items: ["One", "Two"] }] },
+    { slides: [{ title: "Steps", items: ["One", "Two"] }] }
+  ),
+  "opf/layout-failed": ex(
+    "Fix the composition setting or the content structure the message names. The checks that need the layout are skipped for that slide until it can be laid out.",
+    { catalogs: { custom: { layouts: { broken: { name: "Broken", regions: [{ name: "title" }], composition: { padding: 5 } } } } }, slides: [{ title: "Welcome", layout: "broken" }] },
+    { catalogs: { custom: { layouts: { broken: { name: "Broken", regions: [{ name: "title" }] } } } }, slides: [{ title: "Welcome", layout: "broken" }] }
+  ),
+  "opf/min-font-size": ex(
+    "Raise the font size to the readable minimum or more, or shorten the text so it can be drawn larger.",
+    { title: "Notes", text: [{ text: "Tiny print", fontSize: 8 }] },
+    { title: "Notes", text: [{ text: "Readable print", fontSize: 14 }] }
+  ),
+  "opf/region-unknown": ex(
+    "Pin the block to a region the layout has, or remove `region` so the block is placed by its kind.",
+    { catalogs: { custom: { layouts: { roadmap: ROADMAP } } }, slides: [{ layout: "roadmap", blocks: [{ region: "timelin", ...TIMELINE }] }] },
+    { catalogs: { custom: { layouts: { roadmap: ROADMAP } } }, slides: [{ layout: "roadmap", blocks: [{ region: "timeline", ...TIMELINE }] }] }
+  ),
+  "opf/region-kind": ex(
+    "Pin the block to a region that accepts its kind, or remove `region`.",
+    { catalogs: { custom: { layouts: { roadmap: ROADMAP } } }, slides: [{ layout: "roadmap", blocks: [{ region: "timeline", text: "Note" }] }] },
+    { catalogs: { custom: { layouts: { roadmap: ROADMAP } } }, slides: [{ layout: "roadmap", blocks: [{ region: "notes", text: "Note" }] }] }
+  ),
+  "opf/region-full": ex(
+    "Pin the block to another region with room, or remove `region` so it is placed by its kind.",
+    { catalogs: { custom: { layouts: { roadmap: ROADMAP } } }, slides: [{ layout: "roadmap", blocks: [{ region: "timeline", ...TIMELINE }, { region: "timeline", ...TIMELINE }] }] },
+    { catalogs: { custom: { layouts: { roadmap: ROADMAP } } }, slides: [{ layout: "roadmap", blocks: [{ region: "timeline", ...TIMELINE }] }] }
+  ),
+  "opf/layout-unplaced": ex(
+    "Paginate the slide, choose a layout with more room, pin the block to a region with room, or remove a block.",
+    { catalogs: { custom: { layouts: { roadmap: ROADMAP } } }, slides: [{ layout: "roadmap", blocks: [{ ...TIMELINE }, { ...TIMELINE }] }] },
+    { catalogs: { custom: { layouts: { roadmap: ROADMAP } } }, slides: [{ layout: "roadmap", blocks: [{ ...TIMELINE }] }] }
+  ),
+  "opf/furniture-wraps": ex(
+    "Shorten the header or footer text, or move part of it to another zone. Headers and footers should fit on two lines.",
+    { design: { footer: { left: { text: "A footer that keeps going and going and going and going and going and going and going and going and going and going and going and going" }, center: { text: "Confidential" }, right: { text: "{{slide.number}}" } } }, slides: [{ title: "Welcome" }] },
+    { design: { footer: { left: { text: "Acme, confidential" }, right: { text: "{{slide.number}}" } } }, slides: [{ title: "Welcome" }] }
+  ),
+  "opf/font-outside-scheme": ex(
+    "Remove `fontFamily` so the text uses the scheme font, or add the family to the deck's font scheme so it follows scheme changes.",
+    { design: { fontScheme: "aptos" }, slides: [{ title: "Notes", text: [{ text: "Hand-set", fontFamily: "Comic Sans MS" }] }] },
+    { design: { fontScheme: "aptos" }, slides: [{ title: "Notes", text: [{ text: "Hand-set" }] }] }
+  ),
+  "opf/image-resolution": ex(
+    "Use an image with more pixels for the size it is shown at (about 96 per inch), or show it smaller.",
+    { title: "Team", image: { src: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAGQAAABkAAAAAAAAAAAA", alt: "Team" } },
+    { title: "Team", image: { src: "https://example.com/team-2400x1350.png", alt: "Team" } }
+  )
+};
+
+// src/finding-text-explain-content.ts
+var COLUMNS = ["Quarter", "Revenue", "Costs"];
+var ROWS = [["Q1", 12, 8], ["Q2", 15, 9]];
+var ARC = (duration) => ({ name: "Arc", duration, beats: [{ id: "hook", name: "Hook" }, { id: "proof", name: "Proof" }, { id: "ask", name: "Ask" }] });
+var CONTENT_EXPLAIN = {
+  "opf/chart-value-not-numeric": ex(
+    "Store the value as a number and put units, currency or percent in the column `format`. A text value is plotted as a gap.",
+    { title: "Revenue", chart: { type: "column", alt: "Revenue", data: { columns: ["Quarter", "Revenue"], rows: [["Q1", "about 12"]] } } },
+    { title: "Revenue", chart: { type: "column", alt: "Revenue", data: { columns: ["Quarter", { name: "Revenue", format: "$#,##0" }], rows: [["Q1", 12]] } } }
+  ),
+  "opf/chart-mapping-adapted": ex(
+    "Remove the mapping entry, or name a column the chart type can use. The entry is ignored.",
+    { title: "Revenue", chart: { type: "column", alt: "Revenue", data: { columns: COLUMNS, rows: ROWS }, mapping: { x: "Costs" } } },
+    { title: "Revenue", chart: { type: "column", alt: "Revenue", data: { columns: COLUMNS, rows: ROWS } } }
+  ),
+  "opf/chart-highlight-adapted": ex(
+    "Name a series the chart plots in `highlight`, or remove the entry. A column that is the category or X column, or that the mapping leaves out, highlights nothing.",
+    { title: "Revenue", chart: { type: "column", alt: "Revenue", data: { columns: COLUMNS, rows: ROWS }, highlight: { series: ["Quarter"] } } },
+    { title: "Revenue", chart: { type: "column", alt: "Revenue", data: { columns: COLUMNS, rows: ROWS }, highlight: { series: ["Revenue"] } } }
+  ),
+  "opf/code-highlight-out-of-range": ex(
+    "Change the entry to a line the code has (counted from 1), or remove it.",
+    { title: "Code", code: { source: "a\nb\nc", highlight: [7] } },
+    { title: "Code", code: { source: "a\nb\nc", highlight: [3] } }
+  ),
+  "opf/code-highlight-range-reversed": ex(
+    "Write the range with the smaller line number first, or remove it.",
+    { title: "Code", code: { source: "a\nb\nc", highlight: [[3, 1]] } },
+    { title: "Code", code: { source: "a\nb\nc", highlight: [[1, 3]] } }
+  ),
+  "opf/variable-builtin-missing": ex(
+    "Add the field the built-in reads (for example `speaker.name`, `organization.tagline` or the deck's `name`), or remove the token.",
+    { slides: [{ title: "{{speaker.name}}" }] },
+    { speaker: { name: "Ada Lovelace" }, slides: [{ title: "{{speaker.name}}" }] }
+  ),
+  "opf/duration-outside-narrative": ex(
+    "Change `duration`, or choose a narrative that suits it. The range describes the narrative, so nothing is drawn differently.",
+    { duration: 5, narrative: "arc", catalogs: { custom: { narratives: { arc: ARC({ min: 10, max: 20 }) } } }, slides: [{ title: "Intro", beat: "hook" }] },
+    { duration: 15, narrative: "arc", catalogs: { custom: { narratives: { arc: ARC({ min: 10, max: 20 }) } } }, slides: [{ title: "Intro", beat: "hook" }] }
+  ),
+  "opf/narrative-duration-range": ex(
+    "Swap the bounds so `min` is the shortest and `max` the longest talk length, in minutes.",
+    { catalogs: { custom: { narratives: { arc: ARC({ min: 30, max: 10 }) } } }, slides: [{ title: "Intro" }] },
+    { catalogs: { custom: { narratives: { arc: ARC({ min: 10, max: 30 }) } } }, slides: [{ title: "Intro" }] }
+  ),
+  "opf/placeholder-text": ex(
+    'Replace the placeholder (lorem ipsum, "Click to add title", TBD, [Insert ...]) with the real text.',
+    { title: "Overview", text: "Lorem ipsum dolor sit amet" },
+    { title: "Overview", text: "Revenue grew in every quarter." }
+  ),
+  "opf/empty-text": ex(
+    "Write the text, or remove the empty field or item.",
+    { title: "Next steps", items: ["Hire two engineers", ""] },
+    { title: "Next steps", items: ["Hire two engineers", "Ship the beta"] }
+  ),
+  "opf/unused-beat": ex(
+    "Link a slide to the beat with `beat`, or ignore this when the beat is optional for your talk.",
+    { duration: 15, narrative: "arc", catalogs: { custom: { narratives: { arc: ARC({ min: 10, max: 20 }) } } }, slides: [{ title: "One", beat: "hook" }, { title: "Two", beat: "proof" }] },
+    { duration: 15, narrative: "arc", catalogs: { custom: { narratives: { arc: ARC({ min: 10, max: 20 }) } } }, slides: [{ title: "One", beat: "hook" }, { title: "Two", beat: "proof" }, { title: "Three", beat: "ask" }] }
+  ),
+  "opf/empty-slide": ex(
+    "Add content or a title, remove the slide, or give it the `blank` layout if it is meant to be empty.",
+    { slides: [{ title: "Intro", text: "Welcome" }, { id: "spare" }] },
+    { slides: [{ title: "Intro", text: "Welcome" }, { id: "spare", title: "Questions", text: "Ask away" }] }
+  ),
+  "opf/language-tag": ex(
+    "Write a well-formed BCP 47 tag with an assigned region, such as `en-GB` (the United Kingdom is `GB`, not `UK`), `pt-BR` or `es-419`.",
+    { language: { bcp47: "fr-UK" }, slides: [{ title: "Bienvenue" }] },
+    { language: { bcp47: "fr-GB" }, slides: [{ title: "Bienvenue" }] }
+  )
+};
+
+// src/finding-text-explain-format.ts
+var IMG = (name) => ({ src: `https://example.com/${name}.png`, alt: "Team at the offsite" });
+var FORMAT_EXPLAIN = {
+  "opf/json-syntax": ex(
+    "Fix the error at the marked position; the message names the root cause (a missing comma, a quote, a bracket that is never closed), and later errors usually disappear with it.",
+    '{\n  "name": "Q3 review"\n  "slides": [{ "title": "Revenue" }]\n}',
+    '{\n  "name": "Q3 review",\n  "slides": [{ "title": "Revenue" }]\n}'
+  ),
+  "opf/duplicate-key": ex(
+    "Keep one of the two keys, or merge their values into one. JSON keeps only the last value, so the earlier one is ignored.",
+    '{\n  "name": "Q3 review",\n  "slides": [{ "title": "Revenue" }],\n  "name": "Q4 review"\n}',
+    '{\n  "name": "Q4 review",\n  "slides": [{ "title": "Revenue" }]\n}'
+  ),
+  "opf/schema": ex(
+    "Change the value to the form the message names (its type, one of the allowed values, or the missing field). The message says which field and what it should be.",
+    { title: "Revenue", items: "Grew 12%" },
+    { title: "Revenue", items: ["Grew 12%"] }
+  ),
+  "opf/reference-id-duplicate": ex(
+    "Give each reference its own id. Runs cite a reference by its id, so two with the same id cannot be told apart.",
+    { references: [{ id: "gartner", text: "Gartner, 2026" }, { id: "gartner", text: "IDC, 2026" }], slides: [{ title: "Market", text: [{ text: "Up 12%", cite: "gartner" }] }] },
+    { references: [{ id: "gartner", text: "Gartner, 2026" }, { id: "idc", text: "IDC, 2026" }], slides: [{ title: "Market", text: [{ text: "Up 12%", cite: "gartner" }] }] }
+  ),
+  "opf/cite-unknown-reference": ex(
+    "Change `cite` to the id of a reference under `references`, or add the reference it names.",
+    { references: [{ id: "gartner", text: "Gartner, 2026" }], slides: [{ title: "Market", text: [{ text: "Up 12%", cite: "gartnr" }] }] },
+    { references: [{ id: "gartner", text: "Gartner, 2026" }], slides: [{ title: "Market", text: [{ text: "Up 12%", cite: "gartner" }] }] }
+  ),
+  "opf/cite-unsupported-location": ex(
+    "Move the cited run into a text block, bullets or a list item (titles and quotes work too). Table cells, captions and reference text do not draw citation markers.",
+    { references: [{ id: "gartner", text: "Gartner, 2026" }], slides: [{ title: "Market", table: { columns: ["Region", "Growth"], rows: [["EMEA", [{ text: "12%", cite: "gartner" }]]] } }] },
+    { references: [{ id: "gartner", text: "Gartner, 2026" }], slides: [{ title: "Market", text: [{ text: "EMEA grew 12%", cite: "gartner" }], table: { columns: ["Region", "Growth"], rows: [["EMEA", "12%"]] } }] }
+  ),
+  "opf/caption-unsupported-payload": ex(
+    "Put the `caption` on the image, chart, table or video it describes, or remove it.",
+    { title: "Revenue", blocks: [{ text: "Revenue grew", caption: "Source: finance" }] },
+    { title: "Revenue", blocks: [{ chart: CHART, caption: "Source: finance" }] }
+  ),
+  "opf/image-option-unsupported-payload": ex(
+    "Remove the image option, or move it onto an image block. Options such as `fit`, `shape` and `overlay` describe how a picture is drawn.",
+    { title: "Revenue", chart: CHART, fit: "cover" },
+    { title: "Revenue", image: IMG("team"), fit: "cover" }
+  ),
+  "opf/image-placement-invalid": ex(
+    "Use `placement` on a top-level block of the slide, with one placed image per slide edge.",
+    { title: "Team", blocks: [{ image: IMG("a"), placement: { edge: "left" } }, { image: IMG("b"), placement: { edge: "left" } }] },
+    { title: "Team", blocks: [{ image: IMG("a"), placement: { edge: "left" } }, { image: IMG("b"), placement: { edge: "right" } }] }
+  ),
+  "opf/layout-placeholder-group": ex(
+    "Flatten the group so it nests at most three levels, and keep the headings (title, subtitle, tag) at the record's top level. Layout records written for current versions use `regions`, where the same limits apply to splits.",
+    { placeholders: [{ type: "group", placeholders: [{ type: "title" }, { type: "text" }] }] },
+    { placeholders: [{ type: "title" }, { type: "group", placeholders: [{ type: "text" }, { type: "chart" }] }] }
+  ),
+  "opf/dataset-unknown": ex(
+    "Name a dataset that exists under `datasets`, or add the one the chart or table asks for.",
+    { datasets: { sales: { columns: ["Quarter", "Revenue"], rows: [["Q1", 12]] } }, slides: [{ title: "Revenue", chart: { type: "column", data: { dataset: "sale" } } }] },
+    { datasets: { sales: { columns: ["Quarter", "Revenue"], rows: [["Q1", 12]] } }, slides: [{ title: "Revenue", chart: { type: "column", data: { dataset: "sales" } } }] }
+  ),
+  "opf/dataset-field-unknown": ex(
+    "Name only columns the dataset has. The message lists them.",
+    { datasets: { sales: { columns: ["Region", "Revenue"], rows: [["EMEA", 12]] } }, slides: [{ title: "Revenue", table: { dataset: "sales", fields: ["Regon"] } }] },
+    { datasets: { sales: { columns: ["Region", "Revenue"], rows: [["EMEA", 12]] } }, slides: [{ title: "Revenue", table: { dataset: "sales", fields: ["Region"] } }] }
+  ),
+  "opf/data-column-duplicate": ex(
+    "Rename one of the columns so every name is unique. Series, mappings and fields address columns by name.",
+    { datasets: { sales: { columns: ["Region", "Region"], rows: [["EMEA", 12]] } }, slides: [{ title: "Revenue", table: { dataset: "sales" } }] },
+    { datasets: { sales: { columns: ["Region", "Region-2"], rows: [["EMEA", 12]] } }, slides: [{ title: "Revenue", table: { dataset: "sales" } }] }
+  ),
+  "opf/chart-mapping-unknown-column": ex(
+    "Name a column the chart data has in `mapping`. The message lists them.",
+    { title: "Revenue", chart: { type: "column", data: { columns: ["Quarter", "Revenue"], rows: [["Q1", 12]] }, mapping: { series: ["Profit"] } } },
+    { title: "Revenue", chart: { type: "column", data: { columns: ["Quarter", "Revenue"], rows: [["Q1", 12]] }, mapping: { series: ["Revenue"] } } }
+  ),
+  "opf/number-format-invalid": ex(
+    "Write the format as an Excel-style pattern with a numeric part, such as `0.0`, `#,##0`, `0%` or `$#,##0.00`.",
+    { title: "Revenue", table: { columns: [{ name: "Revenue", format: "units" }], rows: [[12]] } },
+    { title: "Revenue", table: { columns: [{ name: "Revenue", format: "$#,##0" }], rows: [[12]] } }
+  ),
+  "opf/variable-invalid-value": ex(
+    "Give the variable a value of its declared type: a plain number for `number`, a date for `date`, a hex color for `color`. The values are what a host passes when it fills the deck (`validate` option `values`, `opf fill`); a declared `value` of the wrong type is reported by the schema.",
+    { values: { seats: "many" } },
+    { values: { seats: 40 } }
+  ),
+  "opf/variable-unknown-builtin": ex(
+    "Use a built-in that exists (`deck.name`, `deck.description`, `deck.author`, `speaker.name`, `organization.name`, `slide.number`, ...), or declare your own variable under `variables`.",
+    { slides: [{ title: "{{deck.nmae}}" }] },
+    { name: "Q3 review", slides: [{ title: "{{deck.name}}" }] }
+  ),
+  "opf/chart-highlight-unknown-name": ex(
+    "Name a series or category the chart data has in `highlight`; a name that matches nothing highlights nothing.",
+    { title: "Revenue", chart: { type: "column", data: { columns: ["Quarter", "Revenue"], rows: [["Q1", 12], ["Q2", 15]] }, highlight: { categories: ["Q9"] } } },
+    { title: "Revenue", chart: { type: "column", data: { columns: ["Quarter", "Revenue"], rows: [["Q1", 12], ["Q2", 15]] }, highlight: { categories: ["Q2"] } } }
+  ),
+  "opf/variable-format": ex(
+    "Give the variable a `format` that fits its type and its values: `#,##0.0` for a number, a date pattern for a date.",
+    { variables: { amount: { type: "number", value: 1e308, format: "0%" } }, slides: [{ title: "Value {{amount}}" }] },
+    { variables: { amount: { type: "number", value: 12.5, format: "#,##0.0" } }, slides: [{ title: "Value {{amount}}" }] }
+  ),
+  "opf/variable-unfilled": ex(
+    "Give the variable a `value`, fill the deck before use, or mark the deck as a template with `template: true`. Otherwise the `{{token}}` would show as typed.",
+    { variables: { client: { type: "text", label: "Client" } }, slides: [{ title: "Proposal for {{client}}" }] },
+    { variables: { client: { type: "text", label: "Client", value: "Acme" } }, slides: [{ title: "Proposal for {{client}}" }] }
+  )
+};
+
+// src/finding-text-explain-references.ts
+var NARRATIVE = { name: "Arc", beats: [{ id: "hook", name: "Hook" }, { id: "proof", name: "Proof" }] };
+var GALLERY_LAYOUT = { name: "Mine", regions: [{ name: "title" }] };
+var DATA = { columns: ["Quarter", "Revenue"], rows: [["Q1", 12]] };
+var REFERENCES_EXPLAIN = {
+  "opf/run-color-unrecognized": ex(
+    "Write a hex color (`#1F4E79`), a color scheme name (`accent1`, `text`) or a `var:` reference to a declared color variable.",
+    { title: "Results", text: [{ text: "Up", color: "accnt1" }] },
+    { title: "Results", text: [{ text: "Up", color: "accent1" }] }
+  ),
+  "opf/numbering-start-ignored": ex(
+    "Add `numbering` to the list, or remove `start`. A start number only matters on a numbered list.",
+    { title: "Steps", items: [{ text: "Third step", start: 3 }] },
+    { title: "Steps", numbering: "decimal", items: [{ text: "Third step", start: 3 }] }
+  ),
+  "opf/slide-size-out-of-range": ex(
+    "Use a custom `widthInches` and `heightInches` between 1 and 56, or a preset size.",
+    { design: { dimensions: { widthInches: 0.5, heightInches: 60 } }, slides: [{ title: "Poster" }] },
+    { design: { dimensions: { widthInches: 13.333, heightInches: 7.5 } }, slides: [{ title: "Poster" }] }
+  ),
+  "opf/undeclared-catalog": ex(
+    "Declare the catalog group under `catalogs` (with its source), or write the reference without the group prefix.",
+    { slides: [{ title: "Welcome", layout: "acme:hero" }] },
+    { slides: [{ title: "Welcome", layout: "hero" }] }
+  ),
+  "opf/asset-reference": ex(
+    "Add the asset to `assets` under that id, or name an asset that exists. External files and URLs are never fetched.",
+    { assets: { logo: { src: "https://example.com/logo.png", alt: "Acme logo" } }, slides: [{ title: "Welcome", image: "asset:lgog" }] },
+    { assets: { logo: { src: "https://example.com/logo.png", alt: "Acme logo" } }, slides: [{ title: "Welcome", image: "asset:logo" }] }
+  ),
+  "opf/asset-cycle": ex(
+    "Give one asset in the loop a real source (an https:// address or embedded data) instead of an `asset:` reference to the next one.",
+    { assets: { a: "asset:b", b: "asset:a" }, slides: [{ title: "Welcome", image: "asset:a" }] },
+    { assets: { a: "asset:b", b: { src: "https://example.com/b.png", alt: "Team" } }, slides: [{ title: "Welcome", image: "asset:a" }] }
+  ),
+  "opf/catalog-record": ex(
+    "Fix the record the way the message says (it names the field and what it should be). References to an invalid record are reported too until it is valid.",
+    { catalogs: { custom: { themes: { mine: { name: "Mine", background: "light1" } } } }, slides: [{ title: "Welcome" }] },
+    { catalogs: { custom: { themes: { mine: { name: "Mine", background: { type: "theme", slot: "light1" } } } } }, slides: [{ title: "Welcome" }] }
+  ),
+  "opf/layout-template": ex(
+    "Correct the region list: 1 to 12 entries, a `direction` of `row` or `column`, numeric sizes above 0 (or `auto` only in a column), and at most three levels of splits.",
+    { catalogs: { custom: { layouts: { mine: { name: "Mine", direction: "row", regions: [{ name: "title" }, { name: "a", accepts: ["text"], size: "auto" }, { name: "b", accepts: ["text"] }] } } } }, slides: [{ title: "Welcome", layout: "mine" }] },
+    { catalogs: { custom: { layouts: { mine: { name: "Mine", regions: [{ name: "title" }, { name: "a", accepts: ["text"], size: "auto" }, { name: "b", accepts: ["text"] }] } } } }, slides: [{ title: "Welcome", layout: "mine" }] }
+  ),
+  "opf/layout-region": ex(
+    "Name each body region with a unique lowercase id that is not reserved (`title`, `subtitle`, `tag`, `auto`, `left`, `center`, `right`, `top`, `middle`, `bottom`), and give it something to accept.",
+    { catalogs: { custom: { layouts: { mine: { name: "Mine", regions: [{ name: "title" }, { name: "left", accepts: ["text"] }] } } } }, slides: [{ title: "Welcome", layout: "mine" }] },
+    { catalogs: { custom: { layouts: { mine: { name: "Mine", regions: [{ name: "title" }, { name: "body", accepts: ["text"] }] } } } }, slides: [{ title: "Welcome", layout: "mine" }] }
+  ),
+  "opf/unresolved-reference": ex(
+    "Choose an id the catalog has (the finding lists the nearest), embed the record under `catalogs.custom`, register the catalog that defines it, or remove the reference.",
+    { slides: [{ title: "Pillars", layout: "pilars" }] },
+    { slides: [{ title: "Pillars", layout: "pillars" }] }
+  ),
+  "opf/catalog-record-not-in-source": ex(
+    "Move the record to `catalogs.custom` (and drop the group prefix from its references), or use an id the catalog publishes.",
+    { catalogs: { default: { source: "https://www.pptx.gallery", layouts: { "my-special": GALLERY_LAYOUT } } }, slides: [{ title: "Welcome", layout: "my-special" }] },
+    { catalogs: { custom: { layouts: { "my-special": GALLERY_LAYOUT } } }, slides: [{ title: "Welcome", layout: "my-special" }] }
+  ),
+  "opf/unused-reference": ex(
+    "Cite the reference from a text, bullet or list item, or remove it. Nothing is drawn for a reference nobody cites.",
+    { references: [{ id: "gartner", text: "Gartner, 2026" }], slides: [{ title: "Market", text: "Up 12%" }] },
+    { references: [{ id: "gartner", text: "Gartner, 2026" }], slides: [{ title: "Market", text: [{ text: "Up 12%", cite: "gartner" }] }] }
+  ),
+  "opf/unused-dataset": ex(
+    "Point a chart or table at the dataset with `dataset`, or remove it.",
+    { datasets: { sales: DATA }, slides: [{ title: "Revenue", text: "Up 12%" }] },
+    { datasets: { sales: DATA }, slides: [{ title: "Revenue", chart: { type: "column", alt: "Revenue", data: { dataset: "sales" } } }] }
+  ),
+  "opf/unknown-beat": ex(
+    "Use one of the narrative's beat ids, add the beat to the narrative record, or remove the `beat` link.",
+    { narrative: "arc", catalogs: { custom: { narratives: { arc: NARRATIVE } } }, slides: [{ title: "Intro", beat: "intro" }] },
+    { narrative: "arc", catalogs: { custom: { narratives: { arc: NARRATIVE } } }, slides: [{ title: "Intro", beat: "hook" }] }
+  ),
+  "opf/slide-theme-dimensions": ex(
+    "Set `design.dimensions` on the deck, or give every slide's theme the same dimensions. A PPTX has one slide size.",
+    { design: { theme: "minimal" }, catalogs: { custom: { themes: { "wide-a4": { name: "A4", dimensions: "a4" } } } }, slides: [{ title: "Letter", design: { theme: "wide-a4" } }] },
+    { design: { theme: "minimal", dimensions: "a4" }, catalogs: { custom: { themes: { "wide-a4": { name: "A4", dimensions: "a4" } } } }, slides: [{ title: "Letter", design: { theme: "wide-a4" } }] }
+  ),
+  "opf/variable-unknown": ex(
+    "Declare the variable under `variables`, correct the name, or write `\\{{` for literal braces.",
+    { variables: { name: { type: "text", value: "Acme" } }, slides: [{ title: "Hello {{nmae}}" }] },
+    { variables: { name: { type: "text", value: "Acme" } }, slides: [{ title: "Hello {{name}}" }] }
+  ),
+  "opf/variable-unknown-value": ex(
+    "Declare the variable the value belongs to under `variables`, or drop the value. The values are what a host passes when it fills the deck (`validate` option `values`, `opf fill`); one for an undeclared variable is ignored.",
+    { values: { name: "Acme", nope: 1 } },
+    { values: { name: "Acme" } }
+  ),
+  "opf/variable-unused": ex(
+    "Use the variable as `{{id}}` or `var:id` where it belongs, or remove its declaration.",
+    { variables: { client: { type: "text", value: "Acme" } }, slides: [{ title: "Proposal" }] },
+    { variables: { client: { type: "text", value: "Acme" } }, slides: [{ title: "Proposal for {{client}}" }] }
+  ),
+  "opf/variable-reference-unknown": ex(
+    "Declare the color variable under `variables`, or use another color. Until then a default color is drawn.",
+    { slides: [{ title: "Results", text: [{ text: "Up", color: "var:brand" }] }] },
+    { variables: { brand: { type: "color", value: "#1F4E79" } }, slides: [{ title: "Results", text: [{ text: "Up", color: "var:brand" }] }] }
+  ),
+  "opf/contract": ex(
+    "Change the value to one the host's policy allows (the finding lists them), or ask the host to widen the policy.",
+    { slides: [{ title: "Welcome", layout: "cover" }] },
+    { slides: [{ title: "Welcome", layout: "text" }] }
+  )
+};
+
+// src/finding-text-explain.ts
+var RULE_EXPLAIN = Object.freeze({
+  ...FORMAT_EXPLAIN,
+  ...REFERENCES_EXPLAIN,
+  ...AUDIT_EXPLAIN,
+  ...CONTENT_EXPLAIN
+});
+
+// src/explain.ts
+function explain(ruleId) {
+  if (typeof ruleId !== "string") return void 0;
+  if (/^(yaml|markdown)\//.test(ruleId)) {
+    const entry = SOURCE_EXPLAIN[ruleId];
+    return entry ? { id: ruleId, name: ruleId.slice(ruleId.indexOf("/") + 1), docs: ruleDocumentation(ruleId), ...entry } : void 0;
+  }
+  const info = findValidationRule(ruleId);
+  if (!info) return void 0;
+  const detail = RULE_EXPLAIN[info.id];
+  return {
+    id: info.id,
+    name: info.name,
+    category: info.category,
+    severity: info.severity,
+    summary: us(info.summary),
+    rationale: us(info.standard && !info.standard.startsWith("spec/") ? `${info.rationale} Basis: ${info.standard}.` : info.rationale),
+    fix: detail?.fix ?? us(info.summary),
+    ...detail ? { example: { problem: exampleText(detail.problem), fixed: exampleText(detail.fixed), language: "json" } } : {},
+    docs: ruleDocumentation(info.id)
+  };
+}
+
+export { explain };