@openpresentation/opf-editor 0.24.3 → 0.25.1

package/README.md

@@ -40,7 +40,8 @@ The release after 0.14.2 moves the editor onto core 0.15 (a breaking, clean spec
 - **Save and export embed.** `prepareSave`/`saveDocument`, `serializeOpfTransfer` (presentation and slide scope) and `convert` (`/export`) call core's `embed`; the playground's OPF download and PPTX export do too.
 - **Paste** (`prepareOpfImport`, insert mode) uses core's `copySlides`: groups match by `source`, identical records are reused, and the result's `renamed` (`custom-conflict`, `catalog-revision`, `group-name`) and `addedGroups` tell the user what changed.
 - **Update from catalog** is an explicit action: `checkCatalogUpdates(presentation, { catalogs })` lists the embedded records whose catalog record differs, and `applyCatalogUpdate(editor, { refs })` applies only the approved ones as one undoable step. The design panel's `catalog` section runs both and lists the `opf/unresolved-reference` and `opf/undeclared-catalog` findings (`referenceFindings(editor.validation)`).
-- **Editing a catalog's record forks it.** An edit of a layout, theme, colour scheme or font scheme embedded under `catalogs.default` or a named group (from a panel, Properties, Source or any `applyPatch`) moves it into `catalogs.custom` as `<id>-custom` (or the id in `meta.forkIds["<group>:<kind>:<id>"]`), rewrites every reference to it and drops the original, in the same undo step. The change and the session event carry `forked` and a `notice` ("… is now this presentation's own; it no longer receives catalog updates"); approved catalog updates and `moveToCustom` change records in place (`meta.catalogRecordEdit: "in-place"`). `moveToCustom(editor, { group, kind, id }, { id })` is the explicit form, offered for `opf/catalog-record-not-in-source`.
+- **Editing a catalog's record forks it.** An edit of a layout, theme, colour scheme or font scheme embedded under `catalogs.default` or a named group (from a panel, Properties, Source or any `applyPatch`) moves it into `catalogs.custom` as `<id>-custom` (or the id in `meta.forkIds["<group>:<kind>:<id>"]`), rewrites every reference to it and drops the original, in the same undo step. The change and the session event carry `forked` and a `notice` ("… is now this presentation's own; it no longer receives catalog updates"); approved catalog updates and `moveToCustom` change records in place (`meta.catalogRecordEdit: "in-place"`). `moveToCustom(editor, { group, kind, id }, { id })` is the explicit form, offered for `opf/catalog-record-not-in-source`. Opening a document is not an edit: use `replaceDocument` (next bullet).
+- **Opening a document: `replaceDocument`.** `editor.replaceDocument(input, meta?)` puts exactly `input` (a parsed document, JSON text or bytes) in the session as ONE undoable change: Undo restores the previous document, Redo the new one, and nothing under `catalogs.default` or a named group is forked into `catalogs.custom`, even when the two documents embed the same record ids with different content (two examples published at different times). Use it for a host's example menu, File > Open, "start over" and restoring a stored copy; keep `applyPatch` for edits, because an `applyPatch` that replaces the root IS read as an edit of the records the documents share and forks them. It validates like any edit (`meta.rejectInvalid` or the session option refuses an invalid document and changes nothing), accepts the usual `meta` (`source` defaults to `"replace-document"`; the `patch` event carries `meta.replaceDocument: true`) and returns the change; it always records one undo step, also for an equal document. The editor's own File > Open (the playground's Import dialog, "Open as a presentation"), the gallery handoff and `createPersistence`'s `restore()` use it.
 - **Backgrounds** take the flat image form `{ type: "image", src, alt, fit, focus, opacity, recolor, overlay }` (fits `cover`, `contain`, `stretch`, `tile`) and the image-source shorthand, on the deck and on a slide. **Image blocks** carry their own fit, focus, treatments and placement (`/image-options`, the panel's `image` section): a full-bleed photo is a background, a picture beside the content is a placed image block. `design.imageFit` is the default fit of image blocks.
 
 Editor 0.15.0 uses core `^0.15.1` and the optional renderer peer `^0.15.0`. Install renderer and PPTX 0.15 together for the coordinated canvas and export workflow. The shared APIs are core's `validate`, `Finding`, `resolveSlideContext` and the catalog helpers above, and the renderer's `loadFonts()` handle passed as `fonts` to the canvas, export, composition and pagination. Historical version changes are recorded in `CHANGELOG.md`.
@@ -109,8 +110,9 @@ const pane = createSourcePane(container, {
 pane.setFormat('yaml'); pane.focusPath('/slides/1/title'); pane.getText(); pane.destroy();
 ```
 
-Methods: `setFindings(list | null)`, `setFormat(format)`, `focusPath(pointer)` (moves the cursor to the line of a JSON Pointer in any format; exact for JSON, best effort for YAML and Markdown), `getText()`, `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?, name?, meta? })` (below), `setFindings(list | null)`, `setFormat(format)`, `focusPath(pointer)` (moves the cursor to the line of a JSON Pointer in any format; exact for JSON, best effort for YAML and Markdown), `getText()`, `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, 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; `source` is the JSON text it was read from (shown byte for byte; `document` itself when that is text) and `name` the file name. In YAML or Markdown the pane shows the document written in that format. Undo and Redo bring back each document's text exactly in the format shown (the opened JSON 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. 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.
 - **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.
@@ -121,6 +123,67 @@ Methods: `setFindings(list | null)`, `setFormat(format)`, `focusPath(pointer)` (
 
 Icons are inline paths from [Lucide](https://lucide.dev) (ISC license). The harness is `examples/source-pane.html` (built by `npm run build:playground`); `npm run test:source-pane-browser` drives it.
 
+## Layout editor (RR-99)
+
+`createLayoutEditor` from `@openpresentation/opf-editor/layout-editor` is a Figma-style GUI for building one layout record: a `direction` plus an ordered `regions` list of regions and splits (FA-33). It is plain DOM, styled only by `--opf-ui-*` tokens (`src/styles/layout-editor.css`, shipped in `styles.css`), and makes no network request. It is built from four parts that are exported separately, so a host can arrange them differently:
+
+| Part | Export | Prefix |
+| --- | --- | --- |
+| Tool palette | `createLayoutToolPalette` | `opf-lx-palette`, `opf-lx-tool` |
+| Canvas: a 16:9 slide frame with the region tree as labeled boxes | `createLayoutCanvas` | `opf-lx-canvas`, `opf-lx-node` |
+| Layers: the tree of splits and regions, with the findings | `createLayoutTree` | `opf-lx-layers`, `opf-lx-tree` |
+| Inspector: the properties of the selection | `createLayoutInspector` | `opf-lx-inspector` |
+
+```js
+import { createLayoutEditor } from '@openpresentation/opf-editor/layout-editor';
+import { toSvg } from '@openpresentation/opf-render/svg';
+
+const layoutEditor = createLayoutEditor(container, {
+  record,                          // { id, name, direction, regions: [...] }; default: a title and one content region
+  onChange: (record) => save(record),   // after each edit, undo and redo (not after setRecord)
+  density: 'comfortable',          // 'touch' makes the controls 40px
+  toSvg, fonts,                    // optional: Preview draws the sample slide with the host's renderer and fonts handle
+});
+layoutEditor.getRecord();          // a copy of the record
+layoutEditor.setRecord(other);     // load a layout; clears the selection and the history
+layoutEditor.getFindings();        // core's findings: { ruleId, severity, message, path, node, field }
+layoutEditor.saveToDeck(session);  // writes catalogs.custom.layouts through saveCustomLayout, one undoable edit
+layoutEditor.applyToSlide(session, 0); // saves, then makes it slide 0's layout, in one undoable edit
+```
+
+To arrange the parts yourself, create one model and pass it to each part; `saveLayoutToDeck(session, model)` and `applyLayoutToSlide(session, model, slideIndex)` are the deck functions the composed editor calls.
+
+```js
+import { createLayoutModel, createLayoutToolPalette, createLayoutCanvas, createLayoutTree, createLayoutInspector } from '@openpresentation/opf-editor/layout-editor';
+const model = createLayoutModel({ record });
+createLayoutToolPalette(paletteHost, { model, orientation: 'horizontal' });
+createLayoutCanvas(canvasHost, { model });
+createLayoutTree(layersHost, { model });
+createLayoutInspector(inspectorHost, { model });
+```
+
+**Tools** (Figma-style shortcuts; the palette buttons have the same names): Select (V), Split into a row (R), Split into a column (C), Insert region (I), Heading regions (T), Hand (H, or hold Space) and Preview (P).
+- **Select:** click a region to select it; click again inside a selected split to select what is inside. Esc selects the parent. Shift-click adds a sibling. Double-click or F2 renames in place.
+- **Split into a row or column:** click a region. The original keeps its name and rules and the new one is called `region-N`; the tool returns to Select. In a list that already runs along that axis the new region is a sibling that shares the original's size, otherwise a split holds both. With a split tool active, Enter splits the selected region.
+- **Insert region:** slots appear between siblings and at a split's edges; click one (or Tab to it and press Enter).
+- **Heading regions:** a menu to add or remove the `title` and `subtitle` regions. Without a title region the engine adds an implicit title row, drawn as a dashed band.
+- **Hand:** pan a zoomed slide (zoom buttons, Ctrl or Cmd with the wheel).
+- **Preview:** placeholder blocks of each region's accepted kinds. With the host's `toSvg` (and its `fonts` handle) the sample slide is drawn by the renderer behind the region outlines; without them a wireframe is drawn. A layout with an error finding shows the wireframe.
+
+**Direct manipulation on the canvas:**
+- **Resize:** drag the divider between siblings. With other siblings the pair keeps its joint size and snaps to whole numbers and halves; alone in its list it snaps to the nearest whole-number ratio. The ratio shows while dragging ("2 : 1"); Shift skips snapping. Double-click a divider to make both sides equal. A divider next to an `auto` size is not a share and is fixed.
+- **Reorder and move:** drag a region (or several selected siblings) before or after a sibling, or into another split, with a drop indicator; a refused drop (too deep, a split into itself) shows the reason. The same drag works in the layers panel.
+- **Delete:** Delete or Backspace. A split left with one child collapses into it, and the child takes the split's size and inherited anchor. The last region of a layout is kept.
+- **Context menu** (right click, the menu key or Shift+F10): wrap in row, wrap in column, unwrap, duplicate, delete, rename.
+
+**Inspector:** with nothing selected, the layout (`id`, `name`, `summary`, `direction`, a default `anchor` that inherits down, `overflowRegion` as a picker over the body regions, and the design hints the record carries, which can be removed). A split has a `direction` toggle, `size` and `anchor`. A region has `name` (unique), `size` (a number, or `auto` only inside a column), `accepts` as chips (none selected means every kind), `role`, `flow`, `max`, `anchor` (shown as "Inherited" with its source while unset), `bleed`, `listColumns` and `empty`. A heading region takes only a size.
+
+**Validation and history:** every edit is checked live by core (`opf/layout-template` and `opf/layout-region`, plus the schema); the finding's region is highlighted on the canvas and in the layers panel, its message is under the field, and the findings are listed under the layers (click one to select its region). Edits that would break the layout (more than three levels, more than twelve entries, a grid over 12 by 12 tracks) are refused with the reason. The editor has its own undo and redo (Cmd or Ctrl+Z, Shift+Z; the buttons in the top bar); one drag is one step and typing a value is one step. `saveToDeck` refuses a layout with an error finding and an id the deck already has, unless `replace: true`.
+
+**Keyboard:** arrows move between siblings, Enter goes into a split and Esc goes up; `[` and `]` move a region earlier or later (at the end of a split it leaves the split); Shift with a bracket moves it into the neighboring split; Cmd or Ctrl+D duplicates; Delete deletes. A divider is `role="separator"` with `aria-valuenow` (the first side's share of the pair, in percent) and `aria-valuetext` ("2 : 1"); Arrow keys resize it by half a share (Shift: one), Enter makes the sides equal. The layers panel is `role="tree"` (Up and Down, Right to open or enter, Left to close or go to the parent, Home, End, F2). Every action is also a button in the inspector. Touch density makes controls 40px and the divider hit area wider; below 760px the palette is a row above the canvas and Layers and Inspector are tabs under it.
+
+The headless operations the editor runs are in `@openpresentation/opf-editor/layout-tree` (`splitRegion`, `wrapNodes`, `unwrapNode`, `moveNodes`, `deleteNodes`, `duplicateNodes`, `resizeSizes`, `layoutBoxes` and more): pure functions that return a new record and the paths to select, or throw a `LayoutOperationError` with the reason, and keep a core-valid record core-valid. `npm run test:layout-editor-browser` drives `examples/layout-editor.html` (built by `npm run build:playground`); the playground's Layouts view mounts the same editor on the presentation's custom layouts. Icons are inline paths from [Lucide](https://lucide.dev) (ISC license).
+
 ## Scope
 
 - Package: `@openpresentation/opf-editor`
@@ -508,9 +571,9 @@ const manager = createSlideManager(document.querySelector("#slide-list"), {
 editor.subscribe(() => manager.render());
 ```
 
-OPF 0.19 layouts have a grid (`areas`) and named content regions. The slide manager's `openLayoutPicker("apply")` groups the 28 built-ins by intent and applies one to the current slide; `openLayoutPicker()` adds a slide. Pass `renderLayoutPreview(presentation, slideIndex, choice)` to render the current slide with each candidate through the shared renderer. The picker shows the record's `preview` when supplied, otherwise a diagram of its areas. It retains content when switching.
+OPF layouts are one ordered list of named content regions, nested with splits for two dimensions (a record has a `direction` and `regions`). The slide manager's `openLayoutPicker("apply")` groups the 28 built-ins by intent and applies one to the current slide; `openLayoutPicker()` adds a slide. Pass `renderLayoutPreview(presentation, slideIndex, choice)` to render the current slide with each candidate through the shared renderer. The picker shows the record's `preview` when supplied, otherwise a diagram of its regions and splits. It retains content when switching.
 
-`@openpresentation/opf-editor/custom-layout-editor` exports `openCustomLayoutEditor(editor)`, the playground's 12 by 12 grid dialog. Draw named rectangular areas, choose the content kinds, role and flow of each body region, and save the record under `catalogs.custom.layouts` in one undoable transaction. The headless `layoutFromGrid`, `prepareCustomLayout`, `saveCustomLayout` and `pinBlockToRegion` operations are in `/layout-templates`. Canvas Arrange mode shows every template region; empty ones say “Drop content here”, and a top-level block can be dragged or chosen by keyboard for a validated region pin. A full or incompatible region refuses the edit instead of silently ignoring the pin. The host registers the 0.19 catalog with the session; the editor ships no catalog data.
+Layouts are built with the layout editor (see [Layout editor](#layout-editor-rr-99)); it replaces the earlier `openCustomLayoutEditor` dialog. The headless `layoutFromRegions`, `prepareCustomLayout`, `saveCustomLayout` (with `{ replace: true }` to edit a layout the deck already has) and `pinBlockToRegion` operations are in `/layout-templates`. Canvas Arrange mode shows every template region; empty ones say “Drop content here”, and a top-level block can be dragged or chosen by keyboard for a validated region pin. A full or incompatible region refuses the edit instead of silently ignoring the pin. The host registers the 0.19 catalog with the session; the editor ships no catalog data.
 
 `@openpresentation/opf-editor/outline` and `/outline-view` edit the deck as an outline: a row per slide title, subtitle, text paragraph and list item, and a read-only row for content that is not text (a chart, a table, an image) or text that carries formatting, so nothing is flattened away. Typing commits as one change when the row loses focus or on Enter. Enter adds a line (after a title: a slide), Alt+Up and Alt+Down move a bullet with the bullets nested under it, or a slide with its text, Alt+Shift+Right demotes and Alt+Shift+Left promotes. Demoting a bullet nests it (`level`); promoting a top-level bullet turns it into a new slide that takes the bullets after it; demoting a plain slide makes it a bullet of the slide before it (refused, with the reason, when that would drop content such as notes, blocks or a design). Backspace on an empty line removes it. Tab keeps moving focus, so the outline is no keyboard trap.
 
@@ -861,7 +924,7 @@ bindPresentShortcut(document, () => presenter.start(current)); // F5
 - **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.
+`createPresentButton(container, { onPresent, disabled, density, variant })` mounts an icon-only button (the Lucide Presentation icon, inlined) named "Present" (`aria-label`), titled "Present (F5)". `variant` is `"quiet"` (the default: a transparent icon in `--opf-ui-muted-fg` that turns `--opf-ui-fg` on `--opf-ui-muted` on hover, like the toolbar's undo and redo, so a lone icon beside a primary Export does not compete with it) or `"primary"` (the filled accent look of 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), setVariant(variant), 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`.
 
@@ -890,7 +953,7 @@ input.onchange = async () => {
 - **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).
+Put the opened document in the session with `editor.replaceDocument(document)` (or `pane.replaceDocument(document, { source })` when a source pane is mounted), not `applyPatch`: opening is one undoable change that forks no catalog record. 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
 

package/dist/galleries.js

@@ -184,9 +184,9 @@ function attachDefinition(presentation, descriptor, gallerySource) {
   groups[group][kind] ??= {};
   let record;
   if (kind === "layouts") {
-    if (!Array.isArray(source.areas)) return;
+    if (!Array.isArray(source.regions)) return;
     record = {name: source.label ?? source.name ?? id};
-    for (const key of ['summary', 'description', 'areas', 'columns', 'rows', 'regions', 'overflowRegion', 'design', 'composition', 'tags', 'preview'])
+    for (const key of ['summary', 'description', 'direction', 'anchor', 'regions', 'overflowRegion', 'design', 'composition', 'tags', 'preview'])
       if (source[key] !== undefined) record[key] = structuredClone(source[key]);
   } else if (kind === "fontSchemes") record = fontSchemeRecord(source, id);
   else record = embeddedRecord(source);

package/dist/index.d.ts

@@ -91,6 +91,14 @@ export interface EditorSession {
   setGroupComposition(path: string, composition: Composition, meta?: Record<string, unknown>): EditorChange;
   setCatalog(path: string | string[], catalogKind: string, id: string, meta?: Record<string, unknown>): EditorChange;
   applyPatch(operations: JsonPatchOperation[], meta?: Record<string, unknown>): EditorChange;
+  /**
+   * Open a different document in the session: the whole document is replaced as one undoable change, and the replacement is never
+   * read as an edit of the catalog records the two documents share, so nothing under `catalogs.default` or a named group is forked
+   * into `catalogs.custom`. `input` is a parsed document, JSON text or bytes. It is validated like any edit (`meta.rejectInvalid` or
+   * the session option refuses an invalid document and changes nothing). It always records its one change, also for an equal document.
+   * `meta.source` defaults to `"replace-document"`; the `patch` event carries `meta.replaceDocument: true`.
+   */
+  replaceDocument(input: unknown, meta?: Record<string, unknown>): EditorChange;
   /** The undo and redo stacks as plain data (oldest entry first), for hosts that persist work. */
   exportHistory(): EditorHistory;
   /** Replace the document and, optionally, the history in one step (one `restore` event). A history that does not replay against the document throws `invalid-history` before anything changes. */

package/dist/index.js

@@ -314,6 +314,23 @@ export function createEditorSession(input, options = {}) {
       return setCatalogId(editor, path, catalogKind, id, meta);
     },
     applyPatch: commitPatch,
+    /**
+     * Open a different document in the session (a host's example menu, File > Open, "start over"): the whole document is replaced as ONE
+     * undoable change (Undo restores the previous document, Redo the new one). Unlike an `applyPatch` that replaces the root, this is
+     * never read as the user editing the catalog records the two documents share: records under `catalogs.default` or a named group
+     * keep the ids and content the new document carries, and nothing is forked into `catalogs.custom`. `input` is a parsed document,
+     * JSON text or bytes. The document is validated like any edit (`meta.rejectInvalid` or the session option refuses an invalid one
+     * and changes nothing). It always records its one change, also when the new document equals the open one (Undo then returns to the
+     * same document, as for any other replace). `meta.source` defaults to `"replace-document"`; the event is a `patch` whose `meta.replaceDocument` is true.
+     */
+    replaceDocument(input, meta = {}) {
+      return commitPatch([{ op: "replace", path: "", value: parseInput(input) }], {
+        ...meta,
+        source: meta.source ?? "replace-document",
+        replaceDocument: true,
+        catalogRecordEdit: "in-place"
+      });
+    },
     /**
      * The undo and redo stacks as plain data (oldest entry first): `{ undo: [{ patches, inversePatches, meta }], redo: [...] }`.
      * Together with `presentation` this is everything `restoreState` needs to bring a session back, for hosts that persist work.