@openpresentation/opf-editor 0.26.4 → 0.26.6

package/dist/source-a11y.js

@@ -77,7 +77,8 @@ export function a11yExtension(announcer, describe = () => "") {
       const open = completionStatus(state) === "active" && currentCompletions(state).length > 0;
       const selected = open ? selectedCompletion(state) : null;
       if (open && !this.open) {
-        announcer.say(plural(currentCompletions(state).length, "suggestion"));
+        const footer = currentCompletions(state).find((completion) => completion.opfFooter)?.opfFooter;
+        announcer.say(`${plural(currentCompletions(state).length, "suggestion")}${footer ? `. ${footer}` : ""}`);
       } else if (open && selected && selected !== this.selected) {
         clearTimeout(this.timer);
         this.timer = setTimeout(() => {
@@ -98,12 +99,28 @@ export function a11yExtension(announcer, describe = () => "") {
       const { view } = this, { state } = view;
       const completions = currentCompletions(state);
       if (!completions.length) return;
+      this.footer(completions);
       for (const node of view.dom.querySelectorAll(".cm-tooltip-autocomplete [role=option]")) {
         const index = Number(node.id.slice(node.id.lastIndexOf("-") + 1));
         const completion = completions[index];
         if (completion) node.setAttribute("aria-label", optionName(completion, index, completions.length));
       }
     }
+    // The line under a list of catalog records whose catalog is not loaded (SPEC 4.5): part of the list's own box, after the options.
+    footer(completions) {
+      const tooltip = this.view.dom.querySelector(".cm-tooltip-autocomplete");
+      if (!tooltip) return;
+      const text = completions.find((completion) => completion.opfFooter)?.opfFooter ?? "";
+      let node = tooltip.querySelector(":scope > .opf-completion-footer");
+      if (!text) { node?.remove(); return; }
+      if (!node) {
+        node = tooltip.ownerDocument.createElement("div");
+        node.className = "opf-completion-footer";
+        node.setAttribute("role", "note");
+      }
+      if (node.textContent !== text) node.textContent = text;
+      if (tooltip.lastElementChild !== node) tooltip.append(node);
+    }
     destroy() { clearTimeout(this.timer); clearTimeout(this.labelTimer); }
   });
 }

package/dist/source-check.js

@@ -0,0 +1,90 @@
+// The source pane's text checks as plain functions of their input (no DOM, no editor session), so the main thread and the Web Worker
+// (`./source-worker.js`) run exactly the same code and give the same answer. `readSource` is what the pane has always done with a text
+// (parse it, collect the syntax findings); `checkSource` adds the validation the editor session would run on the deck it reads, so a worker
+// can hand both back and the session need not repeat it on the main thread. Everything returned is structured-cloneable data.
+import { fromYaml } from "@openpresentation/opf/yaml";
+import { fromMarkdown, toMarkdown } from "@openpresentation/opf/markdown";
+import { checkFormat } from "./checks.js";
+import { normalizeFinding } from "./source-findings.js";
+import { analyzeSyntax, findDuplicateKeys } from "./source-syntax.js";
+import { withSyntaxFixes } from "./source-fixes-syntax.js";
+
+/**
+ * Read the text of one format: `{ deck, findings, notes? }` on success, `{ syntax: true, findings }` when it cannot be read. `findings` carry the
+ * syntax errors (`kind: "syntax"`) or the OPF findings of the parsed deck; `notes` are the reader's warnings that come with a deck.
+ */
+export function readSource(format, text, catalogs) {
+  if (format === "json") {
+    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 });
+  // 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) };
+}
+
+/**
+ * `readSource` plus, when a deck was read, `validation`: the report the editor session computes for that deck (`checkFormat`, with the same
+ * catalogs). `validate: false` skips it (the main thread's own path, where the session validates the patch itself).
+ */
+export function checkSource({ format, text, catalogs, validate = true }) {
+  const read = readSource(format, text, catalogs);
+  if (validate && read.deck) {
+    read.validation = checkFormat(read.deck, { catalogs });
+    // What the Markdown writer cannot hold for this deck: the pane lists it after every applied edit, and writing a big deck back is not cheap.
+    if (format === "md") read.markdownNotes = markdownNotesOf(read.deck);
+  }
+  return read;
+}
+
+/** The notes about what Markdown cannot hold, as findings, from the report of `toMarkdown`. */
+export function markdownNotes(report) {
+  const notes = report.embedded.map((part) => normalizeFinding({ path: part.path, message: `Markdown has no syntax for this, so it is kept as YAML in a fenced block (${part.reason}).`, severity: "warning" }, "format"));
+  for (const entry of report.loss) {
+    const at = entry.indexOf(": ");
+    notes.push(normalizeFinding({ path: at > 0 ? entry.slice(0, at) : "", message: `Left out of the Markdown: ${at > 0 ? entry.slice(at + 2) : entry}.`, severity: "warning" }, "format"));
+  }
+  return notes;
+}
+
+/** The Markdown notes of `deck`; none when it cannot be written as Markdown. */
+export function markdownNotesOf(deck) {
+  try { return markdownNotes(toMarkdown(deck).report); } catch { return []; }
+}
+
+/** The syntax problems of a JSON text as findings (the pane's quick pass, 150 ms after the last key). */
+export function checkSyntaxOnly(text) {
+  return analyzeSyntax(text).map((problem) => normalizeFinding(problem, "syntax"));
+}
+
+/**
+ * The worker's side of the protocol, free of any worker API so it can be tested in Node. `handle(message)` returns the reply for one message
+ * (or null for a message with no reply). Messages: `{ id, type: "catalogs", catalogs }`, `{ id, type: "check", format, text }` and
+ * `{ id, type: "syntax", text }`; replies: `{ id, ok: true, result }` or `{ id, ok: false, error }`.
+ */
+export function createCheckService() {
+  let catalogs;
+  return {
+    handle(message) {
+      const id = message?.id;
+      try {
+        switch (message?.type) {
+          case "catalogs": catalogs = message.catalogs; return { id, ok: true, result: null };
+          case "check": return { id, ok: true, result: checkSource({ format: message.format, text: message.text, catalogs }) };
+          case "syntax": return { id, ok: true, result: checkSyntaxOnly(message.text) };
+          default: return { id, ok: false, error: `Unknown message type ${String(message?.type)}.` };
+        }
+      } catch (error) {
+        return { id, ok: false, error: error instanceof Error ? error.message : String(error) };
+      }
+    },
+  };
+}

