@openpresentation/opf 0.26.4 → 0.26.5

package/dist/explain-JSuESV-Y.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Small helpers for writing a finding in plain words (`describeFinding`, `finding-text.ts`). Pure, browser-safe, no state.
+ * Internal module: `finding-text-rules.ts` and `finding-text.ts` share them.
+ */
+
+/** What a finding is turned into: a sentence that says what is wrong, and (almost always) what could come next. */
+interface FindingText {
+    /** What is wrong, one or two sentences, American spelling, fields in backticks. */
+    message: string;
+    /** What could come next, without a leading "Next:" and starting in lower case. */
+    next?: string;
+}
+/** What the text of a finding may read besides the finding itself. Every member is optional. */
+interface FindingTextContext {
+    /** The checked document: lets a sentence quote the value that is there and read the schema and the ids of the document. */
+    document?: unknown;
+    /** The text format the finding was found in: examples are written for it (`"slides": [ ... ]` or `slides:`). Default `"json"`. */
+    format?: "json" | "yaml" | "md";
+    /** How many records of a catalog kind (`layouts`, `themes`, ...) can be chosen, for "press Ctrl+Space for the 28 layouts". */
+    catalogCount?: (kind: string) => number;
+    /** The chord that opens the list of choices in the editor the text is shown in. Default `Ctrl+Space`. */
+    chord?: string;
+    /** Overrides for what is otherwise read from `document`. */
+    valueAt?: (segments: string[]) => unknown;
+    schemaAt?: (segments: string[]) => Record<string, any> | undefined;
+    keysOf?: (segments: string[]) => string[];
+    catalogKind?: (segments: string[]) => string | undefined;
+    starter?: (segments: string[], property: string) => unknown;
+}
+/** The segments of a JSON Pointer (`/slides/0/title`); `""` is the document. */
+declare function segmentsOf(path: unknown): string[];
+/** Edit distance between two short strings (case-insensitive; enough for "did you mean"). */
+declare function distance(a: string, b: string): number;
+/** The candidates ordered by closeness to `value`; `close` holds those within an edit distance of 2 (or a known alias) and `all` every candidate. */
+declare function nearest(value: unknown, candidates: readonly unknown[], limit?: number): {
+    close: unknown[];
+    all: unknown[];
+};
+/** What `explain(ruleId)` returns: what a rule checks, why it matters and a before/after example. */
+interface RuleExplanation {
+    /** The finding's `ruleId`: `opf/text-contrast`, `yaml/syntax`, `markdown/fence-unterminated`. */
+    id: string;
+    /** The short name: `text-contrast`. */
+    name: string;
+    category: string;
+    /** The default severity (host policy can change it). */
+    severity: "error" | "warning" | "info";
+    /** One sentence: what the rule finds. */
+    summary: string;
+    /** Why it matters to the person who reads or presents the deck, or to the tools that read the file. */
+    rationale: string;
+    /** What to do, in a sentence or two (the general advice behind a finding's `Next:` line). */
+    fix: string;
+    /** A small example of the problem and of the repair, as the author would write it (JSON for `opf/*`, the reader's own format for `yaml/*` and `markdown/*`). */
+    example?: {
+        problem: string;
+        fixed: string;
+        language?: "json" | "yaml" | "markdown";
+    };
+    /** Where the rule is documented. */
+    docs: string;
+}
+
+/**
+ * What a rule checks, why, and what to do (`explain("opf/text-contrast")`, `explain("text-contrast")`, `explain("yaml/syntax")`). The `opf/*` rules come
+ * from the validation registry (summary, rationale, category, default severity, standard) plus a `fix` sentence and a small before/after example;
+ * `yaml/*` and `markdown/*` come from the readers' table. `undefined` for an unknown id.
+ */
+declare function explain(ruleId: string): RuleExplanation | undefined;
+
+export { type FindingTextContext as F, type RuleExplanation as R, type FindingText as a, distance as d, explain as e, nearest as n, segmentsOf as s };

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 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-DSafOGzh.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-DSafOGzh.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-C7o2EpDb.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-C7o2EpDb.js';
+export { R as RuleExplanation, e as explain } from './explain-JSuESV-Y.js';
 import { validate as validate$1 } from './validator.js';
 export { DEFAULT_VALIDATION_THRESHOLDS, OPFValidationError, assertValid, assertValidCatalogRecord, findValidationRule, validateCatalogRecord, validationRules } from './validator.js';
 import { R as ResolveVariablesOptions, h as VariableDiagnostic } from './validation-types-3ARvTsB0.js';

package/dist/index.js

