@openpresentation/opf-editor 0.26.4 → 0.26.6

package/dist/source-references.js

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

package/dist/source-shortcuts.js

@@ -0,0 +1,106 @@
+// The keyboard shortcuts dialog (artifacts/source-editor/SPEC.md, section 8.6): every binding the editor installed, grouped and searchable, with the keys
+// of the platform. The list is `getShortcuts()`, produced from the same table that installs the keymap (source-keymap.js), so it cannot drift from the keys.
+// Cmd/Ctrl+K Cmd/Ctrl+S, F1 or the "?" button of the source pane open it; Escape closes it and returns focus to the editor. A host that wants its own
+// dialog passes `onShowShortcuts(shortcuts)` and returns true. Plain DOM, loaded lazily.
+const FOCUSABLE = 'button, input, [tabindex]:not([tabindex="-1"])';
+let counter = 0;
+const open = new WeakMap();
+
+const element = (doc, tag, className, attributes = {}) => {
+  const node = doc.createElement(tag);
+  if (className) node.className = className;
+  for (const [key, value] of Object.entries(attributes)) node.setAttribute(key, value);
+  return node;
+};
+
+/** The words a search looks in: title, group, id and the keys with `+`, `-` and spaces folded to spaces. */
+const haystack = (row) => `${row.title} ${row.group} ${row.id} ${row.when ?? ""} ${row.keys.join(" ")}`.toLowerCase().replace(/[+-]/g, " ");
+export const matches = (row, query) => {
+  const words = query.toLowerCase().replace(/[+-]/g, " ").split(/\s+/).filter(Boolean);
+  const text = haystack(row);
+  return words.every((word) => text.includes(word));
+};
+
+/** Open the dialog for `view` (or close it when it is open). Returns true: the key was taken. */
+export function showShortcuts(view, context) {
+  const shortcuts = context.getShortcuts();
+  if (context.options.onShowShortcuts?.(shortcuts) === true) return true;
+  const existing = open.get(view);
+  if (existing) { existing.close(); return true; }
+  const doc = view.dom.ownerDocument;
+  const host = view.dom.closest(".opf-ui") ?? doc.body;
+  const opener = doc.activeElement;
+  const id = `opf-shortcuts-${++counter}`;
+  const root = element(doc, "div", `opf-shortcuts${host === doc.body ? " opf-ui" : ""}`);
+  const dialog = element(doc, "div", "opf-shortcuts-dialog", { role: "dialog", "aria-modal": "true", "aria-labelledby": `${id}-title`, "aria-describedby": `${id}-help`, tabindex: "-1" });
+  const head = element(doc, "div", "opf-shortcuts-head");
+  const title = Object.assign(element(doc, "h2", "opf-shortcuts-title", { id: `${id}-title` }), { textContent: "Keyboard shortcuts" });
+  const closeButton = Object.assign(element(doc, "button", "opf-shortcuts-close", { type: "button", "aria-label": "Close the keyboard shortcuts" }), { textContent: "×" });
+  head.append(title, closeButton);
+  const help = Object.assign(element(doc, "p", "opf-shortcuts-help", { id: `${id}-help` }), { textContent: `Keys for ${context.platform === "mac" ? "macOS" : context.platform === "win" ? "Windows" : "Linux"}. Type to search by name or key; Escape closes.` });
+  const search = element(doc, "input", "opf-shortcuts-search", { type: "search", "aria-label": "Search the keyboard shortcuts", placeholder: "Search shortcuts", autocomplete: "off", spellcheck: "false" });
+  const status = element(doc, "div", "opf-shortcuts-status", { role: "status", "aria-live": "polite" });
+  const list = element(doc, "div", "opf-shortcuts-list", { tabindex: "0", role: "region", "aria-label": "Shortcuts" });
+  dialog.append(head, help, search, status, list);
+  root.append(dialog);
+  host.append(root);
+
+  const plural = (count) => `${count} ${count === 1 ? "shortcut" : "shortcuts"}`;
+  function render() {
+    const rows = shortcuts.filter((row) => matches(row, search.value));
+    list.replaceChildren();
+    let group = null, section = null;
+    for (const row of rows) {
+      if (row.group !== group) {
+        group = row.group;
+        section = element(doc, "section", "opf-shortcuts-group", { "aria-label": group });
+        section.append(Object.assign(element(doc, "h3", "opf-shortcuts-group-title"), { textContent: group }));
+        list.append(section);
+      }
+      const item = element(doc, "div", "opf-shortcuts-row", { "data-id": row.id });
+      const name = element(doc, "span", "opf-shortcuts-name");
+      name.append(document.createTextNode(row.title));
+      if (row.when) name.append(Object.assign(element(doc, "span", "opf-shortcuts-when"), { textContent: ` (${row.when})` }));
+      const keys = element(doc, "span", "opf-shortcuts-keys");
+      row.keys.forEach((keyText, index) => {
+        if (index) keys.append(Object.assign(element(doc, "span", "opf-shortcuts-or"), { textContent: "or" }));
+        for (const stroke of keyText.split(" ")) keys.append(Object.assign(element(doc, "kbd", "opf-shortcuts-key"), { textContent: stroke }));
+      });
+      item.append(name, keys);
+      section.append(item);
+    }
+    if (!rows.length) list.append(Object.assign(element(doc, "p", "opf-shortcuts-none"), { textContent: "No shortcut matches." }));
+    status.textContent = search.value ? `${plural(rows.length)} match` : plural(rows.length);
+  }
+
+  function focusables() { return [...dialog.querySelectorAll(FOCUSABLE)].filter((node) => node.getClientRects().length); }
+  function onKeydown(event) {
+    if (event.key === "Escape") { event.preventDefault(); event.stopPropagation(); close(); return; }
+    if (event.key !== "Tab") return;
+    const nodes = focusables();
+    if (!nodes.length) { event.preventDefault(); dialog.focus(); return; }
+    const first = nodes[0], last = nodes.at(-1), active = doc.activeElement;
+    if (event.shiftKey && (active === first || active === dialog)) { event.preventDefault(); last.focus(); }
+    else if (!event.shiftKey && active === last) { event.preventDefault(); first.focus(); }
+    else if (!dialog.contains(active)) { event.preventDefault(); first.focus(); }
+  }
+  function onFocusin(event) { if (!dialog.contains(event.target)) (focusables()[0] ?? dialog).focus(); }
+  function close() {
+    if (!open.has(view)) return;
+    open.delete(view);
+    doc.removeEventListener("focusin", onFocusin, true);
+    root.remove();
+    if (view.dom.isConnected) view.focus(); else if (opener?.isConnected) opener.focus();
+    context.say("Keyboard shortcuts closed");
+  }
+  open.set(view, { close });
+  root.addEventListener("keydown", onKeydown);
+  root.addEventListener("pointerdown", (event) => { if (event.target === root) close(); });
+  closeButton.addEventListener("click", close);
+  search.addEventListener("input", render);
+  doc.addEventListener("focusin", onFocusin, true);
+  render();
+  search.focus();
+  context.say(`Keyboard shortcuts, ${plural(shortcuts.length)}. Type to search, Escape to close.`);
+  return true;
+}

