@openpresentation/opf 0.26.3 → 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-BjsKgxBZ.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-BjsKgxBZ.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,20 +1,23 @@
-import { defaultCatalogs } from './chunk-2ZQBMZTZ.js';
-import { stats, embed, edit, OPFApiError, asApiError } from './chunk-GLLR3AQ5.js';
-export { OPFApiError, OPFExportError, OPFImportError, OPFMoveToCustomError, copySlides, fill, fillRecords, localAssetSources, moveToCustom, parseSlideSelection, sameRecord, updateFromCatalog } from './chunk-GLLR3AQ5.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-54OV2WQC.js';
-export { OPFPaginationError, paginateSlide } from './chunk-54OV2WQC.js';
-export { DECK_FORMATS, deckFormatOf, parse, stringify } from './chunk-FXNUM2PN.js';
-export { fromMarkdown, toMarkdown } from './chunk-WASENX2R.js';
-import './chunk-7RY7QWWJ.js';
-import './chunk-PB5X2VSV.js';
-export { OPFMarkdownError } from './chunk-DEI2M2H6.js';
-import './chunk-PXOXTJTN.js';
-export { diff, merge } from './chunk-YVNFACTC.js';
-import { validate, OPFValidationError } from './chunk-NJWI6MPT.js';
-export { CATALOG_SCHEMA, DEFAULT_VALIDATION_THRESHOLDS, OPFPatchError, OPFPatchValidationError, OPFValidationError, applyPatch, assertValid, assertValidCatalogRecord, catalogDisplayKinds, catalogSchemaNames, findValidationRule, resolveSlideContext, validateCatalogRecord, validationCategories, validationRules } from './chunk-NJWI6MPT.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';
+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';
@@ -30,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-F4UCOGR7.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,7 +1,9 @@
-export { fromMarkdown, toMarkdown } from './chunk-WASENX2R.js';
-import './chunk-7RY7QWWJ.js';
-export { OPFMarkdownError } from './chunk-DEI2M2H6.js';
-import './chunk-PXOXTJTN.js';
-import './chunk-NJWI6MPT.js';
+export { fromMarkdown, toMarkdown } from './chunk-UY6SQVR2.js';
+import './chunk-RYZPBJLB.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-BjsKgxBZ.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-BjsKgxBZ.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,21 +1,24 @@
-import { loadRenderer, listFontDirectories, leaseSharedFonts, prepareFonts } from './chunk-34LIUOT7.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-34LIUOT7.js';
-import { defaultCatalogs } from './chunk-2ZQBMZTZ.js';
-export { defaultCatalogs, galleryMismatch } from './chunk-2ZQBMZTZ.js';
-import { OPFApiError } from './chunk-GLLR3AQ5.js';
-export { OPFApiError, OPFExportError, OPFImportError, asApiError, parseSlideSelection } from './chunk-GLLR3AQ5.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-54OV2WQC.js';
-export { readDeckReport } from './chunk-FXNUM2PN.js';
-import './chunk-WASENX2R.js';
-import './chunk-7RY7QWWJ.js';
-import './chunk-PB5X2VSV.js';
-import './chunk-DEI2M2H6.js';
-import './chunk-PXOXTJTN.js';
-import './chunk-YVNFACTC.js';
-import './chunk-NJWI6MPT.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-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-54OV2WQC.js';
-import './chunk-NJWI6MPT.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-NJWI6MPT.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-NJWI6MPT.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,30 @@
-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"];
+/** Keys of `<!-- block: ... -->`. */
+declare const BLOCK_OPTION_KEYS: readonly ["id", "type", "as", "region"];
+/** Values of `as=` in a block options comment. */
+declare const BLOCK_AS_VALUES: readonly ["bullets", "video"];
+/** The first word of a fence info string that is not code: `chart`, `metric`, `timeline` and the two YAML escape hatches. */
+declare const FENCE_KINDS: readonly ["chart", "metric", "timeline", "opf-block", "opf-slide"];
+/** Lines of a ```metric fence: `key: value`. */
+declare const METRIC_KEYS: readonly ["value", "label", "description", "unit", "delta", "trend", "sentiment"];
+/** Attributes after the info word: `chart` takes `alt`, `timeline` `name` and `description`, a code fence `title`. */
+declare const FENCE_ATTRIBUTES: {
+    readonly chart: readonly ["alt"];
+    readonly timeline: readonly ["name", "description"];
+    readonly code: readonly ["title"];
+};
+/** Flags of an inline span `[text]{bold italic}` (the converter also reads `strikethrough`, `superscript` and `subscript`). */
+declare const SPAN_FLAGS: readonly ["bold", "italic", "underline", "strike", "sup", "sub"];
+/** Attributes of an inline span that take a value: `[text]{color=#B42318 size=24 font="Open Sans" lang=fr}`. */
+declare const SPAN_VALUES: readonly ["color", "size", "font", "lang"];
+/** Keywords a line of a slide can start with. */
+declare const LINE_KEYWORDS: readonly ["Note:", "Notes:"];
+type FenceKind = (typeof FENCE_KINDS)[number];
 
 /**
  * A range of source text in the `Finding.location` convention: UTF-16 offset and length, 1-based line and column (a line break is
@@ -85,13 +111,166 @@ interface PathAtResult {
  * underlined in the source. Tolerant: it reads text with syntax errors, comments and trailing commas as far as it can be read.
  * When the node does not exist, the range is that of the nearest ancestor that does, with `exact: false`.
  *
- * Phase 1 reads JSON. YAML and Markdown return `undefined` (phase 2): no range is guessed.
+ * JSON, YAML and Markdown. YAML is read with the `yaml` library's tolerant parse, so a text with syntax errors is located as far as it
+ * can be read. Markdown uses the ranges the converter records for every part it reads (the ones its findings are located by): a
+ * slide, its title, a list item, a block, the `layout=` of an options comment, the keys of the front matter and of the YAML in
+ * `opf-slide` and `opf-block` fences. A slide field the Markdown writes as a line (`# Title`, `- item`) has `value` = the text after
+ * the marker, `key` = the marker and `entry` = the line.
  */
 declare function locate(text: string, format: SourceFormat, pointer: string | readonly (string | number)[], options?: LocateOptions): TextRange | undefined;
 /**
- * The document path and the kind of position at a character offset (a caret between characters). JSON only (phase 1); YAML and
- * Markdown return `undefined`. Tolerant of broken text.
+ * The document path and the kind of position at a character offset (a caret between characters), in JSON, YAML or Markdown.
+ * Tolerant of broken text. In YAML a position on the whitespace of a blank line is `none` after the last node and `between` inside
+ * a collection; in Markdown a position outside the front matter and the slides is `none`.
  */
 declare function pathAt(text: string, format: SourceFormat, offset: number): PathAtResult | undefined;
 