@@ -1,22 +1,23 @@
-import { defaultCatalogs } from './chunk-ZSZDVIDV.js';
-import { stats, embed, edit, OPFApiError, asApiError } from './chunk-NZLW6FBQ.js';
-export { OPFApiError, OPFExportError, OPFImportError, OPFMoveToCustomError, copySlides, fill, fillRecords, localAssetSources, moveToCustom, parseSlideSelection, sameRecord, updateFromCatalog } from './chunk-NZLW6FBQ.js';
+import { defaultCatalogs } from './chunk-K5Q3LLYK.js';
+import { stats, embed, edit, OPFApiError, asApiError } from './chunk-UFEWQDQI.js';
+export { OPFApiError, OPFExportError, OPFImportError, OPFMoveToCustomError, copySlides, fill, fillRecords, localAssetSources, moveToCustom, parseSlideSelection, sameRecord, updateFromCatalog } from './chunk-UFEWQDQI.js';
 export { specFileEntries, specFileKinds, specFilePaths } from './chunk-UJSAR6GF.js';
 export { FONT_POLICY, applyFontPolicyDecisions, fontAvailabilityDiagnostics, fontPolicyFor } from './chunk-PJSPHHRK.js';
 export { OPFDataImportError, ingest, parseTabularData } from './chunk-TKQ2VFV5.js';
-import { paginate } from './chunk-QH2W6HIM.js';
-export { OPFPaginationError, paginateSlide } from './chunk-QH2W6HIM.js';
-export { DECK_FORMATS, deckFormatOf, parse, stringify } from './chunk-EDCRBTJF.js';
-export { fromMarkdown, toMarkdown } from './chunk-GWJBZ4LC.js';
-import './chunk-PIO73BQ6.js';
+import { paginate } from './chunk-EFMR32A5.js';
+export { OPFPaginationError, paginateSlide } from './chunk-EFMR32A5.js';
+export { DECK_FORMATS, deckFormatOf, parse, stringify } from './chunk-STIYINEL.js';
+export { fromMarkdown, toMarkdown } from './chunk-UY6SQVR2.js';
+import './chunk-WAZDP2WS.js';
 import './chunk-RYZPBJLB.js';
-import './chunk-MN7DRK57.js';
-import './chunk-O6BY3AU2.js';
-export { OPFMarkdownError } from './chunk-QAEBYDKY.js';
-import './chunk-6NBTZYYD.js';
-export { diff, merge } from './chunk-H5QC3X3K.js';
-import { validate, OPFValidationError } from './chunk-XFOOKVRI.js';
-export { CATALOG_SCHEMA, DEFAULT_VALIDATION_THRESHOLDS, OPFPatchError, OPFPatchValidationError, OPFValidationError, applyPatch, assertValid, assertValidCatalogRecord, catalogDisplayKinds, catalogSchemaNames, findValidationRule, resolveSlideContext, validateCatalogRecord, validationCategories, validationRules } from './chunk-XFOOKVRI.js';
+export { explain } from './chunk-MD3CJ5YJ.js';
+import './chunk-MLH5LIGF.js';
+import './chunk-DXTPLVAK.js';
+export { OPFMarkdownError } from './chunk-KPALXWX3.js';
+import './chunk-HPEZCAYC.js';
+export { diff, merge } from './chunk-TAV5S2JG.js';
+import { validate, OPFValidationError } from './chunk-CIWC7DRZ.js';
+export { CATALOG_SCHEMA, DEFAULT_VALIDATION_THRESHOLDS, OPFPatchError, OPFPatchValidationError, OPFValidationError, applyPatch, assertValid, assertValidCatalogRecord, catalogDisplayKinds, catalogSchemaNames, findValidationRule, resolveSlideContext, validateCatalogRecord, validationCategories, validationRules } from './chunk-CIWC7DRZ.js';
 export { CATALOG_GROUP_PATTERN, CATALOG_REFERENCE_PATTERN, CHART_TYPES, DEFAULT_VARIABLE_DATE_FORMAT, ENGINE_DEFAULT_CHART_TYPES, ENGINE_DEFAULT_COLOR_SCHEME, ENGINE_DEFAULT_FONT_SCHEME, ENGINE_DEFAULT_THEME, LANGUAGES, LOGO_SHAPES, OPFCatalogsOptionError, OPFUnresolvedReferenceError, OPFVariableError, SLIDE_SCOPED_BUILTINS, SOCIAL_PLATFORMS, VARIABLE_KINDS, catalogGroupSource, catalogKinds, catalogRecords, catalogReferenceSites, chartNumber, coerceVariableValue, datasetDiagnostics, formatDataNumber, formatVariableNumber, fromExcelNumberFormat, hasContentVariables, inlineChartData, inlineDatasets, inlineTableData, isDatasetRef, isTemplate, isXYChartType, listBuiltinVariables, listVariables, normalizeLanguageFamily, numberFormatError, parseReference, resolveChartData, resolveDesignRecords, resolveFontScheme, resolveReference, resolveSlideVariables, resolveTableData, resolveVariables, suggestChartNumberFix, tableCellDisplayValue, toExcelNumberFormat, unresolvedReference, unusedDatasets, variableDeclarations } from './chunk-XRMV2GMB.js';
 export { OPFFormatError, format } from './chunk-EQ6S5SEZ.js';
 export { audience, chartType, colorScheme, fontScheme, language, layout, narrative, presentation, purpose, schemaEntries, schemaNames, schemas, socialPlatform, theme, tone } from './chunk-F4HFDP6I.js';
