@openpresentation/opf-editor 0.24.0 → 0.24.1

package/README.md

@@ -85,6 +85,40 @@ Run `npm run test:json` and `npm run test:json-browser` for the focused model an
 
 Version 0.7.0 uses core 0.10.0 and renderer 0.8.0. Code source/metadata edits preserve line endings, literal tabs and cancellation/undo through accepted trace targets. Committed preview uses shared quote/code geometry; the active source textarea uses native browser editing. `paginateSlide` records a one-page readability-policy change in undo history, and an unchanged repeat is a no-op. Coordinated examples use PPTX 0.8.0 for exact code source/metadata recovery. Native formatting, font theme and geometry are not restored; quotes still import as editable text blocks with structure and readability-policy loss.
 
+## Source pane (RR-98)
+
+`createSourcePane` from `@openpresentation/opf-editor/source-pane` is the OPF source as JSON, YAML or Markdown, with the file name, the format menu, Format, Copy and Download, line numbers and the findings under the code. It is plain DOM and builds on `mountJsonCodeEditor`, `exact-source` and the field menu of `/json-options`; it adds no second editor and makes no network request.
+
+```js
+import { createSourcePane } from '@openpresentation/opf-editor/source-pane';
+const pane = createSourcePane(container, {
+  editor,                       // the editor session: every edit goes through editor.applyPatch
+  name: 'deck',                 // shown as deck.opf.json; spaces and slashes become "-"
+  onRename: name => save(name),
+  format: 'json',               // 'json' | 'yaml' | 'md'
+  onFormatChange: (format, previous) => remember(format),
+  source: authoredJson,         // optional: the JSON bytes to keep (formatting, escapes, key order)
+  findings: report.findings,    // or getFindings: () => validate(...).findings; default: the session's validation
+  onFindingSelect: (finding, line) => reveal(finding.path),
+  onCopy: file => clipboard.write(file.text),          // default: navigator.clipboard.writeText
+  onDownload: file => saveAs(file.filename, file.text), // default: a Blob link named <name>.opf.<ext>
+  density: 'comfortable',       // 'touch' makes the controls 40px
+  readOnly: false,
+});
+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`.
+
+- **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.
+- **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.
+
+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.
+
 ## Scope
 
 - Package: `@openpresentation/opf-editor`
@@ -478,6 +512,38 @@ OPF 0.19 layouts have a grid (`areas`) and named content regions. The slide mana
 
 `@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.
 
+## Slide navigator and thumbnail strip (RR-98)
+
+Two framework-neutral DOM factories for the slide row under the canvas. Both follow the editor session on their own, take `density: "comfortable" | "touch"` (32px or 40px controls) and style themselves with the `--opf-ui-*` tokens (`src/styles/navigator.css` and `thumbnails.css`, part of `styles.css`; no fallbacks). Icons are the Lucide ChevronLeft and ChevronRight paths (ISC license), inlined; nothing loads from a network.
+
+`@openpresentation/opf-editor/slide-navigator`: previous and next buttons around a mono counter ("01 / 03"; both numbers pad to the width of the slide count, so "001 / 120" from 100 slides). The buttons disable at the ends, and focus moves to the other one when the pressed one disables. With the navigator focused, Left, Right, Up, Down, Home and End move; `bindKeys(target)` adds page-level Left and Right that ignore typing in inputs, selects and editors (CodeMirror, contenteditable), menus, dialogs, modified keys and events another handler already took.
+
+```js
+import { createSlideNavigator } from "@openpresentation/opf-editor/slide-navigator";
+const nav = createSlideNavigator(document.querySelector("#slide-nav"), {
+  editor, slideIndex: current, density: "comfortable",
+  onChange: (index) => { current = index; redraw(); },   // the user moved (also when a shrinking deck clamps the index)
+  labels: { previous: "Previous slide", next: "Next slide" },
+});
+nav.bindKeys(document);   // returns an unbinder; destroy() removes every listener
+nav.setSlide(3);          // show a slide the host chose; no onChange
+nav.refresh();            // the count follows the editor by itself; pass `presentation` (an object or a function) instead of `editor` for a static deck
+```
+
+`@openpresentation/opf-editor/thumbnail-strip`: a `nav` of real slide renders. Each item shows a mono index and the slide title ("Untitled" when it has none); the current one has `aria-current="true"`, an accent ring and is scrolled into view (the strip scrolls itself, never the page). It is horizontal by default; `orientation: "vertical"` stacks it. Arrow keys move focus along the strip (one tab stop), Enter or Space chooses. Thumbnails use the renderer, catalogs and fonts handle the canvas uses (`fonts`, `renderOptions`), wait for the faces the document needs, and are lazy: the items near the viewport draw first through IntersectionObserver (everything draws at once without it, or with `lazy: false`).
+
+```js
+import { createThumbnailStrip } from "@openpresentation/opf-editor/thumbnail-strip";
+const strip = createThumbnailStrip(document.querySelector("#thumb-strip"), {
+  editor, fonts, renderOptions: { catalogs }, slideIndex: current, size: 128,
+  onSelect: (index) => { current = index; redraw(); },
+});
+strip.setSlide(current);               // follow the host
+strip.refresh({ clear: true });        // redraw now; clear drops the cache (after the host loaded fonts)
+```
+
+Thumbnails are cached by `@openpresentation/opf-editor/thumbnail-cache` (`createThumbnailCache({ toSvg, getOptions })`, promoted from the playground example with the same behavior). An entry is keyed by the slide's index, the slide count and the slide's own content, so an edit renders only the slides it changed, in one `toSvg` call that resolves the deck once. Deck metadata, section labels, registered catalogs and render settings are the cache's context: a change to any of them drops every entry, because inherited furniture and design change other slides too. `prepare(deck, indices)` renders only the listed slides, which is how the strip stays lazy. Share one cache between views with the strip's `cache` option.
+
 ## Data grid (RR-24)
 
 `@openpresentation/opf-editor/data-grid` mounts a spreadsheet-like grid for a chart's inline data (the first column is the categories, each further column a series; an empty cell is a gap, never 0) and for tables (rich and styled cells, merged cells drawn with their spans). Cells edit from the keyboard (arrows, Enter, F2, Tab), paste TSV or CSV from Excel and Sheets, copy out as TSV, and rows and columns insert, delete and move, sort (stable and typed) and, for charts, swap. Numbers are read in one stated number format, never guessed; text that is not a number is refused inline with the reason. Every edit is one undoable patch, so the preview redraws from the session events.
@@ -610,6 +676,47 @@ Select a picture on the canvas and use **Crop picture** (or `canvas.cropImage(pa
 
 At 900px and narrower the playground is one screen: the slide strip on top, the slide in the middle, and a bottom bar (Edit, Design, Find, Undo, Redo) whose Edit and Design open the inspector as a **bottom sheet** that leaves the slide in view above it; the header buttons sit behind More; nothing scrolls sideways down to 320px. On a touch screen the canvas grows each text block's selection target to about 44px (up to 24 slide units each way), a tap on text enters editing at that point, `touch-action: manipulation` removes the double-tap delay, and the field being typed in is scrolled above the on-screen keyboard (visual viewport). The inline field mirrors the slide text, which is smaller than 16px on a phone; iOS would zoom into it on focus, so the playground sets `maximum-scale=1` on the viewport only while a slide text field has the focus and restores it after (embedding hosts should do the same, or keep their own fields at 16px). `test/mobile-browser.mjs` drives six emulated devices (iPhone SE, iPhone 14 Pro, Pixel 7, a 320px Android, an iPad and an Android tablet: Chromium with each device's viewport, scale factor, touch and user agent) through the layout, the sheet, tap-to-type, find and replace by touch and a crop by touch; it does not replace a check on a real iOS Safari.
 