-export { type AnalyzeOptions, type LocateOptions, type LocatePart, type PathAtResult, type SourceFormat, type SyntaxFix, type SyntaxProblem, type SyntaxProblemCode, type TextEdit, type TextRange, analyzeJsonSyntax, applyTextEdits, locate, pathAt };
+/** A range of the text: UTF-16 offsets, `from` inclusive and `to` exclusive, and the one-based line `from` is on. */
+interface ScanRange {
+    from: number;
+    to: number;
+    line: number;
+}
+interface MarkdownFrontMatter extends ScanRange {
+    /** The YAML between the two `---` lines: from the end of the opening line to the start of the closing line. */
+    yamlFrom: number;
+    yamlTo: number;
+    /** False when the closing `---` (or `...`) line is missing: then the YAML runs to the end of the text. */
+    closed: boolean;
+}
+interface MarkdownSlideScan extends ScanRange {
+    /** The slide's number in the converted deck (empty segments between `---` lines are not slides). */
+    index: number;
+}
+interface MarkdownCommentScan extends ScanRange {
+    /** `slide` and `block` are options comments (`<!-- slide: ... -->`), `comment` any other. */
+    kind: "slide" | "block" | "comment";
+    /** The text between `<!--` and `-->` (for an unclosed comment, to the end of its last line). */
+    innerFrom: number;
+    innerTo: number;
+    closed: boolean;
+    /** The slide it is in. */
+    slide: number;
+}
+interface MarkdownFenceScan extends ScanRange {
+    /** The opening fence characters (```` ``` ````, `~~~~`). */
+    marker: string;
+    /** The info string after the fence characters, trimmed; `infoFrom` and `infoTo` are its offsets. */
+    info: string;
+    infoFrom: number;
+    infoTo: number;
+    /** The first word of the info string. */
+    word: string;
+    /** `chart`, `metric`, `timeline`, `opf-block`, `opf-slide`, or `code` for any other fence. */
+    kind: FenceKind | "code";
+    /** The lines between the fences: `bodyFrom` is the start of the first line, `bodyTo` the end of the last (equal when the body is empty). */
+    bodyFrom: number;
+    bodyTo: number;
+    closed: boolean;
+    slide: number;
+}
+interface MarkdownNotesScan extends ScanRange {
+    slide: number;
+}
+interface MarkdownScan {
+    frontMatter?: MarkdownFrontMatter;
+    /** The slides, in order; each runs from its first to its last non-blank line. */
+    slides: MarkdownSlideScan[];
+    /** Offsets of the `---` lines that separate slides. */
+    separators: number[];
+    comments: MarkdownCommentScan[];
+    fences: MarkdownFenceScan[];
+    /** Speaker notes: from the `Note:` or `Notes:` line to the end of the slide. */
+    notes: MarkdownNotesScan[];
+}
+interface ScanMarkdownOptions {
+    /** How the text is cut into slides, as for `fromMarkdown`. */
+    split?: "auto" | "rules" | "headings";
+}
+/**
+ * The structure of a Markdown deck, found with the converter's line rules: front matter, slides, option comments, fences and notes, as
+ * offset ranges. Tolerant: an unclosed front matter, comment or fence is reported with `closed: false` and runs to the end of its slide.
+ * It is the one place an editor learns the dialect's regions from.
+ */
+declare function scanMarkdown(source: string, options?: ScanMarkdownOptions): MarkdownScan;
+
+/**
+ * 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 };