package/dist/source-snippets.js

@@ -76,6 +76,18 @@ export const SNIPPETS = Object.freeze([
   { prefix: "notes", where: "markdown", key: "notes", description: "Speaker notes for the slide", fragment: ph(1, "Speaker notes") },
 ]);
 
+/**
+ * Snippets a KEY of the deck is accepted as (SPEC 5: `design`, `organization`, `speaker`): not items of the list on their own (`SNIPPETS` holds
+ * those), but what accepting the property writes, as VS Code does for a property with default snippets. The fragment is the value of the key. They hold
+ * the required members of the object, each a tab stop (SPEC 5 lists only `name` for the speaker; the Speaker schema requires an id too), and `design`
+ * opens the list of the catalog at each stop.
+ */
+export const KEY_SNIPPETS = Object.freeze([
+  { prefix: "design", where: "deck-key", key: "design", description: "The design of the deck: a theme, a color scheme and a font scheme", fragment: { theme: ph(1, "", { choice: true }), colorScheme: ph(2, "", { choice: true }), fontScheme: ph(3, "", { choice: true }) } },
+  { prefix: "organization", where: "deck-key", key: "organization", description: "The organization presenting the deck: an id and a name", fragment: { id: ph(1, "acme"), name: ph(2, "Acme Inc.") } },
+  { prefix: "speaker", where: "deck-key", key: "speaker", description: "The person presenting the deck: an id and a name", fragment: { id: ph(1, "alice"), name: ph(2, "Name") } },
+]);
+
 /** 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);
@@ -88,6 +100,14 @@ export function snippetsFor(mode, path) {
   });
 }
 
+/**
+ * The snippets a key of the object at `path` is accepted as (the deck's `design`, `organization`, `speaker`): not items of their own in the list,
+ * but what accepting that property writes, as VS Code does for a property with default snippets.
+ */
+export function keySnippetsFor(path) {
+  return path.length === 0 ? KEY_SNIPPETS : [];
+}
+
 /** The JSON text of a snippet for insertion: `{ text, fields }`; a dataset is a `"name": { ... }` entry. */
 export function snippetJson(snippet, { comma = false } = {}) {
   if (snippet.key !== undefined) {

package/dist/source-symbols.js

@@ -0,0 +1,156 @@
+// The outline of an OPF document (artifacts/source-editor/SPEC.md, section 8.4): the symbols the picker (Cmd/Ctrl+Shift+O) and the outline panel list, for
+// JSON, YAML and Markdown, read from text that may be broken. A symbol is `{ id, kind, label, detail, depth, from, to, line }` with source offsets:
+// the slides in order ("3. Highlights"), the top-level sections (design, organization, speaker), the assets, datasets, variables and references the
+// document declares, and the catalog records it embeds. Plain functions, no DOM.
+import { parseTree } from "jsonc-parser";
+import { isMap, parseDocument } from "yaml";
+import { scanMarkdown } from "@openpresentation/opf/source";
+
+const SECTIONS = ["design", "organization", "speaker"];
+const DECLARED = [["assets", "asset"], ["datasets", "dataset"], ["variables", "variable"]];
+const CATALOG_KINDS = { layouts: "layout", themes: "theme", colorSchemes: "color scheme", fontSchemes: "font scheme", narratives: "narrative", audiences: "audience", purposes: "purpose", tones: "tone" };
+
+// ---- one tree for the three readers ------------------------------------------------------------------------------------------------------
+// `{ type: "object" | "array" | "scalar", value?, from, to, entries?: [{ key, from, to, node }], items?: [node] }`, offsets in the text.
+function fromJson(text) {
+  const root = parseTree(text, [], { allowTrailingComma: true, disallowComments: false });
+  const convert = (node) => {
+    if (!node) return null;
+    const base = { from: node.offset, to: node.offset + node.length };
+    if (node.type === "object") return { ...base, type: "object", entries: (node.children ?? []).filter((property) => property.children?.[0]).map((property) => ({ key: String(property.children[0].value), from: property.offset, to: property.offset + property.length, node: convert(property.children[1]) })) };
+    if (node.type === "array") return { ...base, type: "array", items: (node.children ?? []).map(convert) };
+    return { ...base, type: "scalar", value: node.value };
+  };
+  return convert(root);
+}
+
+function fromYamlNode(node, shift = 0) {
+  if (!node) return null;
+  const range = node.range ?? [0, 0, 0];
+  const base = { from: range[0] + shift, to: range[1] + shift };
+  if (isMap(node)) {
+    return { ...base, type: "object", entries: node.items.filter((pair) => pair.key).map((pair) => ({ key: String(pair.key.value ?? pair.key), from: (pair.key.range?.[0] ?? range[0]) + shift, to: (pair.value?.range?.[1] ?? pair.key.range?.[1] ?? range[1]) + shift, node: fromYamlNode(pair.value, shift) })) };
+  }
+  if (node.items) return { ...base, type: "array", items: node.items.map((item) => fromYamlNode(item, shift)) };
+  return { ...base, type: "scalar", value: node.value };
+}
+function fromYaml(text, shift = 0) {
+  try { return fromYamlNode(parseDocument(text, { strict: false, uniqueKeys: false }).contents, shift); } catch { return null; }
+}
+
+const lineStarts = (text) => { const starts = [0]; for (let i = 0; i < text.length; i++) if (text[i] === "\n") starts.push(i + 1); return starts; };
+const lineOf = (starts, offset) => { let low = 0, high = starts.length - 1; while (low < high) { const mid = (low + high + 1) >> 1; if (starts[mid] <= offset) low = mid; else high = mid - 1; } return low + 1; };
+
+// ---- helpers -----------------------------------------------------------------------------------------------------------------------------
+const entry = (node, key) => (node?.type === "object" ? node.entries.find((candidate) => candidate.key === key) : undefined);
+const scalar = (node) => (node?.type === "scalar" && typeof node.value === "string" ? node.value : undefined);
+/** A title as text: a string, or the text of a list of runs. */
+function titleOf(node) {
+  if (!node) return "";
+  if (node.type === "scalar") return typeof node.value === "string" ? node.value : "";
+  if (node.type === "array") return node.items.map((item) => (item?.type === "scalar" ? String(item.value ?? "") : titleOf(entry(item, "text")?.node))).join("");
+  return "";
+}
+const clip = (text, max = 80) => { const flat = text.replace(/\s+/g, " ").trim(); return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat; };
+
+function symbolsOfTree(root, starts, { slides = true } = {}) {
+  const out = [];
+  const add = (kind, label, detail, depth, from, to) => out.push({ id: `${kind}:${out.length}`, kind, label, detail, depth, from, to, line: lineOf(starts, from) });
+  if (root?.type !== "object") return out;
+  if (slides) {
+    const list = entry(root, "slides")?.node;
+    if (list?.type === "array") {
+      list.items.forEach((item, index) => {
+        if (!item) return;
+        const title = clip(titleOf(entry(item, "title")?.node));
+        const layout = scalar(entry(item, "layout")?.node), type = scalar(entry(item, "type")?.node);
+        add("slide", `${index + 1}. ${title || "Untitled slide"}`, [layout && `layout ${layout}`, !layout && type].filter(Boolean).join(" "), 0, item.from, item.to);
+      });
+    }
+  }
+  for (const key of SECTIONS) {
+    const found = entry(root, key);
+    if (found?.node?.type === "object") add("section", key, "", 0, found.from, found.to);
+  }
+  for (const [key, kind] of DECLARED) {
+    const found = entry(root, key);
+    if (found?.node?.type !== "object" || !found.node.entries.length) continue;
+    add("section", key, `${found.node.entries.length}`, 0, found.from, found.to);
+    for (const child of found.node.entries) add(kind, child.key, kind === "dataset" ? scalar(entry(child.node, "title")?.node) ?? "" : "", 1, child.from, child.to);
+  }
+  const references = entry(root, "references")?.node;
+  if (references?.type === "array" && references.items.length) {
+    add("section", "references", `${references.items.length}`, 0, entry(root, "references").from, entry(root, "references").to);
+    for (const item of references.items) { const id = scalar(entry(item, "id")?.node); if (id && item) add("reference", id, clip(scalar(entry(item, "text")?.node) ?? "", 50), 1, item.from, item.to); }
+  }
+  const catalogs = entry(root, "catalogs");
+  if (catalogs?.node?.type === "object") {
+    for (const group of catalogs.node.entries) {
+      if (group.node?.type !== "object") continue;
+      for (const [kindKey, kindLabel] of Object.entries(CATALOG_KINDS)) {
+        const records = entry(group.node, kindKey)?.node;
+        if (records?.type === "object") for (const record of records.entries) add("record", `${kindLabel} ${record.key}`, group.key === "custom" ? "this document" : group.key, 0, record.from, record.to);
+        else if (records?.type === "array") for (const record of records.items) { const id = scalar(entry(record, "id")?.node); if (id && record) add("record", `${kindLabel} ${id}`, group.key === "custom" ? "this document" : group.key, 0, record.from, record.to); }
+      }
+    }
+  }
+  // Slides first, as the document reads: sort the rest by position inside their kind order is not needed; the list keeps slides, then the sections in
+  // the order of the text so the picker's order is the document's order.
+  return out.sort((a, b) => a.from - b.from).map((symbol, index) => ({ ...symbol, id: `${symbol.kind}:${index}` }));
+}
+
+// ---- Markdown ----------------------------------------------------------------------------------------------------------------------------
+function markdownSymbols(text, starts) {
+  const scan = scanMarkdown(text);
+  const out = [];
+  if (scan.frontMatter?.closed) {
+    const tree = fromYaml(text.slice(scan.frontMatter.yamlFrom, scan.frontMatter.yamlTo), scan.frontMatter.yamlFrom);
+    out.push(...symbolsOfTree(tree, starts, { slides: false }));
+  }
+  const skipped = [...scan.fences, ...scan.comments].map((range) => [range.from, range.to]);
+  for (const slide of scan.slides) {
+    let title = "", layout;
+    const slideComment = scan.comments.find((comment) => comment.kind === "slide" && comment.slide === slide.index);
+    if (slideComment) layout = /\blayout=("?)([A-Za-z0-9_:-]+)\1/.exec(text.slice(slideComment.innerFrom, slideComment.innerTo))?.[2];
+    const body = text.slice(slide.from, slide.to);
+    let offset = 0;
+    for (const line of body.split("\n")) {
+      const at = slide.from + offset;
+      offset += line.length + 1;
+      if (skipped.some(([from, to]) => at >= from && at < to)) continue;
+      const heading = /^#\s+(.*?)\s*#*\s*$/.exec(line);
+      if (heading) { title = heading[1].replace(/[*_`[\]]/g, ""); break; }
+    }
+    out.push({ id: "", kind: "slide", label: `${slide.index + 1}. ${clip(title) || "Untitled slide"}`, detail: layout ? `layout ${layout}` : "", depth: 0, from: slide.from, to: slide.to, line: slide.line });
+  }
+  return out.sort((a, b) => a.from - b.from).map((symbol, index) => ({ ...symbol, id: `${symbol.kind}:${index}` }));
+}
+
+/** The symbols of `text` in `format` ("json", "yaml" or "md"), in document order. Never throws. */
+export function documentSymbols(format, text) {
+  try {
+    const starts = lineStarts(text);
+    const symbols = format === "md" ? markdownSymbols(text, starts) : symbolsOfTree(format === "yaml" ? fromYaml(text) : fromJson(text), starts);
+    // A YAML block ends with its line break: the range of a symbol stops at its last visible character.
+    return symbols.map((symbol) => { let to = Math.min(symbol.to, text.length); while (to > symbol.from + 1 && /\s/.test(text[to - 1])) to--; return { ...symbol, to }; });
+  } catch { return []; }
+}
+
+/** The innermost symbol that contains `offset` (the slide the caret is in), or null. */
+export function symbolAt(symbols, offset) {
+  let found = null;
+  for (const symbol of symbols) if (symbol.from <= offset && offset <= symbol.to && (!found || symbol.to - symbol.from <= found.to - found.from)) found = symbol;
+  return found;
+}
+
+/** The symbols that match what was typed: every word is in the label, detail or kind; failing that, the letters in order (a fuzzy match). */
+export function filterSymbols(symbols, query) {
+  const words = query.toLowerCase().split(/\s+/).filter(Boolean);
+  if (!words.length) return symbols;
+  const text = (symbol) => `${symbol.label} ${symbol.detail} ${symbol.kind}`.toLowerCase();
+  const exact = symbols.filter((symbol) => words.every((word) => text(symbol).includes(word)));
+  if (exact.length) return exact;
+  const letters = words.join("");
+  return symbols.filter((symbol) => { let at = 0; for (const character of text(symbol)) if (character === letters[at]) at++; return at === letters.length; });
+}
+

package/dist/source-undo-groups.js

@@ -0,0 +1,46 @@
+// One undo step for a suggestion and the value list it opened (artifacts/source-editor/SPEC.md, section 4.6, item 4; TEST-PLAN J-INS-017). Accepting a key
+// of a closed set of values writes `"key": ""` and opens the list of the values; accepting a value is a second edit. Each is an edit of its own in
+// CodeMirror's history, as every accepted suggestion is, so the pair is recorded here and Undo and Redo step over both: one Cmd+Z puts back the text
+// the author had typed before accepting the key (VS Code: "accept is one step with its typed prefix undoable"). Anything typed in between, or any
+// other edit after the pair, makes the pair void, so Undo is the plain one again. Plain functions over an editor view, no DOM.
+import { redo, undo, undoDepth, redoDepth } from "@codemirror/commands";
+
+const pending = new WeakMap();
+const pairs = new WeakMap();
+
+/** A suggestion that opens a list of values was accepted: the text before it and after it. */
+export function beginUndoGroup(view, before) {
+  pending.set(view, { before, after: view.state.doc });
+}
+
+/** A suggestion is about to be accepted: the pair it completes (the key accepted just before, with nothing typed since), or null. */
+export function takeUndoGroup(view) {
+  const link = pending.get(view);
+  pending.delete(view);
+  pairs.delete(view);
+  return link && link.after.eq(view.state.doc) ? link : null;
+}
+
+/** The value was accepted (and the history closed after it): the key and the value are one undo step from now on. */
+export function finishUndoGroup(view, link) {
+  pairs.set(view, { before: link.before, after: view.state.doc, depth: undoDepth(view.state), undone: false });
+}
+
+/** Whether Undo should step over the last pair; does it when so (returns true). Otherwise the caller does the plain undo. */
+export function undoPair(view) {
+  const pair = pairs.get(view);
+  if (!pair || pair.undone || undoDepth(view.state) !== pair.depth || !view.state.doc.eq(pair.after)) return false;
+  for (let step = 0; step < 3 && !view.state.doc.eq(pair.before); step++) if (!undo(view)) break;
+  pair.undone = view.state.doc.eq(pair.before);
+  pair.redoDepth = redoDepth(view.state);
+  return true;
+}
+
+/** The same for Redo: after the pair was undone, Redo puts both back. */
+export function redoPair(view) {
+  const pair = pairs.get(view);
+  if (!pair || !pair.undone || redoDepth(view.state) !== pair.redoDepth || !view.state.doc.eq(pair.before)) return false;
+  for (let step = 0; step < 3 && !view.state.doc.eq(pair.after); step++) if (!redo(view)) break;
+  pair.undone = !view.state.doc.eq(pair.after);
+  return true;
+}

package/dist/source-worker.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The worker script of the source pane's text checks. It exports nothing: bundle it as a module worker script and pass the worker to
+ * `createSourcePane(container, { worker })`, for example
+ * `worker: () => new Worker(new URL("@openpresentation/opf-editor/source-worker", import.meta.url), { type: "module" })`
+ * with a bundler that supports that form, or build `dist/source-worker.js` as its own entry point and serve it next to the page.
+ */
+export {};