+## Styling and theming (RR-98)
+
+The editor panels ship one stylesheet. Import it once, next to your own CSS:
+
+```js
+import "@openpresentation/opf-editor/styles.css";
+```
+
+`npm run build` writes `dist/styles.css`: the token layer (`src/styles/tokens.css`) first, then every other `src/styles/*.css` in alphabetical order. It is plain CSS with no preprocessor, no `@import` and no `url()`: nothing is fetched. The package bundles no fonts either; load Inter and Geist Mono yourself (or leave the fallbacks: `system-ui` and `ui-monospace`). The panels that existed before it (design controls, review, slide manager, find, fill template, numbering, chart options, data grid, crop, the custom layout editor, the JSON editor and the restore banner) are styled with the tokens and nothing else. The find, review, crop and data-grid components still inject a small fallback stylesheet of their own, so they look as before when you do not import `styles.css`; with it, its rules win whichever `<style>` comes last.
+
+**Tokens.** Every rule reads only `--opf-ui-*` custom properties, defined on `:root` and on `.opf-ui`, light by default. Override any of them on `:root`, on a wrapper with the class `opf-ui`, or on one component's container:
+
+```css
+.my-editor.opf-ui {
+  --opf-ui-accent: hsl(262 60% 38%);
+  --opf-ui-accent-strong: hsl(262 60% 38%);
+  --opf-ui-ring: hsl(262 60% 38%);
+  --opf-ui-radius: 4px;
+}
+```
+
+| Group | Tokens |
+|---|---|
+| Surfaces | `--opf-ui-bg`, `--opf-ui-surface`, `--opf-ui-muted`, `--opf-ui-muted-2` |
+| Text | `--opf-ui-fg`, `--opf-ui-muted-fg` |
+| Accent | `--opf-ui-accent`, `--opf-ui-accent-fg`, `--opf-ui-accent-strong`, `--opf-ui-ring` |
+| Lines | `--opf-ui-border`, `--opf-ui-border-strong` |
+| Status | `--opf-ui-danger`, `--opf-ui-warn`, `--opf-ui-success` |
+| Code | `--opf-ui-code-bg`, `--opf-ui-code-border` |
+| Type | `--opf-ui-font` (`Inter, system-ui, sans-serif`), `--opf-ui-mono` (`"Geist Mono", ui-monospace, Menlo, monospace`) |
+| Shape | `--opf-ui-radius-sm` 4px, `--opf-ui-radius` 6px, `--opf-ui-radius-md` 8px, `--opf-ui-radius-lg` 12px |
+| Size, depth, motion | `--opf-ui-control-h` 32px, `--opf-ui-shadow-pop` (menus, popovers and dialogs only), `--opf-ui-ease` `120ms ease` (color and border only) |
+
+Put the class `opf-ui` on an element that wraps a mounted component to get the base rules: the font, the text color, `box-sizing: border-box`, a 2px `--opf-ui-ring` outline with a 2px offset on `:focus-visible`, and no transitions under `prefers-reduced-motion: reduce`.
+
+**Dark mode.** The dark values apply under `.dark .opf-ui`, `.opf-ui.dark`, `[data-theme="dark"]` (on the root or any ancestor) and `:root.dark`. The host decides when: toggle `class="dark"` or `data-theme="dark"` on `<html>`, or on the wrapper. The stylesheet does not read `prefers-color-scheme`, so a host that wants to follow the system setting sets the attribute from `matchMedia("(prefers-color-scheme: dark)")`. Dark also sets `color-scheme: dark`, so native controls follow.
+
+**Touch.** `data-density="touch"` on an `.opf-ui` element raises `--opf-ui-control-h` from 32px to 40px for everything inside it (the mobile design). The new components take the same value as a `density: "comfortable" | "touch"` option.
+
+The example page `examples/playground.html` loads this stylesheet and keeps only its own page layout in `examples/playground.css`. The JSON editor (CodeMirror) ships no CSS of its own; give its container the class `opf-json` or `opf-code`, or put it inside an `.opf-ui`, to style it. The restore banner is a host element: give it the class `restore-banner`.
+
 ## Review panel (RR-29)
 
 `@openpresentation/opf-editor/review-panel` mounts the findings of core's `validate(presentation)` next to the document, grouped by category (format, references, policy, accessibility, layout, content): contrast, text that does not fit, missing alt text, reading order, fonts, links and more (the same rules as `opf validate`; see the [validate guide](https://github.com/OpenPresentation/opf/blob/main/docs/validate.md)). A finding is core's `Finding` (rule id, severity, category, JSON Pointer path, message, `fixes`), so a hosted reviewer that returns a `FindingReport`, such as pptx.dev's review, lists its findings in the same panel.
