@openpresentation/opf-editor 0.26.0 → 0.26.2

package/dist/source-findings.js

@@ -7,9 +7,20 @@ export function normalizeFinding(input, kind) {
   const out = { path: String(finding.path ?? ""), message: String(finding.message ?? ""), severity };
   const line = finding.line ?? finding.location?.line;
   if (Number.isInteger(line) && line > 0) out.line = line;
+  const column = finding.column ?? finding.location?.column;
+  if (Number.isInteger(column) && column > 0) out.column = column;
   const own = finding.kind ?? kind;
   if (own) out.kind = own;
   if (finding.ruleId) out.ruleId = finding.ruleId;
+  // What core knows about a finding beyond the sentence: the help, the source range, the schema keyword and parameters, the suggested
+  // values and the fixes. The pane writes the problem text and its quick fixes from them.
+  for (const key of ["help", "category", "location", "validation", "suggestions", "fixes", "lookup", "definition", "slide", "slideId", "measured", "next"]) {
+    if (finding[key] !== undefined && finding[key] !== null) out[key] = finding[key];
+  }
+  // A problem with a range of its own (the JSON syntax analyzer) and the quick fixes that go with it.
+  if (finding.range && Number.isInteger(finding.range.from) && Number.isInteger(finding.range.to)) out.range = finding.range;
+  if (finding.editFixes) out.editFixes = finding.editFixes;
+  if (Array.isArray(finding.related)) out.related = finding.related;
   return out;
 }
 

package/dist/source-fixes.js

