@openpresentation/opf-editor 0.28.0 → 0.29.1

package/README.md

@@ -32,8 +32,22 @@ import { OpfEditor, useOpfDocument } from "@openpresentation/opf-editor/react";
 const document = useOpfDocument(editor); // also useOpfSelection(editor), useOpfCursor(editor), useOpfEditor(options)
 ```
 
+A source-only host (`layout: "source"`, or `slots` with only `source`) loads no renderer: the slide parts and the renderer are one chunk the entry point imports on demand, only for a layout that shows slides (measured with esbuild: 1,914 KiB minified up front for a source-only host, against 3,086 KiB before; the bare source pane is 1,728 KiB). `editor.setSourceText(text, { format })` loads raw text (a file as read, a draft that does not parse) into the pane without converting it, and `@openpresentation/opf-editor/exact-source` exports the writer that puts an edited document back into its JSON text with the author's bytes (`updateJsonSource`, `createSourceMemory`).
+
 [docs/embedding.md](docs/embedding.md) lists the layouts, `panels`, `slots` (your own arrangement), every option, the handle, the events and the React bindings; [docs/theming.md](docs/theming.md) is the token contract (surface, text, accent, border, radius and font, light and dark) and the `theme` option. `examples/playground.js` is a thin user of it.
 
+## The Studio (CE-20)
+
+`createOpfEditor(element, { layout: "studio" })` is the Presentation and Slide Studio, a Figma Auto Layout-style editor over the same parts: a filmstrip over a layers tree, the slide in a zoomable viewport with selection, drop lines and track dividers, a Design panel bound to the selection, Insert by kind and + Slide by layout, the source as a split synchronized both ways, Present, a context menu, a shortcut sheet (`?`) and one undo history. Slides stay auto-layout: no free positioning. `layout: "playground"` arranges the same editor for first contact, and `editor.setLayout("studio" | "playground")` switches in place.
+
+```js
+const editor = createOpfEditor(element, { layout: "studio", document, catalogs: [gallery], fonts, studio: { hostPanels: [{ id: "agent", label: "Agent", mount(el) {} }] } });
+editor.selection;               // [{ key, path, idPath, kind }]
+editor.commands.run("studio.group");
+```
+
+React: `<OpfEditor layout="studio" hostPanels={[{ id, label, render }]} />`, `useOpfSelection(editor)` and `useOpfCommands(editor)`. [docs/studio.md](docs/studio.md) has the shell, the keyboard map, the API and the known limits; `examples/studio.html` (built by `pnpm run build:playground`) tries it.
+
 ## Install the editor and optional export dependencies (RR-63)
 
 `@openpresentation/opf-render` is an optional peer of the editor, and from render 0.16 its heavy pieces are optional peers too, so install only what you use. The editor itself draws with `@openpresentation/opf-render/svg` and loads fonts with `/fonts-browser`, which need nothing else. Add:
@@ -142,11 +156,11 @@ const pane = createSourcePane(container, {
 pane.setFormat('yaml'); pane.focusPath('/slides/1/title'); pane.getText(); pane.destroy();
 ```
 