@@ -636,7 +743,7 @@ Findings show a severity word, the slide, the rule id and, for a hosted reviewer
 
 ## PDF, PNG and SVG downloads (RR-23)
 
-`convert(deck, { format })` from `@openpresentation/opf-editor/export` turns the deck into files in the page, next to the PowerPoint export; the playground's "PDF · PNG · SVG" button is a thin dialog over it. It has the name and the result of core's in-memory `convert` (OPF 0.18, RR-73): `{ files, findings }`, core's `ConvertResult`.
+`convert(deck, { format })` from `@openpresentation/opf-editor/export` turns the deck into files in the page, next to the PowerPoint export; the [Export menu](#export-menu-and-agent-handoff-rr-98) is a thin host over it. It has the name and the result of core's in-memory `convert` (OPF 0.18, RR-73): `{ files, findings }`, core's `ConvertResult`.
 
 ```js
 import { convert } from "@openpresentation/opf-editor/export";
@@ -679,6 +786,49 @@ Catalog controls initialize an absent deck or slide `design` for known theme, co
 
 Optional downloads can be deferred until requested: dynamically import `@openpresentation/opf-editor/export` inside the download handler. For a PowerPoint download, dynamically import `@openpresentation/opf-pptx` inside that handler too; the `/export` helper covers PDF, PNG and SVG. This defers conversion code, while canvas rendering and font measurement still have their own startup costs.
 
+## Export menu and agent handoff (RR-98)
+
+Three framework-neutral DOM factories, plain DOM like the other modules (no framework, no network, no fonts or CSS fetched at runtime). Their CSS is `src/styles/export-menu.css` and `src/styles/handoff.css`; it uses only the `--opf-ui-*` tokens (each with its light value as a fallback) and the class prefixes `opf-export-*` and `opf-handoff-*`.
+
+```js
+import { createExportMenu } from "@openpresentation/opf-editor/export-menu";
+
+const menu = createExportMenu(document.querySelector("#export"), {
+  getDeck: () => editor.presentation,       // required: called on every export; the menu exports a structuredClone
+  beforeExport: () => !canvas || canvas.commit(), // optional: return false to stop (commit an open canvas edit first)
+  fonts,                                     // the one fonts handle the preview uses
+  catalogs: () => editor.catalogs,           // an array, or a function that returns one
+  renderOptions,
+  exportPptx: async (deck, { signal, onProgress }) => toPptx(deck, { ... }), // PowerPoint, injected (see below)
+  onDownload: ({ blob, fileName, format }) => save(blob, fileName),          // default: a Blob link
+  onAgentHandoff: ({ document, target }) => ...,                              // default: the dialog below
+  items: { slides: ["pdf", "png", "svg", "pptx"], source: ["json", "yaml", "markdown"], agent: true }, // hide groups or formats
+  mode: "menu",                              // "sheet": the mobile bottom sheet (scrim, drag handle, Close)
+  density: "comfortable",                    // "touch": 40px controls (sheet rows 44px)
+  disabled: false,                           // true or a reason string: disables the slide exports
+});
+menu.setDisabled("Showing the last valid slides. Fix the JSON to resume editing and downloads."); // or menu.setDisabled(true)
+menu.setMode(matchMedia("(max-width: 900px)").matches ? "sheet" : "menu");
+```
+
+- **The menu.** A button (Download icon, "Export", ChevronDown) and a `role="menu"` in three groups: **Slides** (PowerPoint (.pptx), PDF, SVG slides, PNG images, each with a hint), **OPF source** (JSON, YAML, Markdown) and **For an agent** (Agent handoff). Items are `role="menuitem"` buttons; ArrowUp, ArrowDown, Home and End move between them, Escape closes and returns focus to the button, Tab closes and moves on. In `mode: "sheet"` the same menu is a `role="dialog"` bottom sheet that traps Tab, closes with Escape, Close or a tap on the scrim, and returns focus.
+- **Slides.** PDF, PNG and SVG run this package's `convert` (above) with your `fonts`, `catalogs` and `renderOptions`; PNG and SVG arrive as one ZIP for several slides. `convertOptions` passes more `convert` options (`scale`, `includeHidden`, `converters`, ...). The menu imports the renderer through `/export`, so a host that bundles it needs `@openpresentation/opf-render` (an optional peer). **PowerPoint lives in `@openpresentation/opf-pptx`, which the editor does not import:** you inject `exportPptx(deck, { signal, onProgress })` and return the bytes (or `{ bytes, fileName?, warnings? }`). Load the fonts the deck needs first, as `examples/export-controls.js` does with `fontGate`. The PPTX item is offered only when `exportPptx` is given.
+- **OPF source.** JSON is the document as "Save OPF" writes it (every catalog record the deck uses is embedded). YAML and Markdown are core's `toYaml` and `toMarkdown` (`@openpresentation/opf/yaml` and `/markdown`, loaded on first use); parts the Markdown dialect has no syntax for are written as YAML fences and reported as notes. File names are `name.opf.json`, `name.opf.yaml` and `name.opf.md`.
+- **Progress, cancel, errors.** While an export runs a status panel under the button shows `onProgress` (a progress bar and the message) and a Cancel button that aborts an `AbortController` (`menu.cancel()` does the same, and `destroy()` too). Success, failure and cancellation each give a status line (`name.pdf · 2 slides · 38 KB · 1 note to review`), announced through an `aria-live="polite"` region; the converter's notes (and your PowerPoint `warnings`, core's YAML and Markdown notes, catalog references that did not resolve) are listed until dismissed. A result without notes hides itself after four seconds. `onStatus({ state, message, notes })` mirrors every change for a host footer, and `onExport({ blob, fileName, format, notes })` fires after a file was handed on.
+- **Disabled.** `setDisabled(reason)` marks the slide exports `aria-disabled` with the reason as their `title` (`true` gives "Showing the last valid slides. Fix the JSON to resume editing and downloads."); source exports and the handoff stay available. While an export runs the others are disabled too.
+
+```js
+import { buildAgentHandoff } from "@openpresentation/opf-editor/agent-handoff";
+import { createAgentHandoffDialog } from "@openpresentation/opf-editor/agent-handoff-dialog";
+
+const { markdown, lines } = buildAgentHandoff(deck, { target: "pptx", fileName: "deck.opf.json" }); // "pptx" | "pdf" | "svg"
+const dialog = createAgentHandoffDialog(document.body, { document: deck, target: "pdf", onClose: () => {} });
+```
+
+`buildAgentHandoff(document, { target, fileName, specUrl, agentGuideUrl })` is a pure function: a Markdown prompt for a coding agent (`# Task`, `## Setup`, `## Steps`, the Spec and Agent guide links, and `## deck.opf.json` with the exact `JSON.stringify(document, null, 2)` in a fenced block that no string in the deck can close). The agent installs `@openpresentation/cli` with `opf-render` (and `opf-pptx` for PowerPoint), validates the deck with `npx opf validate deck.opf.json` (exit 1 and the JSON path of each error for an invalid deck) and renders with `npx opf convert deck.opf.json deck.pptx` (or `deck.pdf`, `deck.svg`, one file per slide); these are the published `opf` command, run against the npm releases in a clean folder when written. The renderer's `@expo-google-fonts/*` packages are optional peers: the first conversion exits 2 with `peer-not-installed` and the exact `npm install` command, which the prompt tells the agent to run. The deck's text is data in the prompt, never instructions. `createAgentHandoffDialog(container, { document, target, onClose })` is the modal: a target switch (a `radiogroup`), the prompt read-only in mono with its line count, **Copy prompt** (Check and "Copied" for 1.2 seconds; when the browser refuses it selects the text and says so), **Download .md** and **Close**. It has `role="dialog"`, `aria-modal`, a focus trap and Escape, and returns focus to the opener. Nothing is sent anywhere.
+
+Icons are inlined path data from [Lucide](https://lucide.dev) (ISC license), never loaded from a CDN.
+
 ## 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.
@@ -718,7 +868,7 @@ Svelte bindings are isolated under `@openpresentation/opf-editor/svelte` as acti
 Public npm package publication is handled by `.github/workflows/release.yml` through npm Trusted Publishing (GitHub Actions OIDC) with npm provenance; no npm token is stored. The owner authorized agents to prepare and publish npm releases whenever a release is required (2026-09-29). This authorization does not waive any gate.
 
 1. Open a release-prep PR containing only the version bump, `CHANGELOG.md` (assembled from `changes/` with `node scripts/changelog-fragments.mjs assemble --version X.Y.Z`), dependency ranges, lockfile and current-instruction docs. Publish in dependency order (core, then renderer, then PPTX, then editor): refresh this repo's lockfile only after the required `@openpresentation/opf`, `@openpresentation/opf-render` and `@openpresentation/opf-pptx` versions are on the registry (`npm install --package-lock-only`), then run `npm run test:packed` against them.
-2. Merge after CI is green, then publish by pushing the git tag `opf-editor-v<version>` (or `@openpresentation/opf-editor@v<version>`) at the merge commit. The workflow verifies that the tag matches `package.json` and reruns audit, typecheck, validate, tests, playground, code/JSON browser and packed checks before `npm publish --access public --provenance`. A manual `workflow_dispatch` runs the same job without the tag check and is a fallback only.
+2. Merge after CI is green, then publish by pushing the git tag `opf-editor-v<version>` (or `@openpresentation/opf-editor@v<version>`) at the merge commit. The workflow verifies that the tag matches `package.json`, that the push-to-`main` run of `ci.yml` on exactly the tagged commit succeeded (`scripts/ci-evidence.mjs`; it fails closed and re-runs no test, RR-100), and the artifact itself (audit, the packed install, `npm pack --dry-run`) before `npm publish --access public --provenance`. A tag pushed while CI still runs fails at the evidence step; re-run the failed job once CI is green. A manual `workflow_dispatch` runs the same job without the tag check and is a fallback only.
 3. Verify with `npm view @openpresentation/opf-editor@<version> version gitHead dist.attestations` and, from the core repo, `node scripts/test-editor-publication.mjs <version> <release-commit> <this-checkout>`. Never republish an existing version.
 
 ## Shared dynamic composition

package/dist/agent-handoff-dialog.d.ts

@@ -0,0 +1,45 @@
+import type { AgentHandoff, AgentHandoffTarget } from "./agent-handoff.js";
+
+export interface AgentHandoffDialogOptions {
+  /** The OPF document the prompt embeds, unchanged, as JSON. */
+  document: unknown;
+  /** The selected target. Default `"pptx"`. */
+  target?: AgentHandoffTarget;
+  /** The name the agent saves the deck as (default `deck.opf.json`). */
+  fileName?: string;
+  specUrl?: string;
+  agentGuideUrl?: string;
+  /** `"touch"` makes the controls 40px. Default `"comfortable"` (32px). */
+  density?: "comfortable" | "touch";
+  /** Called once after the dialog closes (Close, X, Escape or a click on the scrim) and focus has been returned. Not called by `destroy()`. */
+  onClose?: () => void;
+  /** The author switched the target. */
+  onTargetChange?: (target: AgentHandoffTarget) => void;
+  /** "Download .md". Default: save `deck-handoff.md` through a Blob link. */
+  onDownload?: (download: { blob: Blob; fileName: string; format: "handoff" }) => void;
+  /** The element that gets focus back on close. Default: the element focused when the dialog opened. */
+  returnFocus?: HTMLElement | null;
+}
+
+export interface AgentHandoffDialog {
+  /** The overlay (scrim and dialog), already mounted in the container. */
+  element: HTMLElement;
+  /** The prompt now shown: `{ markdown, lines }`. */
+  getPrompt(): AgentHandoff;
+  setTarget(target: AgentHandoffTarget): void;
+  /** Replace the deck the prompt embeds. */
+  setDocument(document: unknown): void;
+  /** Copy the prompt; resolves false when the browser refused (the text is then selected). */
+  copy(): Promise<boolean>;
+  /** Close the dialog, return focus and call `onClose`. */
+  close(): void;
+  /** Remove the dialog without returning focus or calling `onClose`. */
+  destroy(): void;
+}
+
+/**
+ * A modal dialog (`role="dialog"`, `aria-modal`) over the prompt `buildAgentHandoff` writes: a target switch, the read-only prompt in mono
+ * with its line count, Copy prompt (shows "Copied" for 1.2 s) and Close. Focus is trapped inside, Escape closes, and focus returns to the
+ * opener. CSS: `src/styles/handoff.css`, classes `opf-handoff-*`.
+ */
+export declare function createAgentHandoffDialog(container: HTMLElement, options: AgentHandoffDialogOptions): AgentHandoffDialog;

package/dist/agent-handoff-dialog.js

@@ -0,0 +1,182 @@
+// RR-98: the agent handoff dialog. A modal that shows the prompt `buildAgentHandoff` writes for a coding agent, with a target switch
+// (PowerPoint, PDF or SVG), the prompt read-only in mono with its line count, Copy prompt ("Copied" for 1.2 seconds) and Close.
+// Plain DOM, no framework, no network: the prompt never leaves the page until the author pastes it. Styles: src/styles/handoff.css.
+import { HANDOFF_TARGETS, buildAgentHandoff } from "./agent-handoff.js";
+import { el, icon, saveBlob } from "./export-dom.js";
+
+const COPIED_MS = 1200;
+const FOCUSABLE = 'button:not([disabled]), textarea, [href], input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
+const FILE_NAME = "deck-handoff.md";
+let counter = 0;
+
+/**
+ * Open the dialog in `container` (a host element, usually `document.body`). Options: `document` (the OPF deck the prompt embeds), `target`
+ * (`"pptx"` default, `"pdf"` or `"svg"`), `fileName`, `specUrl`, `agentGuideUrl` (all for `buildAgentHandoff`), `density`
+ * (`"comfortable"` or `"touch"`), `onClose`, `onDownload({ blob, fileName, format: "handoff" })` for "Download .md" (default: a Blob link),
+ * `onTargetChange(target)` and `returnFocus` (the element that gets focus back on close; default: the one focused when it opened).
+ * Returns `{ element, getPrompt(), setTarget(), setDocument(), copy(), close(), destroy() }`.
+ */
+export function createAgentHandoffDialog(container, options = {}) {
+  const doc = container.ownerDocument ?? document;
+  const id = `opf-handoff-${++counter}`;
+  const opener = options.returnFocus ?? doc.activeElement;
+  let target = options.target in HANDOFF_TARGETS ? options.target : "pptx";
+  let deck = options.document;
+  let copiedTimer, liveTimer, destroyed = false;
+  let handoff;
+
+  const closeButton = el(doc, "button", { type: "button", class: "opf-handoff-x", "aria-label": "Close" }, icon(doc, "X", 16));
+  const radios = Object.entries(HANDOFF_TARGETS).map(([key, spec]) => el(doc, "button", { type: "button", role: "radio", class: "opf-handoff-target", "data-target": key, text: spec.label }));
+  const group = el(doc, "div", { class: "opf-handoff-segments", role: "radiogroup", "aria-labelledby": `${id}-render` }, ...radios);
+  const count = el(doc, "span", { class: "opf-handoff-count" });
+  const prompt = el(doc, "textarea", { class: "opf-handoff-prompt", readonly: true, spellcheck: "false", wrap: "soft", "aria-label": "Prompt for a coding agent", "aria-describedby": `${id}-count` });
+  count.id = `${id}-count`;
+  const live = el(doc, "div", { class: "opf-handoff-live", role: "status", "aria-live": "polite", "aria-atomic": "true" });
+  const copyLabel = el(doc, "span", { text: "Copy prompt" });
+  const copyButton = el(doc, "button", { type: "button", class: "opf-handoff-button opf-handoff-copy", "data-primary": true }, icon(doc, "Copy"), copyLabel);
+  const downloadButton = el(doc, "button", { type: "button", class: "opf-handoff-button opf-handoff-download" }, icon(doc, "Download"), "Download .md");
+  const closeText = el(doc, "button", { type: "button", class: "opf-handoff-button opf-handoff-close", text: "Close" });
+
+  const dialog = el(doc, "div", { class: "opf-handoff-dialog", role: "dialog", "aria-modal": "true", "aria-labelledby": `${id}-title`, "aria-describedby": `${id}-description`, tabindex: "-1" },
+    el(doc, "div", { class: "opf-handoff-head" },
+      el(doc, "div", { class: "opf-handoff-intro" },
+        el(doc, "h2", { class: "opf-handoff-title", id: `${id}-title`, text: "Agent handoff" }),
+        el(doc, "p", { class: "opf-handoff-description", id: `${id}-description` }, "Paste this into a coding agent. It carries the deck JSON and tells the agent to install ", el(doc, "code", { text: "@openpresentation/opf" }), ", validate the deck and render it."),
+      ),
+      closeButton,
+    ),
+    el(doc, "div", { class: "opf-handoff-targets" }, el(doc, "span", { class: "opf-handoff-render", id: `${id}-render`, text: "Render to" }), group),
+    el(doc, "div", { class: "opf-handoff-box" }, el(doc, "div", { class: "opf-handoff-box-head" }, el(doc, "span", { class: "opf-handoff-file", text: FILE_NAME }), count), prompt),
+    el(doc, "p", { class: "opf-handoff-note", text: "Nothing is sent anywhere. The prompt stays in this browser until you paste it." }),
+    el(doc, "div", { class: "opf-handoff-foot" }, closeText, downloadButton, copyButton),
+    live,
+  );
+  const element = el(doc, "div", { class: "opf-handoff opf-ui", "data-density": options.density === "touch" ? "touch" : "comfortable" }, dialog);
+
+  function say(message) {
+    globalThis.clearTimeout(liveTimer);
+    live.textContent = "";
+    liveTimer = globalThis.setTimeout(() => { live.textContent = message; }, 20);
+  }
+  function build() {
+    handoff = buildAgentHandoff(deck, { target, fileName: options.fileName, specUrl: options.specUrl, agentGuideUrl: options.agentGuideUrl });
+    prompt.value = handoff.markdown;
+    count.textContent = `${handoff.lines} lines`;
+    for (const radio of radios) {
+      const on = radio.dataset.target === target;
+      radio.setAttribute("aria-checked", String(on));
+      radio.tabIndex = on ? 0 : -1;
+    }
+  }
+  function resetCopy() {
+    globalThis.clearTimeout(copiedTimer);
+    copiedTimer = undefined;
+    copyLabel.textContent = "Copy prompt";
+    copyButton.querySelector("svg")?.replaceWith(icon(doc, "Copy"));
+    delete copyButton.dataset.copied;
+  }
+  function setTarget(next, { focus = false } = {}) {
+    if (!(next in HANDOFF_TARGETS) || next === target) return;
+    target = next;
+    build();
+    resetCopy();
+    options.onTargetChange?.(target);
+    if (focus) radios.find((radio) => radio.dataset.target === target)?.focus();
+  }
+  async function copy() {
+    const text = handoff.markdown;
+    let ok = false;
+    try { await globalThis.navigator?.clipboard?.writeText(text); ok = true; }
+    catch {
+      // No Clipboard API (an insecure page, or permission refused): select the text and ask the browser to copy the selection.
+      prompt.focus();
+      prompt.select();
+      try { ok = Boolean(doc.execCommand?.("copy")); } catch { ok = false; }
+    }
+    if (destroyed) return ok;
+    if (!ok) { prompt.focus(); prompt.select(); say("Could not copy. The prompt is selected: press Ctrl+C or Command+C."); return false; }
+    globalThis.clearTimeout(copiedTimer);
+    copyLabel.textContent = "Copied";
+    copyButton.querySelector("svg")?.replaceWith(icon(doc, "Check"));
+    copyButton.dataset.copied = "true";
+    say("Prompt copied to the clipboard.");
+    copiedTimer = globalThis.setTimeout(resetCopy, COPIED_MS);
+    return true;
+  }
+  function download() {
+    const blob = new Blob([handoff.markdown], { type: "text/markdown" });
+    if (options.onDownload) options.onDownload({ blob, fileName: FILE_NAME, format: "handoff" });
+    else saveBlob(doc, blob, FILE_NAME);
+  }
+
+  function focusables() { return [...dialog.querySelectorAll(FOCUSABLE)].filter((node) => !node.hidden && node.getClientRects().length); }
+  function onKeydown(event) {
+    if (event.key === "Escape" && !event.defaultPrevented) { event.preventDefault(); event.stopPropagation(); close(); return; }
+    if (event.key !== "Tab") return;
+    const nodes = focusables();
+    if (!nodes.length) { event.preventDefault(); dialog.focus(); return; }
+    const first = nodes[0], last = nodes[nodes.length - 1], active = doc.activeElement;
+    if (event.shiftKey && (active === first || active === dialog)) { event.preventDefault(); last.focus(); }
+    else if (!event.shiftKey && active === last) { event.preventDefault(); first.focus(); }
+    else if (!dialog.contains(active)) { event.preventDefault(); first.focus(); }
+  }
+  // Focus that escapes (a click on the page behind the scrim, a script) comes straight back.
+  function onFocusin(event) { if (!destroyed && !dialog.contains(event.target)) (focusables()[0] ?? dialog).focus(); }
+  function onKeydownRadio(event) {
+    const keys = { ArrowRight: 1, ArrowDown: 1, ArrowLeft: -1, ArrowUp: -1 };
+    const at = radios.findIndex((radio) => radio.dataset.target === target);
+    let next;
+    if (event.key in keys) next = (at + keys[event.key] + radios.length) % radios.length;
+    else if (event.key === "Home") next = 0;
+    else if (event.key === "End") next = radios.length - 1;
+    else return;
+    event.preventDefault();
+    setTarget(radios[next].dataset.target, { focus: true });
+  }
+
+  function destroy() {
+    if (destroyed) return;
+    destroyed = true;
+    globalThis.clearTimeout(copiedTimer);
+    globalThis.clearTimeout(liveTimer);
+    doc.removeEventListener("keydown", onKeydown, true);
+    doc.removeEventListener("focusin", onFocusin, true);
+    element.remove();
+  }
+  function close() {
+    if (destroyed) return;
+    destroy();
+    if (opener?.isConnected && typeof opener.focus === "function") opener.focus();
+    options.onClose?.();
+  }
+
+  build();
+  for (const radio of radios) {
+    radio.addEventListener("click", () => setTarget(radio.dataset.target));
+    radio.addEventListener("keydown", onKeydownRadio);
+  }
+  closeButton.addEventListener("click", close);
+  closeText.addEventListener("click", close);
+  copyButton.addEventListener("click", copy);
+  downloadButton.addEventListener("click", download);
+  // A press and release on the scrim closes; a drag that starts in the dialog (selecting prompt text) and ends on the scrim does not.
+  let pressedOnScrim = false;
+  element.addEventListener("pointerdown", (event) => { pressedOnScrim = event.target === element; });
+  element.addEventListener("click", (event) => { if (pressedOnScrim && event.target === element) close(); pressedOnScrim = false; });
+  doc.addEventListener("keydown", onKeydown, true);
+  doc.addEventListener("focusin", onFocusin, true);
+  container.append(element);
+  radios.find((radio) => radio.dataset.target === target)?.focus();
+
+  return {
+    element,
+    /** The prompt as shown. */
+    getPrompt: () => ({ ...handoff }),
+    setTarget: (next) => setTarget(next),
+    /** Replace the deck the prompt embeds. */
+    setDocument(next) { deck = next; build(); resetCopy(); },
+    copy,
+    close,
+    destroy,
+  };
+}

package/dist/agent-handoff.d.ts

@@ -0,0 +1,33 @@
+/** The render targets of the handoff prompt. */
+export type AgentHandoffTarget = "pptx" | "pdf" | "svg";
+
+export interface AgentHandoffOptions {
+  /** What the agent renders to. Default `"pptx"`. */
+  target?: AgentHandoffTarget;
+  /** The name the agent saves the deck as, and the base name of the output file. Default `"deck.opf.json"`. */
+  fileName?: string;
+  /** The Spec link. Default `"https://openpresentation.org/spec"`. */
+  specUrl?: string;
+  /** The Agent guide link. Default `"https://openpresentation.org/agents"`. */
+  agentGuideUrl?: string;
+}
+
+export interface AgentHandoff {
+  /** The prompt: `# Task`, `## Setup`, `## Steps`, the Spec and Agent guide links, then the deck in a fenced JSON block. */
+  markdown: string;
+  /** The number of lines in `markdown`. */
+  lines: number;
+}
+
+export declare const DEFAULT_SPEC_URL: "https://openpresentation.org/spec";
+export declare const DEFAULT_AGENT_GUIDE_URL: "https://openpresentation.org/agents";
+export declare const DEFAULT_HANDOFF_FILE_NAME: "deck.opf.json";
+/** Each target's label (as the prompt and the dialog say it), output extension and the npm packages the agent installs. */
+export declare const HANDOFF_TARGETS: Readonly<Record<AgentHandoffTarget, { readonly label: string; readonly extension: string; readonly packages: readonly string[] }>>;
+
+/**
+ * The handoff prompt for a coding agent: install the published CLI (`@openpresentation/cli`, with the renderer and, for PowerPoint, the PPTX converter), save the deck, validate it with `npx opf validate`, render it with `npx opf convert`, report the
+ * output path and warnings. Pure: no DOM or network. The deck is embedded as `JSON.stringify(document, null, 2)`, unchanged, in a fence
+ * longer than any run of backticks in it. Throws `RangeError` for an unknown target and `TypeError` for a document that is not JSON.
+ */
+export declare function buildAgentHandoff(document: unknown, options?: AgentHandoffOptions): AgentHandoff;

package/dist/agent-handoff.js

@@ -0,0 +1,95 @@
+// RR-98: the agent handoff prompt. A pure function: an OPF document in, a Markdown prompt out, for a coding agent that installs the
+// published CLI, validates the deck and renders it to PowerPoint, PDF or SVG. No DOM, no network, no clock. The commands it tells the agent
+// to run are the published `opf` command (@openpresentation/cli 0.24, with the renderer 0.24.1 and PPTX 0.24.0 peers), run in a clean
+// folder: `opf validate deck.opf.json` (exit 1 for an invalid deck, with the JSON path of each finding) and `opf convert deck.opf.json
+// deck.pptx`. The renderer's `@expo-google-fonts/*` packages are optional peers that npm does not install, and the first conversion exits 2
+// with `peer-not-installed` naming the exact (pinned) `npm install` command; the prompt says to run it rather than pin versions here that
+// would go stale.
+
+/** The default Spec link in the prompt. */
+export const DEFAULT_SPEC_URL = "https://openpresentation.org/spec";
+/** The default Agent guide link in the prompt. */
+export const DEFAULT_AGENT_GUIDE_URL = "https://openpresentation.org/agents";
+/** The file name the prompt tells the agent to save the deck as. */
+export const DEFAULT_HANDOFF_FILE_NAME = "deck.opf.json";
+
+/**
+ * The render targets. `packages` are the npm packages the agent installs: PDF and SVG need the renderer, PowerPoint also needs the
+ * PPTX converter. `extension` is the output file's extension.
+ */
+export const HANDOFF_TARGETS = Object.freeze({
+  pptx: Object.freeze({ label: "PowerPoint (.pptx)", extension: "pptx", packages: Object.freeze(["@openpresentation/cli", "@openpresentation/opf-render", "@openpresentation/opf-pptx"]) }),
+  pdf: Object.freeze({ label: "PDF", extension: "pdf", packages: Object.freeze(["@openpresentation/cli", "@openpresentation/opf-render"]) }),
+  svg: Object.freeze({ label: "SVG slides", extension: "svg", packages: Object.freeze(["@openpresentation/cli", "@openpresentation/opf-render"]) }),
+});
+
+const VALIDATE = (file) => `npx opf validate ${file}`;
+const CONVERT = (file, output) => `npx opf convert ${file} ${output}`;
+
+/** The output file for a deck file: `deck.opf.json` gives `deck.pptx`; any other extension is replaced. */
+function outputFor(fileName, extension) {
+  const base = fileName.replace(/\.opf\.(json|ya?ml|md)$/i, "").replace(/\.[^./\\]+$/, "");
+  return `${base || "deck"}.${extension}`;
+}
+
+/** A fence longer than any run of backticks in the text, so the deck's own strings can never close it. */
+function fenceFor(text) {
+  const longest = Math.max(0, ...(text.match(/`+/g) ?? []).map((run) => run.length));
+  return "`".repeat(Math.max(3, longest + 1));
+}
+
+/**
+ * The handoff prompt for a coding agent.
+ *
+ * @param document The OPF document. It goes into the prompt as `JSON.stringify(document, null, 2)`, unchanged.
+ * @param options `target` `"pptx"` (default), `"pdf"` or `"svg"`; `fileName` the name the agent saves the deck as (default
+ *   `deck.opf.json`; the output file takes its base name); `specUrl` and `agentGuideUrl` (defaults: openpresentation.org).
+ * @returns `{ markdown, lines }`: the prompt, and its line count.
+ */
+export function buildAgentHandoff(document, options = {}) {
+  const { target = "pptx", fileName = DEFAULT_HANDOFF_FILE_NAME, specUrl = DEFAULT_SPEC_URL, agentGuideUrl = DEFAULT_AGENT_GUIDE_URL } = options;
+  const spec = HANDOFF_TARGETS[target];
+  if (!spec) throw new RangeError(`Unknown handoff target "${target}". Use one of: ${Object.keys(HANDOFF_TARGETS).join(", ")}.`);
+  const json = JSON.stringify(document, null, 2);
+  if (typeof json !== "string") throw new TypeError("buildAgentHandoff needs an OPF document that can be written as JSON.");
+  const output = outputFor(fileName, spec.extension);
+  const fence = fenceFor(json);
+  const markdown = [
+    "# Task",
+    `Render this Open Presentation Format (OPF) deck to ${spec.label}.`,
+    "",
+    "## Setup",
+    "Needs Node 22 or later. In an empty folder:",
+    "",
+    "```sh",
+    `npm install ${spec.packages.join(" ")}`,
+    "```",
+    "",
+    "The renderer draws with font packages that npm does not install for you. If a render stops with `peer-not-installed`, run the `npm install` command in its message, then run the step again.",
+    "",
+    "## Steps",
+    `1. Save the JSON below as ${fileName}.`,
+    "2. Validate it with the opf command. Fix any schema errors; keep the slide content unchanged. It exits 1 for an invalid deck and names the JSON path of each error; findings with severity warning or info are advisory.",
+    "",
+    "```sh",
+    VALIDATE(fileName),
+    "```",
+    "",
+    `3. Render ${fileName} to ${spec.label} with the same command line tool. It writes ${spec.extension === "svg" ? `one file per slide, named from ${output}` : output}; the JSON it prints lists the files and any findings.`,
+    "",
+    "```sh",
+    CONVERT(fileName, output),
+    "```",
+    "",
+    "4. Report the output file path and any advisory warnings.",
+    "",
+    `Spec: ${specUrl}`,
+    `Agent guide: ${agentGuideUrl}`,
+    "",
+    `## ${fileName}`,
+    `${fence}json`,
+    json,
+    fence,
+  ].join("\n");
+  return { markdown, lines: markdown.split("\n").length };
+}