@@ -0,0 +1,106 @@
+// Quick fixes for the findings of the source pane (artifacts/source-editor/VALIDATOR-HINTS.md, section 12): the text edits behind "Change to center",
+// "Rename to slides", "Remove property", "Add `slides`" and the like, for a JSON text that parses. Pure functions over the source text:
+// each returns `{ id, title, safe, edits: [{ from, to, insert }], caret? }`, source offsets in, so the editor applies it as one undoable change.
+import { findNodeAtLocation, modify, parseTree } from "jsonc-parser";
+import { replacementValues, segmentsOf } from "./source-messages.js";
+
+const toPath = (segments) => segments.map((segment) => (/^\d+$/.test(segment) ? Number(segment) : segment));
+
+/** jsonc-parser's edits as `{ from, to, insert }`. */
+const asEdits = (edits) => edits.map((edit) => ({ from: edit.offset, to: edit.offset + edit.length, insert: edit.content }));
+
+function formatting(unit, text) {
+  return { insertSpaces: unit !== "\t", tabSize: unit === "\t" ? 4 : unit.length, eol: /\r\n/.test(text) ? "\r\n" : "\n" };
+}
+/** The text after `edits` (source offsets, not overlapping; edits at one offset keep their order). */
+export function applySourceEdits(text, edits) {
+  const ordered = edits.map((edit, index) => ({ edit, index })).sort((a, b) => a.edit.from - b.edit.from || a.index - b.index);
+  let next = text;
+  for (const { edit } of ordered.reverse()) next = next.slice(0, edit.from) + edit.insert + next.slice(edit.to);
+  return next;
+}
+
+/** The node at `segments`: `{ node, parent }` or null. */
+function nodeAt(text, segments) {
+  const root = parseTree(text, [], { allowTrailingComma: true });
+  if (!root) return null;
+  const node = findNodeAtLocation(root, toPath(segments));
+  return node ? { root, node } : null;
+}
+/** The property node (`"key": value`) whose value sits at `segments`, and its key node. */
+function propertyAt(text, segments) {
+  const found = nodeAt(text, segments);
+  const property = found?.node.parent;
+  if (!property || property.type !== "property") return null;
+  return { property, key: property.children[0], value: property.children[1] };
+}
+
+/** Replace the value at `segments` with `value` (any JSON value). */
+export function changeValue(text, segments, value) {
+  const found = nodeAt(text, segments);
+  if (!found) return null;
+  return [{ from: found.node.offset, to: found.node.offset + found.node.length, insert: JSON.stringify(value) }];
+}
+/** Rename the property whose value is at `segments`. */
+export function renameKey(text, segments, name) {
+  const found = propertyAt(text, segments);
+  if (!found) return null;
+  return [{ from: found.key.offset, to: found.key.offset + found.key.length, insert: JSON.stringify(name) }];
+}
+/** Remove the property (or list item) at `segments`, with the comma that belonged to it. */
+export function removeAt(text, segments, unit = "  ") {
+  const edits = modify(text, toPath(segments), undefined, { formattingOptions: formatting(unit, text) });
+  return edits.length ? asEdits(edits) : null;
+}
+/** Add `key: value` to the object at `segments`, after its last property. */
+export function addProperty(text, segments, key, value, unit = "  ") {
+  const edits = modify(text, [...toPath(segments), key], value, { formattingOptions: formatting(unit, text) });
+  return edits.length ? asEdits(edits) : null;
+}
+/** Add `value` at the end of the list at `segments`. */
+export function addItem(text, segments, value, unit = "  ") {
+  const found = nodeAt(text, segments);
+  const length = found?.node.type === "array" ? (found.node.children?.length ?? 0) : 0;
+  const edits = modify(text, [...toPath(segments), length], value, { formattingOptions: formatting(unit, text), isArrayInsertion: true });
+  return edits.length ? asEdits(edits) : null;
+}
+/** Wrap the value at `segments` in a one-item list. */
+export function wrapInList(text, segments) {
+  const found = nodeAt(text, segments);
+  if (!found) return null;
+  const { offset, length } = found.node;
+  return [{ from: offset, to: offset, insert: "[" }, { from: offset + length, to: offset + length, insert: "]" }];
+}
+
+/**
+ * The quick fixes of a schema or reference finding in a JSON text that parses. `context` is the one source-messages.js takes plus
+ * `{ unit, starter(segments, property) }` (the value `Add` inserts).
+ */
+export function fixesForFinding(finding, text, context = {}) {
+  if (!finding.path && finding.validation?.keyword !== "required") return [];
+  const segments = segmentsOf(finding.path);
+  const keyword = finding.validation?.keyword;
+  const unit = context.unit ?? "  ";
+  const fixes = [];
+  const push = (id, title, edits, extra = {}) => { if (edits?.length) fixes.push({ id, title, edits, safe: false, ...extra }); };
+  if (keyword === "enum" || finding.ruleId === "opf/unresolved-reference") {
+    for (const value of replacementValues(finding, context)) push(`change-to:${value}`, `Change to ${value}`, changeValue(text, segments, value));
+  } else if (keyword === "additionalProperties") {
+    const name = finding.validation.params?.additionalProperty ?? segments.at(-1);
+    for (const value of replacementValues(finding, context)) push(`rename-to:${value}`, `Rename to ${value}`, renameKey(text, segments, value));
+    push("remove-property", "Remove property", removeAt(text, segments, unit));
+    void name;
+  } else if (keyword === "required") {
+    const property = finding.validation.params?.missingProperty;
+    const starter = context.starter?.(segments, property);
+    if (property && starter !== undefined) push(`add:${property}`, `Add \`${property}\``, addProperty(text, segments, property, starter, unit));
+  } else if (keyword === "type" && finding.validation.params?.type === "array") {
+    push("wrap-in-list", "Wrap in a list", wrapInList(text, segments));
+  } else if (keyword === "minItems" && finding.path === "/slides") {
+    push("add-slide", "Add a slide", addItem(text, segments, { title: "Slide title" }, unit));
+  } else if (finding.ruleId === "opf/duplicate-key") {
+    // The pane marks the second key; removing either one leaves the other.
+    push("remove-duplicate", "Remove the second", removeAt(text, segments, unit));
+  }
+  return fixes;
+}

package/dist/source-format.js

