@openpresentation/opf-editor 0.26.10 → 0.28.0

package/dist/react.js

@@ -1,3 +1,4 @@
+import { createElement, forwardRef, useCallback, useEffect, useImperativeHandle, useRef, useState, useSyncExternalStore } from "react";
 import { commitCatalogControl } from "./catalog-control.js";
 import {
   getCatalogOptions,
@@ -96,3 +97,129 @@ export function createOPFReactComponents(React) {
     OPFCatalogSelect
   };
 }
+
+// ---- CE-06: the embeddable editor for React 18 and 19 ----------------------------------------------------------------------------------
+// `<OpfEditor>` mounts `createOpfEditor` (src/workspace.js) in an effect and destroys it in the cleanup, so it is correct under StrictMode's
+// mount, unmount, mount: the editor module is loaded on demand (an import that resolves after both effects), the first effect's request is
+// cancelled by its cleanup, and only the second creates an editor. The server renders an empty container; nothing of the editor
+// (and none of its code) runs there. React is an optional peer: only this entry point needs it.
+
+const NO_STOP = () => {};
+const isRef = (value) => value !== null && typeof value === "object" && "current" in value;
+
+/** `slots` whose values are React refs (`useRef`) resolve to their elements when the editor mounts, after the commit that attached them. */
+function resolveSlots(slots) {
+  if (!slots) return undefined;
+  const resolved = {};
+  for (const [name, value] of Object.entries(slots)) resolved[name] = isRef(value) ? value.current : value;
+  return resolved;
+}
+
+// The props that are not editor options.
+const COMPONENT_PROPS = new Set(["className", "style", "id", "onEditor", "children", "slots", "onChange", "onSelection", "onCursor", "onError", "onReady"]);
+
+function splitProps(props) {
+  const options = {};
+  const rest = {};
+  for (const [name, value] of Object.entries(props)) (COMPONENT_PROPS.has(name) ? rest : options)[name] = value;
+  return { options, rest };
+}
+
+/**
+ * Create and destroy one editor in the element `container.current` points at. The options are read once, when the editor mounts (change the
+ * `key` of the component to mount another); `theme`, `readOnly`, `view`, `density` and `exportMode` follow later renders. The callbacks
+ * (`onChange`, `onSelection`, `onCursor`, `onError`, `onReady`) always call the latest function passed. Returns the editor once it is mounted, else `null`.
+ */
+function useMountedEditor(container, props, onEditor) {
+  const [editor, setEditor] = useState(null);
+  const latest = useRef(props);
+  latest.current = props;
+  const report = useRef(onEditor);
+  report.current = onEditor;
+  useEffect(() => {
+    const element = container.current;
+    if (!element) return undefined;
+    let cancelled = false;
+    let created = null;
+    import("./workspace.js").then(({ createOpfEditor }) => {
+      if (cancelled) return;
+      const { options } = splitProps(latest.current);
+      const current = () => latest.current;
+      created = createOpfEditor(element, {
+        ...options,
+        slots: resolveSlots(latest.current.slots),
+        onChange: (detail) => current().onChange?.(detail),
+        onSelection: (detail) => current().onSelection?.(detail),
+        onCursor: (detail) => current().onCursor?.(detail),
+        onError: (error, detail) => current().onError?.(error, detail),
+        onReady: (detail) => current().onReady?.(detail),
+      });
+      setEditor(created);
+      report.current?.(created);
+    }, (error) => {
+      if (!cancelled) latest.current.onError?.(error instanceof Error ? error : new Error(String(error)), {});
+    });
+    return () => {
+      cancelled = true;
+      if (!created) return;
+      created.destroy();
+      created = null;
+      setEditor(null);
+      report.current?.(null);
+    };
+    // The editor mounts once per element: later options are applied by the effects below, or by a new `key`.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [container]);
+  const { theme, readOnly, view, density, exportMode } = props;
+  // A theme written inline in JSX is a new object on every render; it is applied again only when its content changed.
+  const themeKey = theme === undefined ? undefined : JSON.stringify(theme);
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  useEffect(() => { if (editor && theme !== undefined) editor.setTheme(theme); }, [editor, themeKey]);
+  useEffect(() => { if (editor && readOnly !== undefined) editor.setReadOnly(readOnly); }, [editor, readOnly]);
+  useEffect(() => { if (editor && view !== undefined && editor.view !== view) editor.setView(view); }, [editor, view]);
+  useEffect(() => { if (editor && density !== undefined) editor.setDensity(density); }, [editor, density]);
+  useEffect(() => { if (editor && exportMode !== undefined) editor.setExportMode(exportMode); }, [editor, exportMode]);
+  return editor;
+}
+
+/**
+ * The editor in a `<div>`. Every prop that is not `className`, `style`, `id`, `slots` or a callback is an option of `createOpfEditor`;
+ * `ref` is the editor handle once mounted, and `onEditor(editor | null)` tells the parent when it is created and destroyed (for the hooks below).
+ */
+export const OpfEditor = forwardRef(function OpfEditor(props, ref) {
+  const container = useRef(null);
+  const editor = useMountedEditor(container, props, props.onEditor);
+  useImperativeHandle(ref, () => editor, [editor]);
+  const { rest } = splitProps(props);
+  return createElement("div", { ref: container, id: rest.id, className: rest.className, style: rest.style, "data-opf-react": "" });
+});
+
+/**
+ * The editor as a hook, for a host that renders its own element: `const { ref, editor } = useOpfEditor(options)` and `<div ref={ref} />`.
+ * `editor` is `null` on the server and until the client has mounted it. Options are read once, as for `<OpfEditor>`.
+ */
+export function useOpfEditor(options = {}) {
+  const ref = useRef(null);
+  const editor = useMountedEditor(ref, options);
+  return { ref, editor };
+}
+
+const subscribeTo = (editor, event) => (notify) => (editor ? editor.on(event, notify) : NO_STOP);
+
+/** The document of an editor, replaced on every change (it is frozen, so it works as a store snapshot). `undefined` until there is an editor. */
+export function useOpfDocument(editor) {
+  const subscribe = useCallback(subscribeTo(editor, "change"), [editor]);
+  return useSyncExternalStore(subscribe, () => (editor ? editor.getDocument() : undefined), () => undefined);
+}
+
+/** The content last selected on the canvas, `{ path, value }`, or `null`. */
+export function useOpfSelection(editor) {
+  const subscribe = useCallback(subscribeTo(editor, "selection"), [editor]);
+  return useSyncExternalStore(subscribe, () => (editor ? editor.selection : null), () => null);
+}
+
+/** The path under the caret of the source pane (the latest `cursor` event: `{ pointer, idPath, from, to, ... }`), or `null` before the first. */
+export function useOpfCursor(editor) {
+  const subscribe = useCallback(subscribeTo(editor, "cursor"), [editor]);
+  return useSyncExternalStore(subscribe, () => (editor ? editor.sourceCursor : null), () => null);
+}

package/dist/slide-retention.js

@@ -0,0 +1,13 @@
+// CE-06 (promoted from openpresentation.org's playground runtime): which slide to show after the document changed outside the canvas
+// (the source pane, an opened file, a restored copy). Stable ids survive a reorder; a deck without ids, or an id that is not unique, keeps
+// the position and clamps it to the deck.
+
+/** @param {readonly {id?: string}[]} before @param {readonly {id?: string}[]} after @param {number} index */
+export function retainedSlideIndex(before, after, index) {
+  const id = before[index]?.id;
+  if (id && before.filter((slide) => slide.id === id).length === 1) {
+    const matches = after.flatMap((slide, position) => (slide.id === id ? [position] : []));
+    if (matches.length === 1) return matches[0];
+  }
+  return Math.max(0, Math.min(index, after.length - 1));
+}

package/dist/source-color-scheme.js

@@ -0,0 +1,60 @@
+import { Compartment } from "@codemirror/state";
+import { EditorView, ViewPlugin } from "@codemirror/view";
+
+// Selection contrast: CodeMirror styles an editor as light or dark through the `EditorView.darkTheme` facet, and its own base theme paints a selection
+// by that flag (`#d7d4f0` for a light editor, drawn behind the text). The editor's colors come from the `--opf-ui-*` tokens, so the flag has to follow
+// the color scheme those tokens resolve to, or a dark surface keeps light text on a light selection. `colorSchemeExtension(parent)` is that facet,
+// kept in step with the page: it reads the `color-scheme` the surface resolves to (the tokens set it with the scheme), and looks again when a class,
+// `data-theme` or `style` attribute changes on the editor or any ancestor, when `prefers-color-scheme` changes (a surface left to `light dark`) and
+// when the editor takes focus.
+
+/** True when `element` is drawn in a dark color scheme: its resolved `color-scheme` is `dark`, or lists both and the system prefers dark. */
+export function prefersDark(element) {
+  const win = element?.ownerDocument?.defaultView;
+  if (!win || !element.isConnected) return false;
+  const scheme = win.getComputedStyle(element).colorScheme.split(/\s+/);
+  if (scheme.includes("dark")) return scheme.includes("light") ? Boolean(win.matchMedia?.("(prefers-color-scheme: dark)").matches) : true;
+  return false;
+}
+
+const DARK = EditorView.darkTheme.of(true);
+
+/** The extension for a view that will be mounted in `parent`: the dark flag now, and the plugin that keeps it in step. */
+export function colorSchemeExtension(parent) {
+  const scheme = new Compartment();
+  const watcher = ViewPlugin.fromClass(class {
+    constructor(view) {
+      this.view = view;
+      this.dark = prefersDark(parent.isConnected ? parent : view.dom);
+      this.dead = false;
+      this.queued = false;
+      const win = view.dom.ownerDocument.defaultView;
+      this.observer = typeof win?.MutationObserver === "function" ? new win.MutationObserver(() => this.queue()) : null;
+      for (let node = view.dom; node; node = node.parentElement) this.observer?.observe(node, { attributes: true, attributeFilter: ["class", "data-theme", "style"] });
+      this.media = win?.matchMedia?.("(prefers-color-scheme: dark)") ?? null;
+      this.onMedia = () => this.queue();
+      this.media?.addEventListener?.("change", this.onMedia);
+      // The surface may not be in the document yet (the host mounts it first, attaches it after): look again once this update is over.
+      this.queue();
+    }
+    update(update) { if (update.focusChanged) this.queue(); }
+    queue() {
+      if (this.queued || this.dead) return;
+      this.queued = true;
+      queueMicrotask(() => { this.queued = false; this.sync(); });
+    }
+    sync() {
+      if (this.dead) return;
+      const dark = prefersDark(this.view.dom);
+      if (dark === this.dark) return;
+      this.dark = dark;
+      this.view.dispatch({ effects: scheme.reconfigure(dark ? DARK : []) });
+    }
+    destroy() {
+      this.dead = true;
+      this.observer?.disconnect();
+      this.media?.removeEventListener?.("change", this.onMedia);
+    }
+  });
+  return [scheme.of(prefersDark(parent) ? DARK : []), watcher];
+}

package/dist/source-pane.d.ts

@@ -74,7 +74,74 @@ export interface OutlineSymbol {
   line: number;
 }
 
+/**
+ * Where the caret is in the text (CE-17), in any of the three formats. Offsets are source offsets: UTF-16 positions in the text as `getText()` returns it.
+ */
+export interface SourceCursor {
+  /** The JSON Pointer of the field under the caret (`/slides/0/title`; `""` outside the document's content). On a property name or value it is that property; between members it is the container. */
+  pointer: string;
+  /** The same place addressed by id (`/slides/@intro/title`), read from the session's document; the pointer itself where an element has no id, or while the text does not read as a document. */
+  idPath: string;
+  /** The start and end of the main selection (equal for a plain caret). */
+  from: number;
+  to: number;
+  /** The end of the selection the caret is at; `pointer` is read here. */
+  head: number;
+  /** What the caret is on: a property name (`key`), a value, whitespace or punctuation inside a container (`between`), or outside the document (`none`). */
+  part: "key" | "value" | "between" | "none";
+  format: SourceFormat;
+}
+
+/** One mark or line class a host draws in the text (CE-17), by path or by range. */
+export interface SourceDecoration {
+  /** A JSON Pointer (or dotted OPF path). The decoration follows the field when slides move, and is not drawn while the text has no such field. */
+  path?: string;
+  /** Which part of the field a `path` marks: the value (default), its `key`, the whole `entry` (key through value), the `open` bracket or the `colon`. */
+  part?: "value" | "key" | "entry" | "open" | "colon";
+  /** Source offsets, instead of a path. They follow the text as it is edited, as text positions, and are not placed again when the format changes. */
+  range?: { from: number; to?: number };
+  /** The class `opf-source-decoration-<kind>`; the built-in looks are `highlight` (default), `error`, `warning`, `info`, `added` and `changed`. Any other kind is styled by the host. */
+  kind?: string;
+  /** The browser tooltip of a mark. */
+  label?: string;
+  /** Put the class on every line the range touches (a `.cm-line`) instead of marking the text. */
+  line?: boolean;
+}
+
+/** A host decoration as drawn now (`getDecorations`). */
+export interface SourceDecorationInfo {
+  group: string;
+  kind: string;
+  label?: string;
+  path?: string;
+  /** The current source offsets; a line decoration spans from the first line's start to the last line's end. */
+  from: number;
+  to: number;
+  line: boolean;
+}
+
+export interface RevealOptions {
+  /** Also focus the code editor (default false: the page's focus stays where it is). */
+  focus?: boolean;
+  /** Also select the range (default false: the caret stays; this also emits a `cursor` event). */
+  select?: boolean;
+  /** Where the start of the range lands: `center` (default), `start` (the top) or `nearest` (the least scrolling). */
+  align?: "center" | "start" | "nearest";
+  /** Mark the first line for a moment. */
+  flash?: boolean;
+  /** Which part of the field a path means (default `entry`: the key through the end of its value). */
+  part?: SourceDecoration["part"];
+}
+
 export interface SourcePaneOptions {
+  /**
+   * The caret or selection moved (also while the pane has no focus), or the text under it changed: the path under the caret. Called after `cursorDelay` of
+   * quiet and not at all for a position it already reported; while a typed edit waits to be applied it waits too, so `idPath` is read from the document
+   * the text reads as. `getCursor()` reads the position at once.
+   */
+  onCursor?(cursor: SourceCursor): void;
+  /** Milliseconds of quiet before `onCursor` is called (default 50; 0 is the next tick). */
+  cursorDelay?: number;
   /** Add an Outline button to the bar and a panel listing the slides and other symbols of the document (`"open"` shows the panel at the start). The symbol picker (Cmd/Ctrl+Shift+O) is always there. */
   outline?: boolean | "open";
   /** Called with `getShortcuts()` when the shortcuts dialog is about to open; returning `true` means the host shows its own and the editor's dialog stays closed. */
@@ -160,6 +227,24 @@ export interface SourcePane {
   getFormat(): SourceFormat;
   /** 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 path under the caret now (see `SourceCursor`), read at once and also while the pane has no focus. */
+  getCursor(): SourceCursor;
+  /**
+   * Scroll a JSON Pointer (or dotted path) or a range `{ from, to }` (source offsets) into view without moving the caret or the focus, which
+   * `focusPath` does. Folded text around the start is opened. Returns the range revealed, its one-based line, and whether the path is exactly in the
+   * text (`false`: the nearest container was revealed); `null` when the path cannot be placed at all.
+   */
+  revealPath(target: string | { from: number; to?: number }, options?: RevealOptions): { from: number; to: number; line: number; exact: boolean } | null;
+  /**
+   * Draw marks or line classes of your own, by path or range, kept apart from the editor's own decorations (squiggles, field highlights, the outline's
+   * marker). `group` (default `default`) names a set; a call replaces the whole set, so validation issues and the paths an agent touched can be
+   * two groups. `[]` or `null` clears the set. A decoration with neither a path nor a range throws a `TypeError`.
+   */
+  setDecorations(decorations: readonly SourceDecoration[] | null, options?: { group?: string }): void;
+  /** Clear the decorations of `group`, or all of the host's without an argument. */
+  clearDecorations(group?: string): void;
+  /** The host decorations drawn now, at their current offsets, in position order; of `group`, or all. */
+  getDecorations(group?: string): SourceDecorationInfo[];
   /** The text as shown, with any pending edit applied first. */
   getText(): string;
   /**

package/dist/source-pane.js

@@ -2,7 +2,7 @@ import { scanYamlComments, toYaml } from "@openpresentation/opf/yaml";
 import { toMarkdown } from "@openpresentation/opf/markdown";
 import { mountJsonCodeEditor } from "./json-editor.js";
 import { MAX_EXACT_SOURCE_LENGTH, createSourceMemory, updateJsonSource } from "./exact-source.js";
-import { lineForPath, offsetOfLine } from "./source-lines.js";
+import { lineForPath, lineOfOffset, offsetOfLine, pathSegments } from "./source-lines.js";
 import { errorText, normalizeFinding, rejectionFindings as findingsOfError } from "./source-findings.js";
 import { formatSource } from "./source-format.js";
 import { buildProblems, summarize } from "./source-problems.js";
@@ -11,7 +11,8 @@ import { createSourceChecker } from "./source-checker.js";
 import { detailsFor } from "./source-details.js";
 import { schemaAtPath, schemaVariants } from "./schema.js";
 import { locateText } from "./source-ranges.js";
-import { scanMarkdown, starterValue } from "@openpresentation/opf/source";
+import { pathAt, scanMarkdown, starterValue } from "@openpresentation/opf/source";
+import { toIdPointer } from "@openpresentation/opf/ids";
 import { listCatalogRecords } from "./catalogs.js";
 import { documentSymbols, symbolAt } from "./source-symbols.js";
 
@@ -135,6 +136,11 @@ export function createSourcePane(container, options = {}) {
   const checker = options.worker ? createSourceChecker({ worker: options.worker, onError: (error) => options.onError?.(error) }) : null;
   let checkToken = 0, syntaxToken = 0, checkBusy = false, syntaxBusy = false;
   const stats = { worker: 0, inline: 0 };
+  // CE-17: the cursor event's pause and what it last said, and the host's decoration groups (below, with the cursor and the decorations).
+  const cursorDelay = Math.max(0, options.cursorDelay ?? 50);
+  let cursorTimer = null, cursorKey = "", cursorWaiting = false;
+  const hostGroups = new Map();
+  let decorationTimer = null, flashTimer = null;
   let problemRows = [], lastDraft = null, lastSummary = "No problems", summaryTimer = null, syntaxTimer = null, recheckTimer = null;
   // The exact text of the documents `replaceDocument` replaced and opened, per format, so Undo and Redo show it again byte for byte
   // (a YAML comment, the author's JSON spelling). Keyed by format and document; the oldest entries go first.
@@ -260,7 +266,8 @@ export function createSourcePane(container, options = {}) {
     onChange: () => schedule(),
     onFormat: () => formatDocument(),
     onFocusProblems: () => focusProblems(),
-    onSelectionChange: () => scheduleOutline(),
+    onSelectionChange: () => { scheduleOutline(); scheduleCursor(); },
+    onDocChange: () => scheduleDecorations(),
     onShowShortcuts: options.onShowShortcuts,
     // The pane supplies the problems itself (every finding, with ranges and fixes).
     syntaxProblems: false,
@@ -667,6 +674,7 @@ export function createSourcePane(container, options = {}) {
     dirty = false;
     control.setLanguage(target.language);
     show(written.text);
+    refreshDecorations();
     if (format === "md") refreshNotes();
     // A draft the document never accepted is checked and applied again, so its findings come back with it.
     if (written.draft) { baseline = null; flush(); }
@@ -689,6 +697,7 @@ export function createSourcePane(container, options = {}) {
     syntaxFindings = [];
     noteFindings = [];
     control.setLanguage(target.language);
+    refreshDecorations();
     updateBar();
     baseline = null;
     flush();
@@ -1137,6 +1146,115 @@ export function createSourcePane(container, options = {}) {
     return true;
   }
 
+  // ---- Cursor (CE-17) -----------------------------------------------------------------------------------------------
+  // The document path under the caret in the text as shown, for any format (core's `pathAt` reads text that does not parse). `idPath` is the same place
+  // addressed by id, read from the session's document: while the text is a draft that has not been applied, the event waits for the apply (the
+  // pointer into a deck the session has not got yet would name another slide), and while the text does not read as a document `idPath` is the pointer.
+  function readCursor() {
+    const text = control.api.getValue();
+    const [from, to] = control.api.getSelection();
+    const head = control.api.getHead();
+    const found = attempt(() => pathAt(text, format, head), undefined);
+    const at = pointer(found?.path ?? []);
+    return { pointer: at, idPath: attempt(() => toIdPointer(deck(), at), at), from, to, head, part: found?.part ?? "none", format };
+  }
+  const settled = () => timer === null && syntaxTimer === null && !checkBusy && !syntaxBusy;
+  function scheduleCursor() {
+    if (destroyed || !options.onCursor) return;
+    clearTimeout(cursorTimer);
+    cursorTimer = setTimeout(emitCursor, cursorDelay);
+  }
+  function emitCursor() {
+    cursorTimer = null;
+    if (destroyed) return;
+    if (!settled()) {
+      if (!cursorWaiting) { cursorWaiting = true; idle().then(() => { cursorWaiting = false; scheduleCursor(); }); }
+      return;
+    }
+    const detail = readCursor();
+    const key = JSON.stringify([detail.format, detail.from, detail.to, detail.head, detail.pointer, detail.idPath, detail.part]);
+    if (key === cursorKey) return;
+    cursorKey = key;
+    try { options.onCursor?.(detail); } catch (error) { options.onError?.(error); }
+  }
+
+  // ---- Host decorations and reveal (CE-17) --------------------------------------------------------------------------------
+  // A host's marks and line classes live in the code editor's own sets (`host:range:<group>` and `host:path:<group>`), apart from the editor's
+  // squiggles and field highlights. A range follows the text as it is edited; a path is found again after each edit (and at once when the format
+  // changes), so it stays on its field when slides move.
+  const kindClass = (kind) => `opf-source-decoration opf-source-decoration-${String(kind || "highlight").toLowerCase().replace(/[^a-z0-9_-]+/g, "-")}`;
+  const hostItem = (group, spec, from, to) => ({ from, to, line: Boolean(spec.line), className: kindClass(spec.kind), title: spec.label, data: { group, kind: spec.kind || "highlight", ...(spec.path !== undefined ? { path: spec.path } : {}) } });
+  function drawPaths(group) {
+    const entry = hostGroups.get(group);
+    if (!entry) return;
+    const text = control.api.getValue();
+    const items = [];
+    for (const spec of entry.paths) {
+      const found = attempt(() => locateText(format, text, pathSegments(spec.path), spec.part ?? "value"), null);
+      if (found?.exact) items.push(hostItem(group, spec, found.from, found.to));
+    }
+    control.setDecorations(`host:path:${group}`, items);
+  }
+  function refreshDecorations() {
+    clearTimeout(decorationTimer);
+    decorationTimer = null;
+    if (!destroyed) for (const [group, entry] of hostGroups) if (entry.paths.length) drawPaths(group);
+  }
+  function scheduleDecorations() {
+    if (destroyed || ![...hostGroups.values()].some((entry) => entry.paths.length)) return;
+    clearTimeout(decorationTimer);
+    decorationTimer = setTimeout(refreshDecorations, 120);
+  }
+  function clearGroup(group) {
+    hostGroups.delete(group);
+    control.clearDecorations(`host:range:${group}`);
+    control.clearDecorations(`host:path:${group}`);
+  }
+  function setHostDecorations(list, { group = "default" } = {}) {
+    if (destroyed) return;
+    const specs = list === null || list === undefined ? [] : list;
+    if (!Array.isArray(specs)) throw new TypeError("setDecorations needs a list of decorations (or null to clear).");
+    const ranges = [], paths = [];
+    for (const spec of specs) {
+      if (typeof spec?.path === "string") paths.push(spec);
+      else if (Number.isFinite(spec?.range?.from) && Number.isFinite(spec?.range?.to ?? spec.range.from)) ranges.push(spec);
+      else throw new TypeError("A decoration needs a path (a JSON Pointer) or a range ({ from, to } in source offsets).");
+    }
+    if (!specs.length) { clearGroup(group); return; }
+    hostGroups.set(group, { paths });
+    control.setDecorations(`host:range:${group}`, ranges.map((spec) => hostItem(group, spec, spec.range.from, spec.range.to ?? spec.range.from)));
+    drawPaths(group);
+  }
+  function revealTarget(target, { focus = false, select = false, align = "center", flash = false, part = "entry" } = {}) {
+    let range;
+    if (typeof target === "string") {
+      const found = attempt(() => locateText(format, control.api.getValue(), pathSegments(target), part), null);
+      if (!found) return null;
+      range = found;
+    } else if (Number.isFinite(target?.from)) {
+      const size = control.api.getValue().length;
+      const from = Math.min(size, Math.max(0, target.from));
+      range = { from, to: Math.min(size, Math.max(from, Number.isFinite(target.to) ? target.to : from)), exact: true };
+    } else throw new TypeError("revealPath needs a JSON Pointer or a range ({ from, to } in source offsets).");
+    control.reveal(range.from, range.to, { align, select, focus });
+    if (flash) {
+      control.setDecorations("flash", [{ from: range.from, to: range.from, line: true, className: "opf-source-flash" }]);
+      clearTimeout(flashTimer);
+      flashTimer = setTimeout(() => { flashTimer = null; if (!destroyed) control.clearDecorations("flash"); }, 1200);
+    }
+    return { from: range.from, to: range.to, line: lineOfOffset(control.api.getValue(), range.from), exact: range.exact };
+  }
+  function hostDecorationList(group) {
+    return control.getDecorations().filter((item) => item.key.startsWith("host:") && (group === undefined || item.data.group === group))
+      .map((item) => ({ group: item.data.group, kind: item.data.kind, ...(item.title ? { label: item.title } : {}), ...(item.data.path !== undefined ? { path: item.data.path } : {}), from: item.from, to: item.to, line: item.line }));
+  }
+  function idle() {
+    return new Promise((resolve) => {
+      const poll = () => { if (destroyed || settled()) resolve(); else setTimeout(poll, 4); };
+      poll();
+    });
+  }
+
   // ---- Public API ---------------------------------------------------------------------------------------------------
   function focusPath(path, finding) {
     flush();
@@ -1220,15 +1338,36 @@ export function createSourcePane(container, options = {}) {
     getOutline: () => documentSymbols(format, control.api.getValue()),
     /** Show or hide the outline panel (needs the `outline` option); with no argument it toggles. Returns whether the panel is open. */
     toggleOutline(open) { if (!outlinePanel) return false; setOutlineOpen(open ?? outlinePanel.hidden); return !outlinePanel.hidden; },
+    /**
+     * CE-17: the path under the caret: `{ pointer, idPath, from, to, head, part, format }` (offsets are source offsets), also when the pane has no focus.
+     * Read now, without waiting for the pending edit or the pause `onCursor` uses.
+     */
+    getCursor: () => readCursor(),
+    /**
+     * CE-17: scroll a JSON Pointer (or dotted path) or a range `{ from, to }` into view without moving the caret or the focus; folded text is opened.
+     * `focus` and `select` do move them. `align`: "center" (default), "start" or "nearest"; `flash` marks the first line for a moment; `part`: which part of
+     * the field a path means (default `entry`: the key through its value). Returns the range, its line and whether the path is exactly there, or `null`.
+     */
+    revealPath: revealTarget,
+    /**
+     * CE-17: draw marks (or line classes) a host owns, by path or range, apart from the editor's own decorations. `group` (default `default`) names a set, and a
+     * call replaces it. A range follows the text as it is edited; a path is placed again after each edit, and not drawn while the text has no such field.
+     * `[]` or `null` clears the set.
+     */
+    setDecorations: setHostDecorations,
+    /** CE-17: clear the decorations of `group`, or every host decoration without an argument. */
+    clearDecorations(group) {
+      if (destroyed) return;
+      if (group !== undefined) { clearGroup(group); return; }
+      for (const name of [...hostGroups.keys()]) clearGroup(name);
+      control.clearDecorations();
+    },
+    /** CE-17: the host decorations drawn now at their current offsets: `{ group, kind, label?, path?, from, to, line }`. */
+    getDecorations: (group) => hostDecorationList(group),
     /** The code editor, for hosts that focus or measure it. */
     editor: control,
     /** Resolves once no edit is waiting for its delay and no check is running (a worker's included): the text on screen has been read and applied. */
-    whenIdle() {
-      return new Promise((resolve) => {
-        const poll = () => { if (destroyed || (timer === null && syntaxTimer === null && !checkBusy && !syntaxBusy)) resolve(); else setTimeout(poll, 4); };
-        poll();
-      });
-    },
+    whenIdle: idle,
     /** How the applied edits were checked: `worker` and `inline` counts, and whether the worker is still usable (`available`). */
     checkerStats: () => ({ worker: stats.worker, inline: stats.inline, available: Boolean(checker?.available) }),
     destroy() {
@@ -1243,6 +1382,9 @@ export function createSourcePane(container, options = {}) {
       clearTimeout(recheckTimer);
       clearTimeout(outlineTimer);
       clearTimeout(outlineMarkTimer);
+      clearTimeout(cursorTimer);
+      clearTimeout(decorationTimer);
+      clearTimeout(flashTimer);
       unsubscribe();
       document.removeEventListener("pointerdown", outside, true);
       control.destroy();

package/dist/studio-kit/commands.d.ts

@@ -0,0 +1,38 @@
+/** CE-18 studio kit (internal): the command registry and keymap. */
+export interface KitCommand<Ctx = unknown> {
+  id: string;
+  label: string;
+  group?: string;
+  /** The scope(s) `handle` runs it in (default "global"). */
+  scope?: string | string[];
+  /** CodeMirror-style key specs: "Mod-z", "Shift-Mod-z", "Ctrl-y", "[", "Delete", "F2". */
+  keys?: string[];
+  /** What a menu shows instead of the formatted first key. */
+  hint?: string;
+  /** false: a held key does not repeat the command. */
+  repeat?: boolean;
+  /** true runs it; false or a reason string disables it. */
+  when?(ctx: Ctx): boolean | string;
+  run(ctx: Ctx, event?: KeyboardEvent): unknown;
+}
+export interface KitCommandInfo { id: string; label: string; group?: string; keys: string[]; shortcut: string; enabled: boolean; reason: string }
+export interface KitKey { key: string; shift: boolean; alt: boolean; mod: boolean; ctrl: boolean; meta: boolean }
+export interface KitCommandRegistry<Ctx = unknown> {
+  register(command: KitCommand<Ctx>): () => void;
+  get(id: string): KitCommand<Ctx> | undefined;
+  has(id: string): boolean;
+  setKeymap(map: Record<string, string | string[] | null>): void;
+  list(ctx: Ctx, options?: { win?: Window }): KitCommandInfo[];
+  enabled(id: string, ctx: Ctx): boolean;
+  run(id: string, ctx: Ctx, event?: KeyboardEvent): boolean;
+  match(event: KeyboardEvent, ctx: Ctx, options?: { scope?: string }): KitCommand<Ctx> | null;
+  handle(event: KeyboardEvent, ctx: Ctx, options?: { scope?: string }): boolean;
+  menu(ids: string[], ctx: Ctx, options?: { win?: Window }): { id: string; label: string; hint?: string; disabled: boolean; title?: string; onSelect(): void }[];
+}
+export declare function createCommandRegistry<Ctx = unknown>(options?: { commands?: KitCommand<Ctx>[] }): KitCommandRegistry<Ctx>;
+export declare function parseKey(spec: string): KitKey;
+export declare function matchKey(event: Pick<KeyboardEvent, "key" | "code" | "shiftKey" | "altKey" | "ctrlKey" | "metaKey">, spec: string | KitKey): boolean;
+export declare function formatKey(spec: string | KitKey, win?: Window): string;
+export declare function isHandled(event: Event): boolean;
+export declare function markHandled(event: Event): void;
+export declare function keyGuard(event: KeyboardEvent): boolean;