@openpresentation/opf-editor 0.27.0 → 0.28.0

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;

package/dist/studio-kit/commands.js

@@ -0,0 +1,148 @@
+// CE-18, the studio kit: the command registry and keymap. A command is `{ id, label, group, scope, keys, hint, repeat, when, run }`; the
+// keyboard, the context menu, the bar's disabled states, the shortcut sheet and a host palette all read one registry, so they cannot drift.
+// Keys are CodeMirror-style strings ("Mod-z", "Shift-Mod-z", "Ctrl-y", "[", "Shift-[", "Delete", "F2"). No DOM beyond the event it is given.
+import { isMac, isTypingTarget } from "./dom.js";
+
+const HANDLED = "opfStudioHandled";
+/** Whether an earlier handler already acted on this key event. */
+export const isHandled = (event) => Boolean(event?.[HANDLED]);
+/** Mark a key event as acted on, so the handlers it bubbles to leave it alone. */
+export const markHandled = (event) => { event[HANDLED] = true; };
+/** Whether a shortcut may act on this event: not handled already, not prevented, not typed into a field, not an IME composition. */
+export const keyGuard = (event) => !(isHandled(event) || event.defaultPrevented || isTypingTarget(event.target) || event.isComposing);
+
+// A key can also be matched by its physical position, so a keyboard layout where "[" needs AltGr (or Shift turns it into "{") still has it.
+const CODES = { "[": "BracketLeft", "]": "BracketRight" };
+const MODIFIERS = new Set(["Shift", "Alt", "Mod", "Ctrl", "Meta", "Cmd"]);
+
+/** Parse "Shift-Mod-z" into `{ key, shift, alt, mod, ctrl, meta }`. A trailing "-" is the minus key ("Mod--"). */
+export function parseKey(spec) {
+  const text = String(spec);
+  if (text === "-") return { key: "-", shift: false, alt: false, mod: false, ctrl: false, meta: false };
+  const parts =text.endsWith("-") && text.length > 1 ? [...text.slice(0, -2).split("-").filter(Boolean), "-"] : text.split("-");
+  const key = parts.pop();
+  const out = { key, shift: false, alt: false, mod: false, ctrl: false, meta: false };
+  for (const part of parts) {
+    if (!MODIFIERS.has(part)) throw new TypeError(`Unknown modifier ${part} in ${spec}`);
+    if (part === "Cmd") out.meta = true; else out[part.toLowerCase()] = true;
+  }
+  return out;
+}
+
+/**
+ * Whether a keyboard event matches one key spec. Shift and Alt must be exactly as listed. `Mod` is satisfied by Cmd or Ctrl on every platform
+ * (so a Windows keyboard on a Mac works), `Ctrl` by Ctrl and `Meta`/`Cmd` by Cmd; with none of the three listed, neither Cmd nor Ctrl may be
+ * down. A one-character key compares without case; "[" and "]" also match their physical key.
+ */
+export function matchKey(event, spec) {
+  const want = typeof spec === "string" ? parseKey(spec) : spec;
+  if (Boolean(event.shiftKey) !== want.shift || Boolean(event.altKey) !== want.alt) return false;
+  if (want.mod || want.ctrl || want.meta) {
+    if (want.mod && !(event.metaKey || event.ctrlKey)) return false;
+    if (want.ctrl && !event.ctrlKey) return false;
+    if (want.meta && !event.metaKey) return false;
+  } else if (event.metaKey || event.ctrlKey) return false;
+  const key = event.key ?? "";
+  if (want.key.length === 1) return key.toLowerCase() === want.key.toLowerCase() || (CODES[want.key] !== undefined && event.code === CODES[want.key]);
+  return key === want.key;
+}
+
+const MAC_NAMES = { shift: "⇧", alt: "⌥", ctrl: "⌃", mod: "⌘", meta: "⌘" };
+const PC_NAMES = { shift: "Shift+", alt: "Alt+", ctrl: "Ctrl+", mod: "Ctrl+", meta: "Win+" };
+const KEY_NAMES = { " ": "Space", ArrowUp: "↑", ArrowDown: "↓", ArrowLeft: "←", ArrowRight: "→", Escape: "Esc" };
+/** A key spec as people read it: "⌘D" on a Mac, "Ctrl+D" elsewhere. */
+export function formatKey(spec, win) {
+  const want = typeof spec === "string" ? parseKey(spec) : spec;
+  const mac = isMac(win);
+  const names = mac ? MAC_NAMES : PC_NAMES;
+  const order = mac ? ["ctrl", "alt", "shift", "mod", "meta"] : ["ctrl", "mod", "meta", "alt", "shift"];
+  const mods = order.filter((name) => want[name] && !(name === "ctrl" && want.mod)).map((name) => names[name]).join("");
+  const key = KEY_NAMES[want.key] ?? (want.key.length === 1 ? want.key.toUpperCase() : want.key);
+  return mods + key;
+}
+
+/**
+ * A command registry. `register(command)` returns the function that removes it. A command has an `id`, a `label`, optional `group`,
+ * `scope` (a name or a list of names; `handle` runs only the commands of the scope it is given; default "global"), `keys` (key specs),
+ * `hint` (what a menu shows instead of the formatted first key), `repeat` (false: a held key does not repeat it), `when(ctx)` (true, false,
+ * or a reason string that disables it) and `run(ctx, event)`.
+ */
+export function createCommandRegistry({ commands = [] } = {}) {
+  const byId = new Map();
+  const overrides = new Map();
+  const keysOf = (command) => (overrides.has(command.id) ? overrides.get(command.id) : command.keys) ?? [];
+  const scopesOf = (command) => [].concat(command.scope ?? "global");
+  const state = (command, ctx) => {
+    const verdict = command.when ? command.when(ctx) : true;
+    return verdict === true ? { enabled: true, reason: "" } : { enabled: false, reason: typeof verdict === "string" ? verdict : "" };
+  };
+
+  const registry = {
+    register(command) {
+      if (!command?.id || typeof command.run !== "function") throw new TypeError("A command needs an id and a run function.");
+      if (byId.has(command.id)) throw new Error(`A command ${command.id} is already registered.`);
+      const parsed = { ...command };
+      byId.set(command.id, parsed);
+      return () => { if (byId.get(command.id) === parsed) byId.delete(command.id); };
+    },
+    get: (id) => byId.get(id),
+    has: (id) => byId.has(id),
+    /** Rebind commands: `{ id: keys }` replaces a command's keys, `{ id: null }` unbinds it. */
+    setKeymap(map = {}) {
+      for (const [id, keys] of Object.entries(map)) overrides.set(id, keys === null ? [] : [].concat(keys));
+    },
+    /** Every command with its state for `ctx`: `{ id, label, group, keys, shortcut, enabled, reason }`, in registration order. */
+    list(ctx, { win } = {}) {
+      return [...byId.values()].map((command) => {
+        const keys = keysOf(command);
+        return { id: command.id, label: command.label, group: command.group, keys: [...keys], shortcut: command.hint ?? (keys[0] ? formatKey(keys[0], win) : ""), ...state(command, ctx) };
+      });
+    },
+    /** Whether `id` may run for `ctx` (`when` returned true). */
+    enabled: (id, ctx) => (byId.has(id) ? state(byId.get(id), ctx).enabled : false),
+    /** Run `id` for `ctx` when it is enabled. Returns false when it is unknown or disabled, else what `run` returned (true when it returned nothing). */
+    run(id, ctx, event) {
+      const command = byId.get(id);
+      if (!command || !state(command, ctx).enabled) return false;
+      const result = command.run(ctx, event);
+      return result === undefined ? true : Boolean(result);
+    },
+    /** The command of `scope` a key event would run: the first whose keys match and whose `when` is true. */
+    match(event, ctx, { scope = "global" } = {}) {
+      for (const command of byId.values()) {
+        if (!scopesOf(command).includes(scope)) continue;
+        if (command.repeat === false && event.repeat) continue;
+        if (!keysOf(command).some((spec) => matchKey(event, spec))) continue;
+        if (state(command, ctx).enabled) return command;
+      }
+      return null;
+    },
+    /**
+     * Act on a key event: the guard (`keyGuard`), then the matching command of `scope`. The event is prevented and marked handled, and true
+     * is returned, whether or not the command changed anything.
+     */
+    handle(event, ctx, { scope = "global" } = {}) {
+      if (!keyGuard(event)) return false;
+      const command = registry.match(event, ctx, { scope });
+      if (!command) return false;
+      event.preventDefault();
+      command.run(ctx, event);
+      markHandled(event);
+      return true;
+    },
+    /**
+     * Menu items for `openMenu` from command ids, in order: `{ id, label, hint, disabled, title, onSelect }`. The state is read when the menu
+     * is built; a disabled item cannot be chosen, and choosing an enabled one runs the command for the `ctx` the menu was built with.
+     */
+    menu(ids, ctx, { win } = {}) {
+      return ids.filter((id) => byId.has(id)).map((id) => {
+        const command = byId.get(id);
+        const keys = keysOf(command);
+        const { enabled, reason } = state(command, ctx);
+        return { id, label: command.label, hint: command.hint ?? (keys[0] ? formatKey(keys[0], win) : undefined), disabled: !enabled, title: reason || undefined, onSelect: () => command.run(ctx) };
+      });
+    },
+  };
+  for (const command of commands) registry.register(command);
+  return registry;
+}

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