package/dist/source-checker.js

@@ -0,0 +1,130 @@
+// The client side of the source worker (`./source-worker.js`): it owns the worker, numbers the requests, keeps the worker's catalogs in step with the
+// pane's, and falls back to the pane's own inline path for good, once, when anything about the worker goes wrong (it cannot start, a script URL is
+// blocked or missing, a message cannot be cloned, the worker throws or stops answering). It never loses an edit: a failed request rejects with
+// `error.workerFailed === true`, and the pane then does the same work inline.
+
+const DEFAULT_TIMEOUT = 15000;
+
+/** A failure of the worker as an error the caller can tell from an exception of the checked text. */
+function failure(cause) {
+  const error = new Error(cause instanceof Error ? cause.message : String(cause ?? "The source worker failed."));
+  error.workerFailed = true;
+  error.cause = cause;
+  return error;
+}
+
+/** The worker the `worker` option stands for: a function is called, an object with `postMessage` is used as given, `true` starts the package's own. */
+function makeWorker(option) {
+  if (typeof option === "function") return option();
+  if (option && typeof option === "object" && typeof option.postMessage === "function") return option;
+  if (option === true) {
+    if (typeof Worker !== "function") throw new Error("Web Workers are not available here.");
+    return new Worker(new URL("./source-worker.js", import.meta.url), { type: "module" });
+  }
+  throw new TypeError("The worker option is true, a Worker, or a function that returns one.");
+}
+
+/**
+ * @param {{ worker: boolean | object | (() => object), onError?: (error: unknown) => void, timeout?: number }} options
+ */
+export function createSourceChecker(options = {}) {
+  const timeout = options.timeout ?? DEFAULT_TIMEOUT;
+  let worker = null;
+  let failed = false;
+  let disposed = false;
+  let nextId = 0;
+  let sentCatalogs;
+  let catalogsSent = false;
+  const pending = new Map();
+  const latest = { check: 0, syntax: 0 };
+  const counts = { worker: 0 };
+
+  function fail(cause) {
+    if (failed || disposed) return;
+    failed = true;
+    const error = failure(cause);
+    for (const entry of pending.values()) { clearTimeout(entry.timer); entry.reject(error); }
+    pending.clear();
+    try { worker?.terminate?.(); } catch { /* Already gone. */ }
+    worker = null;
+    try { options.onError?.(cause instanceof Error ? cause : error); } catch { /* A host callback must not break the fallback. */ }
+  }
+
+  function reply(event) {
+    const data = event?.data;
+    const entry = pending.get(data?.id);
+    if (!entry) return;
+    pending.delete(data.id);
+    clearTimeout(entry.timer);
+    if (data.ok === false) { entry.reject(failure(data.error)); fail(new Error(String(data.error))); return; }
+    if (data.skipped || (entry.kind && latest[entry.kind] !== data.id)) { entry.resolve(null); return; }
+    if (entry.kind) counts.worker++;
+    entry.resolve(data.result);
+  }
+
+  function start() {
+    if (worker) return worker;
+    worker = makeWorker(options.worker);
+    if (!worker || typeof worker.postMessage !== "function") throw new TypeError("The worker option did not give a Worker.");
+    worker.onmessage = reply;
+    worker.onerror = (event) => { event?.preventDefault?.(); fail(new Error(event?.message || "The source worker failed to start.")); };
+    worker.onmessageerror = () => fail(new Error("The source worker sent a message that could not be read."));
+    return worker;
+  }
+
+  function post(message, kind) {
+    if (failed || disposed) return Promise.reject(failure("The source worker is not available."));
+    let target;
+    try { target = start(); } catch (error) { fail(error); return Promise.reject(failure(error)); }
+    const id = ++nextId;
+    if (kind) latest[kind] = id;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => fail(new Error("The source worker did not answer in time.")), timeout);
+      pending.set(id, { resolve, reject, timer, kind });
+      try { target.postMessage({ id, ...message }); } catch (error) { fail(error); }
+    });
+  }
+
+  /** Send the catalogs when they are not the ones the worker already has (by identity), ahead of the request that needs them. */
+  function syncCatalogs(catalogs) {
+    if (catalogsSent && sentCatalogs === catalogs) return;
+    sentCatalogs = catalogs;
+    catalogsSent = true;
+    post({ type: "catalogs", catalogs }).catch(() => { /* `fail` already ran; the request after it rejects too. */ });
+  }
+
+  return {
+    /** Whether the worker can still be used (it may not have been started yet). */
+    get available() { return !failed && !disposed; },
+    /** Whether the worker is running now. */
+    get running() { return worker !== null && !failed && !disposed; },
+    /** The catalogs object the worker's next check will use (the last one sent). */
+    get catalogs() { return catalogsSent ? sentCatalogs : undefined; },
+    /** How many checks the worker answered. */
+    get answered() { return counts.worker; },
+    /**
+     * Check `text` as `format` in the worker, with `catalogs`. Resolves with the `checkSource` result, or with null when a newer check replaced this
+     * one. Rejects with `error.workerFailed` when the worker is not usable (and never again starts it).
+     */
+    check(format, text, catalogs) {
+      if (failed || disposed) return Promise.reject(failure("The source worker is not available."));
+      try { start(); syncCatalogs(catalogs); } catch (error) { fail(error); return Promise.reject(failure(error)); }
+      return post({ type: "check", format, text }, "check");
+    },
+    /** The syntax findings of a JSON text (null when a newer request replaced this one). */
+    syntax(text) {
+      if (failed || disposed) return Promise.reject(failure("The source worker is not available."));
+      try { start(); } catch (error) { fail(error); return Promise.reject(failure(error)); }
+      return post({ type: "syntax", text }, "syntax");
+    },
+    /** Stop the worker and answer nothing more. */
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      for (const entry of pending.values()) { clearTimeout(entry.timer); entry.resolve(null); }
+      pending.clear();
+      try { worker?.terminate?.(); } catch { /* Already gone. */ }
+      worker = null;
+    },
+  };
+}