-Methods: `replaceDocument(document, { source?, format?, name?, meta? })` (below), `setFindings(list | null)`, `setFormat(format)`, `focusPath(pointer)` (moves the cursor to the line of a JSON Pointer in any format, found with core's `locate`), `getText()`, `getCursor()` and the `onCursor` option (the path under the caret), `revealPath(pointer | range, { focus?, select?, align?, flash?, part? })` (scrolls without moving the caret or the focus), `setDecorations(list, { group? })`, `clearDecorations(group?)` and `getDecorations(group?)` (a host's own marks, by path or range; see "The source pane's hooks" in [docs/embedding.md](docs/embedding.md)), `refresh()`, `setName`, `setDensity`, `setReadOnly` and `destroy()`. A finding is `{ path, message, severity, line? }` (core `Finding` objects fit). Rows show the path in mono and the line at the right; a click moves the cursor and calls `onFindingSelect`.
+Methods: `replaceDocument(document, { source?, format?, name?, meta? })` (below), `setSourceText(text, { format?, name? })` (raw text as the whole source, without converting it: true when it applied, false when it stays a draft with its problems), `setFindings(list | null)`, `setFormat(format)`, `focusPath(pointer)` (moves the cursor to the line of a JSON Pointer in any format, found with core's `locate`), `getText()`, `getCursor()` and the `onCursor` option (the path under the caret), `revealPath(pointer | range, { focus?, select?, align?, flash?, part? })` (scrolls without moving the caret or the focus), `setDecorations(list, { group? })`, `clearDecorations(group?)` and `getDecorations(group?)` (a host's own marks, by path or range; see "The source pane's hooks" in [docs/embedding.md](docs/embedding.md)), `refresh()`, `setName`, `setDensity`, `setReadOnly` and `destroy()`. A finding is `{ path, message, severity, line? }` (core `Finding` objects fit). Rows show the path in mono and the line at the right; a click moves the cursor and calls `onFindingSelect`.
 
 - **Opening a document: `pane.replaceDocument(document, { source, format, name })`.** Loading an example or a file into the pane (never by writing its text into the code editor, which the pane applies as a typed edit and forks the catalog records the two documents share) calls `editor.replaceDocument`: one undoable change, no catalog record forked. `document` is a parsed document or JSON text; `name` is the file name. `source` is the text the document was read from, in any of the three formats: the pane shows it as written (the JSON's formatting, the YAML's comments, the Markdown's layout) when the pane is in that format, and core's rewrite of the document otherwise. `format` (`"json"`, `"yaml"` or `"md"`) says which format `source` is; left out, it is inferred as the first of JSON, the pane's format, YAML and Markdown that reads as exactly this document (a `source` that reads as no format, or as another document, is ignored; an unknown `format` throws a `TypeError` before anything changes). The original text of a format other than the one shown is kept too: switching the pane to it shows those bytes, not a rewrite. Undo and Redo bring back each document's text exactly in the format shown (the opened text as written, the replaced document's text as it was, including YAML comments), so one Undo returns to the document and the text the visitor had. The pane keeps the last 8 such texts, which are also what a later load of the same document shows. A refused document throws (`invalid-opf-edit`, with `issues`) and changes nothing, and works in a read-only pane. A diff typed or pasted into the pane is still an edit, and editing a catalog record in it forks the record.
 - **Keyboard Undo and Redo in the pane (one model).** Cmd/Ctrl+Z and Cmd/Ctrl+Shift+Z (Ctrl+Y) work in two layers, in this order. First CodeMirror's history, which holds only the text typed in the pane since its last whole-document change (a `replaceDocument`, or a session Undo, Redo or restore, each of which clears it because the typed edits no longer fit the text). When that has nothing left, the key steps the session over a whole-document replace, exactly as its Undo and Redo do, so the text comes back byte for byte: Undo steps back over the nearest `replaceDocument` together with the pane's own edits typed on it (the typing was already undone, step by step, by CodeMirror's history); Redo steps forward over the replace. The key never reaches over an edit made elsewhere (the canvas, a panel): Undo stops at it, and the host's Undo button (or `editor.undo()`) undoes that edit, after which the key reaches the load again. A read-only pane takes neither key. `mountJsonCodeEditor` exposes the same seam as `historyFallback: { undo(), redo() }` (answer `true` when you did something) plus `resetHistory()` and `undoDepth()` on the control.
-- **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.
+- **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. The writer is a public entry point, `@openpresentation/opf-editor/exact-source`: `updateJsonSource(source, document, memory?)` returns `source` with only the changed values rewritten (indentation, key order, escapes and line endings kept; the whole document is written out only when an edit in place cannot reproduce it), `createSourceMemory()` gives a document its own memory of authored spellings (so a value that comes back with Undo comes back as it was written), and `findDuplicateKey(source)` finds a key JSON.parse would silently collapse. A host that keeps the JSON text of a deck itself uses it instead of a JSON token parser of its own.
 - **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: outside edits drop them and say how many. Format (below) never rewrites from the document, so it keeps them. A document that is not valid OPF cannot be written as YAML or Markdown; the pane stays in JSON and says so.
 - **Completions.** In JSON, YAML and Markdown the pane offers what the schema and the catalogs say belongs at the caret (`completions: false` keeps the field menu only). *Keys*: the properties of the object at the caret, the required ones first, then the common ones in a curated order (a slide: `title`, `subtitle`, `layout`, `items`, `text`, `notes`, ...), then the rest; the promoted region keys of a slide (`top+middle:left+center`) show only once you type three characters of one. Keys already in the object are not offered. Accepting one writes the whole pair: a string key gets `"key": "|"`, a number `"key": |`, an array `"key": [|]`, an object `"key": {|}`, and an object with required members (`organization`: `id`, `name`) writes them one per line, each a tab stop that `Tab` walks (the last `Tab` leaves the braces). A key with a closed set of values (an enum, a catalog id, a boolean) opens the list of its values at once. A comma is added when a property follows, and not before `}`. *Values*: enum values and booleans, and catalog ids (layouts, themes, color and font schemes, narratives, audiences, purposes, tones: the document's own records first, then the registered catalogs', layouts in the order of their intents, each with its description and regions in the documentation panel); after a colon, `{}` and `[]` templates. *Snippets*: `slide`, `slide-text`, `slide-image`, `slide-chart`, `slide-quote`, `slide-metric`, `slide-table`, `slide-code`, `slide-two-column` and `section` in `slides`, `reference` in `references`, `dataset` in `datasets` and `deck` in a blank document, with tab stops (the chart type stop opens the list of chart types). *Triggers*: a quote or a word at a key or value place, `:` and the space after it, and `Ctrl+Space` (`Cmd+I` on macOS) anywhere the schema has something to offer, also right after a finished string; free text (titles, notes, alt text) and numbers never open a list on their own. *Keys in the list*: `Tab` and `Enter` accept (at once, right after a keystroke too), `Shift+Tab` and `Shift+Enter` accept too (an accepted item always replaces the whole token), `Escape` closes it, `Left`, `Right` and `Backspace` inside the word keep it open and filter by the text before the caret, `Ctrl+Space` with the list open shows or hides the documentation panel. With several cursors the accepted item goes in at each of them (as plain text). The data is core's (`describeField` and `catalogKindAt` of `@openpresentation/opf/schema`; `getJsonCompletions` of `/json-options` remains for hosts that want the plain list). `mountJsonCodeEditor` takes the same `completions` option, off by default there.
@@ -163,10 +177,10 @@ Methods: `replaceDocument(document, { source?, format?, name?, meta? })` (below)
 - **Go to definition, peek, references and rename (phase 4).** The ids of a document are symbols, in JSON, YAML and Markdown, also while the text is broken: assets (`asset:logo`, a Markdown `![](asset:logo)`), variables (`var:brand`, `{{name}}`, `{{name|format}}`), datasets and their columns, references (`cite`), slide ids (`"id"`, `id:`, `<!-- slide: id=... -->`), the beats and regions of a narrative or layout, and every catalog id (layout, theme, color scheme, font scheme, narrative, audience, purpose, tone, also as `name:id`). `F12` (and Cmd/Ctrl+click) jumps to the declaration and selects it; a record only a registered catalog has (the app's) opens a read-only card in the widget (name, description, regions, "Provided by app", and the preview from the host's `resolvePreview(kind, id)` option of the pane or the code editor, an element or an `https:` or `data:image/` address); a built-in variable (`organization.name`) or an id nothing declares says so and does not move. On a declaration `F12` lists its uses instead, as VS Code does. `Alt+F12` peeks the declaration (its lines with a line of context) in a widget under the line, with the focus in it: `Enter` goes to the definition, `Escape` closes it and returns to the editor. `Shift+F12` lists the declaration first (marked "Declaration") and then every use with its line, slide number and text: Up, Down, Home and End move, `Enter` (or a click) jumps and selects the use, `Escape` closes. `F2` opens an input at the symbol, filled with the id and selected; the name is checked as you type (not empty, the schema's pattern for that kind of id, no collision with another id of the same kind) and the message appears in the widget and is announced; `Enter` renames the declaration and every use in one transaction, so one undo restores them all, and keeps the selection on the renamed symbol. Renamable: assets, variables (a `{{name|format}}` keeps its format), datasets, references, slide ids and the ids of records embedded in `catalogs` (with the uses of a `name:id` reference of that group). Not renamable, with the reason said: a record only the app provides, a built-in variable, a dataset column, a beat or a region (they are named in their record), an id nothing declares, and anything in a read-only editor. Every command announces what it did in the live region; the widgets are named (`role`, `aria-label`), operable with the keyboard alone and return the focus to the editor; the declaration is marked with the word and an arrow, not by color alone. The widgets move with the edits above them. The work is one read of the text per edit (a big YAML text is read in pieces with the main thread given back between them): on a 1000-slide deck each command answers well under 100 ms (10 to 30 ms measured) and never holds the main thread for 50 ms.
 - **Format document.** `Shift+Alt+F` (and `Cmd/Ctrl+Shift+F`) and the Format button do the same in JSON, YAML and Markdown, and change whitespace only, as one undo step with the cursor kept on its token. JSON is laid out token by token with the document's indentation, also while it does not parse; YAML keeps its comments, blank lines, quote styles, number spellings and key order (the pane says so and does nothing when the YAML has errors); Markdown gets at most one blank line between blocks (code fences untouched), its front matter formatted as YAML, and one newline at the end. A format that would change the document is refused. The pane does not rewrite the text from the document (`toYaml`, `toMarkdown`) any more, so it no longer drops comments.
 - **Canonicalize with OPF.** The old behavior of Format (the text rewritten from the document with `toYaml` or `toMarkdown`, in the order and style OPF writes) is its own button in YAML and Markdown, `pane.canonicalize()`. It drops comments, so when there are any it asks first, names how many (YAML `#` comments; Markdown `<!-- -->` comments other than slide and block options, and the YAML comments of the front matter and fences), and waits for "Canonicalize anyway" or Cancel (`Escape`); undo brings the comments back. It is one undo step.
-- **Checking in a Web Worker (`worker`).** Reading the text (YAML, Markdown), the quick syntax pass of JSON and validating the document take 50 to 100 ms on a thousand slides, so with `worker` the pane does that off the main thread: typing in a 1000-slide deck never blocks the page for 50 ms (the budget is tested in Chromium and WebKit). The worker runs the same functions as the pane's own path (`source-check.js`) and hands back the deck read, the findings and the validation the session would compute, which the session accepts through `editor.applyPatch(operations, meta, { validated })` only for exactly that document and its current `catalogs` (it never lands in the undo history). The host bundles the worker script, `@openpresentation/opf-editor/source-worker` (an ES module with no exports; bundlers such as Vite, webpack and Parcel build it with `new Worker(new URL('@openpresentation/opf-editor/source-worker', import.meta.url), { type: 'module' })`; otherwise build `dist/source-worker.js` as its own entry and serve it next to the page), and passes `worker: () => new Worker(...)` (a function, a `Worker`, or `true` to try `new Worker(new URL('./source-worker.js', import.meta.url), { type: 'module' })` beside the pane's module). Without `worker` (the default) nothing changes: everything runs on the main thread. Only the typing delay (`applyDelay`) uses the worker; `getText()`, switching the format, `replaceDocument`, Format, Undo and `destroy` apply a pending edit on the main thread at once, as before. If the worker cannot start (a CSP, a wrong URL, a bundler), cannot clone a message, throws or stops answering, the pane checks on the main thread from then on, `onError` is called once, and no edit is lost. Results are identical either way (a test compares the problems, squiggles, document and validation for the same texts). `pane.whenIdle()` resolves when no edit waits for its delay and no check runs; `pane.checkerStats()` is `{ worker, inline, available }` (how the applied edits were checked); `data-opf-checking` is on the pane's root while a worker check is running. While you type faster than the worker answers, older answers are dropped and the newest text is applied when you pause.
+- **Checking in a Web Worker (`worker`).** Reading the text (YAML, Markdown), the quick syntax pass of JSON and validating the document take 50 to 100 ms on a thousand slides, so with `worker` the pane does that off the main thread: typing in a 1000-slide deck never blocks the page for 50 ms (the budget is tested in Chromium and WebKit). The worker runs the same functions as the pane's own path (`source-check.js`) and hands back the deck read, the findings and the validation the session would compute, which the session accepts through `editor.applyPatch(operations, meta, { validated })` only for exactly that document and its current `catalogs` (it never lands in the undo history). The worker script is `@openpresentation/opf-editor/source-worker` (an ES module with no exports that imports core, so it runs only bundled). `worker: true` starts it with `new Worker(new URL('./source-worker.js', import.meta.url), { type: 'module' })`, which Next.js (Turbopack and webpack, dev and build), webpack and Vite builds bundle; `worker: () => new Worker(new URL('@openpresentation/opf-editor/source-worker', import.meta.url), { type: 'module' })` works there too and in the Vite dev server with core in `optimizeDeps.include`; with esbuild, build the worker entry as its own entry point and pass its URL (`worker: new URL('./source-worker.js', import.meta.url)`). [The source worker](docs/embedding.md#the-source-worker) has the snippet for each bundler. The worker says it is ready as soon as it runs: one that loads but never does (a script a bundler emptied) is given up after 5 s. Without `worker` (the default) nothing changes: everything runs on the main thread. Only the typing delay (`applyDelay`) uses the worker; `getText()`, switching the format, `replaceDocument`, Format, Undo and `destroy` apply a pending edit on the main thread at once, as before. If the worker cannot start (a CSP, a wrong URL, a bundler), cannot clone a message, throws or stops answering, the pane checks on the main thread from then on, `onError` is called once, and no edit is lost. Results are identical either way (a test compares the problems, squiggles, document and validation for the same texts). `pane.whenIdle()` resolves when no edit waits for its delay and no check runs; `pane.checkerStats()` is `{ worker, inline, available }` (how the applied edits were checked); `data-opf-checking` is on the pane's root while a worker check is running. While you type faster than the worker answers, older answers are dropped and the newest text is applied when you pause.
 - **Accessibility.** One polite live region (`.opf-source-live`) says how many suggestions there are when the list opens, the selected item and the first sentence of its documentation as you arrow (after a short pause), `Inserted design` when you accept, `Tab stop 2 of 3: ...` in a snippet, the problem when the caret enters a squiggle or `F8` reaches it, and `2 problems: 1 error, 1 warning` once the problems stop changing for 600 ms; hosts get every message through the `announce` option. Every suggestion has an accessible name with its kind and its place (`design, property, Design. 1 of 3`), the editor's `aria-description` says how to open the list and how to leave the editor (`Escape` then `Tab`, or `Ctrl+M`; `Ctrl+Shift+M` on macOS), and the problem rows start with the severity as text as well as a shape. 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.** `yaml` (ISC; core already depends on it) formats YAML while keeping its comments. `@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.
+- **Dependency.** `yaml` (ISC; core already depends on it) formats YAML while keeping its comments. The `@codemirror/*` and `@lezer/*` packages are caret ranges, so an app that uses CodeMirror itself shares one copy; two copies of `@codemirror/view` silently break the pane's tooltips, completions, problems and find, and the pane reports them once through `onError` (code `duplicate-codemirror`) or the console ([One copy of CodeMirror](docs/embedding.md#one-copy-of-codemirror)). `@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.
 
 Icons are inline paths from [Lucide](https://lucide.dev) (ISC license). The harness is `examples/source-pane.html` (built by `pnpm run build:playground`); `pnpm run test:source-pane-browser` drives it, and `pnpm run test:source-keyboard-browser` and `pnpm run test:source-keyboard-json-browser` run the keyboard cases (real key events; `OPF_BROWSER_ENGINE=webkit` and `OPF_KEYBOARD_PLATFORM=win32|linux|darwin` pick the browser and the key map).
 
@@ -724,7 +738,7 @@ const selectionControls = createDesignControls(contentPanel, { editor, getSlideI
 controls.refresh(); // when the slide or the selection changes
 ```
 
-Sections: `look` (theme, color scheme, font scheme, language, this slide's layout), `background` (type, theme slot, solid color, gradient with its stops, image with fit, focus, alt text, recolor and overlay, any of the 54 patterns, opacity; a draft until Apply, with Remove), `header-footer` (choose header or footer and a zone, then every part the zone supports: a text box with an "Insert value" menu that puts the slide number, slide count, section, organization, speaker or deck name at the cursor as a `{{ }}` variable (Enter commits, Shift+Enter starts a new line), an image with an "Insert logo" action (a shape and, for several organizations, an organization; it writes the logo reference as the zone's image), social profiles, and the current or fixed date and format, with a summary of the zones in use), `brand` (the organization logo: one image for every shape, or each of the four shapes for both, light and dark backgrounds, for the organization you choose; which organization's logo and shape covers, sections and picture bullets draw, or none; picture bullets, accent font, watermark), `layout-options` (alignment, direction, primary chart, content box, default image fit), `info` (narrative, tone, audience, socials), `selection` (content type with a loss report, list levels, group of metrics, group and ungroup, image to background or watermark, replacement, chart type), `image` (the selected image block's fit, focus, shape, corner radius, border, opacity, recolor, overlay, aspect ratio and placement), `catalog` (reference findings and the explicit "Update from catalog"), `slide-content` (blocks to regions and back, design images back into the content) and `table` (style, merge, split, cell fill, alignment and bold). The panel is native `details`, `fieldset`, `select`, checkbox and text controls with a label on each, so it works with the keyboard and with screen readers: groups open with Enter or Space, a select changes with the arrow keys, text fields commit on Enter or when you leave them, and results and refusals are announced in `role="status"` and `role="alert"` regions. A refused change (an invalid value, text a merge would hide) is explained, changes nothing, and puts the field back. "Applies to" switches the design controls between the whole presentation and the current slide, and a control shows when a slide value is "set on this slide" or "from the presentation". The panel offers only conversions that exist, shows what a conversion loses before you choose it, and lists why an unavailable one is unavailable.
+Sections: `look` (theme, color scheme, font scheme, language, this slide's layout), `background` (type, theme slot, solid color, gradient with its stops, image with fit, focus, alt text, recolor and overlay, any of the 54 patterns, opacity; a draft until Apply, with Remove), `header-footer` (choose header or footer and a zone, then every part the zone supports: a text box with an "Insert value" menu that puts the slide number, slide count, section, organization, speaker or deck name at the cursor as a `{{ }}` variable (Enter commits, Shift+Enter starts a new line), an image with an "Insert logo" action (a shape and, for several organizations, an organization; it writes the logo reference as the zone's image), social profiles, and the current or fixed date and format, with a summary of the zones in use), `brand` (the organization logo: one image for every shape, or each of the four shapes for both, light and dark backgrounds, for the organization you choose; which organization's logo and shape covers, sections and picture bullets draw, or none; picture bullets, accent font, watermark), `layout-options` (alignment, direction, primary chart, content box, default image fit), `info` (narrative, tone, audience, socials), `selection` (content type with a loss report, list levels, group of metrics, group and ungroup, image to background or watermark, replacement, chart type), `image` (the selected image block's fit, focus, shape, corner radius, border, opacity, recolor, overlay, aspect ratio and placement), `catalog` (reference findings and the explicit "Update from catalog"), `slide-content` (blocks to regions and back, design images back into the content) and `table` (style, merge, split, cell fill, alignment and bold). The panel is native `details`, `fieldset`, `select`, checkbox and text controls with a label on each, so it works with the keyboard and with screen readers: groups open with Enter or Space, a select changes with the arrow keys, text fields commit on Enter or when you leave them, and results and refusals are announced in `role="status"` and `role="alert"` regions. A refused change (an invalid value, text a merge would hide) is explained, changes nothing, and puts the field back. "Applies to" switches the design controls between the whole presentation and the current slide, and a control shows when a slide value is "set on this slide" or "from the presentation". The panel shows options, not explanations: every option is a control with a short label, and a hint (a unit, a range, a consequence) is the control's tooltip and accessible description, never a paragraph under it. It offers only conversions that exist and names what a conversion loses on its option; a type the content cannot become is listed but disabled, with the reason as its tooltip and accessible description. The selected block's structural actions (group with the next block, ungroup the selected group or the group around the block, plus a host's own through `blockActions`, such as the Studio's move up, move down, duplicate and delete) are one row of named icon buttons; a disabled one stays focusable (`aria-disabled`) and names why in its tooltip, and an available one shows its shortcut. The selected block's path is a copyable chip under the section's Advanced (`showPath: false` leaves it to a host with its own Advanced).
 
 In React (or Svelte, or anything else) mount it into a ref and destroy it on unmount; it needs no framework runtime:
 
@@ -768,7 +782,7 @@ await persistence.markSaved();        // after the host saved the document somew
 - **Restore** is offered when a stored copy differs from the document the session starts with. `restore()` puts the copy back as one undoable step; into a session nobody has edited it restores the undo history too (`restoreState`, which replays the history against the document and refuses one that does not belong to it, so a stale copy never corrupts the session). If the person keeps editing while the offer is open, the offered copy is first moved aside, so ignoring the prompt never loses it; after a reload the offer mentions the older copy (`restoreEarlier()`). `discard()` deletes the stored copy.
 - **Unsaved changes.** `dirty` is true when the document differs from the last `markSaved()` (or from how the session started); `beforeunload` warns while it is true (`warnOnUnload: false` to opt out) and a final write is started on unload, `pagehide` and when the tab is hidden. A host that loads a document into the editor (the gallery hands a snippet over) calls `rebase()` so that document is neither autosaved nor warned about until the person changes it. The playground marks the document saved on Save OPF, not on a PowerPoint export (a PPTX is not the OPF document).
 - **Degradation.** Private browsing, blocked site data, a failing read or a full store never throw: `status` says `unavailable` or `error` with a sentence the host shows ("... download it to keep it", "browser storage is full ..."), a full store first drops the undo history and then reports, and the next change tries again. Dirty tracking and the unload warning keep working without storage.
-- The playground enables it with the key `opf-editor-playground`. A host page sets `globalThis.OPF_EDITOR_HOST = { persistence: { key, storage, onRestorePrompt } }` (or `persistence: false`) before the script runs; a frame can pass `?persist=<key>` or `?persist=0`. The footer text of the inspector is the autosave indicator and a prompt appears under the document bar.
+- The playground enables it with the key `opf-editor-playground`. A host page sets `globalThis.OPF_EDITOR_HOST = { persistence: { key, storage, onRestorePrompt } }` (or `persistence: false`; `document` starts it with the host's own deck instead of the sample, and `onReady({ editor, session, fonts })` hands the host the live editor and fonts handle) before the script runs; a frame can pass `?persist=<key>` or `?persist=0`. The footer text of the inspector is the autosave indicator and a prompt appears under the document bar.
 ## Fill template panel (RR-32)
 
 A template is an OPF file with variables (`{{id}}` tokens and `var:id` references, root `"template": true`; see [templates and variables](https://github.com/OpenPresentation/opf/blob/main/docs/templates-and-variables.md)). `/templates` is the headless model and `/template-panel` the DOM panel over it. Both need the core release that ships `resolveVariables` (older cores load them and throw `templates-unavailable`).

package/dist/canvas.d.ts

@@ -58,6 +58,13 @@ export interface CanvasEditorOptions {
    * their properties on double-click.
    */
   textEntry?: "click" | "dblclick";
+  /**
+   * CE-20: "interactive" (default) makes each piece of content a focusable button on the slide. "passive" is for a host that draws its own
+   * selection over the slide (the Studio): the slide SVG is `aria-hidden` and its targets leave the tab order; editing works through `beginEdit`.
+   */
+  targets?: "interactive" | "passive";
+  /** CE-20: what Escape does in an inline text field: "cancel" (default) drops the draft, "commit" keeps it and leaves. */
+  escape?: "cancel" | "commit";
   /** Picture tools (default true): a selected picture shows a "Crop picture" button that opens the crop and focal point layer. */
   imageTools?: boolean;
   /** Optional empty host for property forms; defaults to a floating canvas panel. */
@@ -106,7 +113,12 @@ export interface CanvasEditor {
   openInsertMenu(containerPath?: string,index?: number): void;
   select(path: string): void;
   /** Start editing with all text selected (keyboard entry). Pointer entry places the caret at the pointer instead. */
-  beginEdit(path: string): void;
+  beginEdit(path: string, entry?: { point?: { clientX: number; clientY: number } }): void;
+  /** How a pointer enters text editing now; `setTextEntry` changes it without remounting. */
+  readonly textEntry: "click" | "dblclick";
+  setTextEntry(mode: "click" | "dblclick"): void;
+  readonly targets: "interactive" | "passive";
+  setTargets(mode: "interactive" | "passive"): void;
   /** Open structured controls, including rich run fields. */
   editProperties(path: string): boolean;
   commit(): boolean;

package/dist/canvas.js

@@ -73,6 +73,9 @@ export function createCanvasEditor(container, options = {}) {
   // are not loaded yet is never rendered: the canvas has the handle load them first and shows "Loading fonts…" meanwhile. Without a
   // handle every document renders at once, with core's portable text estimate.
   const handle = options.fonts, fonts = fontGate(handle);
+  // The document as the session holds it now: its frozen snapshot, one object per version, so the font gate's answer for it is reused
+  // (CE-20; the session's \`presentation\` copies the whole deck on every read).
+  const current = () => editor.snapshot?.().presentation ?? editor.presentation;
   // The renderer draws with the session's registered catalogs (plus any `renderOptions.catalogs`): the same list core resolves with.
   const resolveOptions = () => ({ ...renderOptions, catalogs: mergeCatalogs(editor.catalogs, renderOptions.catalogs) });
   // RR-61: the handle measures, and the canvas embeds no face: the browser handle already added its faces to the page, so
@@ -95,9 +98,16 @@ export function createCanvasEditor(container, options = {}) {
   // How a pointer enters text editing: "click" (default; PowerPoint / Google Slides) puts the caret at the pressed
   // character on a single press and lets a press-drag select a range; "dblclick" keeps the older double-click gesture
   // but still places the caret at the pointer. Keyboard entry (Enter, Space, F2) always selects all text.
-  const textEntry = options.textEntry ?? "click";
+  let textEntry = options.textEntry ?? "click";
   if (textEntry !== "click" && textEntry !== "dblclick")
     throw new RangeError('textEntry must be "click" or "dblclick".');
+  // CE-20: "passive" targets are for a host that draws its own selection over the slide (the Studio's overlay): the slide is aria-hidden and
+  // its targets leave the tab order, while editing, crop and properties work as before through `beginEdit` and the other calls.
+  let targetMode = options.targets ?? "interactive";
+  if (targetMode !== "interactive" && targetMode !== "passive")
+    throw new RangeError('targets must be "interactive" or "passive".');
+  // CE-20: what Escape does in an inline text field: "cancel" (default) drops the draft; "commit" keeps it and leaves (the Studio, as Figma).
+  const escapeAction = options.escape ?? "cancel";
   const root = doc.createElement("div"),
     preview = doc.createElement("div"),
     overlay = doc.createElement("div"),
@@ -236,7 +246,7 @@ export function createCanvasEditor(container, options = {}) {
   function show(target) {
     if (disposed) return;
     const token = ++showToken;
-    return whenFontsReady(fonts, target ?? editor.presentation, {
+    return whenFontsReady(fonts, target ?? current(), {
       renderOptions: resolveOptions(),
       isCurrent: () => !disposed && token === showToken,
       loading: (pending) => fontsState("loading", pending),
@@ -253,7 +263,7 @@ export function createCanvasEditor(container, options = {}) {
   }
   // Renders now when the document's fonts are loaded (errors throw to the caller), otherwise after loading them.
   function renderFor(presentation) {
-    if (fonts?.pending(presentation ?? editor.presentation, resolveOptions()).length) show(presentation);
+    if (fonts?.pending(presentation ?? current(), resolveOptions()).length) show(presentation);
     else render(presentation);
   }
   // The text an editing target draws: its outermost <text> elements, whitespace collapsed (the renderer's <title> and <desc> are not drawn).
@@ -265,7 +275,7 @@ export function createCanvasEditor(container, options = {}) {
       .replace(/\s+/g, " ")
       .trim();
   }
-  function render(presentation = editor.presentation) {
+  function render(presentation = current()) {
     if (disposed) return;
     requireFonts(presentation);
     showToken++;
@@ -276,11 +286,13 @@ export function createCanvasEditor(container, options = {}) {
     const svg = preview.querySelector("svg");
     svg.setAttribute("role", "group");
     svg.setAttribute("aria-label", "Editable slide");
+    if (targetMode === "passive") svg.setAttribute("aria-hidden", "true");
     // FA-30: the renderer labels its slide root a "slide" group named by the title; the canvas is named for editing instead, so it drops
     // the roledescription rather than announce "Editable slide, slide".
     svg.removeAttribute("aria-roledescription");
     svg.removeAttribute("aria-labelledby");
-    const geometry = resolvePresentation(presentation, drawOptions()).slides[
+    // Only the slide on show is bound (CE-20): a long deck is not composed slide by slide for one draw.
+    const geometry = resolvePresentation(presentation, drawOptions(), { slides: [slideIndex] }).slides[
       slideIndex
     ].geometry;
     const candidates = [...svg.querySelectorAll("[data-opf-path]")];
@@ -396,6 +408,8 @@ export function createCanvasEditor(container, options = {}) {
       node.removeAttribute("tabindex");
       node.setAttribute("aria-label", `${field.charAt(0).toUpperCase()}${field.slice(1)}`);
     }
+    if (targetMode === "passive")
+      for (const node of svg.querySelectorAll("[tabindex]")) node.setAttribute("tabindex", "-1");
     layoutHandles.update(presentation, geometry);
     blockControls.update(presentation, geometry);
     imageCropper?.update();
@@ -491,6 +505,7 @@ export function createCanvasEditor(container, options = {}) {
       geometry = resolvePresentation(
         active.draft ?? editor.presentation,
         drawOptions(),
+        { slides: [slideIndex] },
       ).slides[slideIndex].geometry;
     const item = geometry.items.find((item) => item.path === active.path);
     const metricLayout=geometry.items.find(item=>item.metricLayout?.parts.some(part=>part.path===active.path))?.metricLayout;
@@ -605,8 +620,9 @@ export function createCanvasEditor(container, options = {}) {
     if (active && !commit()) return;
     startEdit(path, { point: event, drag: true });
   }
-  function beginEdit(path) {
-    startEdit(path);
+  // `entry.point` ({ clientX, clientY }) puts the caret there (a double-click in the Studio); without it all text is selected.
+  function beginEdit(path, entry) {
+    startEdit(path, entry?.point ? { point: entry.point } : undefined);
   }
   // entry: undefined selects all text (keyboard and programmatic entry); {point} places the caret at a client point;
   // {point, drag} also selects while the pressed pointer moves.
@@ -702,7 +718,7 @@ export function createCanvasEditor(container, options = {}) {
         } else if (event.key === "Escape") {
           event.preventDefault();
           event.stopPropagation();
-          cancel();
+          if (escapeAction === "commit") commit(); else cancel();
         } else if (event.key === "Enter" && (event.metaKey || event.ctrlKey)) {
           event.preventDefault();
           commit();
@@ -721,7 +737,7 @@ export function createCanvasEditor(container, options = {}) {
       active = {kind:"rich-text",path,base:JSON.stringify(value),valid:true};
       active.rich = createRichTextInput(root, overlay, {
         path, value, getTarget, selectAll: !entry?.point,
-        onInput: queueDraft, onCommit: commit, onCancel: cancel, onError: report,
+        onInput: queueDraft, onCommit: commit, onCancel: () => (escapeAction === "commit" ? commit() : cancel()), onError: report,
         onFormat(start,end) {
           if (!commit()) return;
           if(start===end)richToolbar.selectAll(path);else richToolbar.selectRange(path,start,end);
@@ -1113,6 +1129,20 @@ export function createCanvasEditor(container, options = {}) {
     render,
     setSlide,
     reveal,
+    get textEntry() { return textEntry; },
+    /** CE-20: switch how a pointer enters text editing ("click" or "dblclick") without remounting (the Studio's presets). */
+    setTextEntry(mode) {
+      if (mode !== "click" && mode !== "dblclick") throw new RangeError('textEntry must be "click" or "dblclick".');
+      textEntry = mode;
+    },
+    get targets() { return targetMode; },
+    /** CE-20: "interactive" targets (buttons in the tab order) or "passive" ones (the host draws selection); redraws. */
+    setTargets(mode) {
+      if (mode !== "interactive" && mode !== "passive") throw new RangeError('targets must be "interactive" or "passive".');
+      if (mode === targetMode) return;
+      targetMode = mode;
+      if (!active) renderFor();
+    },
     setRenderOptions(next) {
       if (!commit()) return false;
       richToolbar.hide();

package/dist/chart-options-panel.js

@@ -1,7 +1,7 @@
 // The chart options panel (RR-35): axis titles, legend position and data labels for the selected chart, plus (FA-09) its alt text and
 // (FA-14) which series and categories to highlight.
 // It mounts into any host element over an editor session; every control commits one undoable change through
-// `setChartOptions` (src/chart-options.js), the canvas redraws, and Undo restores the chart. The panel shows only what
+// `setChartOptions` (src/chart-options.js), the canvas redraws, and The panel shows only what
 // the selected chart type can show (core's support table), and hides itself when no chart is selected. On a combo chart
 // (FA-15) a "Series" group sets which series are lines and which lines use the secondary value axis, and a secondary axis
 // title field appears while a line uses that axis. (RR-96) A "Colors" group sets the color of each series (or slice) from the deck's accent
@@ -222,25 +222,25 @@ export function createChartOptionsPanel(host, { editor, getSelectedPath, onStatu
   const checkedNames = (part) => [...fields.highlight[part].querySelectorAll("input:checked")].map((input) => input.value);
   const selectedContent = () => fields.contents.filter((input) => input.checked && !input.closest("label").hidden).map((input) => input.value);
   const listeners = [
-    [fields.alt, "change", () => commit({ alt: fields.alt.value }, "Changed the chart's alt text. Undo restores it.")],
-    [fields.decorative, "change", () => commit({ decorative: fields.decorative.checked }, fields.decorative.checked ? "Marked the chart decorative. Undo restores it." : "The chart is no longer decorative. Undo restores it.")],
-    [fields.category, "change", () => commit({ axisTitles: { category: fields.category.value } }, "Changed the category axis title. Undo restores it.")],
-    [fields.value, "change", () => commit({ axisTitles: { value: fields.value.value } }, "Changed the value axis title. Undo restores it.")],
-    [fields.secondary, "change", () => commit({ axisTitles: { secondary: fields.secondary.value } }, "Changed the secondary axis title. Undo restores it.")],
+    [fields.alt, "change", () => commit({ alt: fields.alt.value }, "Changed the chart's alt text.")],
+    [fields.decorative, "change", () => commit({ decorative: fields.decorative.checked }, fields.decorative.checked ? "Marked the chart decorative." : "The chart is no longer decorative.")],
+    [fields.category, "change", () => commit({ axisTitles: { category: fields.category.value } }, "Changed the category axis title.")],
+    [fields.value, "change", () => commit({ axisTitles: { value: fields.value.value } }, "Changed the value axis title.")],
+    [fields.secondary, "change", () => commit({ axisTitles: { secondary: fields.secondary.value } }, "Changed the secondary axis title.")],
     [fields.series, "change", () => {
       const checked = (option) => [...fields.series.querySelectorAll(`[data-opf-chart-option='${option}']`)].filter((input) => input.checked).map((input) => input.value);
       const line = checked("line");
-      commit({ line, secondaryAxis: checked("secondaryAxis").filter((name) => line.includes(name)) }, "Changed which series are lines. Undo restores them.");
+      commit({ line, secondaryAxis: checked("secondaryAxis").filter((name) => line.includes(name)) }, "Changed which series are lines.");
     }],
-    [fields.legend, "change", () => commit({ legend: fields.legend.value }, "Changed the legend. Undo restores it.")],
-    [fields.labels, "change", () => commit({ dataLabels: fields.labels.checked }, fields.labels.checked ? "Showing data labels. Undo restores the chart." : "Hid the data labels. Undo restores them.")],
-    [fields.position, "change", () => commit({ dataLabels: { position: fields.position.value } }, "Moved the data labels. Undo restores them.")],
-    [fields.separator, "change", () => commit({ dataLabels: { separator: fields.separator.value } }, "Changed the label separator. Undo restores it.")],
+    [fields.legend, "change", () => commit({ legend: fields.legend.value }, "Changed the legend.")],
+    [fields.labels, "change", () => commit({ dataLabels: fields.labels.checked }, fields.labels.checked ? "Showing data labels." : "Hid the data labels.")],
+    [fields.position, "change", () => commit({ dataLabels: { position: fields.position.value } }, "Moved the data labels.")],
+    [fields.separator, "change", () => commit({ dataLabels: { separator: fields.separator.value } }, "Changed the label separator.")],
     [fields.colors, "click", (event) => {
       const button = event.target.closest?.("[data-opf-chart-option='colors.choose']");
       if (!button) return;
       const index = Number(button.closest("[data-position]").dataset.position);
-      commit({ colors: colorsWith(index, button.dataset.color) }, button.dataset.color ? "Changed a chart color. Undo restores it." : "Returned a chart color to the deck palette. Undo restores it.");
+      commit({ colors: colorsWith(index, button.dataset.color) }, button.dataset.color ? "Changed a chart color." : "Returned a chart color to the deck palette.");
     }],
     [fields.colors, "change", (event) => {
       const input = event.target.closest?.("[data-opf-chart-option='colors.hex']");
@@ -248,18 +248,18 @@ export function createChartOptionsPanel(host, { editor, getSelectedPath, onStatu
       const index = Number(input.closest("[data-position]").dataset.position);
       const value = input.value.trim();
       if (value && !isColorRef(value)) { onStatus("Use a hex color such as #7B241C."); refresh(); return; }
-      commit({ colors: colorsWith(index, value) }, "Changed a chart color. Undo restores it.");
+      commit({ colors: colorsWith(index, value) }, "Changed a chart color.");
     }],
-    [fields.colorsReset, "click", () => commit({ colors: null }, "Returned the chart colors to the deck palette. Undo restores them.")],
+    [fields.colorsReset, "click", () => commit({ colors: null }, "Returned the chart colors to the deck palette.")],
     ...["series", "categories"].map((part) => [fields.highlight[part], "change", () => {
       const names = checkedNames(part);
-      commit({ highlight: { [part]: names } }, names.length ? `Highlighted ${names.join(", ")}. Undo restores the colors.` : `Cleared the ${part} highlight. Undo restores it.`);
+      commit({ highlight: { [part]: names } }, names.length ? `Highlighted ${names.join(", ")}.` : `Cleared the ${part} highlight.`);
     }]),
     ...fields.contents.map((input) => [input, "change", () => {
       const content = selectedContent();
       // A label always shows something: unticking the last part keeps it.
       if (!content.length) { input.checked = true; return; }
-      commit({ dataLabels: { content } }, "Changed what the data labels show. Undo restores them.");
+      commit({ dataLabels: { content } }, "Changed what the data labels show.");
     }]),
   ];
   for (const [element, type, handler] of listeners) element.addEventListener(type, handler);

package/dist/codemirror-guard.js

@@ -0,0 +1,69 @@
+// One copy of @codemirror/view. Every CodeMirror package (autocomplete, search, lint, language) builds its view plugins with the
+// `ViewPlugin` of the @codemirror/view copy IT resolves to. When a host app resolves a second copy (its own CodeMirror at another version,
+// or a package manager that did not dedupe), the editor's EditorView never runs those plugins: tooltips, completions, the problems
+// panel and find stop working, with no error. This module finds that case from the extensions the code editor mounts with and says it
+// once per page.
+import { ViewPlugin } from "@codemirror/view";
+
+const REPORTED = Symbol.for("@openpresentation/opf-editor:duplicate-codemirror-view");
+
+/** Whether `value` is a ViewPlugin, of any copy of @codemirror/view (its fields, since `instanceof` is what fails across copies). */
+const looksLikeViewPlugin = (value) => value !== null && typeof value === "object" && typeof value.create === "function" && typeof value.id === "number" && "domEventHandlers" in value && "baseExtensions" in value;
+
+/**
+ * The view plugins in the extension tree `extension` that were made by another copy of @codemirror/view than `ownViewPlugin` (the
+ * editor's own). An empty list means one copy. Walks arrays, precedence and compartment wrappers (`inner`), plugin extensions and
+ * facet providers whose value names a plugin (`plugin.of(arg)`).
+ */
+export function foreignViewPlugins(extension, ownViewPlugin = ViewPlugin) {
+  const found = [];
+  const seen = new Set();
+  const visit = (value) => {
+    if (value === null || typeof value !== "object" || seen.has(value)) return;
+    seen.add(value);
+    if (Array.isArray(value)) {
+      for (const item of value) visit(item);
+      return;
+    }
+    if (looksLikeViewPlugin(value)) {
+      if (!(value instanceof ownViewPlugin)) found.push(value);
+      return;
+    }
+    if (looksLikeViewPlugin(value.value?.plugin)) visit(value.value.plugin);
+    if ("inner" in value) visit(value.inner);
+    if ("extension" in value && value.extension !== value) visit(value.extension);
+  };
+  visit(extension);
+  return found;
+}
+
+/** The error a host hears when the code editor mounts on two copies of @codemirror/view. */
+export function duplicateViewError() {
+  const error = new Error(
+    "Two copies of @codemirror/view are loaded, so the OPF source editor's tooltips, completions, problems and find do not work. " +
+      "Make the app resolve one copy of each @codemirror/* package (npm dedupe; a pnpm override or a bundler alias for @codemirror/view and @codemirror/state).",
+  );
+  error.code = "duplicate-codemirror";
+  return error;
+}
+
+/**
+ * Check the extensions a code editor mounts with and report a second copy of @codemirror/view once per page: through `onError` when
+ * the host gave one, else on the console. Returns whether a second copy was found (on every call, also after it was reported).
+ */
+export function checkCodeMirrorCopies(extension, onError) {
+  if (foreignViewPlugins(extension).length === 0) return false;
+  if (globalThis[REPORTED]) return true;
+  globalThis[REPORTED] = true;
+  const error = duplicateViewError();
+  if (typeof onError === "function") {
+    try {
+      onError(error);
+      return true;
+    } catch {
+      /* A host callback that throws: the console still says it. */
+    }
+  }
+  globalThis.console?.error?.(error.message);
+  return true;
+}