@@ -0,0 +1,36 @@
+/** CE-18 studio kit (internal): DOM helpers, icons, the menu and the typing-target guard. */
+export declare const ICONS: Readonly<Record<string, string>>;
+/** The default class prefix of kit parts ("opf-kit"); Layout Studio passes "opf-lx". */
+export declare const KIT_PREFIX: string;
+export declare function nextId(prefix: string): string;
+export interface KitButtonOptions {
+  label?: string;
+  text?: string;
+  iconName?: string;
+  size?: number;
+  pressed?: boolean;
+  title?: string;
+  attributes?: Record<string, string | number | boolean | undefined | null>;
+}
+export interface KitDom {
+  doc: Document;
+  prefix: string;
+  el<K extends keyof HTMLElementTagNameMap>(tag: K, className?: string, attributes?: Record<string, string | number | boolean | undefined | null>): HTMLElementTagNameMap[K];
+  icon(name: string, size?: number): SVGSVGElement;
+  button(className: string, options?: KitButtonOptions): HTMLButtonElement;
+}
+export declare function createDom(doc: Document, options?: { prefix?: string }): KitDom;
+export declare function isTypingTarget(target: EventTarget | null): boolean;
+export declare function isMac(win?: Window | null): boolean;
+/** A unit fraction as a CSS percentage. */
+export declare function pct(fraction: number): string;
+export interface KitMenuItem {
+  label: string;
+  onSelect?(): void;
+  disabled?: boolean;
+  role?: "menuitem" | "menuitemcheckbox";
+  checked?: boolean;
+  hint?: string;
+}
+export interface KitMenu { element: HTMLElement; close(options?: { restore?: boolean }): void }
+export declare function openMenu(dom: KitDom, host: HTMLElement, options: { x: number; y: number; items: KitMenuItem[]; label: string; returnFocus?: HTMLElement | null; onClose?(): void; className?: string }): KitMenu;