@openpresentation/opf-editor 0.26.3 → 0.26.5

package/dist/source-messages.js

@@ -1,231 +1,47 @@
-// Problem text for the source pane (artifacts/source-editor/VALIDATOR-HINTS.md): what is wrong, where, and what could come next, written from what core's
-// findings already carry (the schema keyword and its parameters, the suggestions, the help). Pure functions, no DOM: `describeFinding(finding, context)`
-// returns `{ message, next }`; the quick fix edits that go with a message are in source-fixes.js.
+// Problem text for the source pane (artifacts/source-editor/VALIDATOR-HINTS.md): what is wrong, where, and what could come next. The sentences are core's
+// (`describeFinding` of `@openpresentation/opf/source`: the schema keywords, every rule, the YAML and Markdown readers), so the CLI, agents and every
+// editor say the same thing; this module adds what only an editor has (the problems its own analyzers found, the replacement values of a quick fix).
+// Pure functions, no DOM: `describeFinding(finding, context)` returns `{ message, next }`; the quick fix edits that go with a message are in source-fixes.js.
+import { describeFinding as describeWithCore, distance, nearest, pointerSegments } from "@openpresentation/opf/source";
 
 /**
- * `context`: `{ valueAt(segments) }` reads a value of the document being checked (the actual value makes "but is `middle`" possible),
- * `{ schemaAt(segments) }` the resolved schema of a field, `{ catalogKind(segments) }` the catalog kind a field references,
- * `{ catalogCount(kind) }` how many records of a kind are available, `{ keysOf(segments) }` the property names the schema allows in an object.
+ * `context`: what core's `FindingTextContext` takes. `{ document }` is the deck being checked (the actual value makes "but is `middle`" possible and the
+ * ids of the document available to the rules), `{ format }` the text format (examples are written for it), `{ catalogCount(kind) }` how many records of a
+ * kind can be chosen. Callbacks `valueAt(segments)`, `schemaAt(segments)`, `keysOf(segments)`, `catalogKind(segments)` and `starter(segments, property)`
+ * take the place of what core would read from `document`.
  */
 
-const WORDS = { object: "an object", array: "a list", string: "text", number: "a number", integer: "a whole number", boolean: "true or false", null: "null" };
-const KIND_WORDS = { layouts: "layout", themes: "theme", colorSchemes: "color scheme", fontSchemes: "font scheme", narratives: "narrative", audiences: "audience", purposes: "purpose", tones: "tone", languages: "language" };
-const KIND_EXAMPLES = { layouts: "`pillars` or `acme:hero`", themes: "`minimal` or `acme:bold`", colorSchemes: "`boost` or `acme:night`", fontSchemes: "`aptos` or `acme:brand`", narratives: "`classic-story`", audiences: "`board`", purposes: "`inform`", tones: "`formal`" };
-const ALIASES = { middle: "center", centre: "center", centered: "center", centred: "center", justify: "left", horizontal: "horizontal", col: "column", cols: "column", pic: "image", picture: "image", photo: "image", paragraph: "text", bullets: "list", bullet: "list" };
+export { distance, nearest };
 
 /** The segments of a JSON Pointer ("/slides/0/title"); "" is the document. */