@@ -32,7 +33,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-QIAJM6DQ.js');
+var engine = () => import('./conversion-PMJWLHDV.js');
 var rethrow = (error, fallback) => {
   if (error instanceof OPFValidationError) throw error;
   throw asApiError(OPFApiError, error, fallback);

package/dist/markdown.js

@@ -1,9 +1,9 @@
-export { fromMarkdown, toMarkdown } from './chunk-GWJBZ4LC.js';
+export { fromMarkdown, toMarkdown } from './chunk-UY6SQVR2.js';
 import './chunk-RYZPBJLB.js';
-import './chunk-MN7DRK57.js';
-import './chunk-O6BY3AU2.js';
-export { OPFMarkdownError } from './chunk-QAEBYDKY.js';
-import './chunk-6NBTZYYD.js';
-import './chunk-XFOOKVRI.js';
+import './chunk-MLH5LIGF.js';
+import './chunk-DXTPLVAK.js';
+export { OPFMarkdownError } from './chunk-KPALXWX3.js';
+import './chunk-HPEZCAYC.js';
+import './chunk-CIWC7DRZ.js';
 import './chunk-XRMV2GMB.js';
 import './chunk-F4HFDP6I.js';

package/dist/node-engine.d.ts

@@ -1,6 +1,6 @@
 export { b as DeckReport, c as DeckReportOptions, r as readDeckReport } from './deck-report-5vwMGcQz.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-DSafOGzh.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-DSafOGzh.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-C7o2EpDb.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-C7o2EpDb.js';
 import { a as Catalog } from './catalog-refs-BSfGELpt.js';
 import { e as PresentationPaginationResult } from './pagination-D_kJe4jH.js';
 import './presentation-Bwo8Ko6D.js';

package/dist/node-engine.js

@@ -1,23 +1,24 @@
-import { loadRenderer, listFontDirectories, leaseSharedFonts, prepareFonts } from './chunk-6IXSHIAL.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-6IXSHIAL.js';
-import { defaultCatalogs } from './chunk-ZSZDVIDV.js';
-export { defaultCatalogs, galleryMismatch } from './chunk-ZSZDVIDV.js';
-import { OPFApiError } from './chunk-NZLW6FBQ.js';
-export { OPFApiError, OPFExportError, OPFImportError, asApiError, parseSlideSelection } from './chunk-NZLW6FBQ.js';
+import { loadRenderer, listFontDirectories, leaseSharedFonts, prepareFonts } from './chunk-L7YEVQHP.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-L7YEVQHP.js';
+import { defaultCatalogs } from './chunk-K5Q3LLYK.js';
+export { defaultCatalogs, galleryMismatch } from './chunk-K5Q3LLYK.js';
+import { OPFApiError } from './chunk-UFEWQDQI.js';
+export { OPFApiError, OPFExportError, OPFImportError, asApiError, parseSlideSelection } from './chunk-UFEWQDQI.js';
 import './chunk-UJSAR6GF.js';
 import './chunk-PJSPHHRK.js';
 import './chunk-TKQ2VFV5.js';
-import { paginate } from './chunk-QH2W6HIM.js';
-export { readDeckReport } from './chunk-EDCRBTJF.js';
-import './chunk-GWJBZ4LC.js';
-import './chunk-PIO73BQ6.js';
+import { paginate } from './chunk-EFMR32A5.js';
+export { readDeckReport } from './chunk-STIYINEL.js';
+import './chunk-UY6SQVR2.js';
+import './chunk-WAZDP2WS.js';
 import './chunk-RYZPBJLB.js';
-import './chunk-MN7DRK57.js';
-import './chunk-O6BY3AU2.js';
-import './chunk-QAEBYDKY.js';
-import './chunk-6NBTZYYD.js';
-import './chunk-H5QC3X3K.js';
-import './chunk-XFOOKVRI.js';
+import './chunk-MD3CJ5YJ.js';
+import './chunk-MLH5LIGF.js';
+import './chunk-DXTPLVAK.js';
+import './chunk-KPALXWX3.js';
+import './chunk-HPEZCAYC.js';
+import './chunk-TAV5S2JG.js';
+import './chunk-CIWC7DRZ.js';
 import './chunk-XRMV2GMB.js';
 import './chunk-EQ6S5SEZ.js';
 import './chunk-F4HFDP6I.js';

package/dist/pagination.js

@@ -1,4 +1,4 @@
-export { OPFPaginationError, paginate, paginateSlide } from './chunk-QH2W6HIM.js';
-import './chunk-XFOOKVRI.js';
+export { OPFPaginationError, paginate, paginateSlide } from './chunk-EFMR32A5.js';
+import './chunk-CIWC7DRZ.js';
 import './chunk-XRMV2GMB.js';
 import './chunk-F4HFDP6I.js';

package/dist/patch.js

@@ -1,3 +1,3 @@
-export { OPFPatchError, OPFPatchValidationError, applyPatch, applyPatchWithInverse, escapePointerToken, formatPointer, getAtPointer, hasPointer, invertPatch, jsonEqual, normalizePatch, parsePointer, pointerFromPath, readPointer, splitPointer, unescapePointerToken } from './chunk-XFOOKVRI.js';
+export { OPFPatchError, OPFPatchValidationError, applyPatch, applyPatchWithInverse, escapePointerToken, formatPointer, getAtPointer, hasPointer, invertPatch, jsonEqual, normalizePatch, parsePointer, pointerFromPath, readPointer, splitPointer, unescapePointerToken } from './chunk-CIWC7DRZ.js';
 import './chunk-XRMV2GMB.js';
 import './chunk-F4HFDP6I.js';

package/dist/schema.js

@@ -1,3 +1,3 @@
-export { COMMON_KEYS, UNRANKED_PRIORITY, activeSchema, catalogKindAt, createSchemaValue, describeField, isPromotedRegionKey, listSchemaFields, resolveSchema, schemaAtPath, schemaCatalogKinds, schemaLabel, schemaType, schemaVariants, splitOpfPath } from './chunk-XFOOKVRI.js';
+export { COMMON_KEYS, UNRANKED_PRIORITY, activeSchema, catalogKindAt, createSchemaValue, describeField, isPromotedRegionKey, listSchemaFields, resolveSchema, schemaAtPath, schemaCatalogKinds, schemaLabel, schemaType, schemaVariants, splitOpfPath } from './chunk-CIWC7DRZ.js';
 import './chunk-XRMV2GMB.js';
 import './chunk-F4HFDP6I.js';

package/dist/source.d.ts

@@ -1,4 +1,6 @@
-import { b as FindingLocation } from './finding-l9dlQ2NF.js';
+import { b as FindingLocation, a as Finding } from './finding-l9dlQ2NF.js';
+import { F as FindingTextContext, a as FindingText } from './explain-JSuESV-Y.js';
+export { R as RuleExplanation, d as distance, e as explain, n as nearest, s as pointerSegments } from './explain-JSuESV-Y.js';
 
 /** Keys of `<!-- slide: ... -->`. */
 declare const SLIDE_OPTION_KEYS: readonly ["id", "type", "layout", "section", "tag", "hidden", "beat"];
@@ -192,4 +194,83 @@ interface ScanMarkdownOptions {
  */
 declare function scanMarkdown(source: string, options?: ScanMarkdownOptions): MarkdownScan;
 
-export { type AnalyzeOptions, BLOCK_AS_VALUES, BLOCK_OPTION_KEYS, FENCE_ATTRIBUTES, FENCE_KINDS, LINE_KEYWORDS, type LocateOptions, type LocatePart, METRIC_KEYS, type MarkdownCommentScan, type MarkdownFenceScan, type MarkdownFrontMatter, type MarkdownNotesScan, type MarkdownScan, type MarkdownSlideScan, type PathAtResult, SLIDE_OPTION_KEYS, SPAN_FLAGS, SPAN_VALUES, type ScanMarkdownOptions, type ScanRange, type SourceFormat, type SyntaxFix, type SyntaxProblem, type SyntaxProblemCode, type TextEdit, type TextRange, analyzeJsonSyntax, applyTextEdits, locate, pathAt, scanMarkdown };
+/**
+ * A finding in plain words (`describeFinding`): what is wrong, where it matters, and what could come next.
+ *
+ * `validate` returns findings written for tools (an Ajv sentence such as "must be equal to one of the allowed values", a rule's own sentence, `help`
+ * text for agents). An editor, the CLI or an agent that shows them to a person wants the sentence of artifacts/source-editor/VALIDATOR-HINTS.md:
+ *
+ *     `titleAlignment` must be left, center or right, but is `middle`.      (message)
+ *     did you mean `center`?                                                (next)
+ *
+ * The text is written from the structured data a finding already carries (the schema keyword and its parameters, the suggestions, the measured
+ * numbers, the path and the document), never by guessing at prose. Every `opf/*` rule has a `next` line (`finding-text-rules.ts`), as do the YAML and
+ * Markdown reader's findings (`finding-text-source.ts`); a finding from another producer keeps its sentence and the first sentence of its `help`.
+ *
+ * Pure and browser-safe. The reader of the text (a person) is addressed in American English, with fields in backticks.
+ */
+
+/** What a regular expression of the schemas means in words: "a hex color like `#1F4E79` (3, 6 or 8 hex digits)". Keyed by the pattern's source. */
+interface PatternPhrase {
+    /** The thing the value should be, after "must be": `a hex color like \`#1F4E79\``. */
+    what: string;
+    /** What to write instead, after "Next:": `write the color as #RRGGBB.` */
+    next: string;
+}
+/**
+ * Every `pattern` of the published schemas, in words. A test walks the schemas and fails when a pattern has no entry here, so a new pattern needs
+ * its phrase in the same change. The catalog reference pattern is written per catalog kind by `describeFinding` and is listed for completeness.
+ */
+declare const PATTERN_PHRASES: Readonly<Record<string, PatternPhrase>>;
+/**
+ * The message and the hint for a finding, in plain words. `message` says what is wrong (fields in backticks, no JSON Pointers, no Ajv keywords),
+ * `next` what could come next (it continues the word "Next:" and starts in lower case; absent only when the finding says nothing more). The
+ * schema findings are written from their keyword and parameters, every `opf/*` rule and every YAML and Markdown reader finding from a table,
+ * and a finding from another producer keeps its own sentence and the first sentence of its `help`.
+ *
+ * `context.document` (the checked deck) makes the text quote the value that is there; without it the text still reads well. Never throws.
+ */
+declare function describeFinding(finding: Finding, context?: FindingTextContext): FindingText;
+/** A starting value for a property the schema requires (`createSchemaValue` with the deck's slides and ids special-cased). */
+declare function starterValue(document: unknown, segments: readonly string[], property: string): unknown;
+
+/**
+ * YAML syntax problems in plain words (VALIDATOR-HINTS section 9): what the `yaml` library reports as "Implicit keys need to be on a single line" or
+ * "Flow sequence in block collection must be sufficiently indented and end with a ]" becomes the sentence an author needs, at the place that matters
+ * (the quote that is never closed, not the end of the file), with the text edits that repair it. One problem per root cause: the damage a mistake
+ * does further down is dropped.
+ *
+ * Internal module for the YAML and Markdown readers (`readYamlDocument`, `readYamlMapping`); `analyzeYamlSyntax` is the public face
+ * (`@openpresentation/opf/source`) that editors use for the edits. Browser-safe.
+ */
+
+/** Why the problem was reported, in kebab-case. */
+type YamlProblemCode = "tab-indent" | "unclosed-quote" | "unclosed-list" | "unclosed-map" | "incomplete-key" | "list-item-under-value" | "colon-in-value" | "misaligned" | "missing-dash" | "trailing-text" | "missing-colon" | "bad-escape" | "reserved-start" | "long-key" | "duplicate-key" | "multiple-documents" | "empty-document" | "not-a-mapping" | "other";
+/** What `analyzeYamlSyntax` returns: a problem with its reader rule, a located range and the text edits that repair it. */
+interface YamlSyntaxProblem {
+    /** The finding id the YAML reader reports it under: `yaml/syntax`, `yaml/duplicate-key`, `yaml/empty`, ... */
+    ruleId: string;
+    code: YamlProblemCode;
+    severity: "error";
+    range: TextRange;
+    message: string;
+    /** What to do, starting in lower case. */
+    next: string;
+    fixes: SyntaxFix[];
+    /** Other places that belong to the problem. */
+    related?: TextRange[];
+}
+interface AnalyzeYamlOptions {
+    /** The most problems returned (default 5). */
+    limit?: number;
+    /** `"any"` accepts a list or a plain value at the top (the YAML of a Markdown fence is checked by its own rules). Default `"mapping"`. */
+    rootKind?: "mapping" | "any";
+}
+/**
+ * The syntax problems of a YAML text, one per root cause, in position order: the `yaml` library's errors in plain words (a tab for indentation, a quote
+ * or bracket never closed, a line that is not `key: value`, a repeated key), an empty text, and a top level that is not a mapping, each with the edits
+ * that repair it. Empty for text the reader accepts as YAML (the OPF schema is another check). The offsets are the ones of `text`.
+ */
+declare function analyzeYamlSyntax(text: string, options?: AnalyzeYamlOptions): YamlSyntaxProblem[];
+
+export { type AnalyzeOptions, type AnalyzeYamlOptions, BLOCK_AS_VALUES, BLOCK_OPTION_KEYS, FENCE_ATTRIBUTES, FENCE_KINDS, FindingText, FindingTextContext, LINE_KEYWORDS, type LocateOptions, type LocatePart, METRIC_KEYS, type MarkdownCommentScan, type MarkdownFenceScan, type MarkdownFrontMatter, type MarkdownNotesScan, type MarkdownScan, type MarkdownSlideScan, PATTERN_PHRASES, type PathAtResult, type PatternPhrase, SLIDE_OPTION_KEYS, SPAN_FLAGS, SPAN_VALUES, type ScanMarkdownOptions, type ScanRange, type SourceFormat, type SyntaxFix, type SyntaxProblem, type SyntaxProblemCode, type TextEdit, type TextRange, type YamlProblemCode, type YamlSyntaxProblem, analyzeJsonSyntax, analyzeYamlSyntax, applyTextEdits, describeFinding, locate, pathAt, scanMarkdown, starterValue };

package/dist/source.js

@@ -1,10 +1,11 @@
-import { readMarkdown, frontMatter, splitSegments, isOutline, NOTES, fenceStart, fenceClose, COMMENT, SLIDE_OPTION_KEYS, FENCE_KINDS } from './chunk-MN7DRK57.js';
-export { BLOCK_AS_VALUES, BLOCK_OPTION_KEYS, FENCE_ATTRIBUTES, FENCE_KINDS, LINE_KEYWORDS, METRIC_KEYS, SLIDE_OPTION_KEYS, SPAN_FLAGS, SPAN_VALUES } from './chunk-MN7DRK57.js';
-import './chunk-O6BY3AU2.js';
-import { splitLines } from './chunk-QAEBYDKY.js';
-import './chunk-6NBTZYYD.js';
-import { rememberByText, createLocator, parsePointer } from './chunk-XFOOKVRI.js';
-export { analyzeJsonSyntax, applyTextEdits } from './chunk-XFOOKVRI.js';
+export { explain } from './chunk-MD3CJ5YJ.js';
+import { readMarkdown, frontMatter, splitSegments, isOutline, NOTES, fenceStart, fenceClose, COMMENT } from './chunk-MLH5LIGF.js';
+import './chunk-DXTPLVAK.js';
+import { splitLines } from './chunk-KPALXWX3.js';
+export { analyzeYamlSyntax } from './chunk-KPALXWX3.js';
+import './chunk-HPEZCAYC.js';
+import { rememberByText, SLIDE_OPTION_KEYS, FENCE_KINDS, createLocator, parsePointer } from './chunk-CIWC7DRZ.js';
+export { BLOCK_AS_VALUES, BLOCK_OPTION_KEYS, FENCE_ATTRIBUTES, FENCE_KINDS, LINE_KEYWORDS, METRIC_KEYS, PATTERN_PHRASES, SLIDE_OPTION_KEYS, SPAN_FLAGS, SPAN_VALUES, analyzeJsonSyntax, applyTextEdits, describeFinding, distance, nearest, segmentsOf as pointerSegments, starterValue } from './chunk-CIWC7DRZ.js';
 import './chunk-XRMV2GMB.js';
 import './chunk-F4HFDP6I.js';
 import { findNodeAtOffset, getNodePath, parseTree } from 'jsonc-parser';
@@ -372,7 +373,7 @@ var indexOrKey = (segment) => /^(?:0|[1-9][0-9]*)$/.test(segment) ? Number(segme
 var isJson = (format) => format === "json";
 var isMarkdown = (format) => format === "md" || format === "markdown";
 var parseText = (text) => parseTree(text.startsWith("\uFEFF") ? ` ${text.slice(1)}` : text, [], { allowTrailingComma: true, allowEmptyContent: true, disallowComments: false });
-function segmentsOf(pointer) {
+function segmentsOf2(pointer) {
   if (Array.isArray(pointer)) return pointer.map(String);
   if (typeof pointer !== "string") return void 0;
   try {
@@ -403,7 +404,7 @@ function partOf(value, property, part) {
   }
 }
 function locate(text, format, pointer, options = {}) {
-  const segments = segmentsOf(pointer);
+  const segments = segmentsOf2(pointer);
   if (!segments) return void 0;
   const part = options.part ?? "value";
   const place = createLocator(text);

package/dist/validator.js

@@ -1,3 +1,3 @@
-export { DEFAULT_VALIDATION_THRESHOLDS, OPFValidationError, assertValid, assertValidCatalogRecord, findValidationRule, validate, validateCatalogRecord, validationCategories, validationRules } from './chunk-XFOOKVRI.js';
+export { DEFAULT_VALIDATION_THRESHOLDS, OPFValidationError, assertValid, assertValidCatalogRecord, findValidationRule, validate, validateCatalogRecord, validationCategories, validationRules } from './chunk-CIWC7DRZ.js';
 export { promotedRegionKeys } from './chunk-XRMV2GMB.js';
 import './chunk-F4HFDP6I.js';

package/dist/yaml.js

@@ -1,8 +1,8 @@
-export { OPFYamlError, YAML_SCHEMA_URL, fromYaml, parseYamlData, scanYamlComments, toYaml } from './chunk-PIO73BQ6.js';
+export { OPFYamlError, YAML_SCHEMA_URL, fromYaml, parseYamlData, scanYamlComments, toYaml } from './chunk-WAZDP2WS.js';
 import './chunk-RYZPBJLB.js';
-import './chunk-QAEBYDKY.js';
-import './chunk-6NBTZYYD.js';
-import './chunk-XFOOKVRI.js';
+import './chunk-KPALXWX3.js';
+import './chunk-HPEZCAYC.js';
+import './chunk-CIWC7DRZ.js';
 import './chunk-XRMV2GMB.js';
 import './chunk-EQ6S5SEZ.js';
 import './chunk-F4HFDP6I.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openpresentation/opf",
-  "version": "0.26.4",
+  "version": "0.26.5",
   "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",
@@ -145,7 +145,7 @@
     "ajv-formats": "^3.0.1",
     "jsonc-parser": "3.3.1",
     "yaml": "^2.9.1",
-    "@openpresentation/gallery": "^0.26.4"
+    "@openpresentation/gallery": "^0.26.5"
   },
   "devDependencies": {
     "@expo-google-fonts/arimo": "0.4.3",
@@ -165,8 +165,8 @@
     "typescript": "~5.9.3"
   },
   "peerDependencies": {
-    "@openpresentation/opf-pptx": "^0.26.4",
-    "@openpresentation/opf-render": "^0.26.4"
+    "@openpresentation/opf-pptx": "^0.26.5",
+    "@openpresentation/opf-render": "^0.26.5"
   },
   "peerDependenciesMeta": {
     "@openpresentation/opf-pptx": {
@@ -186,5 +186,5 @@
     "test:packed": "node test/packed-install-smoke.mjs",
     "pack:dry-run": "pnpm run build:deps && pnpm run build && npm pack --dry-run --cache /tmp/opf-npm-cache"
   },
-  "gitHead": "8809122a74a43aa99cdd383a856839ad6f018af6"
+  "gitHead": "750d120e715b6c4930906aa71322d092d057c58d"
 }

package/dist/chunk-QAEBYDKY.js

@@ -1,192 +0,0 @@
-import { isRecord, same } from './chunk-6NBTZYYD.js';
-import { parseDocument, YAMLMap, Scalar, stringify } from 'yaml';
-
-function splitLines(source) {
-  const lines = [];
-  let start = 0;
-  let no = 1;
-  let i = 0;
-  while (i < source.length) {
-    const c = source[i];
-    if (c === "\n" || c === "\r") {
-      lines.push({ text: source.slice(start, i), start, end: i, no: no++ });
-      if (c === "\r" && source[i + 1] === "\n") i++;
-      i++;
-      start = i;
-    } else i++;
-  }
-  if (start < source.length) lines.push({ text: source.slice(start), start, end: source.length, no });
-  return lines;
-}
-var Ctx = class {
-  constructor(source) {
-    this.source = source;
-    for (let i = 0; i < source.length; i++) {
-      if (source[i] === "\r") {
-        if (source[i + 1] === "\n") i++;
-        this.lineStarts.push(i + 1);
-      } else if (source[i] === "\n") this.lineStarts.push(i + 1);
-    }
-  }
-  source;
-  findings = [];
-  /** JSON Pointer in the converted document to the source range that produced it. */
-  ranges = /* @__PURE__ */ new Map();
-  lineStarts = [0];
-  location(range) {
-    let lo = 0;
-    let hi = this.lineStarts.length;
-    while (lo + 1 < hi) {
-      const mid = lo + hi >> 1;
-      if ((this.lineStarts[mid] ?? 0) <= range.start) lo = mid;
-      else hi = mid;
-    }
-    return { offset: range.start, length: Math.max(0, range.end - range.start), line: lo + 1, column: range.start - (this.lineStarts[lo] ?? 0) + 1 };
-  }
-  report(ruleId, severity, message, help, range, path = "") {
-    this.findings.push({ ruleId, severity, category: "format", scope: "document", path, message, help, location: this.location(range) });
-  }
-  error(rule, message, help, range, path = "") {
-    this.report(`markdown/${rule}`, "error", message, help, range, path);
-  }
-  warn(rule, message, help, range, path = "") {
-    this.report(`markdown/${rule}`, "warning", message, help, range, path);
-  }
-  get errors() {
-    return this.findings.filter((d) => d.severity === "error").length;
-  }
-  /** The source range of a JSON Pointer, falling back to the nearest ancestor that has one. */
-  rangeOf(pointer) {
-    for (let path = pointer; ; path = path.slice(0, path.lastIndexOf("/"))) {
-      const found = this.ranges.get(path);
-      if (found) return found;
-      if (!path) return void 0;
-    }
-  }
-};
-var lineRange = (first, last = first) => ({ start: first.start, end: last.end });
-function readYamlMapping(text, base, ctx, rule, context) {
-  const keys = /* @__PURE__ */ new Map();
-  const doc = parseDocument(text, { schema: "core", uniqueKeys: true, merge: false, prettyErrors: false });
-  let ok = true;
-  for (const error of doc.errors) {
-    ok = false;
-    const [start, end] = error.pos;
-    ctx.error(rule, `YAML: ${error.message.split("\n")[0]}`, "Fix the YAML syntax. Front matter and embedded blocks hold JSON-compatible YAML: mappings, sequences and scalars, no anchors or tags.", { start: base + start, end: base + Math.max(end, start) });
-  }
-  if (!ok) return { value: {}, keys, ok };
-  if (doc.contents === null) return { value: {}, keys, ok };
-  if (!(doc.contents instanceof YAMLMap)) {
-    ctx.error(`${rule}-not-mapping`, "Expected a YAML mapping of keys and values.", "Write `key: value` lines; a list or a bare value is not accepted here.", context);
-    return { value: {}, keys, ok: false };
-  }
-  for (const pair of doc.contents.items) {
-    const key = pair.key;
-    const name = key instanceof Scalar ? String(key.value) : void 0;
-    if (name !== void 0 && key?.range) keys.set(name, { start: base + key.range[0], end: base + (pair.value?.range?.[1] ?? key.range[1]) });
-  }
-  let value;
-  try {
-    value = doc.toJS({ maxAliasCount: 0 });
-  } catch (error) {
-    ctx.error(rule, `YAML: ${error.message}`, "Anchors and aliases are not accepted; write each value out.", context);
-    return { value: {}, keys, ok: false };
-  }
-  const bad = nonJson(value);
-  if (bad) {
-    ctx.error(rule, `YAML value is not JSON-compatible (${bad}).`, "Quote special numbers such as .inf or .nan to keep them as strings.", context);
-    return { value: {}, keys, ok: false };
-  }
-  return { value, keys, ok };
-}
-function nonJson(value) {
-  if (typeof value === "number") return Number.isFinite(value) ? void 0 : "a number that is not finite";
-  if (value === null || typeof value === "string" || typeof value === "boolean") return void 0;
-  if (Array.isArray(value)) return value.map(nonJson).find(Boolean);
-  if (isRecord(value)) return Object.values(value).map(nonJson).find(Boolean);
-  return `a ${typeof value}`;
-}
-function writeYaml(value) {
-  for (const blockQuote of [true, false]) {
-    const text = stringify(value, { indent: 2, lineWidth: 0, minContentWidth: 0, blockQuote, defaultStringType: "PLAIN", defaultKeyType: "PLAIN" });
-    const doc = parseDocument(text, { schema: "core", uniqueKeys: true, merge: false });
-    if (!doc.errors.length && same(doc.toJS({ maxAliasCount: 0 }), value)) return text.endsWith("\n") ? text : `${text}
-`;
-  }
-  return void 0;
-}
-var DECIMAL = /^-?(?:0|[1-9]\d*)(?:\.\d+)?$/;
-function scalarText(value) {
-  if (typeof value === "number") return DECIMAL.test(String(value)) ? String(value) : JSON.stringify(String(value));
-  const plain = value !== "" && value === value.trim() && !value.startsWith('"') && !/[\r\n]/.test(value) && !DECIMAL.test(value);
-  return plain ? value : JSON.stringify(value);
-}
-function readCsv(text) {
-  const rows = [];
-  let row = [];
-  let i = 0;
-  const n = text.length;
-  const endRecord = () => {
-    rows.push(row);
-    row = [];
-  };
-  while (i < n) {
-    while (text[i] === " " || text[i] === "	") i++;
-    if (text[i] === '"') {
-      let value = "";
-      i++;
-      for (; ; ) {
-        if (i >= n) return { rows, error: "A quoted field is not closed." };
-        if (text[i] === '"') {
-          if (text[i + 1] === '"') {
-            value += '"';
-            i += 2;
-            continue;
-          }
-          i++;
-          break;
-        }
-        value += text[i++];
-      }
-      while (text[i] === " " || text[i] === "	") i++;
-      if (i < n && text[i] !== "," && text[i] !== "\n" && text[i] !== "\r") return { rows, error: "Text follows a closing quote." };
-      row.push({ value, quoted: true });
-    } else {
-      let j = i;
-      while (j < n && text[j] !== "," && text[j] !== "\n" && text[j] !== "\r") j++;
-      row.push({ value: text.slice(i, j).trim(), quoted: false });
-      i = j;
-    }
-    if (text[i] === ",") {
-      i++;
-      if (i >= n || text[i] === "\n" || text[i] === "\r") row.push({ value: "", quoted: false });
-      continue;
-    }
-    if (text[i] === "\r" && text[i + 1] === "\n") i++;
-    i++;
-    endRecord();
-  }
-  if (row.length) endRecord();
-  return { rows };
-}
-var needsQuotes = (value) => /[",\r\n]/.test(value) || value !== value.trim() || value === "";
-function csvField(cell, header = false) {
-  if (cell === null) return "";
-  if (typeof cell === "number") return String(cell);
-  if (typeof cell === "boolean") return String(cell);
-  const text = String(cell);
-  const ambiguous = !header && (DECIMAL.test(text) || /^(?:true|false)$/.test(text));
-  return needsQuotes(text) || ambiguous ? `"${text.replaceAll('"', '""')}"` : text;
-}
-var OPFMarkdownError = class extends Error {
-  code;
-  details;
-  constructor(code, message, details = {}) {
-    super(message);
-    this.name = "OPFMarkdownError";
-    this.code = code;
-    this.details = details;
-  }
-};
-
-export { Ctx, DECIMAL, OPFMarkdownError, csvField, lineRange, readCsv, readYamlMapping, scalarText, splitLines, writeYaml };

package/dist/conversion-QIAJM6DQ.js

@@ -1,20 +0,0 @@
-export { convertFiles, deckFileFormat, exportFormatOf, openDeck, planConversion, readInput, saveDeck, writePlanned } from './chunk-6IXSHIAL.js';
-import './chunk-ZSZDVIDV.js';
-import './chunk-NZLW6FBQ.js';
-import './chunk-UJSAR6GF.js';
-import './chunk-PJSPHHRK.js';
-import './chunk-TKQ2VFV5.js';
-import './chunk-QH2W6HIM.js';
-import './chunk-EDCRBTJF.js';
-import './chunk-GWJBZ4LC.js';
-import './chunk-PIO73BQ6.js';
-import './chunk-RYZPBJLB.js';
-import './chunk-MN7DRK57.js';
-import './chunk-O6BY3AU2.js';
-import './chunk-QAEBYDKY.js';
-import './chunk-6NBTZYYD.js';
-import './chunk-H5QC3X3K.js';
-import './chunk-XFOOKVRI.js';
-import './chunk-XRMV2GMB.js';
-import './chunk-EQ6S5SEZ.js';
-import './chunk-F4HFDP6I.js';