@openpresentation/opf-editor 0.26.1 → 0.26.2

package/dist/source-diagnostics.js

@@ -0,0 +1,211 @@
+// Problems in the text (artifacts/source-editor/SPEC.md, section 9): every finding the pane has a range for is a squiggle with its message, what
+// could come next and its quick fixes; F8 and Shift+F8 walk them; Cmd/Ctrl+. lists the fixes at the caret. The pane decides what the problems
+// are (`control.setProblems`); this module only draws them and acts on them. Ranges are original-source offsets (CRLF counts as two).
+import { ChangeSet, EditorSelection, Prec, StateEffect, StateField, Transaction } from "@codemirror/state";
+import { EditorView, activateHover, keymap, showTooltip } from "@codemirror/view";
+import { forEachDiagnostic, linter, setDiagnostics } from "@codemirror/lint";
+import { isolateHistory } from "@codemirror/commands";
+import { textInputMap } from "./text-input.js";
+import { setJsonSource } from "./json-source.js";
+import { applySourceEdits } from "./source-fixes.js";
+
+const SEVERITY_WORD = { error: "Error", warning: "Warning", info: "Note" };
+const MAX_FIXES = 7;
+const el = (tag, className, text) => {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (text !== undefined) node.textContent = text;
+  return node;
+};
+
+/** The platform's name for the quick fix chord, for the hint in a problem's tooltip. */
+const isMac = () => /Mac|iPhone|iPad/.test(globalThis.navigator?.platform ?? "");
+export const quickFixChord = () => (isMac() ? "Cmd+." : "Ctrl+.");
+
+// ---- the diagnostics ---------------------------------------------------------------------------------------------------------------
+/** One problem as CodeMirror's lint state keeps it (`problem` is the pane's object, with source offsets as of when it was set). */
+function toDiagnostic(problem, map, length, applyFix) {
+  const clamp = (offset) => Math.max(0, Math.min(offset, length));
+  const from = map.toInput(clamp(problem.from)), to = map.toInput(clamp(problem.to));
+  return {
+    from, to: Math.max(from, to),
+    severity: problem.severity === "warning" || problem.severity === "info" ? problem.severity : "error",
+    message: problem.message,
+    source: problem.rule,
+    problem,
+    renderMessage: () => renderProblem(problem),
+    actions: (problem.fixes ?? []).slice(0, MAX_FIXES).map((fix) => ({ name: fix.title, apply: () => applyFix(fix, problem) })),
+  };
+}
+/** The tooltip body: the message, what could come next, and the quick fix hint. */
+function renderProblem(problem) {
+  const body = el("div", "opf-problem");
+  body.append(el("div", "opf-problem-message", problem.message));
+  if (problem.next) body.append(el("div", "opf-problem-next", `Next: ${problem.next}`));
+  if (problem.fixes?.length) body.append(el("div", "opf-problem-hint", `Quick Fix (${quickFixChord()}): ${problem.fixes.length} ${problem.fixes.length === 1 ? "action" : "actions"}`));
+  return body;
+}
+
+/** The problems now in the text, in position order, with their current source offsets. */
+export function currentProblems(state, source) {
+  const map = textInputMap(source), out = [];
+  forEachDiagnostic(state, (diagnostic, from, to) => {
+    if (!diagnostic.problem) return;
+    out.push({ ...diagnostic.problem, from: map.toSource(Math.min(from, map.text.length)), to: map.toSource(Math.min(to, map.text.length)), diagnostic });
+  });
+  return out.sort((a, b) => a.from - b.from || a.to - b.to || a.message.localeCompare(b.message));
+}
+
+// ---- quick fix menu ----------------------------------------------------------------------------------------------------------------
+const openFixes = StateEffect.define();
+const closeFixes = StateEffect.define();
+const moveFixes = StateEffect.define();
+const fixMenu = StateField.define({
+  create: () => null,
+  update(value, tr) {
+    for (const effect of tr.effects) {
+      if (effect.is(openFixes)) value = { pos: effect.value.pos, items: effect.value.items, selected: 0 };
+      else if (effect.is(closeFixes)) value = null;
+      else if (effect.is(moveFixes) && value) value = { ...value, selected: (value.selected + effect.value + value.items.length) % value.items.length };
+    }
+    // Any change of the text or the caret closes the menu.
+    if (value && !tr.effects.some((effect) => effect.is(openFixes) || effect.is(moveFixes)) && (tr.docChanged || tr.selection)) value = null;
+    return value;
+  },
+  provide: (field) => showTooltip.from(field, (value) => value && {
+    pos: value.pos,
+    above: false,
+    strictSide: false,
+    arrow: false,
+    create() {
+      const dom = el("div", "cm-tooltip-section opf-fixes");
+      dom.setAttribute("role", "listbox");
+      dom.setAttribute("aria-label", "Quick fixes");
+      value.items.forEach((fix, index) => {
+        const item = el("div", "opf-fix", fix.title);
+        item.setAttribute("role", "option");
+        item.setAttribute("aria-selected", String(index === value.selected));
+        item.dataset.fix = fix.id;
+        if (fix.safe) item.dataset.safe = "true";
+        dom.append(item);
+      });
+      return { dom };
+    },
+  }),
+});
+
+/** The fixes of the problems at the selection (or, when none touches it, on its line), the safest first. */
+export function fixesAtCaret(state, source) {
+  const { from, to } = state.selection.main;
+  const map = textInputMap(source);
+  const problems = currentProblems(state, source);
+  const caretFrom = map.toSource(from), caretTo = map.toSource(to);
+  const touching = problems.filter((problem) => problem.from <= caretTo && problem.to >= caretFrom);
+  let chosen = touching;
+  if (!chosen.length) {
+    const line = state.doc.lineAt(from);
+    chosen = problems.filter((problem) => state.doc.lineAt(map.toInput(Math.min(problem.from, source.length))).number === line.number);
+  }
+  const fixes = [];
+  const seen = new Set();
+  for (const problem of chosen) for (const fix of problem.fixes ?? []) {
+    const key = `${fix.id}|${fix.title}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    fixes.push({ ...fix, problem });
+  }
+  fixes.sort((a, b) => Number(Boolean(b.safe)) - Number(Boolean(a.safe)));
+  return fixes.slice(0, MAX_FIXES);
+}
+
+// ---- the extension -----------------------------------------------------------------------------------------------------------------
+/**
+ * `getSource()` is the original text; `applyFix(fix, problem)` performs a fix (the editor's edits or the pane's own action); `say(message)` is
+ * the live region. Returns `{ extension, draw(view, problems), problems(view) }`.
+ */
+export function createDiagnostics({ getSource, applyFix, say }) {
+  let announced = null;
+  const stepProblem = (forward) => (view) => {
+    const source = getSource(), map = textInputMap(source), list = currentProblems(view.state, source);
+    if (!list.length) { say("No problems"); return true; }
+    const sel = view.state.selection.main, here = map.toSource(sel.from), end = map.toSource(sel.to);
+    let target;
+    if (forward) target = list.find((problem) => problem.from > here || (problem.from === here && problem.to > end)) ?? list[0];
+    else target = [...list].reverse().find((problem) => problem.from < here || (problem.from === here && problem.to < end)) ?? list[list.length - 1];
+    selectProblem(view, target, map);
+    return true;
+  };
+  const selectProblem = (view, problem, map) => {
+    const anchor = map.toInput(problem.from), head = map.toInput(problem.to);
+    view.dispatch({ selection: EditorSelection.single(anchor, head), scrollIntoView: true, userEvent: "select.problem" });
+    announced = problem.diagnostic;
+    say(`${SEVERITY_WORD[problem.severity] ?? "Error"}: ${problem.message}${problem.next ? ` Next: ${problem.next}` : ""}`);
+    activateHover(view, anchor, 1, { until: (tr) => tr.docChanged || (tr.selection !== undefined && !tr.isUserEvent("select.problem")) });
+  };
+  const openMenu = (view) => {
+    const fixes = fixesAtCaret(view.state, getSource());
+    if (!fixes.length) { say("No quick fixes available"); return true; }
+    view.dispatch({ effects: openFixes.of({ pos: view.state.selection.main.from, items: fixes }) });
+    say(`${fixes.length} quick ${fixes.length === 1 ? "fix" : "fixes"}. ${fixes[0].title}`);
+    return true;
+  };
+  const menuOpen = (view) => view.state.field(fixMenu, false) !== null;
+  const whenOpen = (run) => (view) => (menuOpen(view) ? (run(view), true) : false);
+  const move = (by) => (view) => {
+    view.dispatch({ effects: moveFixes.of(typeof by === "function" ? by(view.state.field(fixMenu)) : by) });
+    const menu = view.state.field(fixMenu);
+    say(menu.items[menu.selected].title);
+  };
+  const keys = Prec.highest(keymap.of([
+    { key: "ArrowDown", run: whenOpen(move(1)) },
+    { key: "ArrowUp", run: whenOpen(move(-1)) },
+    { key: "Home", run: whenOpen(move((menu) => -menu.selected)) },
+    { key: "End", run: whenOpen(move((menu) => menu.items.length - 1 - menu.selected)) },
+    { key: "Enter", run: whenOpen((view) => { const menu = view.state.field(fixMenu), fix = menu.items[menu.selected]; view.dispatch({ effects: closeFixes.of(null) }); applyFix(fix, fix.problem); }) },
+    { key: "Escape", run: whenOpen((view) => view.dispatch({ effects: closeFixes.of(null) })) },
+    { key: "Tab", run: whenOpen((view) => view.dispatch({ effects: closeFixes.of(null) })) },
+  ]));
+  const plain = keymap.of([
+    { key: "F8", run: stepProblem(true), shift: stepProblem(false) },
+    { key: "Mod-.", run: openMenu },
+  ]);
+  // The caret entering a squiggle says what the problem is, once per problem (a screen reader user finds it without looking for it).
+  const caretWatch = EditorView.updateListener.of((update) => {
+    if (!update.selectionSet || update.docChanged || update.transactions.some((tr) => tr.isUserEvent("select.problem"))) return;
+    const { head } = update.state.selection.main;
+    let found = null;
+    forEachDiagnostic(update.state, (diagnostic, from, to) => { if (!found && diagnostic.problem && head >= from && head <= to && from !== to) found = diagnostic; });
+    if (found && found !== announced) say(`${SEVERITY_WORD[found.severity] ?? "Error"}: ${found.message}`);
+    announced = found;
+  });
+  return {
+    extension: [linter(null), fixMenu, keys, plain, caretWatch],
+    /** Replace the problems drawn in the text. `problems` carry source offsets into `getSource()`. */
+    draw(view, problems) {
+      const source = getSource(), map = textInputMap(source);
+      announced = null;
+      view.dispatch(setDiagnostics(view.state, problems
+        .filter((problem) => Number.isInteger(problem.from) && Number.isInteger(problem.to) && problem.from <= source.length)
+        .map((problem) => toDiagnostic(problem, map, source.length, applyFix))));
+    },
+    problems: (view) => currentProblems(view.state, getSource()),
+    openMenu,
+    next: stepProblem(true),
+    previous: stepProblem(false),
+  };
+}
+
+/** The edit of a fix as one CodeMirror transaction spec (source offsets in, editor offsets out), or null when an edit splits a CRLF pair. */
+export function editsTransaction(state, source, edits, { caret, select, userEvent = "input.fix" } = {}) {
+  const map = textInputMap(source);
+  const sorted = edits.map((edit, index) => ({ edit, index })).sort((a, b) => a.edit.from - b.edit.from || a.index - b.index).map((entry) => entry.edit);
+  const next = applySourceEdits(source, edits);
+  const changes = ChangeSet.of(sorted.map((edit) => ({ from: map.toInput(edit.from), to: map.toInput(edit.to), insert: textInputMap(edit.insert).text })), state.doc.length);
+  const spec = { changes, effects: setJsonSource.of(next), annotations: [Transaction.userEvent.of(userEvent), isolateHistory.of("full")], scrollIntoView: true };
+  const nextMap = textInputMap(next);
+  // A caret or selection is given as offsets in the new text; otherwise the selection follows the edits.
+  if (select) spec.selection = EditorSelection.single(nextMap.toInput(Math.min(select[0], next.length)), nextMap.toInput(Math.min(select[1], next.length)));
+  else if (caret !== undefined) spec.selection = EditorSelection.single(nextMap.toInput(Math.min(caret, next.length)));
+  else spec.selection = state.selection.map(changes, 1);
+  return spec;
+}

package/dist/source-docs.js

@@ -0,0 +1,87 @@
+// The documentation cards of the source editor: the panel beside the selected suggestion and the hover over a key or a value. One model, two uses,
+// plain DOM (no markup is parsed from the schema: its text is shown as text).
+
+const el = (tag, className, text) => {
+  const node = document.createElement(tag);
+  if (className) node.className = className;
+  if (text !== undefined) node.textContent = text;
+  return node;
+};
+
+/**
+ * @typedef {object} DocModel
+ * @property {string} title       the key, the value or the record name
+ * @property {string} [type]      "string", "array of Slide", "layout"
+ * @property {boolean} [required]
+ * @property {boolean} [deprecated]
+ * @property {string} [description]
+ * @property {{ value: unknown, description?: string }[]} [values]   allowed values, shown as chips
+ * @property {unknown[]} [examples]
+ * @property {string} [definition]   the schema definition's name
+ * @property {string[]} [notes]      extra lines (regions of a layout, where a record comes from)
+ */
+
+const MAX_CHIPS = 12;
+const show = (value) => (typeof value === "string" ? value : JSON.stringify(value));
+
+/** The card as DOM. */
+export function docNode(model) {
+  const root = el("div", "opf-doc");
+  const head = el("div", "opf-doc-head");
+  head.append(el("code", "opf-doc-title", model.title));
+  if (model.type) head.append(el("span", "opf-doc-type", model.type));
+  if (model.required) head.append(el("span", "opf-doc-badge", "required"));
+  if (model.deprecated) head.append(el("span", "opf-doc-badge", "deprecated"));
+  root.append(head);
+  if (model.description) root.append(el("p", "opf-doc-text", model.description));
+  for (const note of model.notes ?? []) root.append(el("p", "opf-doc-note", note));
+  if (model.values?.length) {
+    const chips = el("div", "opf-doc-values");
+    for (const entry of model.values.slice(0, MAX_CHIPS)) {
+      const chip = el("code", "opf-doc-chip", show(entry.value));
+      if (entry.description) chip.title = entry.description;
+      chips.append(chip);
+    }
+    if (model.values.length > MAX_CHIPS) chips.append(el("span", "opf-doc-more", `and ${model.values.length - MAX_CHIPS} more`));
+    root.append(chips);
+  }
+  const example = model.examples?.find((value) => value !== undefined && !(typeof value === "string" && value.includes("...")));
+  if (example !== undefined) {
+    const line = el("p", "opf-doc-example");
+    line.append("Example: ", el("code", undefined, typeof example === "string" ? JSON.stringify(example) : JSON.stringify(example).slice(0, 80)));
+    root.append(line);
+  }
+  if (model.definition) root.append(el("p", "opf-doc-source", `Schema: ${model.definition}`));
+  return root;
+}
+
+/** The card as plain text (what a screen reader hears and what the tests read). */
+export function docText(model) {
+  return [model.title, model.type, model.required ? "required" : "", model.description, ...(model.notes ?? [])].filter(Boolean).join(". ");
+}
+
+/** The model of a field described by `describeField` (`info`), named `title`. */
+export function fieldDoc(info, title) {
+  return {
+    title,
+    type: typeOfInfo(info),
+    required: info.required,
+    deprecated: info.deprecated,
+    description: info.description,
+    values: info.enum,
+    examples: info.examples,
+    definition: info.definition,
+  };
+}
+
+function typeOfInfo(info) {
+  if (info.catalogKind) return info.catalogKind.replace(/s$/, "").replace(/([A-Z])/g, " $1").toLowerCase() + " id";
+  if (info.enum?.length > 1) return "enum";
+  const kinds = info.types.map((type) => (type === "array" && info.itemInfo ? `array of ${info.itemInfo.definition ?? info.itemInfo.types.join(" | ")}` : type));
+  return [...new Set(kinds)].join(" | ");
+}
+
+/** The model of one property of an object (a `FieldChild` of `describeField`): the card beside a key suggestion. */
+export function childDoc(child) {
+  return { title: child.key, type: child.typeLabel, required: child.required, deprecated: child.deprecated, description: child.description };
+}

package/dist/source-findings.js

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

package/dist/source-fixes.js

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

package/dist/source-json.js

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