-export function segmentsOf(path) {
-  if (Array.isArray(path)) return path.map(String);
-  if (typeof path !== "string" || path === "" || path === "/") return [];
-  return path.replace(/^\//, "").split("/").map((part) => part.replaceAll("~1", "/").replaceAll("~0", "~"));
-}
-
-const code = (value) => `\`${value}\``;
-const isIndex = (segment) => /^\d+$/.test(String(segment));
-
-/** What a field is called in a sentence: its name, or "<name> entry" for a list item. */
-export function fieldLabel(segments) {
-  if (!segments.length) return "the deck";
-  const last = segments[segments.length - 1];
-  if (isIndex(last)) {
-    const owner = [...segments].reverse().find((segment) => !isIndex(segment));
-    return owner === "slides" ? `slide ${Number(last) + 1}` : owner ? `${owner} entry ${Number(last) + 1}` : `entry ${Number(last) + 1}`;
-  }
-  return code(last);
-}
-/** What an object is called in a sentence ("the deck", "a slide", "`design`"). */
-function containerName(segments) {
-  if (!segments.length) return "the deck";
-  if (segments.length === 2 && segments[0] === "slides" && isIndex(segments[1])) return "a slide";
-  const last = segments[segments.length - 1];
-  return isIndex(last) ? fieldLabel(segments) : code(last);
-}
-
-/** What a value is, with its text: "text (`Hello`)", "a number (`42`)", "a list". */
-function describeKind(value) {
-  if (typeof value === "string") return value === "" ? "empty text" : `text (${describeValue(value)})`;
-  return describeValue(value);
-}
-
-function typeWords(type) {
-  const list = (Array.isArray(type) ? type : [type]).filter(Boolean).map((entry) => WORDS[entry] ?? String(entry));
-  return [...new Set(list)].join(" or ") || "a different kind of value";
-}
-/** A value in a sentence: "`Hello`", "a number (`42`)", "a list". */
-export function describeValue(value) {
-  if (value === undefined) return "missing";
-  if (value === null) return "null";
-  if (Array.isArray(value)) return value.length ? `a list of ${value.length}` : "an empty list";
-  if (typeof value === "object") return "an object";
-  if (typeof value === "string") return value === "" ? "empty" : `${code(value.length > 30 ? `${value.slice(0, 29)}…` : value)}`;
-  return `${typeof value === "number" ? "a number" : "true or false"} (${code(String(value))})`;
-}
-
-/** Edit distance between two short strings (Damerau-free; enough for "did you mean"). */
-export function distance(a, b) {
-  const x = a.toLowerCase(), y = b.toLowerCase();
-  if (x === y) return 0;
-  const row = Array.from({ length: y.length + 1 }, (_, index) => index);
-  for (let i = 1; i <= x.length; i++) {
-    let previous = row[0];
-    row[0] = i;
-    for (let j = 1; j <= y.length; j++) {
-      const keep = row[j];
-      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, previous + (x[i - 1] === y[j - 1] ? 0 : 1));
-      previous = keep;
-    }
-  }
-  return row[y.length];
-}
-/** The candidates ordered by closeness to `value`; only those within an edit distance of 2 (or a known alias) come first. */
-export function nearest(value, candidates, limit = 5) {
-  const text = String(value ?? "");
-  const alias = ALIASES[text.toLowerCase()];
-  const ranked = candidates.map((candidate) => ({ candidate, score: String(candidate).toLowerCase() === alias ? 0 : distance(text, String(candidate)) }));
-  ranked.sort((a, b) => a.score - b.score);
-  const close = ranked.filter((entry) => entry.score <= Math.max(2, Math.floor(text.length / 4))).map((entry) => entry.candidate);
-  return { close: close.slice(0, limit), all: ranked.map((entry) => entry.candidate) };
-}
-
-/** Values joined for a sentence: "left, center or right"; above five, the first three and the count. */
-function valueList(values, max = 5) {
-  const list = values.map((value) => (typeof value === "string" ? value : JSON.stringify(value)));
-  if (list.length <= max) return list.length > 1 ? `${list.slice(0, -1).join(", ")} or ${list.at(-1)}` : list.join("");
-  return `one of ${list.length} values (${list.slice(0, 3).join(", ")}, …)`;
-}
-
-const firstSentence = (text) => /^.*?[.!?](?=\s|$)/.exec(String(text ?? "").replace(/\s+/g, " ").trim())?.[0] ?? "";
-const chord = (name) => name;
-
-/** The schema keywords of `opf/schema` findings, written in plain words. */
-function describeSchema(finding, segments, context) {
-  const { keyword, params = {}, alternatives } = finding.validation ?? {};
-  const label = fieldLabel(segments);
-  const actual = context.valueAt?.(segments);
-  switch (keyword) {
-    case "required": {
-      const property = params.missingProperty;
-      const sample = property === "slides" ? '[ { "title": "…" } ]' : starterText(context.schemaAt?.([...segments, property]), property);
-      return { message: `${cap(containerName(segments))} is missing ${code(property)}.`, next: `add "${property}": ${sample}.` };
-    }
-    case "type": {
-      const expected = typeWords(params.type);
-      const next = params.type === "array" && typeof actual === "string" ? `write [${JSON.stringify(actual)}].` : params.type === "string" && typeof actual === "number" ? `write ${JSON.stringify(String(actual))}.` : `write ${expected}.`;
-      return { message: `${cap(label)} should be ${expected}, but it is ${describeKind(actual)}.`, next };
-    }
-    case "oneOf":
-    case "anyOf": {
-      const forms = (alternatives ?? []).map((entry) => String(entry).split(":")[0].trim());
-      const words = forms.length ? [...new Set(forms.map((form) => WORDS[form] ?? form))].slice(0, 3).join(" or ") : "a different kind of value";
-      return { message: `${cap(label)} should be ${words}, but it is ${describeKind(actual)}.`, next: forms.length ? `write ${words}.` : "check the schema reference for this field." };
-    }
-    case "enum": {
-      const values = params.allowedValues ?? finding.suggestions?.map((entry) => entry.value) ?? [];
-      const where = nearest(actual, values);
-      const guess = where.close[0];
-      const is = actual === undefined ? "" : `, but is ${describeValue(actual)}`;
-      return {
-        message: `${cap(label)} must be ${valueList(values)}${is}.`,
-        next: guess !== undefined ? `did you mean ${code(guess)}?` : values.length > 5 ? `press ${chord("Ctrl+Space")} for the ${values.length} values.` : "choose one of these values.",
-      };
-    }
-    case "const":
-      return { message: `${cap(label)} must be exactly ${code(params.allowedValue)}.`, next: `write ${JSON.stringify(params.allowedValue)}.` };
-    case "pattern": {
-      const kind = context.catalogKind?.(segments);
-      if (kind) {
-        const word = KIND_WORDS[kind] ?? "catalog";
-        const count = context.catalogCount?.(kind);
-        const is = actual === "" ? "it is empty" : `it is ${describeValue(actual)}`;
-        return { message: `${cap(label)} must be a ${word} id such as ${KIND_EXAMPLES[kind] ?? "`id` or `name:id`"} (lowercase letters, digits and hyphens), but ${is}.`, next: `press ${chord("Ctrl+Space")}${count ? ` for the ${count} ${word}s` : " for the available ids"}, or remove it${kind === "layouts" ? " to let OPF pick" : ""}.` };
-      }
-      if (/#/.test(params.pattern ?? "") && /0-9a-fA-F/.test(params.pattern ?? "")) return { message: `${cap(label)} must be a hex color like ${code("#1F4E79")} (3, 6 or 8 hex digits), but is ${describeValue(actual)}.`, next: "write the color as #RRGGBB." };
-      return { message: `${cap(label)} does not match the expected format${typeof actual === "string" ? `: ${describeValue(actual)}` : ""}.`, next: "check the schema reference for this field." };
-    }
-    case "additionalProperties": {
-      const name = params.additionalProperty ?? segments.at(-1);
-      const parent = segments.slice(0, -1);
-      const allowed = context.keysOf?.(parent) ?? [];
-      const hint = nearest(name, allowed).close[0];
-      return {
-        message: `${code(name)} is not a property of ${containerName(parent)}.`,
-        next: `${hint ? `did you mean ${code(hint)}? ` : ""}To keep custom data, put it under ${code("extensions")}.`.trim(),
-      };
-    }
-    case "minItems":
-      return { message: `${cap(label)} needs at least ${params.limit} item${params.limit === 1 ? "" : "s"}.`, next: label === "`slides`" ? "add a slide." : "add an item." };
-    case "maxItems":
-      return { message: `${cap(label)} can hold at most ${params.limit} items.`, next: "remove the extra ones." };
-    case "uniqueItems":
-      return { message: `${cap(label)} repeats an entry.`, next: "remove the repeated entry." };
-    case "minLength":
-      return { message: `${cap(label)} is empty.`, next: "write some text, or remove the key." };
-    case "maxLength":
-      return { message: `${cap(label)} is longer than ${params.limit} characters.`, next: "shorten it." };
-    case "minimum":
-    case "exclusiveMinimum":
-    case "maximum":
-    case "exclusiveMaximum": {
-      const bound = /minimum/i.test(keyword) ? "at least" : "at most";
-      return { message: `${cap(label)} must be ${keyword.startsWith("exclusive") ? (bound === "at least" ? "greater than" : "less than") : bound} ${params.limit}, but is ${describeValue(actual)}.`, next: `write ${params.limit}${keyword.startsWith("exclusive") ? " or a different number" : ""}.` };
-    }
-    case "format":
-      return { message: `${cap(label)} must be a ${params.format === "uri" ? "web address like https://example.com" : params.format}.`, next: "check the value." };
-    default:
-      return null;
-  }
-}
-
-function cap(text) {
-  return text[0] === "`" ? text : text.charAt(0).toUpperCase() + text.slice(1);
-}
-function starterText(schema, property) {
-  const example = schema?.examples?.find((value) => typeof value === "string" && !value.includes("..."));
-  if (example) return JSON.stringify(example);
-  const type = Array.isArray(schema?.type) ? schema.type[0] : schema?.type;
-  if (type === "object") return "{ … }";
-  if (type === "array") return "[ … ]";
-  if (type === "number" || type === "integer") return "0";
-  if (type === "boolean") return "false";
-  return property === "id" ? '"acme"' : '"…"';
-}
+export const segmentsOf = pointerSegments;
 
 /**
- * The message and the hint for a finding. Findings of the schema are written from their keyword and parameters, an unresolved reference from
- * its suggestions, a duplicate key plainly; any other finding keeps core's own sentence and takes its help as the hint.
- * `finding.path` is a JSON Pointer.
+ * The message and the hint for a finding. A problem that brings its own hint (the syntax analyzers') keeps it whole; every other finding is written by
+ * core from its data. `finding.path` is a JSON Pointer.
  */
 export function describeFinding(finding, context = {}) {
-  const segments = segmentsOf(finding.path);
-  let described = null;
-  if (finding.ruleId === "opf/schema" && finding.validation?.keyword) described = describeSchema(finding, segments, context);
-  else if (finding.ruleId === "opf/duplicate-key") {
-    const key = segments.at(-1);
-    described = { message: `${code(key)} appears twice in this object.`, next: "JSON keeps only the last one, so the first value is ignored. Keep one of them." };
-  } else if (finding.ruleId === "opf/unresolved-reference" && finding.suggestions?.length) {
-    const first = finding.suggestions[0].value;
-    described = { message: finding.message, next: `did you mean ${code(first)}?${finding.suggestions.length > 1 ? ` Others: ${finding.suggestions.slice(1, 4).map((entry) => code(entry.value)).join(", ")}.` : ""}` };
-  }
-  if (described) return described;
-  // A problem that brings its own hint (the syntax analyzer's) keeps it whole; core's help is cut to its first sentence.
   if (finding.next) return { message: finding.message, next: finding.next };
-  const help = firstSentence(finding.help);
-  return { message: finding.message, next: help ? help.charAt(0).toLowerCase() + help.slice(1) : undefined };
+  return describeWithCore(finding, context);
 }
 
 /** The values a quick fix can change an enum or a reference to: the nearest first, then the rest, at most `limit`. */
 export function replacementValues(finding, context = {}, limit = 5) {
   const segments = segmentsOf(finding.path);
   const keyword = finding.validation?.keyword;
+  const read = (path) => (context.valueAt ? context.valueAt(path) : path.reduce((value, key) => (value !== null && typeof value === "object" ? value[key] : undefined), context.document));
   if (keyword === "enum") {
     const values = finding.validation.params?.allowedValues ?? [];
-    const { close, all } = nearest(context.valueAt?.(segments), values, limit);
-    return [...new Set([...close, ...all])].slice(0, limit);
+    // The near misses first, then the values in the order the schema lists them.
+    return [...new Set([...nearest(read(segments), values, limit).close, ...values])].slice(0, limit);
   }
   if (finding.ruleId === "opf/unresolved-reference" && finding.suggestions?.length) return finding.suggestions.map((entry) => entry.value).slice(0, limit);
   if (keyword === "additionalProperties") {
     const parent = segments.slice(0, -1);
-    return nearest(finding.validation.params?.additionalProperty ?? segments.at(-1), context.keysOf?.(parent) ?? [], 3).close;
+    const keys = context.keysOf?.(parent) ?? finding.suggestions?.map((entry) => entry.value) ?? [];
+    return nearest(finding.validation.params?.additionalProperty ?? segments.at(-1), keys, 3).close;
   }
+  // Findings core has suggestions for (a near-miss option name of Markdown, the chart types).
+  if (finding.suggestions?.length && String(finding.ruleId).startsWith("markdown/")) return finding.suggestions.map((entry) => entry.value).slice(0, limit);
   return [];
 }

package/dist/source-pane.d.ts

@@ -71,8 +71,10 @@ export interface SourcePaneOptions {
   /** Accessible name of the code editor (default `OPF source`). */
   label?: string;
   catalogs?: JsonCatalogContext;
-  /** Live completions while typing JSON: property names from the schema and values (enums, booleans, catalog ids, templates, snippets) at the cursor's JSON path. Tab and Enter accept the selected item, Escape closes the list, Ctrl+Space (Cmd+I on macOS) opens it; the field menu is on Alt+Shift+O. Hover documentation, squiggles with quick fixes (Cmd/Ctrl+.) and F8 come with it. YAML and Markdown have no completions yet. Default true. */
+  /** Live completions while typing JSON: property names from the schema and values (enums, booleans, catalog ids, templates, snippets) at the cursor's JSON path. Tab and Enter accept the selected item, Escape closes the list, Ctrl+Space (Cmd+I on macOS) opens it; the field menu is on Alt+Shift+O. Hover documentation, squiggles with quick fixes (Cmd/Ctrl+.) and F8 come with it. The same for YAML and Markdown (front matter, slide and block options, fences, `Note:` and snippets). Default true. */
   completions?: boolean;
+  /** Enter continues a list: a new string item after a string in a JSON list, the next `- ` in YAML, the next marker (or `> `) in Markdown; an empty one ends it. Default true. */
+  smartListEnter?: boolean;
   onError?(error: unknown): void;
 }
 
@@ -110,10 +112,16 @@ export interface SourcePane {
   /** Switch format. Returns false, and says why in the findings, when the document cannot be written in it. Does not call `onFormatChange`. */
   setFormat(format: SourceFormat): boolean;
   getFormat(): SourceFormat;
-  /** Move the cursor to the line of a JSON Pointer (or dotted OPF path) in the current format; best effort for YAML and Markdown. Returns the line. */
+  /** Move the cursor to the line of a JSON Pointer (or dotted OPF path) in the current format (core's `locate` finds it in JSON, YAML and Markdown). Returns the line. */
   focusPath(path: string): number;
   /** The text as shown, with any pending edit applied first. */
   getText(): string;
+  /**
+   * Canonicalize with OPF: rewrite the YAML or Markdown text from the document with core's writer (the old behavior of Format). It drops comments, so it
+   * asks first when there are any (an inline confirmation naming how many); `confirmed: true` has asked already. Returns "applied", "unchanged",
+   * "confirm" (waiting for the answer) or "refused" (JSON, read-only, or text that does not read as a document).
+   */
+  canonicalize(options?: { confirmed?: boolean }): "applied" | "unchanged" | "confirm" | "refused";
   getName(): string;
   setName(name: string): void;
   setDensity(density: SourcePaneDensity): void;

package/dist/source-pane.js

@@ -7,9 +7,11 @@ import { errorText, normalizeFinding, rejectionFindings as findingsOfError } fro
 import { formatSource } from "./source-format.js";
 import { buildProblems, summarize } from "./source-problems.js";
 import { analyzeSyntax, findDuplicateKeys } from "./source-syntax.js";
-import { createSchemaValue, schemaAtPath, schemaVariants } from "./schema.js";
-import { catalogKindAt } from "@openpresentation/opf/schema";
-import { locateJson } from "./source-ranges.js";
+import { withSyntaxFixes } from "./source-fixes-syntax.js";
+import { detailsFor } from "./source-details.js";
+import { schemaAtPath, schemaVariants } from "./schema.js";
+import { locateText } from "./source-ranges.js";
+import { scanMarkdown, starterValue } from "@openpresentation/opf/source";
 import { listCatalogRecords } from "./catalogs.js";
 
 // The source pane (RR-98): the OPF document as JSON, YAML or Markdown, with the file name, the format menu, Format, Copy
@@ -33,6 +35,7 @@ const ICONS = {
   Check: '<path d="M20 6 9 17l-5-5"/>',
   CircleX: '<circle cx="12" cy="12" r="10"/><path d="m15 9-6 6"/><path d="m9 9 6 6"/>',
   Info: '<circle cx="12" cy="12" r="10"/><path d="M12 16v-4"/><path d="M12 8h.01"/>',
+  Sparkles: '<path d="m12 3-1.912 5.813a2 2 0 0 1-1.275 1.275L3 12l5.813 1.912a2 2 0 0 1 1.275 1.275L12 21l1.912-5.813a2 2 0 0 1 1.275-1.275L21 12l-5.813-1.912a2 2 0 0 1-1.275-1.275L12 3Z"/>',
 };
 function icon(name, size = 14) {
   const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
@@ -73,6 +76,19 @@ function same(a, b) {
 const SEVERITY = { error: 0, warning: 1, info: 2 };
 const plural = (count, word) => `${count} ${word}${count === 1 ? "" : "s"}`;
 
+/** The rule's explanation as the body of a row's Details: what it checks, why, what to do, an example and the documentation link. */
+function fillDetails(body, details) {
+  const line = (label, text) => { const row = el("p", "opf-source-finding-explain-line"); row.append(Object.assign(el("strong"), { textContent: `${label} ` }), document.createTextNode(text)); return row; };
+  body.append(line("Checks:", details.summary), line("Why:", details.why), line("Fix:", details.fix));
+  if (details.schema) body.append(line("Schema:", details.schema));
+  if (details.example) {
+    const example = el("div", "opf-source-finding-explain-example");
+    example.append(Object.assign(el("code"), { textContent: details.example.problem || "(empty)" }), Object.assign(el("span", "opf-source-finding-explain-arrow"), { textContent: " becomes " }), Object.assign(el("code"), { textContent: details.example.fixed }));
+    body.append(example);
+  }
+  if (details.docs && /^https?:/.test(details.docs)) body.append(Object.assign(el("a", "opf-source-finding-explain-link", { href: details.docs, target: "_blank", rel: "noopener noreferrer" }), { textContent: "Documentation" }));
+}
+
 /** Read the text of one format. `{ deck }` on success; `findings` carry the syntax errors (`syntax: true`) or the OPF findings of the parsed deck. */
 function readText(format, text, catalogs) {
   if (format === "json") {
@@ -84,9 +100,12 @@ function readText(format, text, catalogs) {
     return { deck, findings: [] };
   }
   const result = format === "yaml" ? (fromYaml(text, { catalogs })) : fromMarkdown(text, { catalogs });
-  const syntax = result.findings.filter((finding) => !finding.ruleId?.startsWith("opf/"));
-  if (syntax.length) return { syntax: true, findings: syntax.map((finding) => normalizeFinding(finding, "syntax")) };
-  return { deck: result.presentation, findings: result.findings.map((finding) => normalizeFinding(finding, "schema")) };
+  // The reader's own findings: errors stop the document being read; its warnings (a numbered list that became bullets) come with the deck.
+  const readerFindings = result.findings.filter((finding) => !finding.ruleId?.startsWith("opf/"));
+  const errors = readerFindings.filter((finding) => finding.severity === "error");
+  const syntax = (list) => withSyntaxFixes(format, text, list).map((finding) => normalizeFinding(finding, "syntax"));
+  if (errors.length) return { syntax: true, findings: syntax(errors) };
+  return { deck: result.presentation, findings: result.findings.map((finding) => normalizeFinding(finding, "schema")), notes: syntax(readerFindings) };
 }
 
 /**
@@ -124,6 +143,9 @@ export function createSourcePane(container, options = {}) {
   // The problems now shown (rows of source-problems.js), the document they were checked as, and the pause timers of the count announcement and the
   // syntax pass.
   const rowOf = new WeakMap();
+  // The problems whose Details are open (by rule, path and message), so a redraw of the panel keeps them open, and a number per key for the element ids.
+  const detailsOpen = new Set();
+  const detailsKeys = { ids: new Map(), id(key) { if (!this.ids.has(key)) this.ids.set(key, this.ids.size + 1); return this.ids.get(key); } };
   let problemRows = [], lastDraft = null, lastSummary = "No problems", summaryTimer = null, syntaxTimer = null, recheckTimer = null;
   // The exact text of the documents `replaceDocument` replaced and opened, per format, so Undo and Redo show it again byte for byte
   // (a YAML comment, the author's JSON spelling). Keyed by format and document; the oldest entries go first.
@@ -170,10 +192,18 @@ export function createSourcePane(container, options = {}) {
   const formatAction = actionButton("Format (fix indentation)", "Braces", "format");
   formatAction.title = "Format (fix indentation), Shift+Alt+F";
   formatAction.setAttribute("aria-keyshortcuts", "Shift+Alt+F");
+  // The old Format (a rewrite through OPF's own writer) is its own command: it drops the comments of YAML and Markdown, so it asks first.
+  const canonicalAction = actionButton("Canonicalize with OPF", "Sparkles", "canonicalize");
+  canonicalAction.title = "Canonicalize with OPF: rewrite the text the way OPF writes it (drops comments)";
   const copyAction = actionButton("Copy source", "Copy", "copy");
   const downloadAction = actionButton("Download source", "Download", "download");
   bar.append(file, actions);
 
+  const confirm = el("div", "opf-source-confirm", { role: "alertdialog", "aria-labelledby": `${id}-confirm-text`, hidden: "" });
+  const confirmText = el("p", "opf-source-confirm-text", { id: `${id}-confirm-text` });
+  const confirmAccept = Object.assign(el("button", "opf-source-confirm-accept", { type: "button" }), { textContent: "Canonicalize anyway" });
+  const confirmCancel = Object.assign(el("button", "opf-source-confirm-cancel", { type: "button" }), { textContent: "Cancel" });
+  confirm.append(confirmText, confirmAccept, confirmCancel);
   const code = el("div", "opf-source-code");
   const status = el("div", "opf-source-status", { role: "status", "aria-live": "polite" });
 
@@ -185,7 +215,7 @@ export function createSourcePane(container, options = {}) {
   const list = el("ul", "opf-source-findings-list", { id: `${id}-findings` });
   findingsRegion.append(toggle, list);
 
-  root.append(bar, code, findingsRegion, status);
+  root.append(bar, confirm, code, findingsRegion, status);
   container.append(root);
 
   // ---- Document <-> text --------------------------------------------------------------------------------------------
@@ -233,6 +263,7 @@ export function createSourcePane(container, options = {}) {
     language: formatOf(format).language,
     readOnly,
     completions: options.completions !== false,
+    smartListEnter: options.smartListEnter,
     catalogs: options.catalogs ?? editor.catalogs,
     describedBy: `${id}-findings`,
     onChange: () => schedule(),
@@ -246,6 +277,7 @@ export function createSourcePane(container, options = {}) {
 
   // ---- Applying edits -----------------------------------------------------------------------------------------------
   function schedule() {
+    closeConfirm(false);
     clearTimeout(timer);
     clearTimeout(syntaxTimer);
     if (delay === 0) { flush(); return; }
@@ -287,7 +319,7 @@ export function createSourcePane(container, options = {}) {
       renderFindings();
       return;
     }
-    syntaxFindings = [];
+    syntaxFindings = read.notes ?? [];
     baseline = source;
     lastDraft = read.deck;
     const before = deck();
@@ -325,6 +357,7 @@ export function createSourcePane(container, options = {}) {
 
   /** Show `value` as the text of the current format, as an external change. */
   function show(value) {
+    closeConfirm(false);
     baseline = value;
     shownInvalid = false;
     control.update(value, false, null, `${id}-findings`);
@@ -632,6 +665,7 @@ export function createSourcePane(container, options = {}) {
     nameButton.setAttribute("aria-label", `Rename ${name}`);
     formatLabel.textContent = `.opf.${current.extension}`;
     root.dataset.format = current.id;
+    canonicalAction.hidden = current.id === "json";
     for (const item of menuItems) item.setAttribute("aria-checked", String(item.dataset.format === current.id));
   }
 
@@ -670,6 +704,61 @@ export function createSourcePane(container, options = {}) {
     return true;
   }
   formatAction.addEventListener("click", () => { formatDocument(); });
+
+  // Canonicalize with OPF: the text rewritten through core's writer (the old Format). Unlike Format it drops comments, so it asks first and says how many.
+  function droppedComments(text) {
+    if (format === "yaml") return scanYamlComments(text).count;
+    if (format !== "md") return 0;
+    const scan = scanMarkdown(text);
+    let count = scan.comments.filter((comment) => comment.kind === "comment").length;
+    if (scan.frontMatter) count += scanYamlComments(text.slice(scan.frontMatter.yamlFrom, scan.frontMatter.yamlTo)).count;
+    for (const fence of scan.fences) if (fence.kind === "opf-slide" || fence.kind === "opf-block") count += scanYamlComments(text.slice(fence.bodyFrom, fence.bodyTo)).count;
+    return count;
+  }
+  let pendingCanonical = null;
+  function closeConfirm(returnFocus) {
+    if (confirm.hidden) return;
+    confirm.hidden = true;
+    pendingCanonical = null;
+    if (returnFocus) control.api.focus();
+  }
+  /** Rewrite the text through OPF's own writer. Asks first when that drops comments (`confirmed: true` has asked already). Returns "applied", "unchanged", "confirm" (waiting for the answer) or "refused". */
+  function canonicalize({ confirmed = false } = {}) {
+    flush();
+    if (readOnly || format === "json" || destroyed) return "refused";
+    if (dirty) { announce("Fix the errors first: the text cannot be read as a document."); control.api.say("Fix the errors first: the text cannot be read as a document."); return "refused"; }
+    let written;
+    try { written = write(format, deck()); } catch (error) { announce(`Cannot canonicalize: ${errorText(error)}`); return "refused"; }
+    const before = control.api.getValue();
+    if (written.text === before) { announce("Already canonical"); control.api.say("Already canonical"); return "unchanged"; }
+    const count = droppedComments(before);
+    if (count > 0 && !confirmed) {
+      pendingCanonical = written.text;
+      confirmText.textContent = `Canonicalizing rewrites the text the way OPF writes it, and drops ${plural(count, "comment")}. Undo brings ${count === 1 ? "it" : "them"} back.`;
+      confirm.hidden = false;
+      confirmAccept.focus();
+      control.api.say(confirmText.textContent);
+      return "confirm";
+    }
+    closeConfirm(false);
+    control.api.replaceDiff(written.text);
+    flush();
+    control.api.focus();
+    announce("Canonicalized");
+    control.api.say(count > 0 ? `Canonicalized. ${plural(count, "comment")} dropped.` : "Canonicalized");
+    return "applied";
+  }
+  canonicalAction.addEventListener("click", () => { canonicalize(); });
+  confirmAccept.addEventListener("click", () => { closeConfirm(false); canonicalize({ confirmed: true }); });
+  confirmCancel.addEventListener("click", () => closeConfirm(true));
+  confirm.addEventListener("keydown", (event) => {
+    if (event.key === "Escape") { event.preventDefault(); event.stopPropagation(); closeConfirm(true); }
+    else if (event.key === "Tab") {
+      const order = [confirmAccept, confirmCancel], at = order.indexOf(document.activeElement);
+      event.preventDefault();
+      order[(at + (event.shiftKey ? order.length - 1 : 1)) % order.length].focus();
+    }
+  });
   copyAction.addEventListener("click", async () => {
     const info = currentFile();
     try {
@@ -738,13 +827,13 @@ export function createSourcePane(container, options = {}) {
   function problemContext() {
     const draft = lastDraft ?? deck();
     return {
+      document: draft,
+      format,
       unit: control.api.indentUnit(),
       valueAt: (segments) => segments.reduce((value, key) => (value !== null && typeof value === "object" ? value[key] : undefined), draft),
-      schemaAt: (segments) => attempt(() => schemaAtPath(draft, segments), undefined),
       keysOf: (segments) => attempt(() => [...new Set(schemaVariants(schemaAtPath(draft, segments)).flatMap((variant) => Object.keys(variant.properties ?? {})))], []),
-      catalogKind: (segments) => catalogKindAt(segments),
       catalogCount: (kind) => attempt(() => listCatalogRecords(draft, kind, { catalogs: catalogs() }).length, 0),
-      starter: (segments, property) => attempt(() => (property === "slides" ? [{ title: "Slide title" }] : createSchemaValue(schemaAtPath(draft, [...segments, property]))), undefined),
+      starter: (segments, property) => attempt(() => starterValue(draft, segments, property), undefined),
     };
   }
   /** Select the field a core "focus" fix names: its path, else the field inside it, else the nearest place there is one. */
@@ -752,11 +841,9 @@ export function createSourcePane(container, options = {}) {
     flush();
     const text = control.api.getValue();
     const segments = String(focus.path ?? "").replace(/^\//, "").split("/").filter(Boolean).map((part) => part.replaceAll("~1", "/").replaceAll("~0", "~"));
-    if (format === "json") {
-      const wanted = focus.field ? locateJson(text, [...segments, focus.field], "value") : null;
-      const where = wanted?.exact ? wanted : locateJson(text, segments, "value");
-      if (where) { control.api.setSelection(where.from, where.to); control.api.focus(); return; }
-    }
+    const wanted = focus.field ? locateText(format, text, [...segments, focus.field], "value") : null;
+    const where = wanted?.exact ? wanted : locateText(format, text, segments, "value");
+    if (where) { control.api.setSelection(where.from, where.to); control.api.focus(); return; }
     focusPath(focus.path ?? "");
   }
   const fixActions = {
@@ -836,13 +923,32 @@ export function createSourcePane(container, options = {}) {
         options.onFindingSelect?.(finding, target);
       });
       item.append(button);
-      if (row.fixes.length) {
+      const details = detailsFor(finding);
+      if (row.fixes.length || details) {
         const fixes = el("span", "opf-source-finding-fixes");
         for (const fix of row.fixes.slice(0, 3)) {
           const fixButton = Object.assign(el("button", "opf-source-finding-fix", { type: "button", "aria-label": `${fix.title}: ${row.message}` }), { textContent: fix.title });
           fixButton.addEventListener("click", () => applyFix(fix, row));
           fixes.append(fixButton);
         }
+        if (details) {
+          // The rule's own explanation, behind a disclosure that stays open across the panel's redraws.
+          const key = `${row.rule}|${row.path}|${row.message}`;
+          const body = el("div", "opf-source-finding-explain", { id: `${id}-explain-${detailsKeys.id(key)}`, role: "region", "aria-label": `About ${row.rule}` });
+          const toggleDetails = Object.assign(el("button", "opf-source-finding-details", { type: "button", "aria-expanded": String(detailsOpen.has(key)), "aria-controls": body.id }), { textContent: "Details" });
+          body.hidden = !detailsOpen.has(key);
+          fillDetails(body, details);
+          toggleDetails.addEventListener("click", () => {
+            const open = body.hidden;
+            body.hidden = !open;
+            toggleDetails.setAttribute("aria-expanded", String(open));
+            if (open) detailsOpen.add(key); else detailsOpen.delete(key);
+            if (open) control.api.say(`${details.summary} ${details.fix}`);
+          });
+          fixes.append(toggleDetails);
+          item.append(fixes, body);
+          return item;
+        }
         item.append(fixes);
       }
       return item;
@@ -913,6 +1019,7 @@ export function createSourcePane(container, options = {}) {
   root.toggleAttribute("data-readonly", readOnly);
   nameButton.disabled = readOnly;
   formatAction.disabled = readOnly;
+  canonicalAction.disabled = readOnly;
   renderFindings();
   syncAttributes();
 
@@ -936,6 +1043,8 @@ export function createSourcePane(container, options = {}) {
     getFormat: () => format,
     /** Move the cursor to the line of a JSON Pointer in the current format (best effort for YAML and Markdown). Returns the line. */
     focusPath: (path) => focusPath(path),
+    /** Canonicalize with OPF (rewrite through core's writer; asks before dropping comments). See `canonicalize` in the pane. */
+    canonicalize,
     /** The source text exactly as shown, with any edit still waiting applied first. */
     getText() { flush(); return control.api.getValue(); },
     getName: () => name,
@@ -946,6 +1055,7 @@ export function createSourcePane(container, options = {}) {
       root.toggleAttribute("data-readonly", readOnly);
       nameButton.disabled = readOnly;
       formatAction.disabled = readOnly;
+      canonicalAction.disabled = readOnly;
       control.setReadOnly(readOnly);
     },
     /** The problems drawn in the text now, in position order: `{ from, to, severity, message, next, rule, fixes }` at source offsets. */

package/dist/source-problems.js

@@ -2,7 +2,8 @@
 // column) and the quick fixes that go with it. The pane lists them in the panel and draws them in the text with the same objects.
 import { describeFinding, segmentsOf } from "./source-messages.js";
 import { fixesForFinding } from "./source-fixes.js";
-import { lineColumn, locateJson, partOf } from "./source-ranges.js";
+import { textFixesForFinding } from "./source-fixes-text.js";
+import { lineColumn, locateText, partOf } from "./source-ranges.js";
 
 const SEVERITY_ORDER = { error: 0, warning: 1, info: 2 };
 
@@ -30,8 +31,9 @@ export function buildProblems({ format, text, findings, context = {}, actions =
     const { message, next } = describeFinding(finding, context);
     let range = null;
     if (finding.range) range = { from: finding.range.from, to: finding.range.to };
-    else if (format === "json" && finding.kind !== "syntax" && finding.path !== undefined && finding.ruleId?.startsWith("opf/")) {
-      const located = locateJson(text, segmentsOf(finding.path), partOf(finding));
+    else if (finding.kind !== "syntax" && finding.path !== undefined && finding.ruleId?.startsWith("opf/")) {
+      // The finding names a field of the document: core finds it in the text of any format.
+      const located = locateText(format, text, segmentsOf(finding.path), partOf(finding));
       if (located) range = { from: located.from, to: located.to };
     }
     if (!range && Number.isInteger(finding.location?.offset)) range = { from: finding.location.offset, to: finding.location.offset + Math.max(0, finding.location.length ?? 0) };
@@ -40,8 +42,11 @@ export function buildProblems({ format, text, findings, context = {}, actions =
       if (fix.action === "switch-format") fixes.push({ id: fix.id, title: fix.title, safe: fix.safe === true, run: () => actions.switchFormat?.(fix.format) });
       else fixes.push({ ...fix, edits: toEdits(fix.edits) });
     }
-    if (format === "json" && finding.kind !== "syntax") fixes.push(...fixesForFinding(finding, text, context));
+    if (finding.kind !== "syntax") fixes.push(...(format === "json" ? fixesForFinding(finding, text, context) : textFixesForFinding(format, finding, text, context)));
     for (const fix of finding.fixes ?? []) { const row = coreFix(fix, actions); if (row) fixes.push(row); }
+    // A repair core ships as a patch and the editor also writes as a text edit is offered once, as the text edit (it keeps comments and layout).
+    const titles = new Set();
+    for (let at = 0; at < fixes.length; at++) { if (titles.has(fixes[at].title)) fixes.splice(at--, 1); else titles.add(fixes[at].title); }
     const row = { finding, index, severity: finding.severity, message, next, rule: finding.ruleId, path: finding.path ?? "", fixes };
     if (range) {
       row.from = range.from;