@openpresentation/opf-editor 0.27.0 → 0.29.0

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-completions.js

@@ -6,7 +6,7 @@ import { isolateHistory } from "@codemirror/commands";
 import { EditorSelection } from "@codemirror/state";
 import { describeField } from "@openpresentation/opf/schema";
 import { listCatalogRecords, mergeCatalogs } from "./catalogs.js";
-import { LAYOUT_INTENT_GROUPS, layoutRegionSummary } from "./layout-templates.js";
+import { CUSTOM_LAYOUTS_GROUP, layoutGroupName, layoutGroupOrder, layoutRegionSummary } from "./layout-templates.js";
 import { Document, parse as parseYamlDocument, parseDocument } from "yaml";
 import { pathAt, scanMarkdown } from "@openpresentation/opf/source";
 import { findNodeAtLocation, getNodeValue } from "jsonc-parser";
@@ -188,12 +188,14 @@ function literalOption(label, literal, extra) {
 function catalogOptions(kind, context, catalogs) {
   let records = [];
   try { records = listCatalogRecords(context.document, kind, { catalogs }); } catch { records = []; }
+  // Deck records first, then the catalog's groups in its own order (and its records in its order within a group), then custom layouts.
+  const position = new Map(records.map((record, index) => [record, index]));
+  const groups = kind === "layouts" ? layoutGroupOrder(records) : [];
   const order = (record) => {
     if (record.origin === "document") return -1;
     if (kind !== "layouts") return 0;
-    const id = record.id.replace(/^default:/, "");
-    const group = LAYOUT_INTENT_GROUPS.findIndex((entry) => entry.ids.includes(id));
-    return group < 0 ? LAYOUT_INTENT_GROUPS.length * 100 : group * 100 + LAYOUT_INTENT_GROUPS[group].ids.indexOf(id);
+    const group = layoutGroupName(record);
+    return (group === CUSTOM_LAYOUTS_GROUP ? groups.length : groups.indexOf(group)) * 100000 + position.get(record);
   };
   records.sort((a, b) => order(a) - order(b) || a.label.localeCompare(b.label, "en", { numeric: true }) || a.id.localeCompare(b.id, "en"));
   const intent = kind === "layouts";

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. */
@@ -112,13 +179,17 @@ export interface SourcePaneOptions {
   smartListEnter?: boolean;
   /**
    * Run the pane's text checks (reading YAML or Markdown, the syntax pass of JSON and the document validation) in a Web Worker, so typing in a deck
-   * of a thousand slides never blocks the main thread. A function returns the Worker (`() => new Worker(new URL("@openpresentation/opf-editor/source-worker", import.meta.url), { type: "module" })`
-   * with a bundler that supports that form); a Worker is used as given; `true` starts `source-worker.js` beside the package's own module, which works
-   * when a bundler follows `new URL(..., import.meta.url)`. Only the typing delay uses the worker: every explicit action (`getText`, switching the format,
-   * `replaceDocument`, Format, Undo) is applied on the main thread at once. When the worker cannot start, fails or stops answering, the pane checks on the
-   * main thread from then on and `onError` is called once; no edit is lost. Default `false` (everything on the main thread).
+   * of a thousand slides never blocks the main thread. `true` starts the package's own worker with `new Worker(new URL("./source-worker.js",
+   * import.meta.url), { type: "module" })`, which webpack, Turbopack and Vite (build) bundle; a function returns the Worker
+   * (`() => new Worker(new URL("@openpresentation/opf-editor/source-worker", import.meta.url), { type: "module" })`); a Worker is used as given; a URL
+   * (or a string) is the address of a worker script the host built itself (esbuild: build `@openpresentation/opf-editor/source-worker` as an entry
+   * point) and is started as a module worker. The worker file imports core, so it only runs bundled. See docs/embedding.md, "The source worker",
+   * for each bundler. Only the typing delay uses the worker: every explicit action (`getText`, switching the format, `replaceDocument`, Format, Undo)
+   * is applied on the main thread at once. When the worker cannot start, fails, stops answering, or loads but does not say it is ready within 5 s (a
+   * script the bundler emptied), the pane checks on the main thread from then on and `onError` is called once with a message that names the
+   * worker; no edit is lost. Default `false` (everything on the main thread).
    */
-  worker?: boolean | Worker | (() => Worker);
+  worker?: boolean | string | URL | Worker | (() => Worker);
   /** A preview for the card F12 and Alt+F12 open on a catalog record only the app provides (see `JsonCodeEditorOptions.resolvePreview`). */
   resolvePreview?: (kind: string, id: string) => HTMLElement | string | undefined | Promise<HTMLElement | string | undefined>;
   onError?(error: unknown): void;
@@ -151,6 +222,14 @@ export interface SourcePane {
    * (`invalid-opf-edit` with `issues`) and changes nothing. Works in a read-only pane.
    */
   replaceDocument(document: unknown, options?: ReplaceDocumentOptions): EditorChange;
+  /**
+   * Load raw source text as the pane's whole text, as if pasted over everything: a file as it was read, a draft that does not parse. Nothing is
+   * converted; the bytes stay as given (line endings included; a leading byte order mark is dropped). `options.format` switches the pane to the
+   * text's format first (without writing the document in it), `options.name` renames the file. Text that reads as a document the session
+   * accepts is applied at once as one undoable edit; anything else stays as a draft with its problems and the session keeps its last valid
+   * document. Returns true when the session now holds the text's document. Throws in a read-only pane.
+   */
+  setSourceText(text: string, options?: { format?: SourceFormat; name?: string }): boolean;
   /** Re-read the document from the session. */
   refresh(): void;
   /** Replace the host findings; `null` returns to the session's own validation. */
@@ -160,6 +239,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();
@@ -699,6 +708,44 @@ export function createSourcePane(container, options = {}) {
     options.onFormatChange?.(format, previous);
   }
 
+  /**
+   * Put `text` in the pane as its whole source, in `next` (default the pane's format), as if the person had pasted it over everything: no
+   * conversion, the bytes as given (line endings included; a byte order mark is dropped). Text that reads as a document the session accepts is
+   * applied at once (one undoable edit; Undo in the code brings the old text back); anything else stays in the pane as a draft with its problems,
+   * and the session keeps its last valid document. Returns true when the session now holds the text's document.
+   */
+  function setSourceText(text, { format: next, name: nextName } = {}) {
+    if (destroyed) throw new Error("The source pane was destroyed.");
+    if (typeof text !== "string") throw new TypeError("setSourceText needs the source text as a string.");
+    if (next !== undefined && !FORMATS.some((entry) => entry.id === next)) throw new TypeError(`setSourceText: format must be "json", "yaml" or "md", not ${JSON.stringify(next)}.`);
+    if (readOnly) throw new Error("The source pane is read-only.");
+    flush();
+    closeConfirm(false);
+    const previous = format;
+    for (const key of Object.keys(drafts)) delete drafts[key];
+    transientNotes = [];
+    rejectionFindings = [];
+    syntaxFindings = [];
+    if (next !== undefined && next !== format) {
+      format = next;
+      noteFindings = [];
+      control.setLanguage(formatOf(next).language);
+      refreshDecorations();
+    }
+    if (nextName !== undefined) name = sanitizeName(nextName) || "deck";
+    updateBar();
+    control.api.replace(0, control.api.getValue().length, text.replace(/^\uFEFF/, ""));
+    control.api.setSelection(0);
+    // Read and apply it now, also when it is the text already shown (in another format, say).
+    baseline = null;
+    flush();
+    renderedKey = "";
+    renderFindings();
+    syncAttributes();
+    if (format !== previous) options.onFormatChange?.(format, previous);
+    return !dirty;
+  }
+
   // ---- Menu ---------------------------------------------------------------------------------------------------------
   const menuOpen = () => !menu.hidden;
   function openMenu(focus = "checked") {
@@ -786,6 +833,8 @@ export function createSourcePane(container, options = {}) {
     nameButton.textContent = name;
     nameButton.setAttribute("aria-label", `Rename ${name}`);
     formatLabel.textContent = `.opf.${current.extension}`;
+    // The visible extension is part of the button's name (WCAG 2.5.3, label in name).
+    formatButton.setAttribute("aria-label", `Source format .opf.${current.extension}`);
     root.dataset.format = current.id;
     canonicalAction.hidden = current.id === "json";
     for (const item of menuItems) item.setAttribute("aria-checked", String(item.dataset.format === current.id));
@@ -1137,6 +1186,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();
@@ -1173,6 +1331,11 @@ export function createSourcePane(container, options = {}) {
       renderedKey = "";
       renderFindings();
     },
+    /**
+     * Load raw source text (a file, a paste, a draft that does not parse) as the pane's whole text, in `options.format`, without converting it.
+     * Returns true when it read as a document the session accepted, false when it stays a draft with its problems. See `setSourceText` above.
+     */
+    setSourceText,
     /** Switch the source format ("json", "yaml" or "md"). Returns false when the document cannot be written in it. */
     setFormat: (next) => setFormatInternal(next, false),
     getFormat: () => format,
@@ -1220,15 +1383,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 +1427,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/source-worker.js

@@ -1,7 +1,9 @@
-// The worker entry of the source pane's text checks (`createSourcePane(el, { worker })`). A host bundles this file as its own worker script
-// (`@openpresentation/opf-editor/source-worker`), for example `new Worker(new URL("@openpresentation/opf-editor/source-worker", import.meta.url), { type: "module" })`
-// with a bundler that understands that form, or builds it as an extra entry point and serves it next to the page. It does the same work as the pane's
-// own inline path (`./source-check.js`), off the main thread. Requests run in order, but when several checks of one kind are waiting only the newest runs
+// The worker entry of the source pane's text checks (`createSourcePane(el, { worker })`). `worker: true` starts it with
+// `new Worker(new URL("./source-worker.js", import.meta.url), { type: "module" })`, which webpack, Turbopack, Vite (build) and Parcel bundle; a host can
+// also write `new Worker(new URL("@openpresentation/opf-editor/source-worker", import.meta.url), { type: "module" })` itself, or build this file as an
+// extra entry point (esbuild) and pass its URL. The file imports core, so it runs only bundled. See docs/embedding.md, "The source worker". It does the
+// same work as the pane's own inline path (`./source-check.js`), off the main thread. It says `{ ready: true }` once it runs, so the pane can tell a
+// worker that loaded but never started (an emptied script) from a slow check. Requests run in order, but when several checks of one kind are waiting only the newest runs
 // (the older ones are answered with `skipped`): the pane drops stale replies anyway.
 import { createCheckService } from "./source-check.js";
 
@@ -23,6 +25,8 @@ function drain() {
   });
 }
 
+self.postMessage({ ready: true });
+
 self.onmessage = (event) => {
   queue.push(event.data);
   // Messages that arrive while a check runs queue behind it; draining on the next task lets everything already waiting be seen together.

package/dist/studio-canvas.d.ts

@@ -0,0 +1,34 @@
+/** CE-20 (internal): the Studio's canvas: the kit viewport and overlay over the workspace's canvas, driven by the slide adapter. */
+import type { KitDom } from "./studio-kit/dom.js";
+import type { CanvasEditor } from "./canvas.js";
+import type { SlideAdapter } from "./slide-adapter.js";
+import type { SceneNode } from "./slide-scene.js";
+
+export declare function dottedPath(pointer: string): string;
+export declare function isTextNode(node: SceneNode | null | undefined): boolean;
+export interface StudioCanvas {
+  paint(): void;
+  paintHover(): void;
+  readonly zoom: number;
+  readonly panMode: boolean;
+  setZoom(zoom: number, options?: { anchor?: { clientX: number; clientY: number } }): number;
+  step(direction: number): number;
+  fit(mode?: "slide" | "width"): number;
+  readonly tool: "select" | "hand" | "text";
+  setTool(tool: "select" | "hand" | "text"): void;
+  focusPrimary(): void;
+  boxOf(key: string): Element | undefined;
+  describe(node: SceneNode): string;
+  beginInsertDrag(kind: string, event: PointerEvent, options?: { onEnd?(): void }): boolean;
+  readonly dragging: boolean;
+  cancelDrag(): void;
+  setEnabled(on: boolean): void;
+  destroy(): void;
+}
+export declare function createStudioCanvas(options: {
+  dom: KitDom;
+  elements: { root: HTMLElement; viewport: HTMLElement; stage: HTMLElement; frame: HTMLElement; overlay: HTMLElement };
+  canvas: CanvasEditor;
+  adapter: SlideAdapter;
+  studio: any;
+}): StudioCanvas;