package/dist/source-completions.js

@@ -5,15 +5,18 @@ import { hasNextSnippetField, hasPrevSnippetField, pickedCompletion, snippet, st
 import { isolateHistory } from "@codemirror/commands";
 import { EditorSelection } from "@codemirror/state";
 import { describeField } from "@openpresentation/opf/schema";
-import { listCatalogRecords } from "./catalogs.js";
+import { listCatalogRecords, mergeCatalogs } from "./catalogs.js";
 import { LAYOUT_INTENT_GROUPS, layoutRegionSummary } from "./layout-templates.js";
-import { Document, parse as parseYamlDocument } from "yaml";
-import { pathAt } from "@openpresentation/opf/source";
+import { Document, parse as parseYamlDocument, parseDocument } from "yaml";
+import { pathAt, scanMarkdown } from "@openpresentation/opf/source";
+import { findNodeAtLocation, getNodeValue } from "jsonc-parser";
 import { contextAt, nextSignificant, nodeAt, skeleton, tokenAt } from "./source-json.js";
+import { PROMOTED_REGIONS, beatsOf, builtinVariables, columnSourceFor, factsOf, jsonDeckParts, layoutKeys, referenceSiteAt, regionNames, slidePath, valueAt, variableNames, yamlDeckParts } from "./source-references.js";
+import { beginUndoGroup, finishUndoGroup, takeUndoGroup } from "./source-undo-groups.js";
 import { scalarValue, yamlContextAt } from "./source-yaml.js";
 import { markdownContextAt, markdownOptions, markdownPlan, markdownHoverAt } from "./source-markdown.js";
 import { childDoc, docNode, docText, fieldDoc } from "./source-docs.js";
-import { snippetJson, snippetYaml, snippetsFor } from "./source-snippets.js";
+import { keySnippetsFor, snippetJson, snippetYaml, snippetsFor } from "./source-snippets.js";
 
 export { contextAt, tokenAt };
 
@@ -114,16 +117,38 @@ function advancedShown(children, typed, explicit) {
   return children.some((child) => child.advanced && child.key.toLowerCase().startsWith(typed));
 }
 
-function keyOptions(context, text, caret, explicit) {
+/**
+ * The keys of an object in the order the list shows them (SPEC 4.4): the required ones first, then, for a slide with a layout, the keys the layout's
+ * regions call for that are not set yet, then the common order the schema gives (`children` arrives in that order and keeps it).
+ */
+function rankKeys(context, shown, catalogs) {
+  const slide = context.path.length === 2 && context.path[0] === "slides" ? valueAt(context.document, context.path) : undefined;
+  const layout = typeof slide?.layout === "string" ? slide.layout : undefined;
+  let wanted = [];
+  if (layout) {
+    try {
+      const record = listCatalogRecords(context.document, "layouts", { catalogs }).find((entry) => entry.id === layout)?.record;
+      wanted = layoutKeys(record, shown.map((child) => child.key));
+    } catch { wanted = []; }
+  }
+  const rank = (child) => (child.required ? 0 : wanted.includes(child.key) ? 1 : 2);
+  return shown.map((child, index) => ({ child, index })).sort((a, b) => rank(a.child) - rank(b.child) || (rank(a.child) === 1 ? wanted.indexOf(a.child.key) - wanted.indexOf(b.child.key) : a.index - b.index)).map((entry) => entry.child);
+}
+
+function keyOptions(context, text, caret, explicit, catalogs) {
   const info = describeField(context.path, context.document);
   const typed = text.slice(context.token.from, caret).toLowerCase();
   const options = [];
   if (info.known) {
     const free = info.children.filter((child) => !context.existing.has(child.key));
     const withAdvanced = advancedShown(free, typed, explicit);
-    const shown = free.filter((child) => !child.advanced || (withAdvanced && child.key.toLowerCase().startsWith(typed)));
+    const shown = rankKeys(context, free.filter((child) => !child.advanced || (withAdvanced && child.key.toLowerCase().startsWith(typed))), catalogs);
     // A blank document starts with a deck: its snippet comes first.
     if (context.blank) for (const entry of snippetsFor("value", [])) options.push(snippetOption(entry, 99));
+    // A key a snippet is written for (the deck's `design`, `organization`, `speaker`) is accepted as that snippet, as VS Code does for a property
+    // with default snippets: its members come with it, each a tab stop.
+    const keySnippets = snippetsFor("key", context.path);
+    const forKey = (key) => (context.flow ? undefined : keySnippetsFor(context.path).find((entry) => entry.key === key));
     shown.forEach((child, index) => options.push({
       label: child.key,
       type: "property",
@@ -131,10 +156,10 @@ function keyOptions(context, text, caret, explicit) {
       boost: boostAt(index + (context.blank ? 1 : 0)),
       opfRequired: child.required,
       opfDoc: child.description ?? "",
-      opf: { kind: "key", key: child.key },
+      opf: { kind: "key", key: child.key, ...(forKey(child.key) ? { snippet: child.key } : {}) },
       info: () => docNode(describeChild(context, child)),
     }));
-    for (const entry of snippetsFor("key", context.path)) options.push(snippetOption(entry, boostAt(options.length)));
+    for (const entry of keySnippets) options.push(snippetOption(entry, boostAt(options.length)));
     // A key right after a list dash is also the start of the item: the item snippets (a slide, a reference) fit there.
     if (context.itemStart) for (const entry of snippetsFor("item", context.path)) options.push(snippetOption(entry, boostAt(options.length)));
     return { options, advanced: withAdvanced };
@@ -183,12 +208,141 @@ function catalogOptions(kind, context, catalogs) {
   });
 }
 
-function valueOptions(context, catalogs) {
+// ---- cross references (SPEC 3.4) --------------------------------------------------------------------------------------------------------
+/**
+ * Where the references of the document are read from, for the context: `facts()` the assets, datasets, variables, references and the narrative
+ * (once), `read(path)` a value of the text being edited (a draft: undefined when the text does not say). `format` is the editor's: "json", "yaml"
+ * or "md" (the deck of a Markdown text is its front matter).
+ */
+export function referenceScope(context, text, format) {
+  let facts, parsed;
+  const deckParts = () => {
+    if (format === "json") return context.root ? jsonDeckParts(context.root, getNodeValue) : {};
+    if (format === "md") {
+      const front = scanMarkdown(text).frontMatter;
+      return front ? yamlDeckParts(text.slice(front.yamlFrom, front.yamlTo)) : {};
+    }
+    return yamlDeckParts(text);
+  };
+  return {
+    facts: () => (facts ??= factsOf(deckParts())),
+    read(path) {
+      if (format === "json") {
+        const node = context.root ? findNodeAtLocation(context.root, path) : undefined;
+        return node ? getNodeValue(node) : undefined;
+      }
+      if (parsed === undefined) {
+        try { parsed = parseDocument(context.sourceText ?? text, { strict: false, uniqueKeys: false }).toJS({ maxAliasCount: -1 }); } catch { parsed = null; }
+      }
+      return valueAt(parsed, path.slice(context.prefix?.length ?? 0));
+    },
+  };
+}
+
+const REFERENCE_LABELS = { asset: "asset", dataset: "dataset", datasetColumn: "dataset column", cite: "reference", beat: "narrative beat", region: "layout region", color: "color variable" };
+const referenceOption = (id, value, extra) => literalOption(id, JSON.stringify(value), { type: "reference", value, ...extra });
+
+function referenceOptions(site, context, catalogs, scope) {
+  const facts = scope.facts();
+  const options = [];
+  const add = (id, value, extra = {}) => options.push(referenceOption(id, value, { boost: boostAt(options.length), info: () => docNode({ title: id, type: REFERENCE_LABELS[site.kind], description: extra.doc || undefined, notes: [extra.detail].filter(Boolean) }), ...extra }));
+  switch (site.kind) {
+    case "asset":
+      for (const asset of facts.assets) add(`asset:${asset.id}`, `asset:${asset.id}`, { detail: asset.detail || "asset", doc: asset.detail });
+      for (const variable of facts.variables) if (variable.type === "image") add(`var:${variable.id}`, `var:${variable.id}`, { detail: "image variable" });
+      break;
+    case "dataset":
+      for (const dataset of facts.datasets) add(dataset.id, dataset.id, { detail: dataset.title || `${dataset.columns.length} columns`, doc: dataset.columns.join(", ") });
+      break;
+    case "datasetColumn": {
+      const source = columnSourceFor(site, (path) => scope.read(path));
+      const columns = source?.dataset !== undefined ? facts.datasets.find((entry) => entry.id === source.dataset)?.columns : source?.inline;
+      for (const column of columns ?? []) add(column, column, { detail: source.dataset !== undefined ? `column of ${source.dataset}` : "column" });
+      break;
+    }
+    case "cite":
+      for (const reference of facts.references) add(reference.id, reference.id, { detail: brief(reference.text) ?? "reference", doc: reference.text });
+      break;
+    case "beat": {
+      let record;
+      if (facts.narrative) {
+        try { record = listCatalogRecords(context.document, "narratives", { catalogs }).find((entry) => entry.id === facts.narrative)?.record; } catch { record = undefined; }
+      }
+      for (const beat of beatsOf(record)) add(beat.id, beat.id, { detail: beat.name || "beat", doc: brief(beat.description) });
+      break;
+    }
+    case "region": {
+      const slide = slidePath(context.path);
+      const layout = slide ? valueAt(context.document, slide)?.layout : undefined;
+      let names = [];
+      if (typeof layout === "string") {
+        try { names = regionNames(listCatalogRecords(context.document, "layouts", { catalogs }).find((entry) => entry.id === layout)?.record); } catch { names = []; }
+      }
+      for (const name of names) add(name, name, { detail: `region of ${layout}` });
+      for (const name of PROMOTED_REGIONS) if (!names.includes(name)) add(name, name, { detail: "promoted region" });
+      break;
+    }
+    case "color":
+      for (const variable of facts.variables) if (variable.type === "color") add(`var:${variable.id}`, `var:${variable.id}`, { detail: "color variable" });
+      break;
+    default:
+  }
+  return options;
+}
+
+// `{{name}}` in a text, offered once `{{` is typed: the variables the document declares first, then the built-in ones the engine resolves
+// (`deck.*`, `speaker.*`, `organization.*`, `slide.*`), grouped by prefix, each saying whether the document sets it. `before` is the text of the value
+// before the caret.
+const VARIABLE_OPEN = /\{\{([A-Za-z0-9._-]*)$/;
+function variableOptions(scope) {
+  const facts = scope.facts();
+  const options = [];
+  variableNames(facts).forEach((variable) => options.push({ label: variable.id, type: "reference", detail: `${variable.type} variable`, boost: boostAt(options.length), opfDoc: `The variable ${variable.id}`, opf: { kind: "variable", name: variable.id } }));
+  for (const builtin of builtinVariables(facts)) {
+    options.push({
+      label: builtin.name, type: "reference", detail: builtin.detail, boost: boostAt(options.length), opfDoc: builtin.doc, opf: { kind: "variable", name: builtin.name, builtin: true },
+      info: () => docNode({ title: builtin.name, type: "built-in variable", description: builtin.doc, notes: [builtin.available ? "" : "Not set in this document"].filter(Boolean) }),
+    });
+  }
+  return options;
+}
+
+/** The result for a caret right after `{{` in a text value, or null: the variable names, replacing what is typed after the braces. */
+function variableResult(context, text, position, scope) {
+  const token = context.token;
+  if (!token || context.mode === "key") return null;
+  const open = VARIABLE_OPEN.exec(text.slice(token.from, Math.min(position, token.to)));
+  return open ? variableList(scope, position - open[1].length, position) : null;
+}
+
+function variableList(scope, from, position) {
+  const options = variableOptions(scope);
+  return options.length ? { from, to: position, filter: true, options, validFor: (typed) => /^[A-Za-z0-9._-]*$/.test(typed) } : null;
+}
+
+/**
+ * The line under a list of catalog records when a group of the document names a source no registered catalog matches (SPEC 4.5): its records
+ * beyond the embedded ones are not available here. Empty when every source is registered.
+ */
+export function unloadedFooter(document, catalogs) {
+  const groups = document && typeof document === "object" ? document.catalogs : undefined;
+  if (!groups || typeof groups !== "object") return "";
+  let registered = [];
+  try { registered = mergeCatalogs(catalogs).map((entry) => entry.source); } catch { registered = []; }
+  const names = Object.entries(groups).filter(([name, group]) => name !== "custom" && group && typeof group === "object" && typeof group.source === "string" && !registered.includes(group.source)).map(([name]) => name);
+  return names.length ? `Records from catalog ${names.join(", ")} are not loaded` : "";
+}
+
+function valueOptions(context, catalogs, scope) {
   const info = describeField(context.path, context.document);
   const options = [];
   if (!info.known) return { options };
   const variant = primaryVariant(info);
-  if (info.catalogKind) options.push(...catalogOptions(info.catalogKind, context, catalogs));
+  const site = scope ? referenceSiteAt(context.path, context.document) : null;
+  if (info.catalogKind) {
+    const footer = unloadedFooter(context.document, catalogs);
+    for (const option of catalogOptions(info.catalogKind, context, catalogs)) options.push(footer ? { ...option, opfFooter: footer } : option);
+  }
   else if (info.enum?.length) {
     // In the order VS Code lists them: by label.
     info.enum.forEach((entry) => options.push(literalOption(String(entry.value), JSON.stringify(entry.value), {
@@ -201,6 +355,7 @@ function valueOptions(context, catalogs) {
     const label = variant.type === "object" ? "{}" : "[]";
     options.push({ label, type: "keyword", detail: variant.type === "object" ? "object" : "list", boost: 99, opfDoc: info.description ?? "", opf: { kind: "template" }, info: () => docNode(fieldDoc(info, context.key ?? label)) });
   }
+  if (site) options.push(...referenceOptions(site, context, catalogs, scope));
   for (const entry of snippetsFor(context.mode, context.path)) options.push(snippetOption(entry, boostAt(options.length)));
   return { options };
 }
@@ -234,12 +389,15 @@ export function completionResult(state, position, { explicit, catalogs, format =
   const text = state.doc.toString();
   let context = contextFor(format, text, position, explicit);
   if (!context) return null;
-  if (context.format === "md") return markdownResult(context, text, position, { explicit, catalogs });
+  const scope = referenceScope(context, text, format);
+  if (context.format === "md") return context.region === "variable" ? variableList(scope, context.token.from, position) : markdownResult(context, text, position, { explicit, catalogs, scope });
   if (context.format === "yaml") {
     context = settleYamlContext(context, text);
     if (!context) return null;
   }
-  const { options, advanced } = context.mode === "key" ? keyOptions(context, text, position, explicit) : valueOptions(context, catalogs);
+  const variables = context.mode !== "key" ? variableResult(context, text, position, scope) : null;
+  if (variables || context.multiline) return variables;
+  const { options, advanced } = context.mode === "key" ? keyOptions(context, text, position, explicit, catalogs) : valueOptions(context, catalogs, scope);
   if (!options.length) return null;
   return listResult(context, options, advanced, { position, explicit });
 }
@@ -261,8 +419,8 @@ function listResult(context, options, advanced, { position, explicit }) {
   };
 }
 
-function markdownResult(context, text, position, { explicit, catalogs }) {
-  const built = markdownOptions(context, { catalogs, explicit, text, position, makers: { snippetOption, literalOption, boostAt, docNode, valueOptions, listCatalogRecords } });
+function markdownResult(context, text, position, { explicit, catalogs, scope }) {
+  const built = markdownOptions(context, { catalogs, explicit, text, position, scope, makers: { snippetOption, literalOption, boostAt, docNode, valueOptions, listCatalogRecords } });
   if (!built?.options.length) return null;
   const { token } = context;
   return {
@@ -289,9 +447,14 @@ const yamlKey = (key) => (/^[A-Za-z_$][A-Za-z0-9_.$+-]*(?::[A-Za-z0-9_.$+-]+)*$/
 const escapeTemplate = (text) => text.replace(/[\\{}]/g, (character) => `\\${character}`);
 
 /** What accepting a key writes in YAML: `key: ` for a scalar, `key:` and a new line for a mapping or a list. */
-function yamlKeyPlan(context, key, text, end) {
+function yamlKeyPlan(context, key, text, end, snippetKey) {
   const written = yamlKey(key);
   if (/^[ \t]*:/.test(text.slice(end))) return { template: escapeTemplate(written), fields: 0, chain: false };
+  const entry = snippetKey ? keySnippetsFor(context.path).find((candidate) => candidate.key === snippetKey) : undefined;
+  if (entry && !context.flow) {
+    const rendered = snippetYaml(entry, { dash: 0 });
+    return { template: rendered.text, fields: rendered.fields.length, chain: false, choices: rendered.fields };
+  }
   let info;
   try { info = describeField([...context.path, key], context.document); } catch { info = null; }
   const kind = info?.known ? variantKind(info) : "string";
@@ -313,7 +476,7 @@ function yamlKeyPlan(context, key, text, end) {
 /** What accepting `completion` writes in YAML: `{ start, end, template, fields, chain, choices }`. */
 function planYaml(context, completion, text, end) {
   const kind = completion.opf?.kind;
-  if (kind === "key") return yamlKeyPlan(context, completion.opf.key, text, end);
+  if (kind === "key") return yamlKeyPlan(context, completion.opf.key, text, end, completion.opf.snippet);
   if (kind === "literal") {
     const value = completion.opf.value;
     const prefix = context.needsSpace ? " " : "";
@@ -345,6 +508,11 @@ export function planCompletion(context, completion, text, end) {
     const key = completion.opf.key;
     const quoted = JSON.stringify(key);
     if (/^\s*:/.test(text.slice(end))) return { template: quoted, fields: 0, chain: false };
+    const entry = completion.opf.snippet ? keySnippetsFor(context.path).find((candidate) => candidate.key === completion.opf.snippet) : undefined;
+    if (entry) {
+      const rendered = snippetJson(entry, { comma: needsComma });
+      return { template: rendered.text, fields: rendered.fields.length, chain: false, choices: rendered.fields };
+    }
     let info;
     try { info = describeField([...context.path, key], context.document); } catch { info = null; }
     const value = info?.known ? valueTemplate(info) : { template: '"${1}"', fields: 1, chain: false };
@@ -363,7 +531,7 @@ export function planCompletion(context, completion, text, end) {
   if (kind === "snippet") {
     const entry = snippetsFor(context.mode, context.path).find((candidate) => candidate.prefix === completion.opf.prefix);
     if (!entry) return null;
-    const rendered = snippetJson(entry, { comma: needsComma && context.mode !== "key" });
+    const rendered = snippetJson(entry, { comma: needsComma && !/^\s*:/.test(text.slice(end)) });
     return { template: rendered.text, fields: rendered.fields.length, chain: false, choices: rendered.fields };
   }
   return null;
@@ -374,10 +542,20 @@ export function applyCompletion(view, completion, fallbackFrom, fallbackTo, say,
   const { state } = view;
   const text = state.doc.toString();
   const main = state.selection.main;
+  if (completion.opf?.kind === "variable") { applyVariable(view, completion, fallbackFrom, fallbackTo); return; }
+  // A value accepted right after the key that opened its list is one undo step with that key (R-CMP-14).
+  const group = takeUndoGroup(view);
   const context = contextFor(format, text, main.head, true);
   const token = context?.token;
   const start = token ? token.start : fallbackFrom, end = token ? token.end : fallbackTo;
   const plan = context ? planCompletion(context, completion, text, end) : null;
+  // Accepting is one undo step: what is typed next starts another.
+  const finish = (chain) => {
+    view.dispatch({ annotations: isolateHistory.of("full") });
+    if (group) finishUndoGroup(view, group);
+    // A key whose value is one of a closed set opens that list at once.
+    if (chain) { beginUndoGroup(view, state.doc); startCompletion(view); }
+  };
   if (!plan) {
     view.dispatch({ changes: { from: fallbackFrom, to: fallbackTo, insert: completion.label }, selection: { anchor: fallbackFrom + completion.label.length }, annotations: [pickedCompletion.of(completion)], userEvent: "input.complete" });
     return;
@@ -393,6 +571,7 @@ export function applyCompletion(view, completion, fallbackFrom, fallbackTo, say,
     if (next !== "" && !",}]".includes(next)) changes.push({ from: token.end, insert: "," });
     const caret = inSnippet ? token.from + inner.length : token.end + inner.length - (token.to - token.from);
     view.dispatch({ changes, selection: { anchor: caret }, annotations: [pickedCompletion.of(completion)], userEvent: "input.complete", scrollIntoView: true });
+    finish(false);
     return;
   }
   // YAML and Markdown values inside quotes: only the inside changes, and the caret ends after the closing quote.
@@ -400,6 +579,7 @@ export function applyCompletion(view, completion, fallbackFrom, fallbackTo, say,
     const insert = plan.template.replace(/\\([{}\\])/g, "$1");
     const caret = token.closed ? token.end + insert.length - (token.to - token.from) : token.from + insert.length;
     view.dispatch({ changes: { from: token.from, to: token.to, insert }, selection: { anchor: caret }, annotations: [pickedCompletion.of(completion)], userEvent: "input.complete", scrollIntoView: true });
+    finish(false);
     return;
   }
   const from = plan.replaceFrom ?? start, to = plan.replaceTo ?? end;
@@ -407,16 +587,46 @@ export function applyCompletion(view, completion, fallbackFrom, fallbackTo, say,
     snippet(plan.template)(view, completion, from, to);
     if (plan.choices) snippetRuns.set(view, { fields: plan.choices, index: -1 });
     else snippetRuns.delete(view);
-    if (plan.choices) snippetStep(view, true, { start: true, say });
+    if (plan.choices) snippetStep(view, true, { start: true, say: say && ((message) => say(`Inserted ${completion.label}. ${message}`)) });
   } else {
     const insert = plan.template.replace(/\\([{}\\])/g, "$1");
     view.dispatch({ changes: { from, to, insert }, selection: { anchor: from + insert.length }, annotations: [pickedCompletion.of(completion)], userEvent: "input.complete", scrollIntoView: true });
     snippetRuns.delete(view);
   }
-  // Accepting is one undo step: what is typed next starts another.
-  view.dispatch({ annotations: isolateHistory.of("full") });
-  // A key whose value is one of a closed set opens that list at once.
-  if (plan.chain) startCompletion(view);
+  finish(plan.chain);
+}
+
+/**
+ * `{{na|` becomes `{{name}}`: the name replaces what was typed after the braces and the closing braces are written unless they are there. With
+ * several cursors it does so at each of them, in one undo step. A cursor with no `{{` before it replaces as many characters as the main cursor's typed
+ * name when they are the same text (VS Code applies the item at every cursor the same way), and adds the braces all the same.
+ */
+function applyVariable(view, completion, fallbackFrom, fallbackTo) {
+  const { state } = view;
+  const text = state.doc.toString();
+  const insert = `${completion.opf.name}}}`;
+  const annotations = [pickedCompletion.of(completion), isolateHistory.of("full")];
+  if (state.selection.ranges.length <= 1) {
+    const to = text.startsWith("}}", fallbackTo) ? fallbackTo + 2 : fallbackTo;
+    view.dispatch({ changes: { from: fallbackFrom, to, insert }, selection: { anchor: fallbackFrom + insert.length }, annotations, userEvent: "input.complete", scrollIntoView: true });
+    return;
+  }
+  const typed = text.slice(fallbackFrom, fallbackTo);
+  const sorted = [...state.selection.ranges].sort((a, b) => a.from - b.from);
+  const changes = [], carets = [];
+  let shift = 0;
+  for (const range of sorted) {
+    const head = range.head;
+    const open = VARIABLE_OPEN.exec(text.slice(Math.max(0, head - 200), head));
+    const length = open ? open[1].length : text.slice(head - typed.length, head) === typed ? typed.length : 0;
+    const from = head - length;
+    const to = text.startsWith("}}", head) ? head + 2 : head;
+    changes.push({ from, to, insert });
+    carets.push(from + shift + insert.length);
+    shift += insert.length - (to - from);
+  }
+  const main = sorted.indexOf(state.selection.main);
+  view.dispatch({ changes, selection: EditorSelection.create(carets.map((position) => EditorSelection.cursor(position)), Math.max(0, main)), annotations, userEvent: "input.complete", scrollIntoView: true });
 }
 
 // With several cursors the item goes in at each of them as plain text (no tab stops), each over its own token.