@openpresentation/opf-editor 0.26.3 → 0.26.4

package/dist/source-markdown.js

@@ -0,0 +1,551 @@
+// The Markdown text adapter of the source editor (artifacts/source-editor/SPEC.md, section 3.3): what a position in an OPF Markdown draft means. Core's
+// `scanMarkdown` finds the regions with the converter's own rules; this module turns the caret's region into a context for completion and hover:
+// the YAML of the front matter and of `opf-slide` and `opf-block` fences (the YAML adapter, shifted into the text), the keys and values of a slide or
+// block options comment, the info line of a fence, the lines of a metric fence, and the start of a line in the body (`Note:`, snippets). Plain
+// functions, no DOM.
+import { parse as parseYaml } from "yaml";
+import { describeField } from "@openpresentation/opf/schema";
+import { BLOCK_AS_VALUES, BLOCK_OPTION_KEYS, FENCE_ATTRIBUTES, LINE_KEYWORDS, METRIC_KEYS, SLIDE_OPTION_KEYS, SPAN_FLAGS, SPAN_VALUES, scanMarkdown, pathAt } from "@openpresentation/opf/source";
+import { fromMarkdown } from "@openpresentation/opf/markdown";
+import { yamlContextAt } from "./source-yaml.js";
+import { snippetMarkdown, snippetsForMarkdown } from "./source-snippets.js";
+import { fieldDoc } from "./source-docs.js";
+
+const OPTION_KEY = /^[A-Za-z][A-Za-z0-9_-]*$/;
+const BARE = /^[A-Za-z0-9_-]+$/;
+const LANGUAGES = ["javascript", "typescript", "python", "rust", "go", "bash", "json", "yaml", "toml", "ini", "markup", "css", "sql", "java", "csharp", "kotlin", "swift", "ruby", "php", "c", "hcl", "dockerfile", "js", "ts", "py", "sh", "html", "md"];
+// Keys whose values come from a closed set the schema or the catalogs know; accepting the key opens that list.
+const CHAIN_SLIDE = new Set(["layout", "type", "hidden"]);
+const CHAIN_BLOCK = new Set(["type", "as", "region"]);
+// The promoted regions of a slide that a block can be pinned to when the layout names none.
+const PROMOTED = ["top", "middle", "bottom", "left", "center", "right", "top:left", "top:center", "top:right", "middle:left", "middle:center", "middle:right", "bottom:left", "bottom:center", "bottom:right"];
+
+const lineAt = (text, position) => {
+  const start = Math.max(text.lastIndexOf("\n", position - 1), text.lastIndexOf("\r", position - 1)) + 1;
+  let end = position;
+  while (end < text.length && text[end] !== "\n" && text[end] !== "\r") end++;
+  return { start, end, text: text.slice(start, end) };
+};
+
+// ---- regions -----------------------------------------------------------------------------------------------------------------------
+/**
+ * Which part of a Markdown deck the caret is in: `{ region, ... }` with region `front-matter` (`yamlFrom`, `yamlTo`), `comment` (`comment`),
+ * `fence` (`fence`, `part`: "info", "body" or "close"), `notes` or `body`. Used by the editing rules (Enter, Tab, pairs, comments) and the adapter.
+ */
+export function markdownRegionAt(text, position) {
+  const scan = scanMarkdown(text);
+  const front = scan.frontMatter;
+  if (front) {
+    if (position < front.yamlFrom + 1 && position <= front.yamlFrom) return { region: "front-matter-edge", front };
+    if (position > front.yamlFrom && (front.closed ? position < front.yamlTo : true)) return { region: "front-matter", front, scan };
+    if (front.closed && position >= front.yamlTo && position <= front.to) return { region: "front-matter-edge", front };
+  }
+  for (const fence of scan.fences) {
+    if (position < fence.from || position > fence.to) continue;
+    const opening = lineAt(text, fence.from);
+    if (position <= opening.end) return { region: "fence", fence, part: "info", scan };
+    if (fence.closed && position >= fence.to - lineAt(text, fence.to).text.length) return { region: "fence", fence, part: "close", scan };
+    return { region: "fence", fence, part: "body", scan };
+  }
+  for (const comment of scan.comments) if (position >= comment.from && position <= comment.to) return { region: "comment", comment, scan };
+  for (const notes of scan.notes) if (position >= notes.from && position <= notes.to) return { region: "notes", notes, scan };
+  return { region: "body", scan };
+}
+
+const shiftToken = (token, base) => ({ ...token, start: token.start + base, end: token.end + base, from: token.from + base, to: token.to + base });
+
+// The embedded catalogs of the front matter, so the options of a slide can list the records the deck carries.
+function frontCatalogs(text, scan) {
+  const front = scan.frontMatter;
+  if (!front) return undefined;
+  try { return parseYaml(text.slice(front.yamlFrom, front.yamlTo))?.catalogs; } catch { return undefined; }
+}
+
+function skeletonFor(text, scan, slide) {
+  const document = { slides: Array.from({ length: Math.max(0, slide) + 1 }, () => ({})) };
+  const catalogs = frontCatalogs(text, scan);
+  if (catalogs) document.catalogs = catalogs;
+  return document;
+}
+
+// ---- the context at a caret --------------------------------------------------------------------------------------------------------
+/**
+ * What the draft means at `position`, or null. A caret in YAML (front matter, an `opf-slide` or `opf-block` fence) gives the YAML adapter's context,
+ * shifted into this text (`format: "yaml"`). Otherwise `{ format: "md", region, mode, token, ... }`:
+ * - `region: "options"`: `optionKind` ("slide" or "block"), `mode` "key" or "value", `key`, `existing`, `needsSpace`, `slide`, `layout`
+ * - `region: "comment-start"`: after `<!--` at the start of a line (offers `slide:` and `block:`)
+ * - `region: "fence-info"`: `mode` "kind" (the first word), "type" (the chart type) or "attribute"; `word`
+ * - `region: "metric"`: `mode` "key" or "value", `key`, `existing`
+ * - `region: "body"`: the word at the start of a line (`Note:`, a snippet prefix), `separator` (a `---` goes first)
+ */
+export function markdownContextAt(text, position, { explicit = false } = {}) {
+  const where = markdownRegionAt(text, position);
+  switch (where.region) {
+    case "front-matter": {
+      const base = where.front.yamlFrom;
+      const context = yamlContextAt(text.slice(base, where.front.closed ? where.front.yamlTo : text.length), position - base, { explicit, exclude: ["slides"] });
+      return context ? { ...context, token: shiftToken(context.token, base) } : null;
+    }
+    case "fence":
+      return fenceContext(text, position, where, explicit);
+    case "comment":
+      return commentContext(text, position, where, explicit);
+    case "body":
+      return bodyContext(text, position, where, explicit);
+    default:
+      return null;
+  }
+}
+
+// ---- options comments --------------------------------------------------------------------------------------------------------------
+/** The `key`, `key=value` tokens of an options comment between `from` and `to`: `{ start, end, key, keyEnd, eq, valueStart, quoted }`. */
+function optionTokens(text, from, to) {
+  const tokens = [];
+  let index = from;
+  while (index < to) {
+    while (index < to && /\s/.test(text[index])) index++;
+    if (index >= to) break;
+    const start = index;
+    while (index < to && /[A-Za-z0-9_-]/.test(text[index])) index++;
+    const keyEnd = index;
+    let eq = -1, valueStart = -1, quoted = false;
+    if (text[index] === "=") {
+      eq = index;
+      index++;
+      valueStart = index;
+      if (text[index] === '"') {
+        quoted = true;
+        index++;
+        while (index < to && text[index] !== '"') index += text[index] === "\\" ? 2 : 1;
+        if (index < to) index++;
+      } else while (index < to && !/[\s,]/.test(text[index])) index++;
+    } else while (index < to && !/\s/.test(text[index])) index++;
+    tokens.push({ start, end: index, key: text.slice(start, keyEnd), keyEnd, eq, valueStart, quoted });
+    if (index === start) index++;
+  }
+  return tokens;
+}
+
+function slideLayout(text, scan, slide) {
+  for (const comment of scan.comments) {
+    if (comment.kind !== "slide" || comment.slide !== slide) continue;
+    const tokens = optionTokens(text, comment.innerFrom, comment.innerTo);
+    const found = tokens.find((token) => token.key === "layout" && token.eq >= 0);
+    if (found) return text.slice(found.valueStart + (found.quoted ? 1 : 0), found.end - (found.quoted && text[found.end - 1] === '"' ? 1 : 0));
+  }
+  return undefined;
+}
+
+function commentContext(text, position, where, explicit) {
+  const { comment, scan } = where;
+  const line = lineAt(text, position);
+  const before = text.slice(line.start, position);
+  // `<!-- ` and nothing else on the line: the comment may be a slide or block options comment.
+  const start = /^ {0,3}<!--[ \t]*([a-z]*)$/.exec(before);
+  if (start && (comment.kind === "comment" || comment.kind === "slide" || comment.kind === "block") && !/^\s*(slide|block)\s*:/.test(text.slice(line.start + before.length - start[1].length - 0, line.end))) {
+    const wordStart = position - start[1].length;
+    const afterWord = text.slice(position, line.end);
+    if (!explicit && start[1] === "" && !/[ \t]$/.test(before)) return null;
+    return { format: "md", region: "comment-start", token: { quoted: false, closed: false, start: wordStart, end: position, from: wordStart, to: position }, closes: /-->/.test(afterWord), document: {}, path: [] };
+  }
+  if (comment.kind !== "slide" && comment.kind !== "block") return null;
+  // A comment on one line only.
+  const first = lineAt(text, comment.from);
+  if (first.start !== line.start) return null;
+  const colon = /^\s*(slide|block)\s*(:?)/.exec(text.slice(comment.innerFrom, line.end));
+  if (!colon) return null;
+  const keywordEnd = comment.innerFrom + colon[0].length;
+  const innerEnd = comment.closed ? Math.min(comment.innerTo, line.end) : line.end;
+  if (position < keywordEnd || position > innerEnd) return null;
+  const kind = colon[1];
+  const tokens = optionTokens(text, keywordEnd, innerEnd);
+  const here = tokens.find((token) => position >= token.start && position <= token.end);
+  const slide = comment.slide;
+  const needsSpace = position === keywordEnd && colon[2] === ":" && text[position] !== " ";
+  const keys = kind === "slide" ? SLIDE_OPTION_KEYS : BLOCK_OPTION_KEYS;
+  const existing = new Set(tokens.filter((token) => token !== here && token.key !== "beat").map((token) => token.key));
+  const base = { format: "md", region: "options", optionKind: kind, slide, existing, needsSpace, keys, document: skeletonFor(text, scan, slide), layout: slideLayout(text, scan, slide), path: [] };
+  if (here && here.eq >= 0 && position > here.eq) {
+    const first = here.valueStart;
+    if (here.quoted) {
+      const closed = text[here.end - 1] === '"' && here.end - 1 > first;
+      const token = { quoted: true, closed, start: first, end: here.end, from: first + 1, to: closed ? here.end - 1 : Math.max(position, first + 1) };
+      return { ...base, mode: "value", key: here.key, token };
+    }
+    return { ...base, mode: "value", key: here.key, token: { quoted: false, closed: false, start: first, end: here.end, from: first, to: here.end } };
+  }
+  if (here && !OPTION_KEY.test(text.slice(here.start, here.keyEnd))) return null;
+  const start0 = here ? here.start : position;
+  const end0 = here ? here.keyEnd : position;
+  return { ...base, mode: "key", key: undefined, followedByEquals: Boolean(here && here.eq >= 0), token: { quoted: false, closed: false, start: start0, end: end0, from: start0, to: end0 } };
+}
+
+// ---- fences ------------------------------------------------------------------------------------------------------------------------
+function fenceContext(text, position, where, explicit) {
+  const { fence, part, scan } = where;
+  if (part === "close") return null;
+  if (part === "info") {
+    const line = lineAt(text, fence.from);
+    const indent = /^ */.exec(line.text)[0].length;
+    const open = line.start + indent + fence.marker.length;
+    if (position < open) return null;
+    // Typed info: words separated by spaces; the caret is in one of them.
+    const before = text.slice(open, position);
+    const words = before.split(/\s+/);
+    const typed = words.at(-1);
+    const first = before.trimStart().split(/\s+/)[0];
+    const tokenStart = position - typed.length;
+    let tokenEnd = position;
+    while (tokenEnd < line.end && /[A-Za-z0-9_+#.-]/.test(text[tokenEnd])) tokenEnd++;
+    const token = { quoted: false, closed: false, start: tokenStart, end: tokenEnd, from: tokenStart, to: tokenEnd };
+    const done = before.trim().split(/\s+/).filter(Boolean);
+    const wordIndex = /\s$/.test(before) ? done.length : Math.max(0, done.length - 1);
+    if (wordIndex === 0) return { format: "md", region: "fence-info", mode: "kind", word: first || "", token, document: {}, path: [] };
+    const kind = first;
+    if (kind === "chart" && wordIndex === 1 && !/=/.test(typed)) return { format: "md", region: "fence-info", mode: "type", word: kind, token, document: skeletonFor(text, scan, fence.slide), path: [] };
+    if (!/=/.test(typed) && (kind === "chart" || kind === "timeline" || !["opf-slide", "opf-block", "metric"].includes(kind))) {
+      const have = new Set(optionTokens(text, open, line.end).map((item) => item.key));
+      return { format: "md", region: "fence-info", mode: "attribute", word: kind, existing: have, token, document: {}, path: [] };
+    }
+    return null;
+  }
+  // The body.
+  if (fence.kind === "metric") return metricContext(text, position, fence);
+  if (fence.kind === "timeline") return timelineContext(text, position);
+  if (fence.kind === "opf-slide" || fence.kind === "opf-block") {
+    const base = fence.bodyFrom;
+    const prefix = fence.kind === "opf-slide" ? ["slides", fence.slide] : ["slides", fence.slide, "blocks", 0];
+    const context = yamlContextAt(text.slice(base, fence.bodyTo), position - base, { explicit, prefix });
+    if (!context) return null;
+    const catalogs = frontCatalogs(text, scan);
+    if (catalogs && context.document && typeof context.document === "object") context.document.catalogs = catalogs;
+    return { ...context, token: shiftToken(context.token, base) };
+  }
+  return null;
+}
+
+// A timeline event may start with a task-list mark that sets its status: `[x]` done, `[>]` current ("we are here"), `[ ]` planned.
+function timelineContext(text, position) {
+  const line = lineAt(text, position);
+  const before = text.slice(line.start, position);
+  if (!/^(?:\[[x> ]?\]?)?$/.test(before) || /^\s/.test(line.text)) return null;
+  let end = position;
+  while (end < line.end && /[x> \]]/.test(text[end]) && text[end] !== " ") end++;
+  return { format: "md", region: "timeline", token: { quoted: false, closed: false, start: line.start, end, from: line.start, to: end }, document: {}, path: [] };
+}
+
+function metricContext(text, position, fence) {
+  const line = lineAt(text, position);
+  const before = text.slice(line.start, position);
+  const bodyLines = text.slice(fence.bodyFrom, fence.bodyTo).split(/\r\n|\r|\n/);
+  const existing = new Set(bodyLines.map((item) => /^([A-Za-z]+):/.exec(item)?.[1]).filter(Boolean));
+  const document = { slides: [{ metric: {} }] };
+  const value = /^([A-Za-z]+):[ \t]*(.*)$/.exec(before);
+  if (value) {
+    const start = position - value[2].length;
+    let end = position;
+    while (end < line.end && !/\s/.test(text[end])) end++;
+    return { format: "md", region: "metric", mode: "value", key: value[1], existing, token: { quoted: false, closed: false, start, end, from: start, to: end }, document, path: ["slides", 0, "metric", value[1]], needsSpace: value[2] === "" && !/:[ \t]$/.test(before) };
+  }
+  if (!/^[A-Za-z]*$/.test(before)) return null;
+  let end = position;
+  while (end < line.end && /[A-Za-z]/.test(text[end])) end++;
+  const start = position - before.length;
+  const self = /^([A-Za-z]+):/.exec(line.text)?.[1];
+  if (self) existing.delete(self);
+  return { format: "md", region: "metric", mode: "key", existing, token: { quoted: false, closed: false, start, end, from: start, to: end }, document, path: ["slides", 0, "metric"] };
+}
+
+// ---- the body ----------------------------------------------------------------------------------------------------------------------
+function bodyContext(text, position, where, explicit) {
+  const { scan } = where;
+  const line = lineAt(text, position);
+  const before = text.slice(line.start, position);
+  // Inside the braces of an inline span: `[text]{bold color=#B42318}`.
+  const span = /\]\{((?:[A-Za-z0-9_-]+(?:=(?:"[^"]*"|[^\s"}]*))?\s+)*)([A-Za-z]*)$/.exec(before);
+  if (span) {
+    let end = position;
+    while (end < line.end && /[A-Za-z]/.test(text[end])) end++;
+    const used = new Set([...span[1].matchAll(/([A-Za-z0-9_-]+)/g)].map((entry) => entry[1].toLowerCase()));
+    const start = position - span[2].length;
+    return { format: "md", region: "span", token: { quoted: false, closed: false, start, end, from: start, to: end }, existing: used, document: {}, path: [], explicit, opened: span[2] === "" };
+  }
+  if (!/^[A-Za-z][A-Za-z-]*$|^$/.test(before)) return null;
+  if (before === "" && !explicit) return null;
+  // Typing prose is not interrupted: a list opens by itself from the third letter on.
+  if (!explicit && before.length < 3) return null;
+  let end = position;
+  while (end < line.end && /[A-Za-z-]/.test(text[end])) end++;
+  // A slide follows another when there is content above that is not already a separator.
+  const above = text.slice(0, line.start).replace(/\s+$/, "");
+  const lastLine = above.slice(above.lastIndexOf("\n") + 1);
+  const hasContent = above.trim() !== "" && !(scan.frontMatter && above.length <= scan.frontMatter.to);
+  const separator = hasContent && !/^-{3,}[ \t]*$/.test(lastLine);
+  const previousBlank = line.start === 0 || lineAt(text, line.start - 1).text.trim() === "";
+  const slide = scan.slides.filter((item) => item.from < line.start).length;
+  return { format: "md", region: "body", token: { quoted: false, closed: false, start: line.start, end, from: line.start, to: end }, separator, previousBlank, document: {}, path: [], slide };
+}
+
+// ---- the options -------------------------------------------------------------------------------------------------------------------
+const kindOption = (label, type, detail, doc, boost, kind, extra = {}) => ({ label, type, detail, boost, opfDoc: doc, opf: { kind, ...extra } });
+
+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 completion options of a Markdown context: `{ options, validFor? }`, or null. `makers` are the option builders of the completion engine. */
+export function markdownOptions(context, { catalogs, text, explicit, makers }) {
+  const { literalOption, boostAt, docNode } = makers;
+  const options = [];
+  if (context.region === "comment-start") {
+    options.push(kindOption("slide:", "keyword", "options", "Options of this slide: id, layout, section, ...", boostAt(0), "comment", { word: "slide:" }));
+    options.push(kindOption("block:", "keyword", "options", "Options of the next block: id, type, as, region.", boostAt(1), "comment", { word: "block:" }));
+    return { options, validFor: /^[a-z]*$/ };
+  }
+  if (context.region === "options") return optionsOptions(context, { catalogs, makers });
+  if (context.region === "fence-info") {
+    if (context.mode === "kind") {
+      let order = 0;
+      for (const kind of ["chart", "metric", "timeline", "opf-block", "opf-slide"]) {
+        const doc = { chart: "A chart: the type, then CSV with a header row", metric: "One big number: value, label, unit, delta", timeline: "Events, one per line", "opf-block": "A content block written as YAML", "opf-slide": "Slide fields written as YAML" }[kind];
+        options.push(kindOption(kind, "keyword", "fence", doc, boostAt(order++), "fence", { word: kind }));
+      }
+      for (const language of LANGUAGES) options.push(kindOption(language, "text", "code", `Code in ${language}`, boostAt(order++), "fence", { word: language }));
+      return { options, validFor: /^[A-Za-z0-9_+#.-]*$/ };
+    }
+    if (context.mode === "type") {
+      let info;
+      try { info = describeField(["slides", 0, "chart", "type"], context.document); } catch { info = null; }
+      for (const entry of info?.enum ?? []) options.push(literalOption(String(entry.value), JSON.stringify(entry.value), { value: entry.value, doc: entry.description ?? "", info: entry.description ? () => docNode({ title: String(entry.value), type: "chart type", description: entry.description }) : undefined }));
+      return { options, validFor: /^[A-Za-z0-9_-]*$/ };
+    }
+    if (context.mode === "attribute") {
+      const attributes = FENCE_ATTRIBUTES[context.word] ?? (["opf-slide", "opf-block", "metric"].includes(context.word) ? [] : FENCE_ATTRIBUTES.code);
+      attributes.filter((name) => !context.existing.has(name)).forEach((name, index) => options.push(kindOption(name, "property", "attribute", `The ${name} of the ${context.word} fence`, boostAt(index), "fenceAttribute", { name })));
+      return { options, validFor: /^[A-Za-z]*$/ };
+    }
+  }
+  if (context.region === "metric") {
+    if (context.mode === "key") {
+      METRIC_KEYS.filter((key) => !context.existing.has(key)).forEach((key, index) => {
+        let info;
+        try { info = describeField(["slides", 0, "metric", key], context.document); } catch { info = null; }
+        options.push({ label: key, type: "property", detail: info?.known ? (info.enum?.length ? "enum" : info.types.join(" | ")) : "string", boost: boostAt(index), opfDoc: info?.description ?? "", opf: { kind: "metricKey", key, chain: Boolean(info?.enum?.length) }, info: () => docNode({ title: key, type: info?.types.join(" | "), description: info?.description }) });
+      });
+      return { options, validFor: /^[A-Za-z]*$/ };
+    }
+    let info;
+    try { info = describeField(context.path, context.document); } catch { info = null; }
+    for (const entry of info?.enum ?? []) options.push(literalOption(String(entry.value), JSON.stringify(entry.value), { value: entry.value, doc: entry.description ?? "" }));
+    return { options, validFor: /^[A-Za-z0-9_-]*$/ };
+  }
+  if (context.region === "timeline") {
+    const marks = [["[x]", "done", "The event is done."], ["[>]", "current", "The event is where the story is now (\"we are here\")."], ["[ ]", "planned", "The event is planned."]];
+    marks.forEach(([mark, word, doc], index) => options.push(kindOption(mark, "keyword", word, doc, boostAt(index), "status", { mark })));
+    return { options, validFor: /^(?:\[[x> ]?\]?)?$/ };
+  }
+  if (context.region === "span") {
+    // Right after `{` or a space the list opens by itself (the characters that begin a new attribute); Ctrl+Space opens it anywhere in the braces.
+    const docs = { bold: "Bold text", italic: "Italic text", underline: "Underlined text", strike: "Struck-through text", sup: "Superscript", sub: "Subscript", color: "Text color: a hex color, a scheme slot or var:name", size: "Font size in points", font: "Font family", lang: "Language of the text (a BCP-47 tag)" };
+    [...SPAN_FLAGS.map((name) => [name, false]), ...SPAN_VALUES.map((name) => [name, true])].filter(([name]) => !context.existing.has(name)).forEach(([name, takesValue], index) => options.push(kindOption(name, "property", takesValue ? "value" : "flag", docs[name], boostAt(index), "spanAttribute", { name, takesValue })));
+    return { options, validFor: /^[A-Za-z]*$/ };
+  }
+  if (context.region === "body") {
+    const typed = text.slice(context.token.from, context.token.to).toLowerCase();
+    let order = 0;
+    for (const word of LINE_KEYWORDS) if (word.toLowerCase().startsWith(typed)) options.push(kindOption(word, "keyword", "speaker notes", "Speaker notes: every line to the end of the slide.", boostAt(order++), "keyword", { word }));
+    for (const entry of snippetsForMarkdown()) if (entry.prefix.toLowerCase().startsWith(typed)) options.push({ label: entry.prefix, type: "snippet", detail: "snippet", boost: boostAt(order++), opfDoc: entry.description, opf: { kind: "snippet", prefix: entry.prefix }, info: () => docNode({ title: entry.prefix, type: "snippet", description: entry.description }) });
+    return { options, validFor: /^[A-Za-z-]*$/ };
+  }
+  return null;
+}
+
+function optionsOptions(context, { catalogs, makers }) {
+  const { literalOption, boostAt, docNode } = makers;
+  const options = [];
+  if (context.mode === "key") {
+    const chain = context.optionKind === "slide" ? CHAIN_SLIDE : CHAIN_BLOCK;
+    context.keys.filter((key) => !context.existing.has(key)).forEach((key, index) => {
+      let info;
+      try { info = context.optionKind === "slide" ? describeField(["slides", context.slide, key], context.document) : undefined; } catch { info = null; }
+      const doc = info?.description ?? BLOCK_DOCS[key] ?? "";
+      options.push({ label: key, type: "property", detail: info?.known ? info.typeLabel ?? info.types.join(" | ") : context.optionKind === "block" ? "option" : "string", boost: boostAt(index), opfDoc: doc, opf: { kind: "optionKey", key, chain: chain.has(key) }, info: () => docNode({ title: key, type: `${context.optionKind} option`, description: doc }) });
+    });
+    return { options, validFor: /^[A-Za-z0-9_-]*$/ };
+  }
+  const key = context.key;
+  if (context.optionKind === "block") {
+    if (key === "as") for (const value of BLOCK_AS_VALUES) options.push(literalOption(value, JSON.stringify(value), { value, doc: value === "bullets" ? "Store a list as bullets instead of items." : "Store an image line as video." }));
+    else if (key === "region") {
+      const names = [];
+      if (context.layout) {
+        try { const found = makers.listCatalogRecords(context.document, "layouts", { catalogs }).find((entry) => entry.id === context.layout); names.push(...regionNames(found?.record)); } catch { /* No regions known. */ }
+      }
+      for (const name of [...names, ...PROMOTED.filter((item) => !names.includes(item))]) options.push(literalOption(name, JSON.stringify(name), { value: name, doc: names.includes(name) ? `A region of the ${context.layout} layout` : "A promoted region of the slide", boost: names.includes(name) ? 99 : undefined }));
+    } else if (key === "type") {
+      let info;
+      try { info = describeField(["slides", 0, "blocks", 0, "type"], context.document); } catch { info = null; }
+      for (const entry of info?.enum ?? []) options.push(literalOption(String(entry.value), JSON.stringify(entry.value), { value: entry.value, doc: entry.description ?? "" }));
+    }
+    return { options, validFor: /^[A-Za-z0-9_:+-]*$/ };
+  }
+  if (!SLIDE_OPTION_KEYS.includes(key)) return null;
+  const pseudo = { format: "md", mode: "value", path: ["slides", context.slide, key], document: context.document, key, token: context.token };
+  const built = makers.valueOptions(pseudo, catalogs);
+  options.push(...built.options);
+  return { options, validFor: /^[A-Za-z0-9_:+-]*$/ };
+}
+
+const BLOCK_DOCS = {
+  id: "A name for the block, so a finding or a patch can point at it.",
+  type: "The block's content kind, when it cannot be told from the content.",
+  as: "bullets stores a list as bullets; video stores an image line as a video.",
+  region: "Pin the block to a region of the slide's layout, or to a promoted region (left, top:left, ...).",
+};
+
+// ---- accepting ---------------------------------------------------------------------------------------------------------------------
+const escapeTemplate = (text) => text.replace(/[\\{}]/g, (character) => `\\${character}`);
+const optionValue = (value) => (typeof value === "string" && BARE.test(value) ? value : JSON.stringify(value));
+
+/** What accepting `completion` writes in a Markdown context: `{ template, fields, chain, choices, inner? }`. */
+export function markdownPlan(context, completion, text, end) {
+  const kind = completion.opf?.kind;
+  if (context.region === "comment-start") {
+    const word = completion.opf.word;
+    return { template: context.closes ? `${word} ` : `${word} \${0} -->`, fields: context.closes ? 0 : 1, chain: true };
+  }
+  if (kind === "optionKey") {
+    if (context.followedByEquals) return { template: escapeTemplate(completion.opf.key), fields: 0, chain: false };
+    const lead = context.needsSpace ? " " : "";
+    return { template: `${lead}${completion.opf.key}=`, fields: 0, chain: Boolean(completion.opf.chain) };
+  }
+  if (context.region === "options" && kind === "literal") {
+    const value = completion.opf.value;
+    if (context.token.quoted) {
+      const inner = typeof value === "string" ? value.replace(/\\/g, "\\\\").replace(/"/g, '\\"') : String(value);
+      return { template: escapeTemplate(inner), fields: 0, chain: false, inner: true };
+    }
+    return { template: escapeTemplate(optionValue(value)), fields: 0, chain: false };
+  }
+  if (kind === "fence") return { template: `${escapeTemplate(completion.opf.word)}${completion.opf.word === "chart" ? " " : ""}`, fields: 0, chain: completion.opf.word === "chart" };
+  if (kind === "fenceAttribute") return { template: `${completion.opf.name}="\${1}"\${0}`, fields: 2, chain: false };
+  if (context.region === "fence-info" && kind === "literal") return { template: escapeTemplate(String(completion.opf.value)), fields: 0, chain: false };
+  if (kind === "metricKey") {
+    if (/^[ \t]*:/.test(text.slice(end))) return { template: completion.opf.key, fields: 0, chain: false };
+    return { template: `${completion.opf.key}: `, fields: 0, chain: Boolean(completion.opf.chain) };
+  }
+  if (context.region === "metric" && kind === "literal") return { template: `${context.needsSpace ? " " : ""}${escapeTemplate(String(completion.opf.value))}`, fields: 0, chain: false };
+  if (kind === "status") return { template: `${completion.opf.mark} `, fields: 0, chain: false };
+  if (kind === "spanAttribute") return { template: `${completion.opf.name}${completion.opf.takesValue ? "=" : ""}`, fields: 0, chain: false };
+  if (kind === "keyword") return { template: `${escapeTemplate(completion.opf.word)} `, fields: 0, chain: false };
+  if (kind === "snippet") {
+    const entry = snippetsForMarkdown().find((candidate) => candidate.prefix === completion.opf.prefix);
+    if (!entry) return null;
+    const rendered = snippetMarkdown(entry, { separator: context.separator });
+    // A separator needs a blank line above it.
+    const lead = context.separator && !context.previousBlank ? "\n" : "";
+    return { template: `${lead}${rendered.text}`, fields: rendered.fields.length, chain: false, choices: rendered.fields };
+  }
+  return null;
+}
+
+// ---- hover -------------------------------------------------------------------------------------------------------------------------
+// What a piece of the dialect's syntax stands for, as a card: the schema's words for the field it writes, and how it is written.
+const SYNTAX_FIELDS = {
+  title: { key: "title", written: "# Title" },
+  subtitle: { key: "subtitle", written: "## Subtitle" },
+  notes: { key: "notes", written: "Note: text, to the end of the slide" },
+  items: { key: "items", written: "- item (two spaces per level)" },
+  quote: { key: "quote", written: "> text, then > — Name, Title" },
+  chart: { key: "chart", written: "```chart column, then CSV" },
+  metric: { key: "metric", written: "```metric, then key: value lines" },
+  timeline: { key: "timeline", written: "```timeline, then one event per line" },
+  code: { key: "code", written: "```js title=\"file\"" },
+  image: { key: "image", written: "![alt](src)" },
+  table: { key: "table", written: "| a | b | rows with a | --- | row" },
+};
+function syntaxCard(name, document, extra) {
+  const spec = SYNTAX_FIELDS[name];
+  let info;
+  try { info = describeField(["slides", 0, spec.key], document); } catch { info = null; }
+  const model = info?.known ? fieldDoc(info, spec.key) : { title: spec.key };
+  return { ...model, ...extra, notes: [`Written as ${spec.written}`, ...(extra?.notes ?? [])] };
+}
+
+/** The card for the dialect syntax under `position` (a heading marker, `Note:`, a list marker, a fence word, `---`, `slide:`), as `{ from, to, model }`, or null. */
+function syntaxHoverAt(text, position, where, document) {
+  const line = lineAt(text, position);
+  const column = position - line.start;
+  const card = (name, from, to, extra) => ({ from, to, model: syntaxCard(name, document, extra) });
+  if (where.region === "fence") {
+    if (where.part !== "info") return null;
+    const { fence } = where;
+    const wordFrom = fence.infoFrom, wordTo = fence.infoFrom + fence.word.length;
+    if (position < wordFrom || position > wordTo || !fence.word) return null;
+    if (fence.kind === "opf-slide") return { from: wordFrom, to: wordTo, model: { title: "opf-slide", type: "fence", description: "Slide fields the Markdown has no syntax for (`composition`, `design`, `extensions`, ...), written as YAML. A field set here and in Markdown is an error." } };
+    if (fence.kind === "opf-block") return { from: wordFrom, to: wordTo, model: { title: "opf-block", type: "fence", description: "A content block written as YAML: any content field, `id`, `type` and nested `blocks`." } };
+    return card(fence.kind === "code" ? "code" : fence.kind, wordFrom, wordTo);
+  }
+  if (where.region === "comment") {
+    const comment = where.comment;
+    if (comment.kind !== "slide" && comment.kind !== "block") return null;
+    const word = /^\s*(slide|block)/.exec(text.slice(comment.innerFrom, comment.innerTo));
+    if (!word) return null;
+    const from = comment.innerFrom + word[0].length - word[1].length, to = from + word[1].length;
+    if (position < from || position > to) return null;
+    const keys = (word[1] === "slide" ? SLIDE_OPTION_KEYS : BLOCK_OPTION_KEYS).join(", ");
+    return { from, to, model: { title: `${word[1]}:`, type: "options comment", description: word[1] === "slide" ? `Options of this slide, written as key=value: ${keys}. Values are bare words or JSON strings.` : `Options of the next block: ${keys}. \`as=bullets\` stores a list as bullets, \`region=\` pins it to a region.` } };
+  }
+  if (where.region === "notes") {
+    const match = /^(Notes?):/.exec(line.text);
+    return match && column <= match[1].length + 1 ? card("notes", line.start, line.start + match[1].length + 1) : null;
+  }
+  if (where.region !== "body") return null;
+  if (/^-{3,}[ \t]*$/.test(line.text)) return { from: line.start, to: line.end, model: { title: "---", type: "slide separator", description: "Starts the next slide. Slides are the text between these lines." } };
+  const heading = /^( {0,3})(#{1,6})(?=[ \t])/.exec(line.text);
+  if (heading && column >= heading[1].length && column <= heading[0].length) {
+    const level = heading[2].length;
+    const from = line.start + heading[1].length, to = line.start + heading[0].length;
+    if (level === 1) return card("title", from, to);
+    if (level === 2) return card("subtitle", from, to);
+    return { from, to, model: { title: heading[2], type: "heading", description: "Only # (title) and ## (subtitle) are slide fields: a deeper heading becomes a bold paragraph." } };
+  }
+  const item = /^(\s*)([-*+]|\d{1,9}[.)])(?=[ \t])/.exec(line.text);
+  if (item && column >= item[1].length && column <= item[0].length) return card("items", line.start + item[1].length, line.start + item[0].length);
+  const quote = /^ {0,3}>/.exec(line.text);
+  if (quote && column <= quote[0].length) return card("quote", line.start, line.start + quote[0].length);
+  return null;
+}
+
+/**
+ * The card for what is under `position`: a front matter key or value, a slide option, or the dialect's own syntax (a heading marker, `Note:`, a list
+ * marker, the word of a fence, `---`, `slide:`): `{ from, to, model }` or null. `describeFound` is the completion engine's card builder.
+ */
+export function markdownHoverAt(text, position, { catalogs, describeFound }) {
+  const where = markdownRegionAt(text, position);
+  let inOptions = false;
+  if (where.region === "comment") inOptions = where.comment.kind === "slide";
+  let document;
+  const deck = () => {
+    if (!document) { try { document = fromMarkdown(text, { validate: false }).presentation; } catch { document = { slides: [] }; } }
+    return document;
+  };
+  if (where.region === "front-matter" || inOptions) {
+    const found = pathAt(text, "md", position);
+    if (found?.range && (found.part === "key" || found.part === "value")) {
+      const source = text.slice(found.range.offset, found.range.offset + found.range.length);
+      const value = found.part === "value" && !/^[[{]/.test(source) ? source.replace(/^"|"$/g, "") : undefined;
+      const card = describeFound({ kind: found.part, path: found.path, from: found.range.offset, to: found.range.offset + found.range.length, value, nodeType: /^[[{]/.test(source) ? "array" : "scalar" }, deck(), catalogs);
+      if (card) return card;
+    }
+  }
+  return syntaxHoverAt(text, position, where, { slides: [{}] });
+}

package/dist/source-pane.d.ts

@@ -71,8 +71,10 @@ export interface SourcePaneOptions {
   /** Accessible name of the code editor (default `OPF source`). */
   label?: string;
   catalogs?: JsonCatalogContext;
-  /** 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. */
+  /** 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. The same for YAML and Markdown (front matter, slide and block options, fences, `Note:` and snippets). Default true. */
   completions?: boolean;
+  /** Enter continues a list: a new string item after a string in a JSON list, the next `- ` in YAML, the next marker (or `> `) in Markdown; an empty one ends it. Default true. */
+  smartListEnter?: boolean;
   onError?(error: unknown): void;
 }
 
@@ -110,10 +112,16 @@ export interface SourcePane {
   /** Switch format. Returns false, and says why in the findings, when the document cannot be written in it. Does not call `onFormatChange`. */
   setFormat(format: SourceFormat): boolean;
   getFormat(): SourceFormat;
-  /** Move the cursor to the line of a JSON Pointer (or dotted OPF path) in the current format; best effort for YAML and Markdown. Returns the line. */
+  /** Move the cursor to the line of a JSON Pointer (or dotted OPF path) in the current format (core's `locate` finds it in JSON, YAML and Markdown). Returns the line. */
   focusPath(path: string): number;
   /** The text as shown, with any pending edit applied first. */
   getText(): string;
+  /**
+   * Canonicalize with OPF: rewrite the YAML or Markdown text from the document with core's writer (the old behavior of Format). It drops comments, so it
+   * asks first when there are any (an inline confirmation naming how many); `confirmed: true` has asked already. Returns "applied", "unchanged",
+   * "confirm" (waiting for the answer) or "refused" (JSON, read-only, or text that does not read as a document).
+   */
+  canonicalize(options?: { confirmed?: boolean }): "applied" | "unchanged" | "confirm" | "refused";
   getName(): string;
   setName(name: string): void;
   setDensity(density: SourcePaneDensity): void;