@@ -0,0 +1,92 @@
+// Format document for the source pane (Shift+Alt+F, Cmd/Ctrl+Shift+F and the Format button): whitespace only, in every format, and nothing the
+// author wrote is dropped. JSON is laid out token by token (so a draft that does not parse is laid out too), YAML goes through the `yaml`
+// library's document round trip (comments, anchors, key order and scalar styles stay), and Markdown gets one blank line between blocks with its
+// front matter formatted as YAML. Plain functions, no DOM: `formatSource(format, text, { unit })` returns `{ text }` or `{ error }`.
+import { parseDocument } from "yaml";
+import { formatJsonSource } from "./json-format.js";
+
+const lineEnding = (source) => /\r\n|\r|\n/.exec(source)?.[0] ?? "\n";
+
+/** YAML text laid out with a 2-space indent, long lines kept whole; its comments, blank lines, scalar styles and key order stay as written. */
+export function formatYamlSource(source) {
+  if (source.trim() === "") return { text: source };
+  const bom = source.startsWith("\uFEFF") ? "\uFEFF" : "";
+  const eol = lineEnding(source);
+  const document = parseDocument(bom ? source.slice(1) : source, { prettyErrors: false, customTags: keepNumberSpelling });
+  if (document.errors.length) return { error: "The YAML has errors, so it cannot be formatted. Fix them first." };
+  // Only comments: there is no document to write, and writing one would add a `null`.
+  if (document.contents === null || document.contents === undefined) return { text: source };
+  let text = document.toString({ indent: 2, lineWidth: 0, flowCollectionPadding: false });
+  // The library ends every document with a newline; keep the author's choice.
+  if (!/[\r\n]\s*$/.test(source) && text.endsWith("\n")) text = text.slice(0, -1);
+  if (eol !== "\n") text = text.replaceAll("\n", eol);
+  return { text: bom + text };
+}
+
+// The library writes a number from its value (1e3 becomes 1e+3, 0x1F 0x1f, .5 0.5, +1 1); the author's spelling is kept instead.
+const NUMBER_TAGS = new Set(["tag:yaml.org,2002:int", "tag:yaml.org,2002:float"]);
+const keepNumberSpelling = (tags) => tags.map((tag) => (
+  typeof tag === "object" && tag && typeof tag.stringify === "function" && NUMBER_TAGS.has(tag.tag)
+    ? { ...tag, stringify: (item, context, onComment, onChompKeep) => (typeof item.source === "string" && item.source !== "" ? item.source : tag.stringify(item, context, onComment, onChompKeep)) }
+    : tag
+));
+
+const FENCE = /^ {0,3}(`{3,}|~{3,})/;
+const INDENTED = /^(?: {4}|\t)/;
+
+/**
+ * Markdown laid out with at most one blank line between blocks (code fences and runs inside an indented block are left as written), the front
+ * matter formatted as YAML, one line ending (the first one found) and one newline at the end.
+ */
+export function formatMarkdownSource(source) {
+  const eol = lineEnding(source);
+  const lines = source.split(/\r\n|\r|\n/);
+  let body = 0;
+  const out = [];
+  if (lines[0] === "---") {
+    const close = lines.findIndex((line, index) => index > 0 && (line === "---" || line === "..."));
+    if (close > 0) {
+      const front = formatYamlSource(lines.slice(1, close).join("\n"));
+      out.push("---", ...(front.error || front.text === "" ? lines.slice(1, close) : front.text.replace(/\n$/, "").split("\n")), lines[close]);
+      body = close + 1;
+    }
+  }
+  let fence = null, blanks = 0, lastIndented = false;
+  for (let index = body; index < lines.length; index++) {
+    const line = lines[index];
+    if (fence) {
+      out.push(line);
+      const marker = FENCE.exec(line)?.[1];
+      if (marker && marker[0] === fence[0] && marker.length >= fence.length && line.trim() === marker) fence = null;
+      continue;
+    }
+    if (line.trim() === "") { blanks++; continue; }
+    if (blanks) {
+      // A blank run inside an indented block (code) is content; elsewhere it is one blank line.
+      const keep = lastIndented && INDENTED.test(line) ? blanks : 1;
+      for (let count = 0; count < keep; count++) out.push("");
+    }
+    blanks = 0;
+    out.push(line);
+    lastIndented = INDENTED.test(line);
+    const opened = FENCE.exec(line)?.[1];
+    if (opened) fence = opened;
+  }
+  // A document that ends inside a fence keeps its last lines as written; otherwise it ends with one newline.
+  while (!fence && out.length && out[out.length - 1].trim() === "") out.pop();
+  return { text: out.length ? out.join(eol) + (fence ? "" : eol) : "" };
+}
+
+/**
+ * Format `text` as `format` ("json", "yaml" or "md"). `unit` is the editor's indentation unit for JSON (a tab or spaces). Returns `{ text }`
+ * (possibly the same text) or `{ error }` with a sentence for the author.
+ */
+export function formatSource(format, text, { unit } = {}) {
+  try {
+    if (format === "yaml") return formatYamlSource(text);
+    if (format === "md") return formatMarkdownSource(text);
+    return { text: formatJsonSource(text, unit) };
+  } catch (error) {
+    return { error: `Formatting failed: ${error instanceof Error ? error.message : String(error)}` };
+  }
+}

package/dist/source-json.js

@@ -0,0 +1,139 @@
+// The JSON text adapter of the source editor (artifacts/source-editor/SPEC.md, section 3.1): what a position in a JSON draft means. Everything the
+// completion list, the hover and the hints know about the caret comes from `contextAt`: the token being typed, whether it sits where a key, a value
+// or a list item belongs, the path of the node in the document, the keys already there, and what the text around needs when something is inserted
+// (a colon, a comma). It reads drafts that do not parse: the token under the caret is swapped for a placeholder string and the rest is read with
+// the tolerant parser.
+import { findNodeAtOffset, getNodePath, getNodeValue, parseTree } from "jsonc-parser";
+
+const PLACEHOLDER = "__opf_completion__";
+const WORD = /[A-Za-z0-9_.-]/;
+
+/**
+ * The token being typed at `position`: inside a string (a quote opened earlier on this line), or a bare word, or nothing yet where a value or key
+ * would go. JSON strings never span lines. Returns `{ quoted, closed, start, end, from, to }` (`start..end` is the whole token with its quotes,
+ * `from..to` the text between them), or null when no token can be completed here. `explicit` (Ctrl+Space) also takes the empty place after `{`,
+ * `,`, `:` and `[`, the string just closed, and a blank document; typing `:` or the space after it takes the empty place after the colon.
+ */
+export function tokenAt(text, position, explicit) {
+  const lineStart = Math.max(text.lastIndexOf("\n", position - 1), text.lastIndexOf("\r", position - 1)) + 1;
+  let open = -1, last = null;
+  for (let index = lineStart; index < position; index++) {
+    if (open >= 0) { if (text[index] === "\\") index++; else if (text[index] === '"') { last = { start: open, end: index }; open = -1; } }
+    else if (text[index] === '"') open = index;
+  }
+  // Asked for explicitly (Ctrl+Space) right after a closing quote: the string just ended is the token, as in VS Code.
+  if (open < 0 && explicit && last?.end === position - 1) return { quoted: true, closed: true, start: last.start, end: position, from: last.start + 1, to: position - 1 };
+  if (open >= 0) {
+    let close = -1;
+    for (let index = position; index < text.length && text[index] !== "\n" && text[index] !== "\r"; index++) {
+      if (text[index] === "\\") index++;
+      else if (text[index] === '"') { close = index; break; }
+    }
+    return { quoted: true, closed: close >= 0, start: open, end: close >= 0 ? close + 1 : position, from: open + 1, to: close >= 0 ? close : position };
+  }
+  let start = position, end = position;
+  while (start > lineStart && WORD.test(text[start - 1])) start--;
+  while (end < text.length && WORD.test(text[end])) end++;
+  if (start === position && !explicit && !/:[ \t]?$/.test(text.slice(lineStart, position))) return null;
+  let before = start - 1;
+  while (before >= lineStart && /\s/.test(text[before])) before--;
+  // A bare word starts a key or a value only after `{`, `,`, `:` or `[` (or at the start of an empty line).
+  const previous = before >= lineStart ? text[before] : (text.slice(0, lineStart).trimEnd().at(-1) ?? "");
+  const blank = previous === "" && text.slice(0, start).trim() === "" && text.slice(end).trim() === "";
+  if (!["{", ",", ":", "["].includes(previous) && !blank) return null;
+  return { quoted: false, closed: false, start, end, from: start, to: end };
+}
+
+/** The first non-blank character after `offset` (skipping whitespace and line breaks), or "". */
+export function nextSignificant(text, offset) {
+  for (let index = offset; index < text.length; index++) if (!/\s/.test(text[index])) return text[index];
+  return "";
+}
+
+/**
+ * A copy of the document with only what choosing the schema form along `path` needs: the nodes on the path in full, every other value cut to its
+ * type (an object to `{}`, a list to an empty list as long as it is), so the cost does not grow with the deck. `catalogs` is kept in full because
+ * embedded records are offered as values.
+ */
+export function skeleton(root, path, skip) {
+  const shallow = (node) => {
+    if (node.type === "object") return {};
+    if (node.type === "array") return new Array((node.children ?? []).length);
+    return node.value;
+  };
+  const build = (node, rest, skip) => {
+    if (node.type === "object") {
+      const out = {};
+      for (const property of node.children ?? []) {
+        const key = property.children?.[0]?.value, value = property.children?.[1];
+        if (typeof key !== "string" || !value) continue;
+        if (rest.length && String(key) === String(rest[0])) {
+          if (rest.length === 1 && skip) continue;
+          out[key] = build(value, rest.slice(1), skip);
+        } else out[key] = key === "catalogs" && rest.length === 0 ? getNodeValue(value) : shallow(value);
+      }
+      return out;
+    }
+    if (node.type === "array") {
+      const out = new Array((node.children ?? []).length);
+      (node.children ?? []).forEach((child, index) => {
+        if (rest.length && String(index) === String(rest[0])) { if (!(rest.length === 1 && skip)) out[index] = build(child, rest.slice(1), skip); }
+        else out[index] = shallow(child);
+      });
+      return out;
+    }
+    return node.value;
+  };
+  const document = build(root, path, skip);
+  // The embedded catalogs, whole, whatever the path (their records are offered as values).
+  const catalogs = (root.children ?? []).find((property) => property.children?.[0]?.value === "catalogs")?.children?.[1];
+  if (catalogs && root.type === "object" && path[0] !== "catalogs") document.catalogs = getNodeValue(catalogs);
+  return document;
+}
+
+/**
+ * What the draft means at `position`, or null: `{ mode, token, path, key, existing, siblingsAfter, document, node }`.
+ * `mode` is "key" (a property name goes here; `path` is the object), "value" (the value of the property at `path`; `key` is its name) or "item" (an
+ * entry of the list at `path`, which ends with the entry's index). `existing` holds the other property names of the object. `document` is the
+ * skeleton that `describeField` reads. `node` is the placeholder node of the draft.
+ */
+export function contextAt(text, position, { explicit = false } = {}) {
+  const token = tokenAt(text, position, explicit);
+  if (!token) return null;
+  const draft = text.slice(0, token.start) + JSON.stringify(PLACEHOLDER) + text.slice(token.end);
+  const root = parseTree(draft, [], { allowTrailingComma: true });
+  if (!root) return null;
+  const node = findNodeAtOffset(root, token.start + 1, true);
+  if (node?.type !== "string" || node.value !== PLACEHOLDER) return null;
+  const parent = node.parent;
+  if (!parent) return { mode: "value", token, path: [], key: undefined, existing: new Set(), document: {}, node, root };
+  if (parent.type === "property" && parent.children?.[0] === node) {
+    const object = parent.parent;
+    if (!object || object.type !== "object") return null;
+    const path = getNodePath(object);
+    const existing = new Set((object.children ?? []).filter((property) => property !== parent).map((property) => property.children?.[0]?.value));
+    return { mode: "key", token, path, key: undefined, existing, document: skeleton(root, path, false), node, root, object };
+  }
+  const path = getNodePath(node);
+  if (parent.type === "property") return { mode: "value", token, path, key: String(path.at(-1)), existing: new Set(), document: skeleton(root, path, true), node, root };
+  if (parent.type === "array") return { mode: "item", token, path, key: undefined, existing: new Set(), document: skeleton(root, path, true), node, root };
+  return null;
+}
+
+/**
+ * The node under `position` in a JSON text for hover: `{ kind: "key" | "value", path, from, to, value }` (offsets of the key or value token), or
+ * null. Works on text that does not parse.
+ */
+export function nodeAt(text, position) {
+  const root = parseTree(text, [], { allowTrailingComma: true, disallowComments: false });
+  if (!root) return null;
+  const node = findNodeAtOffset(root, position, true);
+  if (!node) return null;
+  const parent = node.parent;
+  if (node.type === "string" && parent?.type === "property" && parent.children?.[0] === node) {
+    return { kind: "key", path: [...getNodePath(parent), node.value], from: node.offset, to: node.offset + node.length, value: node.value, root, node };
+  }
+  if (node.type === "property") return null;
+  if (!["string", "number", "boolean", "object", "array", "null"].includes(node.type)) return null;
+  return { kind: "value", path: getNodePath(node), from: node.offset, to: node.offset + node.length, value: node.type === "object" || node.type === "array" ? undefined : node.value, nodeType: node.type, root, node };
+}

package/dist/source-messages.js

@@ -0,0 +1,231 @@
+// 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.
+
+/**
+ * `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.
+ */
+
+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" };
+
+/** 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"' : '"…"';
+}
+
+/**
+ * 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.
+ */
+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 };
+}
+
+/** 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;
+  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);
+  }
+  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;
+  }
+  return [];
+}

package/dist/source-pane.d.ts

@@ -1,6 +1,6 @@
 import type { EditorChange, EditorSession } from "./index.js";
 import type { JsonCatalogContext } from "./json-options.js";
-import type { JsonCodeEditor } from "./json-editor.js";
+import type { EditorProblem, JsonCodeEditor } from "./json-editor.js";
 
 /** The source formats of the pane: `json` is canonical; `yaml` and `md` are core's `@openpresentation/opf/yaml` and `/markdown`. */
 export type SourceFormat = "json" | "yaml" | "md";
@@ -18,6 +18,18 @@ export interface SourceFinding {
   /** `schema` (the default count label), `syntax`, `format` (a note about what the format cannot hold) or `rejected` (the session refused the edit). */
   kind?: string;
   ruleId?: string;
+  /** A one-based column, with `line`. */
+  column?: number;
+  /**
+   * What core's findings carry beyond the sentence, kept and used: `validation` (the schema keyword and its parameters) and `suggestions` write the
+   * plain-words message and its "Next" hint and offer "Change to ..." fixes; `location` ranges the squiggle; `fixes` of kind `patch` and `focus` become
+   * quick fixes; `help` is the hint when nothing better is known.
+   */
+  help?: string;
+  location?: { offset: number; length: number; line?: number; column?: number };
+  validation?: { keyword?: string; params?: Record<string, unknown>; alternatives?: string[] };
+  suggestions?: { value: unknown; label?: string }[];
+  fixes?: { id: string; title: string; kind: "patch" | "focus"; safe?: boolean; patch?: unknown[]; focus?: { path?: string; field?: string } }[];
 }
 
 /** What a host receives when the pane copies or downloads. */
@@ -59,7 +71,7 @@ export interface SourcePaneOptions {
   /** Accessible name of the code editor (default `OPF source`). */
   label?: string;
   catalogs?: JsonCatalogContext;
-  /** Live completions while typing JSON: property names and values (enums, booleans, catalog references) at the cursor's JSON path, from the same data as the field menu. YAML and Markdown keep the menu only. 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. YAML and Markdown have no completions yet. Default true. */
   completions?: boolean;
   onError?(error: unknown): void;
 }
@@ -106,6 +118,16 @@ export interface SourcePane {
   setName(name: string): void;
   setDensity(density: SourcePaneDensity): void;
   setReadOnly(readOnly: boolean): void;
+  /** The problems drawn in the text now, in position order, at source offsets. */
+  getProblems(): EditorProblem[];
+  /** Select the next problem in the text (F8) and say what it is; wraps. */
+  nextProblem(): boolean;
+  /** Select the previous problem (Shift+F8). */
+  previousProblem(): boolean;
+  /** Select problem number `index` (zero-based, position order) and say what it is. Returns false when there is none. */
+  showProblem(index: number): boolean;
+  /** Open the suggestion list at the caret, as Ctrl+Space does. */
+  triggerCompletion(): boolean;
   /** The underlying code editor (`mountJsonCodeEditor`). */
   readonly editor: JsonCodeEditor;
   destroy(): void;