@openpresentation/opf-editor 0.26.4 → 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.js

@@ -7,10 +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 { 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 } from "@openpresentation/opf/source";
+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
@@ -75,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") {
@@ -86,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) };
 }
 
 /**
@@ -126,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.
@@ -299,7 +319,7 @@ export function createSourcePane(container, options = {}) {
       renderFindings();
       return;
     }
-    syntaxFindings = [];
+    syntaxFindings = read.notes ?? [];
     baseline = source;
     lastDraft = read.deck;
     const before = deck();
@@ -807,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. */
@@ -903,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;

package/dist/source-problems.js

@@ -44,6 +44,9 @@ export function buildProblems({ format, text, findings, context = {}, actions =
     }
     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;

package/dist/source-references.js

@@ -0,0 +1,227 @@
+// Cross-references inside the document as completion values (artifacts/source-editor/SPEC.md, section 3.4): `asset:<id>` from `assets`, dataset ids
+// and column names from `datasets`, `var:<id>` and `{{name}}` from `variables`, `cite` ids from `references`, `beat` ids from the deck's narrative and
+// `region` names from the slide's layout. Which field takes which kind of reference is ONE table (`REFERENCE_RULES`) read against the schema: a rule
+// names the schema definitions whose fields are references (`Asset`, `DatasetId`, ...) and the property names, with a phrase the property's own
+// description must carry (any of `phrases`), for the fields written inline in their parent. test/source-completions-units.mjs checks every entry against the schema,
+// so a renamed definition or a reworded description fails the test instead of silently dropping a list. Plain functions, no DOM.
+import { parse as parseYaml } from "yaml";
+import { describeField } from "@openpresentation/opf/schema";
+
+/**
+ * The rules. `definitions`: a field whose own schema is that definition (`$defs` name). `keys` + `phrases`: a string field with one of those property
+ * names whose description contains one of the phrases. `item`: the field is a list (or a string or a list) and every entry is a reference.
+ */
+export const REFERENCE_RULES = Object.freeze([
+  { kind: "asset", definitions: ["Asset", "LogoSource", "ImageSource"], keys: ["src", "logo", "watermark"], phrases: ["asset:<id>", "or Asset"] },
+  { kind: "dataset", definitions: ["DatasetId"], keys: [], phrases: [] },
+  { kind: "datasetColumn", definitions: ["DatasetFields"], keys: ["category", "x", "series", "line", "secondaryAxis"], phrases: ["column"], item: true },
+  { kind: "cite", definitions: [], keys: ["cite"], phrases: ["references"], item: true },
+  { kind: "beat", definitions: [], keys: ["beat"], phrases: ["narrative"], item: true },
+  { kind: "region", definitions: [], keys: ["region"], phrases: ["template layout"] },
+  { kind: "color", definitions: ["ColorRef"], keys: ["color"], phrases: ["var:<id>"] },
+]);
+
+/** The promoted regions of a slide a block can be pinned to (the lower-case names the `region` pattern accepts). */
+export const PROMOTED_REGIONS = Object.freeze(["top", "middle", "bottom", "left", "center", "right"]);
+
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const isIndex = (segment) => typeof segment === "number" || /^(?:0|[1-9]\d*)$/.test(String(segment));
+
+function ruleOf(info, key) {
+  if (!info?.known || !(info.types.includes("string") || info.types.includes("array"))) return null;
+  for (const rule of REFERENCE_RULES) {
+    if (info.definition && rule.definitions.includes(info.definition)) return rule;
+    if (key !== undefined && rule.keys.includes(key) && rule.phrases.some((phrase) => (info.fullDescription ?? info.description ?? "").includes(phrase))) return rule;
+  }
+  return null;
+}
+
+/**
+ * What the value at `path` of `document` references: `{ kind, path }` (`path` is the field, for a list entry the list's), or null. A list entry
+ * (`cite: ["a", |]`, `fields: [|]`) is the entry of the list field the rule names; a field that can only be a list takes its references one by one.
+ */
+export function referenceSiteAt(path, document) {
+  if (!Array.isArray(path) || !path.length) return null;
+  const last = path.at(-1);
+  const describe = (at) => { try { return describeField(at, document); } catch { return null; } };
+  if (!isIndex(last)) {
+    const info = describe(path);
+    const rule = ruleOf(info, String(last));
+    const listOnly = info?.types.length === 1 && info.types[0] === "array";
+    return rule && !listOnly ? { kind: rule.kind, path } : null;
+  }
+  // An entry whose own schema is a reference definition (`chart.colors[i]`: a ColorRef) is a reference whatever the list is called.
+  const own = describe(path);
+  const byDefinition = own?.known && own.definition ? REFERENCE_RULES.find((rule) => rule.definitions.includes(own.definition)) : undefined;
+  if (byDefinition && !own.types.every((type) => type === "array")) return { kind: byDefinition.kind, path };
+  const field = path.slice(0, -1);
+  while (field.length && isIndex(field.at(-1))) field.pop();
+  if (!field.length) return null;
+  const rule = ruleOf(describe(field), String(field.at(-1)));
+  return rule?.item ? { kind: rule.kind, path: field } : null;
+}
+
+// ---- the facts of a document -------------------------------------------------------------------------------------------------------
+const stringOf = (value) => (typeof value === "string" ? value : undefined);
+const columnName = (column) => (typeof column === "string" ? column : isObject(column) && typeof column.name === "string" ? column.name : undefined);
+
+/**
+ * The parts of a deck the references read, from the plain value of the top level (`assets`, `datasets`, `variables`, `references`, `narrative`):
+ * `{ assets: [{ id, detail }], datasets: [{ id, title, columns }], variables: [{ id, type }], references: [{ id, text }], narrative }`.
+ * Anything else the value holds, and anything malformed, is ignored: the text being edited is a draft.
+ */
+export function factsOf(deck) {
+  const out = { assets: [], datasets: [], variables: [], references: [], narrative: undefined };
+  if (!isObject(deck)) return out;
+  if (isObject(deck.assets)) {
+    for (const [id, asset] of Object.entries(deck.assets)) out.assets.push({ id, detail: stringOf(asset) ?? stringOf(asset?.src) ?? stringOf(asset?.title) ?? "" });
+  }
+  if (isObject(deck.datasets)) {
+    for (const [id, dataset] of Object.entries(deck.datasets)) {
+      const columns = Array.isArray(dataset?.columns) ? dataset.columns.map(columnName).filter(Boolean) : [];
+      out.datasets.push({ id, title: stringOf(dataset?.title) ?? "", columns });
+    }
+  }
+  if (isObject(deck.variables)) {
+    for (const [id, variable] of Object.entries(deck.variables)) {
+      // A hex string is shorthand for a color variable.
+      const type = typeof variable === "string" ? "color" : stringOf(variable?.type) ?? "color";
+      out.variables.push({ id, type });
+    }
+  }
+  if (Array.isArray(deck.references)) {
+    for (const reference of deck.references) if (isObject(reference) && typeof reference.id === "string" && reference.id) out.references.push({ id: reference.id, text: stringOf(reference.text) ?? "" });
+  }
+  out.narrative = stringOf(deck.narrative);
+  return out;
+}
+
+/** The top-level parts of a JSON draft the references read (`root` is a jsonc-parser tree), as a plain value for `factsOf`. */
+export function jsonDeckParts(root, getNodeValue) {
+  const deck = {};
+  if (root?.type !== "object") return deck;
+  for (const property of root.children ?? []) {
+    const key = property.children?.[0]?.value, value = property.children?.[1];
+    if (!value || !["assets", "datasets", "variables", "references", "narrative"].includes(key)) continue;
+    if (key === "datasets" && value.type === "object") {
+      // Only the names and the columns: the rows can be the bulk of a deck.
+      deck.datasets = {};
+      for (const entry of value.children ?? []) {
+        const id = entry.children?.[0]?.value, body = entry.children?.[1];
+        if (typeof id !== "string" || body?.type !== "object") continue;
+        const columns = (body.children ?? []).find((child) => child.children?.[0]?.value === "columns")?.children?.[1];
+        const title = (body.children ?? []).find((child) => child.children?.[0]?.value === "title")?.children?.[1];
+        deck.datasets[id] = { columns: columns ? getNodeValue(columns) : [], title: title?.type === "string" ? title.value : undefined };
+      }
+    } else deck[key] = getNodeValue(value);
+  }
+  return deck;
+}
+
+const TOP_LEVEL = ["assets", "datasets", "variables", "references", "narrative"];
+
+/** The text of the top-level blocks of a YAML text that hold the keys the references read, parsed (tolerant: a broken block gives nothing). */
+export function yamlDeckParts(text) {
+  const lines = text.split(/\r\n|\r|\n/);
+  const deck = {};
+  for (let number = 0; number < lines.length; number++) {
+    const match = /^([A-Za-z]+)\s*:/.exec(lines[number]);
+    if (!match || !TOP_LEVEL.includes(match[1])) continue;
+    let end = number + 1;
+    while (end < lines.length && (lines[end].trim() === "" || /^[ \t]/.test(lines[end]) || lines[end].startsWith("- "))) end++;
+    try {
+      const value = parseYaml(lines.slice(number, end).join("\n"), { strict: false, uniqueKeys: false });
+      if (isObject(value) && match[1] in value) deck[match[1]] = value[match[1]];
+    } catch { /* A block that does not parse offers nothing. */ }
+  }
+  return deck;
+}
+
+/** `value` at `path` of a plain document, or undefined. */
+export function valueAt(value, path) {
+  let current = value;
+  for (const step of path) {
+    if (current === null || typeof current !== "object") return undefined;
+    current = current[step];
+  }
+  return current;
+}
+
+/**
+ * What a column field reads its names from: `{ dataset }` (the id of the dataset: a `dataset` beside the field, or the chart's `data.dataset`) or
+ * `{ inline }` (the `columns` of the chart's own `data`), looking outward from the field; null when the draft says neither. `read(path)` gives a
+ * value of the document.
+ */
+export function columnSourceFor(site, read) {
+  for (let depth = site.path.length - 1; depth >= 0; depth--) {
+    const owner = site.path.slice(0, depth);
+    const direct = read([...owner, "dataset"]);
+    if (typeof direct === "string") return { dataset: direct };
+    const via = read([...owner, "data", "dataset"]);
+    if (typeof via === "string") return { dataset: via };
+    const inline = read([...owner, "data", "columns"]);
+    if (Array.isArray(inline)) return { inline: inline.map(columnName).filter(Boolean) };
+  }
+  return null;
+}
+
+/** The names of the regions of a layout record a block can be pinned to (the title and the subtitle are not regions of the body). */
+export function regionNames(record) {
+  const names = [];
+  const walk = (regions) => {
+    for (const region of Array.isArray(regions) ? regions : []) {
+      if (typeof region?.name === "string" && region.name !== "title" && region.name !== "subtitle") names.push(region.name);
+      if (region?.regions) walk(region.regions);
+    }
+  };
+  walk(record?.regions);
+  return names;
+}
+
+/** The regions of a layout record in reading order (nested ones included) as `{ name, accepts }`. */
+export function flatRegions(record) {
+  const out = [];
+  const walk = (regions) => {
+    for (const region of Array.isArray(regions) ? regions : []) {
+      if (typeof region?.name === "string") out.push({ name: region.name, accepts: Array.isArray(region.accepts) ? region.accepts : [] });
+      if (region?.regions) walk(region.regions);
+    }
+  };
+  walk(record?.regions);
+  return out;
+}
+
+// The slide key that holds content of a kind a region accepts.
+const PAYLOAD_KEYS = { text: "text", list: "items", image: "image", video: "video", chart: "chart", table: "table", quote: "quote", code: "code", metric: "metric", timeline: "timeline" };
+
+/**
+ * The slide keys a layout's regions call for, in region order: a region named like a slide key (`title`, `items`) calls for that key; any other region
+ * that accepts one or two kinds of content (`media`: image, video) for the keys of those kinds. `keys` are the slide keys that exist.
+ */
+export function layoutKeys(record, keys) {
+  const wanted = [];
+  const add = (key) => { if (keys.includes(key) && !wanted.includes(key)) wanted.push(key); };
+  for (const region of flatRegions(record)) {
+    if (keys.includes(region.name)) add(region.name);
+    else if (region.accepts.length > 0 && region.accepts.length <= 2) for (const kind of region.accepts) add(PAYLOAD_KEYS[kind]);
+  }
+  return wanted;
+}
+
+/** The ids of the beats of a narrative record. */
+export function beatsOf(record) {
+  return (Array.isArray(record?.beats) ? record.beats : []).filter((beat) => isObject(beat) && typeof beat.id === "string").map((beat) => ({ id: beat.id, name: stringOf(beat.name) ?? "", description: stringOf(beat.description) ?? "" }));
+}
+
+/**
+ * The names of the variables a `{{` in text can reference: the document's own, with their type. (The built-in `organization.*`, `speaker.*` and
+ * `deck.*` variables are not offered: they are not declared in the document.)
+ */
+export function variableNames(facts) {
+  return facts.variables.map((variable) => ({ id: variable.id, type: variable.type }));
+}
+
+/** The slide a path of a deck sits in: `["slides", n]`, or null. */
+export function slidePath(path) {
+  return path[0] === "slides" && isIndex(path[1]) ? [path[0], Number(path[1])] : null;
+}