@openpresentation/opf-editor 0.26.0 → 0.26.2

package/dist/source-pane.js

@@ -1,10 +1,16 @@
-import { parse as parseJsonc, printParseErrorCode } from "jsonc-parser";
 import { fromYaml, scanYamlComments, toYaml } from "@openpresentation/opf/yaml";
 import { fromMarkdown, toMarkdown } from "@openpresentation/opf/markdown";
 import { mountJsonCodeEditor } from "./json-editor.js";
-import { MAX_EXACT_SOURCE_LENGTH, createSourceMemory, findDuplicateKey, updateJsonSource } from "./exact-source.js";
-import { lineForPath, lineOfOffset, offsetOfLine } from "./source-lines.js";
+import { MAX_EXACT_SOURCE_LENGTH, createSourceMemory, updateJsonSource } from "./exact-source.js";
+import { lineForPath, offsetOfLine } from "./source-lines.js";
 import { errorText, normalizeFinding, rejectionFindings as findingsOfError } from "./source-findings.js";
+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 { 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
 // and Download, and the findings under the code. JSON is canonical and keeps its authored bytes (exact-source); YAML and
@@ -67,27 +73,15 @@ function same(a, b) {
 const SEVERITY = { error: 0, warning: 1, info: 2 };
 const plural = (count, word) => `${count} ${word}${count === 1 ? "" : "s"}`;
 
-const JSON_ERRORS = { InvalidSymbol: "Invalid symbol", InvalidNumberFormat: "Invalid number", PropertyNameExpected: "Property name expected", ValueExpected: "Value expected", ColonExpected: "Colon expected", CommaExpected: "Comma expected", CloseBraceExpected: "Closing brace expected", CloseBracketExpected: "Closing bracket expected", EndOfFileExpected: "End of file expected", InvalidCommentToken: "Comments are not allowed in JSON", UnexpectedEndOfComment: "Unexpected end of comment", UnexpectedEndOfString: "Unexpected end of string", UnexpectedEndOfNumber: "Unexpected end of number", InvalidUnicode: "Invalid unicode escape", InvalidEscapeCharacter: "Invalid escape character", InvalidCharacter: "Invalid character" };
-
 /** 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") {
-    try {
-      const deck = JSON.parse(text);
-      if (!isObject(deck)) return { syntax: true, findings: [normalizeFinding({ message: "An OPF document is a JSON object.", line: 1 }, "syntax")] };
-      const duplicate = findDuplicateKey(text);
-      if (duplicate) {
-        const path = pointer([...duplicate.path, duplicate.key]);
-        return { syntax: true, findings: [normalizeFinding({ path, message: `Duplicate key "${duplicate.key}". Remove the repeated key.` }, "syntax")] };
-      }
-      return { deck, findings: [] };
-    } catch (error) {
-      const errors = [];
-      parseJsonc(text, errors, { allowTrailingComma: false, disallowComments: true });
-      const first = errors[0];
-      const message = first ? `${JSON_ERRORS[printParseErrorCode(first.error)] ?? printParseErrorCode(first.error)}.` : `${error.message}.`;
-      return { syntax: true, findings: [normalizeFinding({ message, line: first ? lineOfOffset(text, first.offset) : 1 }, "syntax")] };
-    }
+    const problems = analyzeSyntax(text);
+    if (problems.length) return { syntax: true, findings: problems.map((problem) => normalizeFinding(problem, "syntax")) };
+    const deck = JSON.parse(text);
+    const duplicates = findDuplicateKeys(text);
+    if (duplicates.length) return { syntax: true, findings: duplicates };
+    return { deck, findings: [] };
   }
   const result = format === "yaml" ? (fromYaml(text, { catalogs })) : fromMarkdown(text, { catalogs });
   const syntax = result.findings.filter((finding) => !finding.ruleId?.startsWith("opf/"));
@@ -127,6 +121,10 @@ export function createSourcePane(container, options = {}) {
   // Whether the findings include an error, and what the editor's `aria-invalid` currently says (null: not yet set).
   let invalid = false, shownInvalid = null;
   const lineCache = { key: "", values: new Map() };
+  // 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();
+  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.
   const exactTexts = new Map();
@@ -170,6 +168,8 @@ export function createSourcePane(container, options = {}) {
     return button;
   };
   const formatAction = actionButton("Format (fix indentation)", "Braces", "format");
+  formatAction.title = "Format (fix indentation), Shift+Alt+F";
+  formatAction.setAttribute("aria-keyshortcuts", "Shift+Alt+F");
   const copyAction = actionButton("Copy source", "Copy", "copy");
   const downloadAction = actionButton("Download source", "Download", "download");
   bar.append(file, actions);
@@ -236,6 +236,10 @@ export function createSourcePane(container, options = {}) {
     catalogs: options.catalogs ?? editor.catalogs,
     describedBy: `${id}-findings`,
     onChange: () => schedule(),
+    onFormat: () => formatDocument(),
+    onFocusProblems: () => focusProblems(),
+    // The pane supplies the problems itself (every finding, with ranges and fixes).
+    syntaxProblems: false,
     historyFallback: { undo: () => stepReplace("undo"), redo: () => stepReplace("redo") },
     onError: (error) => options.onError?.(error),
   });
@@ -243,8 +247,25 @@ export function createSourcePane(container, options = {}) {
   // ---- Applying edits -----------------------------------------------------------------------------------------------
   function schedule() {
     clearTimeout(timer);
+    clearTimeout(syntaxTimer);
     if (delay === 0) { flush(); return; }
     timer = setTimeout(flush, delay);
+    // Syntax problems come first, 150 ms after the last key: the rest of the checking waits for the apply delay.
+    if (delay > 150) syntaxTimer = setTimeout(checkSyntax, 150);
+  }
+  /** Show or clear the syntax problems of the text now, without applying it to the document. */
+  function checkSyntax() {
+    syntaxTimer = null;
+    if (destroyed || format !== "json") return;
+    const problems = analyzeSyntax(control.api.getValue());
+    if (!problems.length) {
+      if (!syntaxFindings.length) return;
+      syntaxFindings = [];
+      renderFindings();
+      return;
+    }
+    syntaxFindings = problems.map((problem) => normalizeFinding(problem, "syntax"));
+    renderFindings();
   }
   /** Apply any edit still waiting for its delay. */
   function flush() {
@@ -268,6 +289,7 @@ export function createSourcePane(container, options = {}) {
     }
     syntaxFindings = [];
     baseline = source;
+    lastDraft = read.deck;
     const before = deck();
     if (!same(read.deck, before)) {
       applying = true;
@@ -315,6 +337,7 @@ export function createSourcePane(container, options = {}) {
     rejectionFindings = [];
     transientNotes = [];
     dirty = false;
+    lastDraft = null;
     let written;
     try { written = write(format, deck()); }
     catch (error) {
@@ -500,6 +523,28 @@ export function createSourcePane(container, options = {}) {
     return true;
   }
 
+  /** Read the text as `next` (it is that format already: a YAML deck pasted into the JSON pane) without rewriting it. */
+  function switchFormatKeepingText(next) {
+    const target = formatOf(next);
+    if (destroyed || target.id === format) return;
+    flush();
+    const previous = format;
+    format = target.id;
+    transientNotes = [];
+    rejectionFindings = [];
+    syntaxFindings = [];
+    noteFindings = [];
+    control.setLanguage(target.language);
+    updateBar();
+    baseline = null;
+    flush();
+    renderedKey = "";
+    renderFindings();
+    syncAttributes();
+    control.api.focus();
+    options.onFormatChange?.(format, previous);
+  }
+
   // ---- Menu ---------------------------------------------------------------------------------------------------------
   const menuOpen = () => !menu.hidden;
   function openMenu(focus = "checked") {
@@ -601,30 +646,30 @@ export function createSourcePane(container, options = {}) {
     const current = formatOf(format);
     return { name, filename: `${name}.opf.${current.extension}`, text: control.api.getValue(), format: current.id, mime: current.mime };
   }
-  formatAction.addEventListener("click", () => {
+  // Format document: the button and the keys (Shift+Alt+F, Cmd/Ctrl+Shift+F) do the same in every format. Whitespace only: JSON is laid out
+  // token by token (also while it does not parse), YAML keeps its comments, and a rewrite that would change the document is refused.
+  function formatDocument() {
     flush();
-    if (readOnly) return;
-    if (format === "json") { control.api.format(); control.api.focus(); return; }
-    const read = readText(format, control.api.getValue(), catalogs());
-    if (!read.deck) { renderFindings(); return; }
-    let written;
-    try { written = write(format, read.deck); }
-    catch (error) {
-      rejectionFindings = [normalizeFinding({ message: `Cannot rewrite the ${formatOf(format).label}: ${errorText(error)}`, kind: "rejected" })];
-      renderFindings();
-      return;
-    }
+    if (readOnly) return false;
     const before = control.api.getValue();
-    if (written.text !== before) {
-      const comments = format === "yaml" ? scanYamlComments(before).count : 0;
-      control.api.replace(0, before.length, written.text);
-      flush();
-      transientNotes = comments > 0 ? [normalizeFinding({ message: `${plural(comments, "comment")} in the YAML ${comments === 1 ? "was" : "were"} dropped when the text was rewritten.`, severity: "warning" }, "format")] : [];
-      renderedKey = "";
-      renderFindings();
-    }
+    const result = formatSource(format, before, { unit: control.api.indentUnit() });
     control.api.focus();
-  });
+    if (result.error) { announce(result.error); return false; }
+    if (result.text === before) { announce("Already formatted"); return true; }
+    if (format !== "json") {
+      let unchanged = true;
+      try {
+        const was = readText(format, before, catalogs()).deck;
+        unchanged = !was || same(was, readText(format, result.text, catalogs()).deck);
+      } catch { unchanged = false; }
+      if (!unchanged) { announce("Formatting would change the document, so the text was left as it is."); return false; }
+    }
+    control.api.replaceDiff(result.text);
+    flush();
+    announce("Formatted");
+    return true;
+  }
+  formatAction.addEventListener("click", () => { formatDocument(); });
   copyAction.addEventListener("click", async () => {
     const info = currentFile();
     try {
@@ -670,14 +715,14 @@ export function createSourcePane(container, options = {}) {
     for (const group of [syntaxFindings, rejectionFindings, transientNotes, noteFindings, host]) {
       const keys = [];
       for (const finding of group) {
-        const key = `${finding.severity}|${finding.path}|${finding.message}`;
+        const key = `${finding.severity}|${finding.path}|${finding.message}|${finding.range?.from ?? ""}`;
         if (seen.has(key)) continue;
         keys.push(key);
         all.push(finding);
       }
       for (const key of keys) seen.add(key);
     }
-    return all.map((finding, index) => ({ finding, index })).sort((a, b) => SEVERITY[a.finding.severity] - SEVERITY[b.finding.severity] || a.index - b.index).map((entry) => entry.finding);
+    return all;
   }
   function lineOf(finding) {
     const value = control.api.getValue();
@@ -688,23 +733,75 @@ export function createSourcePane(container, options = {}) {
     if (!lineCache.values.has(cacheKey)) lineCache.values.set(cacheKey, finding.path === "" ? null : lineForPath(format, value, finding.path));
     return lineCache.values.get(cacheKey) ?? explicit ?? null;
   }
+  // What the messages and the quick fixes read: the document being checked (the typed draft, else the session's) and its schema.
+  const attempt = (run, fallback) => { try { return run(); } catch { return fallback; } };
+  function problemContext() {
+    const draft = lastDraft ?? deck();
+    return {
+      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),
+    };
+  }
+  /** Select the field a core "focus" fix names: its path, else the field inside it, else the nearest place there is one. */
+  function focusField(focus) {
+    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; }
+    }
+    focusPath(focus.path ?? "");
+  }
+  const fixActions = {
+    applyPatch(patch) {
+      flush();
+      try { editor.applyPatch(patch, { source: "source-pane", format }); } catch (error) { rejectionFindings = findingsOfError(error); renderedKey = ""; renderFindings(); }
+      control.api.focus();
+    },
+    focusField,
+    switchFormat(next) { switchFormatKeepingText(next); },
+  };
+  /** Problems the author is in the middle of typing (a key with a list of keys open next to it) are not shown yet. */
+  function withheld(row) {
+    if (row.finding.kind !== "syntax" || row.from === undefined || !control.isCompleting()) return false;
+    const [caret] = control.api.getSelection();
+    return caret >= row.from - 1 && caret <= row.to + 1;
+  }
   function renderFindings() {
     paintFindings();
     if (!destroyed && invalid !== shownInvalid) syncAttributes();
   }
   function paintFindings() {
     if (destroyed) return;
-    const all = collect();
-    const rows = all.map((finding) => ({ finding, line: lineOf(finding) }));
-    invalid = rows.some((row) => row.finding.severity === "error");
-    const key = JSON.stringify([format, collapsed, rows.map(({ finding, line }) => [finding.severity, finding.path, finding.message, finding.kind, line])]);
+    const text = control.api.getValue();
+    let rows = buildProblems({ format, text, findings: collect(), context: problemContext(), actions: fixActions, lineOf });
+    const hidden = rows.filter(withheld);
+    if (hidden.length) {
+      rows = rows.filter((row) => !hidden.includes(row));
+      clearTimeout(recheckTimer);
+      recheckTimer = setTimeout(() => { if (!destroyed) { renderedKey = ""; renderFindings(); } }, 600);
+    }
+    problemRows = rows;
+    invalid = rows.some((row) => row.severity === "error");
+    const key = JSON.stringify([format, collapsed, rows.map((row) => [row.severity, row.path, row.message, row.next, row.finding.kind, row.line, row.column, row.from, row.to, row.fixes.map((fix) => fix.title)])]);
     if (key === renderedKey) return;
     renderedKey = key;
+    // The same problems are drawn in the text, with their tooltips and quick fixes.
+    control.setProblems(rows.filter((row) => row.from !== undefined).flatMap((row) => [row, ...(row.finding.related ?? []).map((range) => ({ ...row, from: range.from, to: range.to }))])
+      .map((row) => ({ from: row.from, to: row.to, severity: row.severity, message: row.message, next: row.next, rule: row.rule, fixes: row.fixes })));
+    announceSummary(rows);
     findingsRegion.hidden = rows.length === 0;
     root.dataset.findings = String(rows.length);
     if (!rows.length) { list.replaceChildren(); return; }
-    const errors = rows.filter((row) => row.finding.severity === "error");
-    const warnings = rows.filter((row) => row.finding.severity === "warning");
+    const errors = rows.filter((row) => row.severity === "error");
+    const warnings = rows.filter((row) => row.severity === "warning");
     const infos = rows.length - errors.length - warnings.length;
     const parts = [];
     if (errors.length) parts.push(plural(errors.length, errors.every((row) => row.finding.kind === "schema" || !row.finding.kind) ? "schema error" : "error"));
@@ -717,25 +814,88 @@ export function createSourcePane(container, options = {}) {
     toggle.setAttribute("aria-expanded", String(!collapsed));
     list.hidden = collapsed;
     const shown = rows.slice(0, 200);
-    list.replaceChildren(...shown.map(({ finding, line }) => {
+    list.replaceChildren(...shown.map((row) => {
+      const { finding } = row;
       const item = el("li", "opf-source-finding-item");
-      const button = el("button", "opf-source-finding", { type: "button", "data-severity": finding.severity });
+      const button = el("button", "opf-source-finding", { type: "button", "data-severity": row.severity });
       if (finding.kind) button.dataset.kind = finding.kind;
-      const path = finding.path ? el("code", "opf-source-finding-path") : null;
-      if (path) path.textContent = finding.path;
-      const message = Object.assign(el("span", "opf-source-finding-message"), { textContent: finding.message });
-      const where = Object.assign(el("span", "opf-source-finding-line"), { textContent: line ? `Ln ${line}` : "" });
-      button.append(...(path ? [path] : []), message, where);
+      const word = row.severity === "error" ? "Error" : row.severity === "warning" ? "Warning" : "Note";
+      const severity = Object.assign(el("span", "opf-source-finding-severity"), { textContent: `${word}: ` });
+      const path = row.path ? el("code", "opf-source-finding-path") : null;
+      if (path) path.textContent = row.path;
+      const message = Object.assign(el("span", "opf-source-finding-message"), { textContent: row.message });
+      const next = row.next ? Object.assign(el("span", "opf-source-finding-next"), { textContent: `Next: ${row.next}` }) : null;
+      const where = Object.assign(el("span", "opf-source-finding-line"), { textContent: row.line ? (row.column ? `Ln ${row.line}, Col ${row.column}` : `Ln ${row.line}`) : "" });
+      const rule = row.rule ? Object.assign(el("span", "opf-source-finding-rule"), { textContent: row.rule }) : null;
+      rowOf.set(button, row);
+      const head = el("span", "opf-source-finding-head");
+      head.append(...(path ? [path] : []), message);
+      button.append(severity, head, ...(next ? [next] : []), where, ...(rule ? [rule] : []));
       button.addEventListener("click", () => {
-        const target = focusPath(finding.path, finding);
+        const target = selectRow(row);
         options.onFindingSelect?.(finding, target);
       });
       item.append(button);
+      if (row.fixes.length) {
+        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);
+        }
+        item.append(fixes);
+      }
       return item;
     }));
     if (rows.length > shown.length) list.append(Object.assign(el("li", "opf-source-finding-more"), { textContent: `${rows.length - shown.length} more not shown.` }));
   }
   toggle.addEventListener("click", () => { collapsed = !collapsed; renderedKey = ""; renderFindings(); });
+  /** "2 problems: 1 error, 1 warning" in the live region once the problems stop changing for a moment. */
+  function announceSummary(rows) {
+    const summary = summarize(rows);
+    clearTimeout(summaryTimer);
+    if (summary === lastSummary) return;
+    summaryTimer = setTimeout(() => { if (!destroyed) { lastSummary = summary; control.api.say(summary); } }, 600);
+  }
+  /** Run a fix of a row: its edits as one undoable change in the text, or its own action. */
+  function applyFix(fix, row) {
+    if (readOnly) return;
+    control.applyFix(fix, row);
+  }
+  /** Put the caret on a row's place in the text, selecting the range when it has one. Returns the line. */
+  function selectRow(row) {
+    flush();
+    const text = control.api.getValue();
+    if (row.from !== undefined) {
+      control.api.setSelection(Math.min(row.from, text.length), Math.min(row.to, text.length));
+      control.api.focus();
+      return row.line ?? 1;
+    }
+    return focusPath(row.path, row.finding);
+  }
+  // The panel with the keyboard: arrows, Home and End move between rows, Escape returns to the code, Cmd/Ctrl+. applies the first fix of the row.
+  list.addEventListener("keydown", (event) => {
+    const rows = [...list.querySelectorAll(".opf-source-finding")];
+    const at = rows.indexOf(document.activeElement);
+    const move = (to) => { event.preventDefault(); rows[Math.max(0, Math.min(rows.length - 1, to))]?.focus(); };
+    if (event.key === "ArrowDown") move(at + 1);
+    else if (event.key === "ArrowUp") move(at - 1);
+    else if (event.key === "Home") move(0);
+    else if (event.key === "End") move(rows.length - 1);
+    else if (event.key === "Escape") { event.preventDefault(); control.api.focus(); }
+    else if (event.key === "." && (event.metaKey || event.ctrlKey) && at >= 0) {
+      const row = rowOf.get(rows[at]);
+      const fix = row?.fixes[0];
+      if (fix) { event.preventDefault(); applyFix(fix, row); } else control.api.say("No quick fixes available");
+    }
+  });
+  /** Move focus to the first problem of the panel (Cmd/Ctrl+Shift+M in the code). */
+  function focusProblems() {
+    if (findingsRegion.hidden) { control.api.say("No problems"); return true; }
+    if (collapsed) { collapsed = false; renderedKey = ""; renderFindings(); }
+    list.querySelector(".opf-source-finding")?.focus();
+    return true;
+  }
 
   // ---- Public API ---------------------------------------------------------------------------------------------------
   function focusPath(path, finding) {
@@ -788,6 +948,23 @@ export function createSourcePane(container, options = {}) {
       formatAction.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. */
+    getProblems: () => control.getProblems(),
+    /** Select the next problem in the text (F8) and say what it is; wraps. */
+    nextProblem: () => control.nextProblem(),
+    /** Select the previous problem in the text (Shift+F8); wraps. */
+    previousProblem: () => control.previousProblem(),
+    /** Select problem number `index` (zero-based, position order) and say what it is. */
+    showProblem(index) {
+      const problems = control.getProblems(), problem = problems[index];
+      if (!problem) return false;
+      control.api.setSelection(problem.from, problem.to);
+      control.api.focus();
+      control.api.say(`${problem.severity === "error" ? "Error" : problem.severity === "warning" ? "Warning" : "Note"}: ${problem.message}`);
+      return true;
+    },
+    /** Open the suggestion list at the caret, as Ctrl+Space does. */
+    triggerCompletion: () => control.triggerCompletion(),
     /** The code editor, for hosts that focus or measure it. */
     editor: control,
     destroy() {
@@ -796,6 +973,9 @@ export function createSourcePane(container, options = {}) {
       destroyed = true;
       clearTimeout(timer);
       clearTimeout(copyTimer);
+      clearTimeout(summaryTimer);
+      clearTimeout(syntaxTimer);
+      clearTimeout(recheckTimer);
       unsubscribe();
       document.removeEventListener("pointerdown", outside, true);
       control.destroy();

package/dist/source-problems.js

@@ -0,0 +1,81 @@
+// The problems of the source pane: every finding with its plain-words message, what could come next, where it is in the text (a range, a line and a
+// 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";
+
+const SEVERITY_ORDER = { error: 0, warning: 1, info: 2 };
+
+/**
+ * A fix core ships (`fixes[]` of a finding) as a pane fix: a `patch` goes through the session, a `focus` selects the field.
+ * `actions`: `{ applyPatch(patch), focusField(focus) }`.
+ */
+function coreFix(fix, actions) {
+  if (!fix || typeof fix !== "object" || typeof fix.id !== "string") return null;
+  const base = { id: fix.id, title: String(fix.title ?? fix.id), safe: fix.safe === true };
+  if (fix.kind === "patch" && Array.isArray(fix.patch)) return { ...base, run: () => actions.applyPatch(fix.patch) };
+  if (fix.kind === "focus" && fix.focus) return { ...base, run: () => actions.focusField(fix.focus) };
+  return null;
+}
+
+/** Edits from a syntax problem (`{ offset, length, insert }` or `{ from, to, insert }`) as `{ from, to, insert }`. */
+const toEdits = (edits = []) => edits.map((edit) => (edit.from !== undefined ? edit : { from: edit.offset, to: edit.offset + edit.length, insert: edit.insert ?? edit.content ?? "" }));
+
+/**
+ * The problems of `findings` in `text`. `context` is what source-messages.js takes plus `{ unit, starter }`; `actions` is what coreFix takes.
+ * Returns rows in position order (errors first at one place), each `{ finding, severity, message, next, rule, path, from?, to?, line?, column?, fixes }`.
+ */
+export function buildProblems({ format, text, findings, context = {}, actions = {}, lineOf }) {
+  const rows = findings.map((finding, index) => {
+    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));
+      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) };
+    const fixes = [];
+    for (const fix of finding.editFixes ?? []) {
+      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));
+    for (const fix of finding.fixes ?? []) { const row = coreFix(fix, actions); if (row) fixes.push(row); }
+    const row = { finding, index, severity: finding.severity, message, next, rule: finding.ruleId, path: finding.path ?? "", fixes };
+    if (range) {
+      row.from = range.from;
+      row.to = Math.max(range.from, range.to);
+      const where = lineColumn(text, range.from);
+      row.line = where.line;
+      row.column = where.column;
+    } else {
+      const line = lineOf?.(finding) ?? finding.line;
+      if (line) {
+        row.line = line;
+        if (finding.column) row.column = finding.column;
+      }
+    }
+    return row;
+  });
+  return mergeRenames(rows).sort((a, b) => (a.line ?? Infinity) - (b.line ?? Infinity) || (a.column ?? 0) - (b.column ?? 0) || SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity] || a.index - b.index);
+}
+
+/** The count line of the panel and the live region: "2 problems: 1 error, 1 warning". */
+export function summarize(rows) {
+  const count = (severity) => rows.filter((row) => row.severity === severity).length;
+  const parts = [[count("error"), "error"], [count("warning"), "warning"], [count("info"), "note"]].filter(([n]) => n > 0).map(([n, word]) => `${n} ${word}${n === 1 ? "" : "s"}`);
+  return rows.length ? `${rows.length} problem${rows.length === 1 ? "" : "s"}: ${parts.join(", ")}` : "No problems";
+}
+
+// An unknown key that is a near miss of a missing required key says it once: the rename fixes both, so the "missing" row goes.
+function mergeRenames(rows) {
+  const renamed = new Set();
+  for (const row of rows) {
+    if (row.finding.validation?.keyword !== "additionalProperties") continue;
+    const parent = segmentsOf(row.finding.path).slice(0, -1).join("/");
+    for (const fix of row.fixes) if (fix.id.startsWith("rename-to:")) renamed.add(`${parent}|${fix.id.slice("rename-to:".length)}`);
+  }
+  if (!renamed.size) return rows;
+  return rows.filter((row) => !(row.finding.validation?.keyword === "required" && renamed.has(`${segmentsOf(row.finding.path).join("/")}|${row.finding.validation.params?.missingProperty}`)));
+}

package/dist/source-ranges.js

@@ -0,0 +1,32 @@
+// Where a finding is in the text (artifacts/source-editor/VALIDATOR-HINTS.md, section 4, rule 4): the smallest thing the message is about. A JSON
+// Pointer becomes a range of the key, the value, the whole entry or the opening bracket of the container. Ranges are original-source offsets.
+import { locate } from "@openpresentation/opf/source";
+
+/** One-based line and column of a source offset (a CRLF pair is one line break). */
+export function lineColumn(text, offset) {
+  let line = 1, start = 0;
+  const end = Math.min(offset, text.length);
+  for (let i = 0; i < end; i++) {
+    const code = text.charCodeAt(i);
+    if (code === 10 || (code === 13 && text.charCodeAt(i + 1) !== 10)) { line++; start = i + 1; }
+  }
+  return { line, column: offset - start + 1 };
+}
+
+/**
+ * The range of `segments` in the JSON `text`, or null (core's `locate`, which reads text that does not parse). `part`: "value" (default), "key" (the
+ * property name), "entry" (key to the end of the value), "colon" (the key and its colon) or "open" (the first character of the value, the `{` of an
+ * object). A path that is not there gives the range of its nearest container, with `exact: false`.
+ */
+export function locateJson(text, segments, part = "value") {
+  const range = locate(text, "json", segments.map(String), { part });
+  return range ? { from: range.offset, to: range.offset + range.length, exact: range.exact !== false } : null;
+}
+
+/** The part of the text a finding is about, by what it says (VALIDATOR-HINTS section 4). */
+export function partOf(finding) {
+  const keyword = finding.validation?.keyword;
+  if (keyword === "additionalProperties" || finding.ruleId === "opf/duplicate-key") return "key";
+  if (keyword === "required") return "open";
+  return "value";
+}

package/dist/source-snippets.js

@@ -0,0 +1,93 @@
+// Snippets of the source editor (artifacts/source-editor/SPEC.md, section 5): a new slide, a chart slide, a quote and the like. Each is written once as an
+// OPF fragment with numbered placeholders and rendered per format (JSON here; YAML and Markdown follow in phase 2), then handed to CodeMirror's
+// snippet engine, which walks the tab stops. Plain functions, no DOM.
+
+const PLACEHOLDER = Symbol("opf-placeholder");
+
+/**
+ * A placeholder inside a fragment: tab stop `index` (1 first; 0 is where the caret ends), `text` is what it holds until typed over, `raw` keeps it
+ * out of string quotes (a number), `choice` opens the list of the field's values when the tab stop is reached (`value` is what a document has
+ * when the stop is left empty, for tests).
+ */
+export const ph = (index, text = "", options = {}) => ({ [PLACEHOLDER]: true, index, text, ...options });
+const isPlaceholder = (value) => value !== null && typeof value === "object" && value[PLACEHOLDER] === true;
+
+const tabs = (depth) => "\t".repeat(depth);
+// The snippet syntax treats braces and backslashes in a placeholder's text as markup.
+const escapeText = (text) => text.replace(/[\\{}]/g, (character) => `\\${character}`);
+const field = (placeholder) => `\${${placeholder.index}${placeholder.text ? `:${escapeText(JSON.stringify(placeholder.text).slice(1, -1))}` : ""}}`;
+
+/** `{ text, fields }`: the fragment as JSON text with CodeMirror snippet markers (indentation as leading tabs, which become the editor's unit). */
+export function renderJson(fragment, { comma = false } = {}) {
+  const fields = [];
+  const render = (value, depth) => {
+    if (isPlaceholder(value)) {
+      fields.push({ index: value.index, text: value.text, ...(value.choice ? { choice: true } : {}) });
+      return value.raw ? field(value) : `"${field(value)}"`;
+    }
+    if (value === null || typeof value !== "object") return JSON.stringify(value);
+    if (Array.isArray(value)) {
+      if (!value.length) return "[]";
+      return `[\n${value.map((item) => `${tabs(depth + 1)}${render(item, depth + 1)}`).join(",\n")}\n${tabs(depth)}]`;
+    }
+    const entries = Object.entries(value);
+    if (!entries.length) return "{}";
+    return `{\n${entries.map(([key, item]) => `${tabs(depth + 1)}${JSON.stringify(key)}: ${render(item, depth + 1)}`).join(",\n")}\n${tabs(depth)}}`;
+  };
+  let text = render(fragment, 0);
+  if (comma) text += ",";
+  return { text: `${text}\${0}`, fields: fields.sort((a, b) => a.index - b.index) };
+}
+
+/** The same fragment with every placeholder replaced by its text (what a document has when the placeholders are left as they are). */
+export function fragmentValue(fragment, { empty = false, literal = false } = {}) {
+  const visit = (value) => {
+    if (isPlaceholder(value)) return value.raw ? Number(value.text || 0) : (empty ? "" : (literal ? value.text : (value.value ?? value.text)));
+    if (Array.isArray(value)) return value.map(visit);
+    if (value !== null && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, visit(item)]));
+    return value;
+  };
+  return visit(fragment);
+}
+
+const columns = (first, second) => [ph(first, "Category"), ph(second, "Value")];
+
+/**
+ * The snippets. `where`: "slide" (an entry of `slides`), "reference" (an entry of `references`), "dataset" (a new key of `datasets`), "deck" (a blank
+ * document). `fragment` is the OPF fragment; for "dataset" `name` is the entry's key.
+ */
+export const SNIPPETS = Object.freeze([
+  { prefix: "slide", where: "slide", description: "A slide with a title and a list", fragment: { title: ph(1, "Slide title"), items: [ph(2, "First point")] } },
+  { prefix: "slide-text", where: "slide", description: "A slide with a title and a paragraph", fragment: { title: ph(1, "Title"), text: ph(2, "Body text") } },
+  { prefix: "slide-image", where: "slide", description: "A slide with a picture and its alt text", fragment: { title: ph(1, "Title"), image: { src: ph(2, "asset:photo"), alt: ph(3, "Describe the picture") } } },
+  { prefix: "slide-chart", where: "slide", description: "A slide with a chart", fragment: { title: ph(1, "Title"), chart: { type: ph(2, "", { choice: true, value: "column" }), data: { columns: columns(3, 4), rows: [[ph(5, "A"), ph(6, "1", { raw: true })]] } } } },
+  { prefix: "slide-quote", where: "slide", description: "A slide with a quote", fragment: { quote: { text: ph(1, "Quote"), attribution: ph(2, "Name, Title") } } },
+  { prefix: "slide-metric", where: "slide", description: "A slide with one big number", fragment: { metric: { value: ph(1, "42"), label: ph(2, "Label") } } },
+  { prefix: "slide-table", where: "slide", description: "A slide with a table", fragment: { title: ph(1, "Title"), table: { columns: [ph(2, "Name"), ph(3, "Value")], rows: [[ph(4, "A"), ph(5, "1")]] } } },
+  { prefix: "slide-code", where: "slide", description: "A slide with a piece of code", fragment: { code: { source: ph(1, "code"), language: ph(2, "js") } } },
+  { prefix: "slide-two-column", where: "slide", description: "A slide with two columns", fragment: { title: ph(1, "Title"), layout: "two-column", left: { items: [ph(2, "Left")] }, right: { items: [ph(3, "Right")] } } },
+  { prefix: "section", where: "slide", description: "A section divider", fragment: { layout: "section", title: ph(1, "Section title") } },
+  { prefix: "reference", where: "reference", description: "A reference a slide can cite", fragment: { id: ph(1, "smith2020"), text: ph(2, "Citation") } },
+  { prefix: "dataset", where: "dataset", description: "A table of data that charts and tables can share", name: ph(1, "sales"), fragment: { columns: [ph(2, "Category"), ph(3, "Value")], rows: [[ph(4, "A"), ph(5, "1", { raw: true })]] } },
+  { prefix: "deck", where: "deck", description: "A starter deck", fragment: { name: ph(1, "Deck name"), slides: [{ title: ph(2, "Title") }] } },
+]);
+
+/** The snippets that fit where the caret is: `where` and the path of the node (see source-json.js). */
+export function snippetsFor(mode, path) {
+  const last = path.at(-1);
+  return SNIPPETS.filter((snippet) => {
+    if (snippet.where === "slide") return mode === "item" && path.length === 2 && path[0] === "slides" && typeof last === "number";
+    if (snippet.where === "reference") return mode === "item" && path.length === 2 && path[0] === "references" && typeof last === "number";
+    if (snippet.where === "dataset") return mode === "key" && path.length === 1 && path[0] === "datasets";
+    if (snippet.where === "deck") return mode === "value" && path.length === 0;
+    return false;
+  });
+}
+
+/** The JSON text of a snippet for insertion: `{ text, fields }`; a dataset is a `"name": { ... }` entry. */
+export function snippetJson(snippet, { comma = false } = {}) {
+  if (snippet.where !== "dataset") return renderJson(snippet.fragment, { comma });
+  const body = renderJson(snippet.fragment, { comma });
+  const key = `"${field(snippet.name)}"`;
+  return { text: `${key}: ${body.text}`, fields: [{ index: snippet.name.index, text: snippet.name.text }, ...body.fields].sort((a, b) => a.index - b.index) };
+}