@openpresentation/opf-editor 0.24.1 → 0.24.3

package/README.md

@@ -104,6 +104,7 @@ const pane = createSourcePane(container, {
   onDownload: file => saveAs(file.filename, file.text), // default: a Blob link named <name>.opf.<ext>
   density: 'comfortable',       // 'touch' makes the controls 40px
   readOnly: false,
+  completions: true,            // live property and value suggestions while typing JSON (default true)
 });
 pane.setFormat('yaml'); pane.focusPath('/slides/1/title'); pane.getText(); pane.destroy();
 ```
@@ -113,7 +114,8 @@ Methods: `setFindings(list | null)`, `setFormat(format)`, `focusPath(pointer)` (
 - **JSON is canonical** and keeps the author's bytes: a YAML or Markdown edit rewrites only the changed JSON tokens (`exact-source`), and Undo restores the exact spelling.
 - **YAML and Markdown** are core's browser-safe converters, `@openpresentation/opf/yaml` and `/markdown`. Switching format writes the session's document in the new format. An edit parses back to the document and reaches the session as one `replace` patch, after a short delay (`applyDelay`, default 250 ms) so one burst of typing is one undo step. A syntax error, or an OPF rule the session refuses, is listed with its line and never reaches the document; Undo, Redo and outside edits replace a draft that did not parse.
 - **Nothing is lost silently.** Markdown writes what its dialect has no syntax for (a `design`, region keys, nested groups) as YAML in `opf-slide` and `opf-block` fences; each such part is a warning finding with its JSON Pointer and reason. Comments in YAML cannot survive a rewrite from the document: Format and outside edits drop them and say how many. A document that is not valid OPF cannot be written as YAML or Markdown; the pane stays in JSON and says so.
-- **Accessibility.** The format button (`aria-label="Source format"`) opens a `role="menu"` of `menuitemradio` items: Arrow keys, Home, End, Enter, Escape (focus returns to the button) and Tab. The file name is a button that becomes a text input; Enter or Escape commits. Controls show a 2px `--opf-ui-ring` focus outline.
+- **Completions.** In JSON the pane offers property names and values as you type (`completions: false` keeps the field menu only): the keys the schema allows at the cursor's object, and the enum, boolean and catalog values of the field, from the same data as the field menu (`getJsonCompletions` in `/json-options`, which reads drafts that do not parse yet). Enter accepts, Escape closes, and Ctrl+Space or Alt+ArrowDown still open the field menu. YAML and Markdown keep the menu only. `mountJsonCodeEditor` takes the same `completions` option, off by default there.
+- **Accessibility.** The editor's `aria-invalid` is `true` while the findings include an error and `false` otherwise. The format button (`aria-label="Source format"`) opens a `role="menu"` of `menuitemradio` items: Arrow keys, Home, End, Enter, Escape (focus returns to the button) and Tab. The file name is a button that becomes a text input; Enter or Escape commits. Controls show a 2px `--opf-ui-ring` focus outline.
 - **Styles.** `src/styles/source-pane.css` uses only `--opf-ui-*` tokens under the `opf-source-` prefix. It ships in the editor's `styles.css` (`@openpresentation/opf-editor/styles.css`), which also defines the tokens.
 - **Dependency.** `@codemirror/lang-yaml` (MIT) highlights YAML; Markdown uses a small stream tokenizer built on `@codemirror/language`, so no Markdown, HTML, CSS or JavaScript grammar is added.
 
@@ -829,6 +831,67 @@ const dialog = createAgentHandoffDialog(document.body, { document: deck, target:
 
 Icons are inlined path data from [Lucide](https://lucide.dev) (ISC license), never loaded from a CDN.
 
+## Presenter and Present button (RR-98)
+
+`@openpresentation/opf-editor/presenter` shows the deck full screen, one slide at a time. It is plain DOM like the other modules, with no network, no fonts or CSS fetched at runtime, and no second renderer: slides are drawn by `toSvg` with the same fonts handle, catalogs and render options the canvas and the thumbnails use. Its CSS is `src/styles/presenter.css` (classes `opf-presenter-*` and `opf-present-button`; `--opf-ui-*` tokens only, part of `styles.css`). The module needs `@openpresentation/opf-render`, an optional peer, like the thumbnail strip.
+
+```js
+import { createPresenter, createPresentButton, bindPresentShortcut } from "@openpresentation/opf-editor/presenter";
+
+const presenter = createPresenter(document.body, {
+  editor,                      // or presentation: deck (an object, or a function returning it)
+  fonts,                       // the renderer's fonts handle, the same one the canvas and the exports use
+  renderOptions: { catalogs }, // merged after the session's catalogs
+  slideIndex: current,         // the slide start() opens on (default 0)
+  onSlideChange: (index) => {},  // the shown slide changed (deck index)
+  onExit: (index) => { current = index; redraw(); }, // by any route: the host returns to that slide
+  density: "comfortable",      // "touch": the exit button is 40px
+});
+createPresentButton(document.querySelector("#present"), { onPresent: () => presenter.start(current) });
+bindPresentShortcut(document, () => presenter.start(current)); // F5
+```
+
+`createPresenter(container, options)` returns `{ element, start(slideIndex?), stop(), next(), previous(), goTo(index), getSlide(), isRunning(), destroy() }`. The presenter stays hidden until `start`. Call `start` from a user gesture (a click or a key press): the browser grants full screen only then. `start` resolves `"fullscreen"` or `"overlay"`.
+
+- **Display.** The presenter's own element goes full screen through the Fullscreen API. When the browser refuses (no gesture, an iframe without `allow="fullscreen"`, iPhone Safari), the same element is a fixed overlay over the window, so everything below works the same. Slides fill the viewport and letterbox on black. The next and previous slides are drawn ahead, so advancing draws nothing. Slides draw with their `{{variables}}` resolved, as the exports do.
+- **Navigation.** Right, Space, PageDown and Enter go forward; Left, PageUp and Backspace go back; Home and End jump; Esc exits. A click advances, and a click on the left third goes back. On touch, a swipe left goes forward and a swipe right goes back; a tap uses the same zones. Keys with Ctrl, Alt or Meta are left to the browser, and the keys the presenter handles do not reach the host page.
+- **Hidden slides** are skipped, as the exports skip them (`slidesToConvert`; `includeHidden: true` presents them). `start(i)` and `goTo(i)` on a hidden slide show the next slide that is not hidden (`onSlideChange` says which). A deck with only hidden slides shows a message and `onExit(-1)`.
+- **Counter.** A subtle "03 / 12" (mono, the navigator's format; hidden slides are not counted) and the exit button show on pointer move and hide after 2 seconds, with the cursor.
+- **Exit.** Esc, the exit button, leaving full screen (the browser's Esc), `stop()` and `destroy()` all call `onExit(index)` with the deck index of the slide shown, then focus returns to the element that was focused at `start`.
+- **Accessibility.** The element is `role="dialog"` with `aria-modal="true"` and an `aria-label` ("Presentation"; `labels.dialog`). Focus moves into it on start and stays in it (Tab cycles the dialog and the exit button). An `aria-live="polite"` region announces "Slide 3 of 12" (`labels.position`).
+- **Fonts.** Like the canvas, the presenter waits for the faces the deck needs (`fonts.pending` and `fonts.ensure`) and shows "Loading fonts…" meanwhile.
+
+`createPresentButton(container, { onPresent, disabled, density })` mounts an icon-only button (the Lucide Presentation icon, inlined) named "Present" (`aria-label`), titled "Present (F5)" and styled like the Export menu's trigger. `disabled` is `true` or a reason string (the title); the button stays focusable (`aria-disabled`) and does nothing. It returns `{ element, setDisabled(reason), setDensity(density), destroy() }`. `bindPresentShortcut(target, onPresent)` binds F5 (and prevents the browser's reload); it ignores F5 while typing in inputs, selects and editors (CodeMirror, contenteditable), in menus and dialogs, and with a modifier key, and returns a function that removes the listener. `examples/playground.js` wires all three next to the Export menu.
+
+Tests: `npm run test:presenter-browser` and `npm run test:present-button-browser`.
+
+## Opening a deck file (RR-98)
+
+`@openpresentation/opf-editor/read-deck-file` reads a deck file in any OPF source format, with no DOM:
+
+```js
+import { readDeckFile, DECK_FILE_ACCEPT, DeckFileError } from "@openpresentation/opf-editor/read-deck-file";
+
+input.accept = DECK_FILE_ACCEPT;            // ".json,.opf,.yaml,.yml,.md"
+input.onchange = async () => {
+  try {
+    const { document, format, name, findings } = await readDeckFile(input.files[0], { catalogs });
+    const editor = createEditorSession(document, { catalogs }); // the session validates it; findings say what to fix first
+  } catch (error) {
+    if (error instanceof DeckFileError) show(error.code, error.message, error.findings);
+  }
+};
+```
+
+`readDeckFile(file | { name, text }, { catalogs? })` takes a `File` (or anything with `name` and `text()`), or `{ name, text }` with the text as a string, and returns `{ document, format: "json" | "yaml" | "md", name, findings }`.
+
+- **Format.** The extension picks it: `.yaml` and `.yml` are YAML, `.md` is Markdown, and `.json`, `.opf` or anything else is JSON. If JSON fails to parse, the text is tried as YAML, and as Markdown when it starts with front matter (`---`); `format` is the one that read it. YAML and Markdown go through core's browser-safe `fromYaml` and `fromMarkdown` (`@openpresentation/opf/yaml` and `/markdown`, loaded on first use). JSON that wraps a deck (`opfSnippet`, `opf`, `presentation`) is unwrapped as `parseOpfTransfer` does.
+- **Name.** The file name without a directory and without `.opf.json`, `.opf.yaml`, `.opf.md` or its plain extension (`Q3 plan.opf.yaml` gives `Q3 plan`).
+- **Findings.** The conversion's findings for YAML and Markdown, in core's `Finding` shape: `path` (a JSON Pointer such as `/slides/1/bogus`), `message`, `severity` and `location` (line and column in the file). A deck that reads but has OPF errors is returned with them, so a host can show them; JSON gives none (the editor session validates it).
+- **Errors.** Text that cannot be read at all throws `DeckFileError` with a `code` and a clear message: `unreadable`, `file-too-large` (over 20 MB), `empty-file`, `unsupported-file` (a .pptx or other binary file), `invalid-json`, `invalid-yaml`, `invalid-markdown` (with the syntax `findings` and the line) and `not-a-deck` (JSON without a `slides` list, such as one slide or a block, which a host can send to its paste path as the playground does).
+
+The source pane has no file-opening path of its own, so it keeps no second copy of this. The playground's Import dialog uses `readDeckFile` and `DECK_FILE_ACCEPT` for its file tab and for dropped files (`examples/transfer-controls.js`). Icons in the presenter button are inlined [Lucide](https://lucide.dev) paths (ISC license).
+
 ## Optional React Bindings
 
 React bindings are isolated under `@openpresentation/opf-editor/react` and require the host app to pass its React runtime. The core package does not add React to the critical path.

package/dist/json-editor.d.ts

@@ -23,6 +23,8 @@ export interface JsonCodeEditorOptions {
   /** Highlighting and behavior: "json" (default) adds the parse linter, field highlights and the option menu. */
   language?: "json" | "yaml" | "markdown";
   readOnly?: boolean;
+  /** Live completion popup in JSON: property names and enum, boolean and catalog values at the cursor's JSON path, from the same data as the field menu (default false here; the source pane turns it on). Ctrl+Space still opens the field menu. */
+  completions?: boolean;
   catalogs?: JsonCatalogContext;
   /** Overrides the built-in menu, allowing an existing host UI to keep its appearance. */
   onOptions?(left?: number, top?: number): void;

package/dist/json-editor.js

@@ -4,7 +4,7 @@ import { defaultKeymap, history, historyKeymap, indentWithTab, isolateHistory, r
 import { HighlightStyle, StreamLanguage, bracketMatching, codeFolding, foldKeymap, indentOnInput, indentUnit, syntaxHighlighting } from "@codemirror/language";
 import { json, jsonParseLinter } from "@codemirror/lang-json";
 import { yaml } from "@codemirror/lang-yaml";
-import { closeBrackets, closeBracketsKeymap } from "@codemirror/autocomplete";
+import { autocompletion, closeBrackets, closeBracketsKeymap, completionKeymap, startCompletion } from "@codemirror/autocomplete";
 import { highlightSelectionMatches, search, searchKeymap } from "@codemirror/search";
 import { linter } from "@codemirror/lint";
 import { tags } from "@lezer/highlight";
@@ -65,10 +65,25 @@ const markdownLanguage = StreamLanguage.define({
     return null;
   }
 });
-function languageExtension(name) {
+function languageExtension(name, completions) {
   if (name === "yaml") return yaml();
   if (name === "markdown") return markdownLanguage;
-  return [json(), linter(jsonParseLinter(), { delay: 500 }), fieldDecorations];
+  return [json(), linter(jsonParseLinter(), { delay: 500 }), fieldDecorations, completions ?? []];
+}
+// The completion popup keeps CodeMirror's keys (arrows, Enter, Escape) but not Ctrl-Space, which opens the field menu.
+const completionKeys = Prec.highest(keymap.of(completionKeymap.filter((binding) => binding.run !== startCompletion)));
+// Accept a completion by rewriting its whole token (quotes included), so a string key, a bare word and a changed value type all land
+// as valid JSON. A key adds ": " when none follows and then offers the values of that key.
+function completionApply(found, option) {
+  return (view, completion, from, to) => {
+    const start = found.quoted ? from - 1 : from;
+    const end = found.closed ? to + 1 : to;
+    let insert = JSON.stringify(option.value);
+    const chain = found.kind === "key" && !/^\s*:/.test(view.state.sliceDoc(end, Math.min(view.state.doc.length, end + 200)));
+    if (chain) insert += ": ";
+    view.dispatch({ changes: { from: start, to: end, insert }, selection: { anchor: start + insert.length }, userEvent: "input.complete", scrollIntoView: true });
+    if (chain) setTimeout(() => startCompletion(view), 0);
+  };
 }
 function indentation(source) {
   const spaces = source.match(/^[\t ]+(?=\S)/gm) ?? [];
@@ -168,6 +183,20 @@ function mountJsonCodeEditor(parent, options) {
       menu=mountJsonFieldMenu(parent,api,catalogs,left,top,()=>{menu=null;});
     }catch(error){options.onError?.(error);}
   }
+  // Live completions (JSON only, `completions: true`): property names and values at the cursor's JSON path, from the same data as the
+  // field menu. The data loads with the field menu's chunk on first use.
+  async function completionSource(context) {
+    if (disposed || languageName !== "json") return null;
+    let module;
+    try { module = await import('./json-options.js'); } catch (error) { options.onError?.(error); return null; }
+    if (disposed || context.aborted) return null;
+    const found = module.getJsonCompletions(context.state.doc.toString(), context.pos, catalogs, { explicit: context.explicit });
+    if (!found) return null;
+    return { from: found.from, to: found.to, filter: true, options: found.options.map((option) => ({
+      label: option.label, detail: option.detail, info: option.info, boost: option.boost, type: found.kind === "key" ? "property" : "enum", apply: completionApply(found, option),
+    })) };
+  }
+  const completionExtension = options.completions ? [autocompletion({ override: [completionSource], defaultKeymap: false, icons: false, maxRenderedOptions: 60 }), completionKeys] : null;
   let currentIndent = indentation(options.code);
   const contentAttributes = (invalid = options.invalid, describedBy = options.describedBy) => EditorView.contentAttributes.of({
     "aria-label": options.label,
@@ -179,7 +208,7 @@ function mountJsonCodeEditor(parent, options) {
     autocorrect: "off"
   });
   const view = new EditorView({ parent, state: EditorState.create({ doc: options.code, extensions: [
-    language.of(languageExtension(languageName)),
+    language.of(languageExtension(languageName, completionExtension)),
     editable.of(editableExtension(options.readOnly)),
     jsonSource.init(()=>options.code),jsonSourceHistory,
     indent.of(indentUnit.of(currentIndent)),
@@ -300,7 +329,7 @@ function mountJsonCodeEditor(parent, options) {
     setLanguage(name){
       if(name===languageName)return;
       languageName=name;closeOptions();
-      view.dispatch({ effects: language.reconfigure(languageExtension(name)) });
+      view.dispatch({ effects: language.reconfigure(languageExtension(name, completionExtension)) });
     },
     setReadOnly(value){view.dispatch({ effects: editable.reconfigure(editableExtension(value)) });},
     /** The CodeMirror view, for hosts that scroll or measure it. */

package/dist/json-options.d.ts

@@ -31,3 +31,24 @@ export declare function getJsonFieldContext(source: string, position: number, lo
 export declare function replaceFieldOption(context: JsonFieldContext, value: JsonOptionValue): string;
 /** Minimal single replacement for atomic source-editor undo. */
 export declare function fieldOptionEdit(context: JsonFieldContext, value: JsonOptionValue): {from:number;to:number;insert:string};
+export interface JsonCompletionOption {
+  /** A key option's property name, or the JSON value to write. */
+  value: JsonOptionValue;
+  label: string;
+  detail?: string;
+  info?: string;
+  /** CodeMirror ranking, -99 to 99. */
+  boost: number;
+}
+export interface JsonCompletions {
+  kind: 'key' | 'value';
+  /** The text being typed: inside the quotes of a string, or the bare word. */
+  from: number;
+  to: number;
+  quoted: boolean;
+  /** Whether a closing quote follows the typed text. */
+  closed: boolean;
+  options: JsonCompletionOption[];
+}
+/** The property names and values to offer at `position` of a JSON draft (it need not parse); null when there are none. `explicit` also offers choices where nothing is typed yet. */
+export declare function getJsonCompletions(source: string, position: number, loadedCatalogs?: JsonCatalogContext, options?: { explicit?: boolean }): JsonCompletions | null;

package/dist/json-options.js

@@ -1,7 +1,7 @@
 import { checkFormat, firstErrorMessage } from "./checks.js";
 import { listCatalogRecords } from "./catalogs.js";
-import { schemaAtPath, schemaVariants } from "./schema.js";
-import { findNodeAtOffset, getNodePath, parseTree } from "jsonc-parser";
+import { resolveSchema, schemaAtPath, schemaVariants } from "./schema.js";
+import { findNodeAtOffset, getNodePath, parse as parseJsonc, parseTree } from "jsonc-parser";
 import { LAYOUT_INTENT_GROUPS, layoutRegionSummary } from "./layout-templates.js";
 // The catalog kind a field references (OPF 0.15: every content kind is `id` or `name:id`), read from where the field sits.
 const ROOT_REFERENCES = { narrative: "narratives", audience: "audiences", purpose: "purposes", tone: "tones" };
@@ -39,29 +39,9 @@ function describeOptions(choices, records, current, catalog) {
     const priority = option => option.source === "Document catalog" ? 2 : option.source === "Loaded catalog" ? 1 : 0;
     return choices.sort((a, b) => (catalog === "layouts" ? layoutGroups.indexOf(a.layoutGroup) - layoutGroups.indexOf(b.layoutGroup) : priority(b) - priority(a)) || a.label.localeCompare(b.label, "en", {numeric: true}) || String(a.value).localeCompare(String(b.value), "en"));
 }
-// The installed schema identifies fields; a document field merely named "layout"
-// inside arbitrary metadata is not mistaken for an OPF layout reference.
-export function getJsonFieldContext(source, position, loadedCatalogs = []) {
-    let presentation;
-    try {
-        presentation = JSON.parse(source);
-    }
-    catch {
-        return null;
-    }
-    const root = parseTree(source);
-    if (!root)
-        return null;
-    let node = findNodeAtOffset(root, position, true);
-    if (node?.parent?.type === "property" && node.parent.children?.[0] === node)
-        node = node.parent.children[1];
-    if (node?.type === "object")
-        node = node.children?.find(property => property.children?.[0]?.value === "id")?.children?.[1];
-    if (!node || !["string", "number", "boolean"].includes(node.type))
-        return null;
-    const path = getNodePath(node);
-    if (!path.length)
-        return null;
+// The choices a field offers, shared by the field menu and live completions: catalog records for a reference field (when the
+// value is a string), schema enum values and booleans otherwise.
+function fieldOptions(presentation, path, loadedCatalogs, { string, boolean }) {
     const schema = schemaAtPath(presentation, path.map(String));
     const variants = schemaVariants(schema);
     const catalog = catalogAtPath(path);
@@ -70,7 +50,7 @@ export function getJsonFieldContext(source, position, loadedCatalogs = []) {
     // A document group whose source no registered catalog matches: its records beyond the embedded ones are not available here.
     const registered = new Set((Array.isArray(loadedCatalogs) ? loadedCatalogs : []).map(entry => entry?.source));
     const unloadedSource = Boolean(catalog) && Object.entries(presentation.catalogs ?? {}).some(([name, group]) => name !== "custom" && group && typeof group === "object" && typeof group.source === "string" && !registered.has(group.source));
-    if (catalog && typeof node.value === "string") {
+    if (catalog && string) {
         const hostCatalogs = Array.isArray(loadedCatalogs) ? loadedCatalogs : [];
         // A draft whose own catalogs are malformed still offers the host's records; a malformed host list offers nothing.
         const attempt = (document) => { try { return listCatalogRecords(document, catalog, { catalogs: hostCatalogs }); } catch { return undefined; } };
@@ -87,11 +67,37 @@ export function getJsonFieldContext(source, position, loadedCatalogs = []) {
                 if (["string", "number", "boolean"].includes(typeof value))
                     options.set(JSON.stringify(value), { value, label: String(value), source: "Schema" });
             }
-        if (node.type === "boolean" && variants.some(variant => variant.type === "boolean" && variant.const === undefined)) {
+        if (boolean && variants.some(variant => variant.type === "boolean" && variant.const === undefined)) {
             for (const value of [true, false])
                 options.set(String(value), { value, label: String(value), source: "Schema" });
         }
     }
+    return { options, records, catalog, unloadedSource };
+}
+// The installed schema identifies fields; a document field merely named "layout"
+// inside arbitrary metadata is not mistaken for an OPF layout reference.
+export function getJsonFieldContext(source, position, loadedCatalogs = []) {
+    let presentation;
+    try {
+        presentation = JSON.parse(source);
+    }
+    catch {
+        return null;
+    }
+    const root = parseTree(source);
+    if (!root)
+        return null;
+    let node = findNodeAtOffset(root, position, true);
+    if (node?.parent?.type === "property" && node.parent.children?.[0] === node)
+        node = node.parent.children[1];
+    if (node?.type === "object")
+        node = node.children?.find(property => property.children?.[0]?.value === "id")?.children?.[1];
+    if (!node || !["string", "number", "boolean"].includes(node.type))
+        return null;
+    const path = getNodePath(node);
+    if (!path.length)
+        return null;
+    const { options, records, catalog, unloadedSource } = fieldOptions(presentation, path, loadedCatalogs, { string: typeof node.value === "string", boolean: node.type === "boolean" });
     if (!options.size)
         return null;
     const choices = [...options.values()];
@@ -122,3 +128,97 @@ export function fieldOptionEdit(context, value) {
     while (to > from && end > from && source[to - 1] === next[end - 1]) { to--; end--; }
     return {from, to, insert: next.slice(from, end)};
 }
+
+// ---- Live completions ----------------------------------------------------------------------------------------------------------
+// What the editor offers while you type: the property names the schema allows at the cursor's object, and the same enum, boolean and
+// catalog choices the field menu lists at a value. The draft is usually not valid JSON mid-keystroke, so the token under the cursor
+// is swapped for a placeholder string and the rest is read with the tolerant parser.
+const PLACEHOLDER = "__opf_completion__";
+const WORD = /[A-Za-z0-9_.-]/;
+// The token being typed: inside a string (a quote opened earlier on this line) or a bare word. JSON strings never span lines.
+function tokenAt(text, position, explicit) {
+    const lineStart = Math.max(text.lastIndexOf("\n", position - 1), text.lastIndexOf("\r", position - 1)) + 1;
+    let open = -1;
+    for (let index = lineStart; index < position; index++) {
+        if (open >= 0) { if (text[index] === "\\") index++; else if (text[index] === '"') open = -1; }
+        else if (text[index] === '"') open = index;
+    }
+    if (open >= 0) {
+        let close = -1;
+        for (let index = position; index < text.length && text[index] !== "\n" && text[index] !== "\r"; index++) {
+            if (text[index] === "\\") index++;
+            else if (text[index] === '"') { close = index; break; }
+        }
+        return { quoted: true, closed: close >= 0, start: open, end: close >= 0 ? close + 1 : position, from: open + 1, to: close >= 0 ? close : position };
+    }
+    let start = position, end = position;
+    while (start > lineStart && WORD.test(text[start - 1])) start--;
+    while (end < text.length && WORD.test(text[end])) end++;
+    if (start === position && !explicit) return null;
+    let before = start - 1;
+    while (before >= lineStart && /\s/.test(text[before])) before--;
+    // A bare word starts a key or a value only after `{`, `,`, `:` or `[` (or at the start of an empty line).
+    const previous = before >= lineStart ? text[before] : (text.slice(0, lineStart).trimEnd().at(-1) ?? "");
+    if (!["{", ",", ":", "["].includes(previous)) return null;
+    return { quoted: false, closed: false, start, end, from: start, to: end };
+}
+
+// Schema descriptions run to paragraphs; the popup shows the first sentence, at most 200 characters.
+function brief(text) {
+    if (typeof text !== "string" || !text.trim()) return undefined;
+    const flat = text.replace(/\s+/g, " ").trim();
+    const sentence = /^.*?[.!?](?=\s|$)/.exec(flat)?.[0] ?? flat;
+    return sentence.length <= 200 ? sentence : `${sentence.slice(0, 199).trimEnd()}…`;
+}
+
+/**
+ * The completions at `position` of a JSON draft (it need not parse): `{ kind: "key" | "value", from, to, quoted, closed, options }`,
+ * or null when nothing is offered. `from` and `to` bound the text being typed (inside the quotes of a string); each option is
+ * `{ value, label, detail?, info?, boost }`. A key option's `value` is the property name; a value option's is the JSON value.
+ * `explicit` also offers choices where nothing has been typed yet.
+ */
+export function getJsonCompletions(source, position, loadedCatalogs = [], { explicit = false } = {}) {
+    const token = tokenAt(source, position, explicit);
+    if (!token) return null;
+    const draft = source.slice(0, token.start) + JSON.stringify(PLACEHOLDER) + source.slice(token.end);
+    const root = parseTree(draft, [], { allowTrailingComma: true });
+    if (!root) return null;
+    const node = findNodeAtOffset(root, token.start + 1, true);
+    if (node?.type !== "string" || node.value !== PLACEHOLDER) return null;
+    const presentation = parseJsonc(draft, [], { allowTrailingComma: true });
+    if (presentation === null || typeof presentation !== "object" || Array.isArray(presentation)) return null;
+    const range = { from: token.from, to: token.to, quoted: token.quoted, closed: token.closed };
+    try {
+        if (node.parent?.type === "property" && node.parent.children?.[0] === node) {
+            const object = node.parent.parent;
+            const present = new Set((object?.children ?? []).filter(property => property !== node.parent).map(property => property.children?.[0]?.value));
+            const properties = new Map();
+            for (const variant of schemaVariants(schemaAtPath(presentation, getNodePath(object).map(String))))
+                for (const [key, child] of Object.entries(variant.properties ?? {}))
+                    if (!present.has(key) && !properties.has(key)) properties.set(key, { child, required: (variant.required ?? []).includes(key) });
+            if (!properties.size) return null;
+            const options = [...properties].map(([key, { child, required }], index) => {
+                const resolved = resolveSchema(child);
+                const type = Array.isArray(resolved.type) ? resolved.type.join(" | ") : resolved.type ?? (resolved.enum ? "enum" : resolved.oneOf || resolved.anyOf ? "choice" : "");
+                return { value: key, label: key, detail: type || undefined, info: brief(child.description ?? resolved.description), boost: Math.max(-99, (required ? 50 : 0) - index) };
+            });
+            return { kind: "key", ...range, options };
+        }
+        const path = getNodePath(node);
+        if (!path.length) return null;
+        const { options: found, records, catalog } = fieldOptions(presentation, path, loadedCatalogs, { string: true, boolean: true });
+        if (!found.size) return null;
+        const choices = describeOptions([...found.values()], records, undefined, catalog);
+        const options = choices.map((option, index) => ({
+            value: option.value,
+            label: String(option.value),
+            detail: String(option.label) !== String(option.value) ? String(option.label) : option.sourceLabel,
+            info: [brief(option.description), option.regions].filter(Boolean).join("\n") || undefined,
+            boost: Math.max(-99, 50 - index),
+        }));
+        return { kind: "value", ...range, options };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/presenter.d.ts

@@ -0,0 +1,102 @@
+import type { EditorSession } from "./index.js";
+import type { ToSvgOptions } from "@openpresentation/opf-render";
+import type { EditorFonts } from "./canvas.js";
+
+export interface PresenterLabels {
+  /** The accessible name of the presenter dialog. Default: "Presentation". */
+  dialog?: string;
+  /** The accessible name and title of the exit button. Default: "Exit presentation". */
+  exit?: string;
+  /** Default: "Exit (Esc)". */
+  exitTitle?: string;
+  /** What the live region announces. Default: "Slide 3 of 12" (both numbers count the slides that are shown, not the hidden ones). */
+  position?: (position: number, count: number) => string;
+  /** Shown while the faces the deck needs load. Default: "Loading fonts…". */
+  loading?: string;
+  /** Shown when every slide is hidden. */
+  empty?: string;
+}
+
+export interface PresenterOptions {
+  /** The editor session. The presenter reads its current document and catalogs. */
+  editor?: EditorSession;
+  /** Without an editor: an OPF presentation, or a function returning the current one. Keep the object stable while presenting: slides are drawn once per object. */
+  presentation?: { slides?: unknown[] } | (() => { slides?: unknown[] });
+  /**
+   * The renderer's fonts handle (`loadFonts()`), the one the canvas, the thumbnails and the exports use. With its `pending` and `ensure` the
+   * presenter loads the faces a deck needs before it draws ("Loading fonts…" meanwhile).
+   */
+  fonts?: EditorFonts;
+  /** Extra `toSvg` options, such as `catalogs` (merged after the session's). Slides draw with `text: "system"`, `trace: false` and their `{{variables}}` resolved. */
+  renderOptions?: ToSvgOptions;
+  /** The slide `start()` opens on (0-based deck index; default 0). A hidden slide opens the next one that is not hidden. */
+  slideIndex?: number;
+  /** The presentation closed, by any route (Esc, the exit button, leaving full screen, `stop()`, `destroy()`). `index` is the deck index of the slide it showed, so the host can return to it. */
+  onExit?(index: number): void;
+  /** The shown slide changed (deck index): by key, click, swipe or `next`, `previous` and `goTo`. Also once at start when a hidden slide was requested. */
+  onSlideChange?(index: number): void;
+  /** `"touch"` makes the exit button 40px. Default `"comfortable"` (32px). */
+  density?: "comfortable" | "touch";
+  /** Show hidden slides too (default false: they are skipped, as the exports skip them). */
+  includeHidden?: boolean;
+  labels?: PresenterLabels;
+}
+
+export interface Presenter {
+  /** The root element, mounted in the container: `role="dialog"`, `aria-modal`, hidden until `start`. `data-mode` is `fullscreen` or `overlay`. */
+  readonly element: HTMLElement;
+  /**
+   * Open the presentation on `slideIndex` (default: the `slideIndex` option) and ask the browser for full screen. Call it from a user gesture
+   * (a click, a key press): browsers refuse full screen otherwise, and the presentation then fills the window as a fixed overlay. Resolves
+   * with the mode once the browser answered. Calling it while open goes to that slide.
+   */
+  start(slideIndex?: number): Promise<"fullscreen" | "overlay">;
+  /** Close the presentation, leave full screen, return focus to the element that was focused at `start`, and call `onExit(index)`. */
+  stop(): void;
+  /** Show the next slide that is not hidden. Returns false at the end. */
+  next(): boolean;
+  /** Show the previous slide that is not hidden. Returns false at the start. */
+  previous(): boolean;
+  /** Show a slide by its deck index (a hidden slide shows the next one that is not hidden). Returns false when the shown slide did not change. */
+  goTo(index: number): boolean;
+  /** The deck index of the shown slide; -1 when stopped or when every slide is hidden. */
+  getSlide(): number;
+  isRunning(): boolean;
+  /** `stop()`, then remove the element. */
+  destroy(): void;
+}
+
+/**
+ * The presenter: full screen (or a fixed overlay), one slide at a time on black, drawn by the renderer, catalogs and fonts handle the canvas
+ * uses. Right, Space, PageDown and Enter go forward; Left, PageUp and Backspace go back; Home and End jump; Esc exits. A click goes forward,
+ * a click on the left third goes back, and a swipe on touch moves. A "03 / 12" counter shows on pointer move for 2 seconds.
+ * CSS: `src/styles/presenter.css`, classes `opf-presenter-*`.
+ */
+export declare function createPresenter(container: HTMLElement, options: PresenterOptions): Presenter;
+
+export interface PresentButtonOptions {
+  /** The button was activated (not called while disabled). */
+  onPresent?(event: MouseEvent): void;
+  /** `true` disables with a default reason, a string with your own (it is the title). The button stays focusable (`aria-disabled`) and does nothing. */
+  disabled?: boolean | string;
+  /** `"touch"` makes the button 40px. Default `"comfortable"` (32px). */
+  density?: "comfortable" | "touch";
+  /** The accessible name (default "Present"). */
+  label?: string;
+}
+
+export interface PresentButton {
+  readonly element: HTMLButtonElement;
+  setDisabled(reason?: boolean | string): void;
+  setDensity(density: "comfortable" | "touch"): void;
+  destroy(): void;
+}
+
+/** The icon-only Present button: a Lucide Presentation icon, `aria-label="Present"`, title "Present (F5)", styled like the Export trigger. */
+export declare function createPresentButton(container: HTMLElement, options?: PresentButtonOptions): PresentButton;
+
+/**
+ * Bind F5 to `onPresent(event)` on `target` (default: the document); the browser's reload is suppressed when it fires. F5 is ignored while
+ * typing in inputs, selects and editors, in menus and dialogs, and with a modifier key held. Returns a function that removes the listener.
+ */
+export declare function bindPresentShortcut(target: Document | HTMLElement | Window | undefined | null, onPresent: (event: KeyboardEvent) => void): () => void;