@openpresentation/opf-editor 0.6.0 → 0.7.0

package/README.md

@@ -1,8 +1,40 @@
 # OPF Editor
 
+Version 0.7.0 and this checkout require Node 24 (`24.x`). Use `.nvmrc` for local development. Earlier published versions retain their original engine declarations. Browser entrypoints remain browser-safe; native application compatibility is verified separately.
+
+Version 0.7.0 forwards effective title alignment and shared outline placement options through composition and explicit pagination. Use the same `textMeasurement` and `textRasterPadding` in canvas rendering and export. Accepted rich-text trace origins support selection, caret placement and undo. See the [source contract and limits](https://github.com/OpenPresentation/opf/blob/f94125a1ff95bf0974a055fe1c081d348dad54f2/docs/plans/text-placement.md); native PowerPoint fidelity remains separate.
+
 Embeddable local editor primitives for Open Presentation Format documents. The package turns traced `@openpresentation/opf-render` SVG output into JSON-path-aware edits, validates OPF after each change, and records undo/redo as JSON Patch operations.
 
-Version 0.6.0 uses core 0.9.0 and renderer 0.7.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.7.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.
+### Reusable JSON control (0.7.0)
+
+Version 0.7.0 exposes `mountJsonCodeEditor` from `@openpresentation/opf-editor/json-editor` and `getJsonFieldContext` / `replaceFieldOption` from `/json-options`. Earlier published version 0.6.0 does not include these exports. They extract the code editing and contextual choices already used on openpresentation.org, so hosts can reuse them without replacing their surrounding UI.
+
+```js
+import { mountJsonCodeEditor } from '@openpresentation/opf-editor/json-editor';
+const control = mountJsonCodeEditor(container, {
+  code: source,
+  label: 'OPF JSON document',
+  lineNumbers: true,
+  catalogs: loadedCatalogRecords,
+  onChange: nextSource => receiveDraft(nextSource),
+  onError: error => showError(error),
+});
+// After a preview edit, send the updated source back through the same control.
+control.update(nextSource);
+// On unmount:
+control.destroy();
+```
+
+The host owns the source draft, OPF validation, slide preview, persistence and session history. `onChange` includes invalid JSON while typing; keep the last valid preview until the draft validates. `update` applies external source without emitting `onChange` or creating a local undo step. It preserves unrelated edits through CodeMirror's history mapping; it is not a collaboration/conflict-resolution protocol. Importing either entrypoint does not require a DOM; mounting requires an existing browser container.
+
+The control provides indentation, paired quotes/brackets, folding shortcuts, search, undo/redo, JSON syntax diagnostics and explicit formatting (`Cmd/Ctrl+Shift+F`). Enter at the end of a nonempty string array item supplies indentation, quotes and commas. Other Enter positions use ordinary JSON indentation. Source offsets are UTF-16 in the original authored string. Existing CRLF, CR and LF spellings survive ordinary edits and undo; new typed lines use the first existing separator. Paste retains the text delivered by the browser clipboard event. Explicit formatting deliberately standardizes whitespace, preserving JSON values and numeric lexemes.
+
+Click a categorical property/value or press `Ctrl+Space`, `Cmd+Space` or `Alt+Down` to open its choices. Document catalog records override already-loaded records, which override built-ins; the actual schema supplies enums and booleans. Prose and extension fields do not gain menus just because their keys resemble schema fields. External catalog URLs are not fetched. `setCatalogs` replaces the host's loaded context and closes stale choices. Supply `onOptions(left?, top?)` to retain an existing menu UI; the host can use the pure `/json-options` helpers, checking that `context.source` still matches before replacing its token with `control.api.replace`.
+
+Run `npm run test:json` and `npm run test:json-browser` for the focused model and offline browser checks. The browser runner also accepts a report path followed by a clean installed consumer directory. These checks cover the JSON control; renderer, native PowerPoint and production adoption remain separate acceptance steps.
+
+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.
 
 ## Scope
 
@@ -34,7 +66,7 @@ await canvas.ready;
 
 Load the same font bytes into the browser using `loadBrowserFontRegistry` from `@openpresentation/opf-render/fonts-browser` before mounting. The host owns font URLs, storage and collaboration. `onDraft` provides live document drafts; the session only changes on commit. Escape cancels. Concurrent edits to the selected payload cancel a stale draft.
 
-These APIs were introduced in 0.1.0. Version 0.6.0 requires core 0.9.0 and renderer 0.7.0 for the canvas, including shared quote/code geometry, styled/merged cells, rich table values, headers and content-aware row heights. See the OPF repository’s `docs/live-editor.md` for setup, the support matrix and roadmap. `pnpm pack:ecosystem` in that repository also prepares local preview tarballs for coordinated development.
+These APIs were introduced in 0.1.0. Version 0.7.0 requires core 0.10.0 and renderer 0.8.0 for the canvas, including shared accepted geometry, styled/merged cells, rich table values, headers and content-aware row heights. See the OPF repository’s `docs/live-editor.md` for setup, the support matrix and roadmap. `pnpm pack:ecosystem` in that repository also prepares local preview tarballs for coordinated development.
 
 The canvas retains canonical SVG glyphs while a transparent native input supplies the caret. Advanced shaping, freeform object positioning, all chart/media treatments, and cross-engine pixel identity remain work in progress. The Source dialog in the playground now provides a live JSON preview; changes are validated before committing.
 
@@ -174,7 +206,7 @@ This repo does not require an npm automation token when Trusted Publishing is co
 
 The current checkout uses `@openpresentation/opf/composition` for portable geometry. Slides can select `auto`, `row`, `column`, or `grid`, set weighted tracks, and request path-specific overflow diagnostics. See the sibling OPF repo's `docs/dynamic-composition.md` for the complete contract.
 
-Version 0.6.0 requires `@openpresentation/opf@^0.9.0`. The optional renderer peer requires `@openpresentation/opf-render@^0.7.0`. Clean registry installs support the composition APIs without sibling checkouts. For coordinated source development, build OPF and run `node scripts/link-ecosystem.mjs` there; `pnpm test:ecosystem` verifies shared geometry and import/export behavior.
+Version 0.7.0 requires `@openpresentation/opf@^0.10.0`. The optional renderer peer requires `@openpresentation/opf-render@^0.8.0`. Clean registry installs support the composition APIs without sibling checkouts. For coordinated source development, build OPF and run `node scripts/link-ecosystem.mjs` there; `pnpm test:ecosystem` verifies shared geometry and import/export behavior.
 
 ## Local interactive demo
 
@@ -215,6 +247,10 @@ Slide insertion does not merge root speakers, organizations, or narrative metada
 
 Select rendered rich text to format it, or double-click a rich text block to type. The toolbar supports character styles, point size, font family, hex color, links, scripts, and selected-text replacement. Plain text payloads offer **Format text** during inline editing. **Edit runs** opens the structured fields; `canvas.editProperties(path)` does the same programmatically. Each action is validated and undoable. Version 0.1.1 supports direct mixed-style typing: double-click to type, drag to select, use Format selection for styles, and commit with Done or Ctrl/Cmd+Enter. Escape cancels. Native input and composition events preserve run metadata; the canonical SVG supplies glyph/caret geometry. The whole session commits as one undo step, with draft undo/redo available while typing. Empty-line caret geometry requires renderer 0.1.1 or later; cross-engine and real operating-system IME verification remain open.
 
+Version 0.7.0: rich input maps the textarea's LF-normalized offsets back to the original source. Typing preserves untouched CRLF/CR endings and surrounding run metadata; newly inserted newlines use the first source line-ending style. The `updateRichTextInput` change offsets are native textarea offsets, while formatting and replacement helpers continue to use original source offsets.
+
+Browser regression checks run with `npm run test:rich-input-browser -- artifacts/rich-input-browser.json measured` (or `estimated`). An optional consumer path after the mode selects an existing coordinated installed consumer; all browser runtime and font-preparation imports must then resolve inside that consumer. See [line-ending acceptance](docs/evidence/rich-input-line-endings-20260915/README.md) for scope and preserved failures.
+
 Headless applications and agents can import `formatRichTextRange`, `replaceRichTextRange`, and `richTextContent` from `@openpresentation/opf-editor/rich-text`. The helpers preserve surrounding run metadata and accept UTF-16 offsets on whole grapheme boundaries. A null format value removes an override. Apply the returned value through the editor session or validate the resulting document before saving.
 
 

package/dist/canvas-fields.js

@@ -5,6 +5,8 @@ import {
   splitOpfPath,
   opfPathToJsonPointer,
 } from "./index.js";
+import {preserveTextLineEndings} from './text-input.js';
+export {preserveTextLineEndings} from './text-input.js';
 /** Scalar fields and collection paths use JSON Pointer to preserve arbitrary object keys. */
 export function getEditableFields(value, path) {
   const fields = [],
@@ -50,18 +52,6 @@ export function parseCanvasValue(text, type, original) {
   return type === 'string' && typeof original === 'string' ? preserveTextLineEndings(original,String(text)) : text;
 }
 
-/** Textareas normalize line endings; retain unchanged source bytes around an edit. */
-export function preserveTextLineEndings(original, input) {
-  const normalized=original.replace(/\r\n|\r/g,'\n'),next=input.replace(/\r\n|\r/g,'\n');
-  if(normalized===next)return original;
-  let prefix=0,suffix=0;
-  while(prefix<normalized.length&&prefix<next.length&&normalized[prefix]===next[prefix])prefix++;
-  while(suffix<normalized.length-prefix&&suffix<next.length-prefix&&normalized[normalized.length-1-suffix]===next[next.length-1-suffix])suffix++;
-  const offsets=[0];
-  for(let i=0;i<original.length;i++){if(original[i]==='\r'&&original[i+1]==='\n')i++;offsets.push(i+1);}
-  const ending=/\r\n|\r|\n/.exec(original)?.[0]??'\n';
-  return original.slice(0,offsets[prefix])+next.slice(prefix,next.length-suffix).replaceAll('\n',ending)+original.slice(offsets[normalized.length-suffix]);
-}
 export function createCanvasDraft(document, path, value) {
   const draft = applyJsonPatch(
     document,

package/dist/canvas.js

@@ -137,6 +137,7 @@ export function createCanvasEditor(container, options = {}) {
         seen.has(path) ||
         node.getAttribute('data-opf-generated') === 'true' ||
         (node.hasAttribute('data-opf-code-container') && typeof value === 'string') ||
+        (node.hasAttribute('data-opf-metric-container') && ['string','number'].includes(typeof value)) ||
         (!item && !node.matches("g") && !node.matches("image")) ||
         value === undefined ||
         path === `slides.${slideIndex}` ||
@@ -159,7 +160,7 @@ export function createCanvasEditor(container, options = {}) {
       );
       if (node.matches("g")) {
         let bounds = node.getBBox();
-        if (!bounds.width && !bounds.height && node.hasAttribute('data-opf-code-role')) bounds={x:Number(node.dataset.opfBoxX),y:Number(node.dataset.opfBoxY),width:Number(node.dataset.opfBoxWidth),height:Number(node.dataset.opfBoxHeight)};
+        if (!bounds.width && !bounds.height && (node.hasAttribute('data-opf-code-role')||node.hasAttribute('data-opf-metric-role')||node.hasAttribute('data-opf-source-text'))) bounds={x:Number(node.dataset.opfBoxX),y:Number(node.dataset.opfBoxY),width:Number(node.dataset.opfBoxWidth),height:Number(node.dataset.opfBoxHeight)};
         const lines = JSON.parse(node.getAttribute("data-opf-rich-lines") ?? "[]");
         if (!bounds.width && !bounds.height && lines.length) bounds = {x:lines[0].x,y:lines[0].y,width:Number(node.getAttribute("data-opf-box-width"))||8,height:lines.reduce((sum,line)=>sum+line.height,0)};
         const rect = doc.createElementNS("http://www.w3.org/2000/svg", "rect");
@@ -261,11 +262,15 @@ export function createCanvasEditor(container, options = {}) {
         renderOptions,
       ).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;
+    const metricPart=metricLayout?.parts.find(part=>part.path===active.path);
+    const timelinePart=geometry.items.find(item=>item.timelineLayout?.parts.some(part=>part.path===active.path))?.timelineLayout?.parts.find(part=>part.path===active.path);
+    const internalPart=metricPart??timelinePart;
     const allText = target.querySelectorAll("text");
-    const lineHeight =
+    const lineHeight = internalPart?.fit?.lineHeight ?? (
       allText.length > 1
         ? Number(allText[1].getAttribute("y")) - Number(text.getAttribute("y"))
-        : fontSize * 1.22;
+        : fontSize * 1.22);
     const canvas = doc.createElement("canvas"),
       ctx = canvas.getContext("2d");
     ctx.font = `${font.fontStyle} ${font.fontWeight} ${fontSize}px ${font.fontFamily}`;
@@ -278,17 +283,18 @@ export function createCanvasEditor(container, options = {}) {
     const bounds = target.getBBox(),
       anchor = text.getAttribute("text-anchor");
     const tracedWidth = Number(target.getAttribute("data-opf-box-width"));
-    const width = item?.box.width ?? (tracedWidth > 0 ? tracedWidth : Math.max(80, bounds.width + 20));
-    const left = anchor === "middle" ? x - width / 2 : anchor === "end" ? x - width : x;
+    const width = internalPart?.box.width ?? item?.box.width ?? (tracedWidth > 0 ? tracedWidth : Math.max(80, bounds.width + 20));
+    const left = internalPart?.box.x ?? (anchor === "middle" ? x - width / 2 : anchor === "end" ? x - width : x);
+    const visibleText=active.composing||active.isCode||active.isMetric;
     Object.assign(active.input.style, {
       fontFamily: font.fontFamily,
       fontSize: `${fontSize * scale}px`,
       fontWeight: font.fontWeight,
       fontStyle: font.fontStyle,
       lineHeight: `${lineHeight * scale}px`,
-      color: active.composing || active.isCode ? font.fill : "transparent",
+      color: visibleText ? font.fill : "transparent",
       caretColor: font.fill,
-      textAlign: anchor === "middle" ? "center" : anchor === "end" ? "right" : "left",
+      textAlign: timelinePart?.alignment ?? metricLayout?.alignment ?? (anchor === "middle" ? "center" : anchor === "end" ? "right" : "left"),
       width: `${width * scale}px`,
       height: `${Math.max(lineHeight, allText.length * lineHeight) * scale + 2}px`,
       minHeight: "0",
@@ -297,9 +303,9 @@ export function createCanvasEditor(container, options = {}) {
     active.input.style.left = `${svgRect.left - rootRect.left + (left - viewBox.x) * scale}px`;
     active.input.style.top = `${svgRect.top - rootRect.top + (y - viewBox.y) * scale}px`;
     // When the input supplies visible text, its selected text needs the same fill.
-    active.input.style.setProperty('--opf-inline-selection-color',active.composing || active.isCode ? font.fill : 'transparent');
+    active.input.style.setProperty('--opf-inline-selection-color',visibleText ? font.fill : 'transparent');
     // Other text keeps the canonical SVG visible beneath the transparent input.
-    target.style.opacity = active.composing || active.isCode ? "0" : "1";
+    target.style.opacity = visibleText ? "0" : "1";
   }
   function beginEdit(path) {
     if (disposed) return;
@@ -327,6 +333,8 @@ export function createCanvasEditor(container, options = {}) {
       input.value = String(value);
       input.setAttribute("aria-label", `Edit ${path.split(".").at(-1)} inline`);
       const isCode=text.hasAttribute('data-opf-code-role');
+      const isMetric=text.hasAttribute('data-opf-metric-role');
+      const isTimeline=!!text.closest('[data-opf-timeline-role]');
       input.spellcheck = !isCode;
       input.style.cssText =
         "position:absolute;pointer-events:auto;resize:none;border:0;outline:1px solid #8975d9;outline-offset:4px;margin:0;padding:0;background:transparent;overflow:hidden;min-height:0;box-shadow:none;border-radius:0;white-space:pre-wrap;overflow-wrap:break-word;box-sizing:border-box;z-index:2";
@@ -336,12 +344,15 @@ export function createCanvasEditor(container, options = {}) {
         base: JSON.stringify(value),
         originalValue:value,
         isCode,
+        isMetric,
         type: typeof value,
         input,
         valid: true,
       };
       overlay.append(input);
       if(isCode){input.style.background='#111827';input.style.tabSize='4';input.style.overflow='auto';}
+      if(isMetric){input.style.tabSize='4';input.style.overflow='auto';}
+      if(isTimeline)input.style.tabSize='4';
       // Only offer rich text where the canonical schema accepts TextRun[].
       if (typeof value === "string") {
         try {
@@ -362,7 +373,14 @@ export function createCanvasEditor(container, options = {}) {
         } catch { /* This scalar field does not accept rich text. */ }
       }
       positionInput();
-      input.addEventListener("input", queueDraft);
+      input.addEventListener("input", () => {
+        // Compare each browser edit with the last canonical draft. Comparing
+        // only with the value at focus would normalize untouched mixed line
+        // endings between two edits in different parts of the same field.
+        if (active?.input===input && active.type==='string')
+          active.originalValue=parseCanvasValue(input.value,'string',active.originalValue);
+        queueDraft();
+      });
       input.addEventListener("compositionstart", () => {
         if (active) {
           active.composing = true;

package/dist/index.js

@@ -19,7 +19,7 @@ function resolveCompositionOptions(document, slideIndex, options = {}) {
       const reference = slide.design?.fontScheme ?? document.design?.fontScheme ?? theme?.fontScheme ?? "roboto";
       const id = typeof reference === "string" ? reference : reference.id;
       const fontScheme = {...(document.catalogs?.fontSchemes?.records?.find(record=>record.id===id) ?? bundledCatalogs.fontSchemes.find(record=>record.id===id)),...(typeof reference === "object" ? reference : {})};
-      return { ...resolveCanvasDimensions(slide.design?.dimensions ?? document.design?.dimensions ?? theme?.dimensions), fonts:resolveFontFamilies(fontScheme), ...options, layout, slideIndex };
+      return { ...resolveCanvasDimensions(slide.design?.dimensions ?? document.design?.dimensions ?? theme?.dimensions), fonts:resolveFontFamilies(fontScheme), contentAlignment:slide.design?.contentAlignment??document.design?.contentAlignment, titleAlignment:slide.design?.titleAlignment??document.design?.titleAlignment, contentBox:slide.design?.contentBox??document.design?.contentBox, ...options, layout, slideIndex };
 }
 
 export const packageName = "@openpresentation/opf-editor";

package/dist/json-editor.d.ts

@@ -0,0 +1,39 @@
+import type { JsonCatalogContext } from './json-options.js';
+
+/** All offsets address the original source in UTF-16, including CRLF pairs. */
+export interface JsonEditorApi {
+  getValue(): string;
+  getSelection(): [number, number];
+  hasFocus(): boolean;
+  focus(): void;
+  setSelection(from: number, to?: number): void;
+  /** Replace one source range atomically; boundaries inside CRLF are rejected. */
+  replace(from: number, to: number, text: string): void;
+  coordinates(): { left: number; top: number };
+  /** Explicit, undoable whitespace formatting; returns false for invalid JSON. */
+  format(): boolean;
+}
+export interface JsonCodeEditorOptions {
+  code: string;
+  label: string;
+  onChange(source: string): void;
+  invalid?: boolean;
+  describedBy?: string;
+  lineNumbers?: boolean;
+  catalogs?: JsonCatalogContext;
+  /** Overrides the built-in menu, allowing an existing host UI to keep its appearance. */
+  onOptions?(left?: number, top?: number): void;
+  onFocus?(): void;
+  onHoverField?(path: string | null): void;
+  onError?(error: unknown): void;
+}
+export interface JsonCodeEditor {
+  api: JsonEditorApi;
+  /** Apply external source without emitting onChange or adding a local undo step. */
+  update(code: string, invalid?: boolean, field?: string | null, describedBy?: string): void;
+  setCatalogs(catalogs: JsonCatalogContext): void;
+  openOptions(left?: number, top?: number): Promise<void>;
+  destroy(): void;
+}
+/** Mount after the host DOM exists. Importing this module does not require a DOM. */
+export declare function mountJsonCodeEditor(parent: HTMLElement, options: JsonCodeEditorOptions): JsonCodeEditor;

package/dist/json-editor.js

@@ -0,0 +1,278 @@
+import { Annotation, Compartment, EditorSelection, EditorState, Prec, StateEffect, StateField, Transaction } from "@codemirror/state";
+import { Decoration, EditorView, drawSelection, keymap, lineNumbers } from "@codemirror/view";
+import { defaultKeymap, history, historyKeymap, indentWithTab, isolateHistory, redo } from "@codemirror/commands";
+import { HighlightStyle, bracketMatching, codeFolding, foldKeymap, indentOnInput, indentUnit, syntaxHighlighting } from "@codemirror/language";
+import { json, jsonParseLinter } from "@codemirror/lang-json";
+import { closeBrackets, closeBracketsKeymap } from "@codemirror/autocomplete";
+import { highlightSelectionMatches, search, searchKeymap } from "@codemirror/search";
+import { linter } from "@codemirror/lint";
+import { tags } from "@lezer/highlight";
+import { applyEdits, findNodeAtOffset, format, getNodePath, parseTree } from "jsonc-parser";
+import {jsonSource,jsonSourceHistory,setJsonSource} from './json-source.js';
+import {textInputMap,preferredLineEnding} from './text-input.js';
+const external = Annotation.define();
+const hoverField = StateEffect.define();
+const activeField = StateField.define({ create: () => null, update: (value, tr) => tr.effects.reduce((value2, effect) => effect.is(hoverField) ? effect.value : value2, value) });
+const highlightStyle = HighlightStyle.define([
+  { tag: tags.propertyName, class: "tok-key" },
+  { tag: tags.string, class: "tok-str" },
+  { tag: [tags.number, tags.bool, tags.null], class: "tok-num" },
+  { tag: tags.punctuation, class: "tok-punct" },
+  { tag: tags.bracket, class: "tok-brace" }
+]);
+function indentation(source) {
+  const spaces = source.match(/^[\t ]+(?=\S)/gm) ?? [];
+  return spaces.some((value) => value.includes("	")) ? "	" : " ".repeat(spaces.length ? Math.min(8, ...spaces.map((value) => value.length)) : 2);
+}
+function sourceDecorations(state) {
+  const ranges = [];
+  const lines = /* @__PURE__ */ new Set();
+  const active = state.field(activeField);
+  function visit(node) {
+    if (node.type === "property" && node.children?.[1]) {
+      const key = node.children[0], path = getNodePath(node.children[1]);
+      const field = path.map((part, i) => typeof part === "number" ? `[${part}]` : `${i ? "." : ""}${part}`).join("");
+      ranges.push(Decoration.mark({ class: `code-key${field === active ? " is-active" : ""}`, attributes: { "data-field": field } }).range(key.offset, key.offset + key.length));
+      if (active && (field === active || field.startsWith(`${active}.`) || field.startsWith(`${active}[`))) {
+        const last = state.doc.lineAt(node.offset + node.length).number;
+        for (let line = state.doc.lineAt(key.offset).number; line <= last; line++) lines.add(state.doc.line(line).from);
+      }
+    }
+    node.children?.forEach(visit);
+  }
+  const root = parseTree(state.doc.toString());
+  if (root) visit(root);
+  for (const from of lines) ranges.push(Decoration.line({ class: "is-hover" }).range(from));
+  return Decoration.set(ranges, true);
+}
+const fieldDecorations = StateField.define({
+  create: sourceDecorations,
+  update: (value, tr) => tr.docChanged || tr.effects.some((effect) => effect.is(hoverField)) ? sourceDecorations(tr.state) : value,
+  provide: (field) => EditorView.decorations.from(field)
+});
+function nextStringItem(view) {
+  const { state } = view, { from, to } = state.selection.main;
+  if (from !== to || state.selection.ranges.length !== 1) return false;
+  const source = state.doc.toString();
+  try {
+    JSON.parse(source);
+  } catch {
+    return false;
+  }
+  const root = parseTree(source);
+  let node = findNodeAtOffset(root, Math.max(0, from - 1), true);
+  if (node?.type !== "string") {
+    node = findNodeAtOffset(root, Math.max(0, from - 2), true);
+  }
+  if (node?.type !== "string" || node.parent?.type !== "array" || !node.value) return false;
+  const end = node.offset + node.length;
+  if (from !== end - 1 && from !== end && !(from === end + 1 && source[end] === ",")) return false;
+  const siblings = node.parent.children ?? [], hasNext = siblings.indexOf(node) < siblings.length - 1;
+  const comma = /^\s*,/.exec(source.slice(end));
+  if (hasNext && !comma) return false;
+  const replaceTo = hasNext ? end + comma[0].length : end;
+  const line = state.doc.lineAt(node.offset);
+  const existingIndent = /^\s*/.exec(line.text)[0];
+  const parentLine = state.doc.lineAt(node.parent.offset);
+  const indent = line.number === parentLine.number ? /^\s*/.exec(parentLine.text)[0] + indentation(source) : existingIndent;
+  const inserted = `,
+${indent}""${hasNext ? "," : ""}`;
+  view.dispatch({
+    changes: { from: end, to: replaceTo, insert: inserted },
+    selection: { anchor: end + inserted.length - (hasNext ? 2 : 1) },
+    annotations: [Transaction.userEvent.of("input.complete"), isolateHistory.of("full")],
+    scrollIntoView: true
+  });
+  return true;
+}
+function skipDelimiter(view, delimiter) {
+  const { from, empty } = view.state.selection.main;
+  if (!empty || view.state.selection.ranges.length !== 1) return false;
+  const source = view.state.doc.toString();
+  if (source[from] !== delimiter) return false;
+  try {
+    JSON.parse(source);
+  } catch {
+    return false;
+  }
+  const node = findNodeAtOffset(parseTree(source), from, true);
+  if (delimiter === '"' && (node?.type !== "string" || from !== node.offset + node.length - 1)) return false;
+  if (delimiter === "," && node?.type === "string" && from < node.offset + node.length) return false;
+  view.dispatch({ selection: { anchor: from + 1 }, scrollIntoView: true });
+  return true;
+}
+function mountJsonCodeEditor(parent, options) {
+  const attributes = new Compartment(), indent = new Compartment();
+  let disposed=false, menu=null, catalogs=options.catalogs??{}, generation=0;
+  function closeOptions(){generation++;menu?.destroy();menu=null;}
+  async function openOptions(left,top){
+    closeOptions();
+    if(disposed)return;
+    if(options.onOptions){options.onOptions(left,top);return;}
+    const revision=generation,source=api.getValue(),selection=api.getSelection();
+    try{
+      const {mountJsonFieldMenu}=await import('./json-menu.js');
+      if(disposed||revision!==generation||source!==api.getValue()||selection.some((value,index)=>value!==api.getSelection()[index])||!api.hasFocus())return;
+      menu=mountJsonFieldMenu(parent,api,catalogs,left,top,()=>{menu=null;});
+    }catch(error){options.onError?.(error);}
+  }
+  let currentIndent = indentation(options.code);
+  const contentAttributes = (invalid = options.invalid, describedBy = options.describedBy) => EditorView.contentAttributes.of({
+    "aria-label": options.label,
+    "aria-invalid": String(Boolean(invalid)),
+    "aria-describedby": describedBy ?? "",
+    "aria-keyshortcuts": "Control+Space Meta+Space Alt+ArrowDown",
+    spellcheck: "false",
+    autocapitalize: "off",
+    autocorrect: "off"
+  });
+  const view = new EditorView({ parent, state: EditorState.create({ doc: options.code, extensions: [
+    json(),
+    jsonSource.init(()=>options.code),jsonSourceHistory,
+    indent.of(indentUnit.of(currentIndent)),
+    indentOnInput(),
+    history(),
+    drawSelection(),
+    bracketMatching(),
+    closeBrackets(),
+    codeFolding(),
+    search({ top: true }),
+    highlightSelectionMatches(),
+    linter(jsonParseLinter(), { delay: 500 }),
+    syntaxHighlighting(highlightStyle),
+    activeField,
+    fieldDecorations,
+    attributes.of(contentAttributes()),
+    options.lineNumbers ? lineNumbers() : [],
+    EditorView.lineWrapping,
+    // Some platforms report a lowercase key even with Shift held. Handle
+    // formatting before the standard Mod-f search binding normalizes the key.
+    Prec.high(EditorView.domEventHandlers({ keydown(event) {
+      // A lowercase "z" with Shift can match CodeMirror's unshifted undo
+      // binding first. Resolve redo before that fallback, even with older
+      // undo steps still available (otherwise it silently performs undo).
+      if ((event.metaKey || event.ctrlKey) && event.shiftKey && !event.altKey && event.key.toLowerCase() === "z") {
+        event.preventDefault();
+        redo(view);
+        return true;
+      }
+      if ((event.metaKey || event.ctrlKey) && event.shiftKey && !event.altKey && event.key.toLowerCase() === "f") {
+        event.preventDefault();
+        api.format();
+        return true;
+      }
+      return false;
+    } })),
+    keymap.of([
+      { key: "Enter", run: nextStringItem },
+      { key: '"', run: (view2) => skipDelimiter(view2, '"') },
+      { key: ",", run: (view2) => skipDelimiter(view2, ",") },
+      { key: "Mod-Space", run: () => {
+        void openOptions();
+        return true;
+      } },
+      { key: "Ctrl-Space", run: () => {
+        void openOptions();
+        return true;
+      } },
+      { key: "Alt-ArrowDown", run: () => {
+        void openOptions();
+        return true;
+      } },
+      indentWithTab,
+      ...closeBracketsKeymap,
+      ...defaultKeymap,
+      ...historyKeymap,
+      ...searchKeymap,
+      ...foldKeymap
+    ]),
+    EditorView.domEventHandlers({
+      click(event) {
+        if (view.state.selection.main.empty) void openOptions(event.clientX, event.clientY + 12);
+      },
+      paste(event){
+        if(!event.clipboardData||view.state.selection.ranges.length!==1)return false;
+        const text=event.clipboardData.getData('text/plain');
+        if(!text)return false;
+        event.preventDefault();api.replace(...api.getSelection(),text);return true;
+      },
+      focus() {
+        options.onFocus?.();
+      },
+      mousemove(event) {
+        options.onHoverField?.(event.target.closest("[data-field]")?.dataset.field ?? null);
+      },
+      mouseleave() {
+        options.onHoverField?.(null);
+      }
+    }),
+    EditorView.updateListener.of((update) => {
+      if(update.docChanged||update.selectionSet)closeOptions();
+      if (update.docChanged && !update.transactions.every((tr) => tr.annotation(external))) options.onChange(update.state.field(jsonSource));
+    })
+  ] }) });
+  const api = {
+    getValue: () => view.state.field(jsonSource),
+    getSelection: () => {const map=textInputMap(api.getValue());return [map.toSource(view.state.selection.main.from),map.toSource(view.state.selection.main.to)];},
+    hasFocus: () => view.hasFocus,
+    focus: () => view.focus(),
+    setSelection: (from, to=from) => {const map=textInputMap(api.getValue());view.dispatch({ selection: EditorSelection.single(map.toInput(from),map.toInput(to)), scrollIntoView: true });},
+    replace: (from, to, text) => {
+      const source=api.getValue(),map=textInputMap(source),a=map.toInput(from),b=map.toInput(to);
+      if(to<from||map.toSource(a)!==from||map.toSource(b)!==to)throw new RangeError('JSON edits must use source boundaries outside a CRLF pair.');
+      const insert=textInputMap(text).text,next=source.slice(0,from)+text+source.slice(to);
+      view.dispatch({changes:{from:a,to:b,insert},selection:{anchor:a+insert.length},effects:setJsonSource.of(next),
+        annotations:[Transaction.userEvent.of('input.complete'),isolateHistory.of('full')],scrollIntoView:true});
+    },
+    coordinates: () => {
+      const rect = view.coordsAtPos(view.state.selection.main.head) ?? parent.getBoundingClientRect();
+      return { left: rect.left, top: rect.bottom + 8 };
+    },
+    format: () => {
+      const source = api.getValue();
+      try {
+        JSON.parse(source);
+      } catch {
+        return false;
+      }
+      const unit = indentation(source);
+      const next = applyEdits(source, format(source, void 0, { insertSpaces: unit !== "	", tabSize: unit.length, eol: preferredLineEnding(source) }));
+      if (source !== next) api.replace(0, source.length, next);
+      return true;
+    }
+  };
+  return {
+    api,
+    openOptions,
+    setCatalogs(value){catalogs=value??{};closeOptions();},
+    update(code, invalid=false, field=null, describedBy) {
+      if(code!==api.getValue())closeOptions();
+      const current = view.state.doc.toString(), normalized=textInputMap(code).text;
+      const effects = [attributes.reconfigure(contentAttributes(invalid, describedBy)), hoverField.of(field),setJsonSource.of(code)];
+      const nextIndent = indentation(code);
+      if (nextIndent !== currentIndent) {
+        currentIndent = nextIndent;
+        effects.push(indent.reconfigure(indentUnit.of(nextIndent)));
+      }
+      if (current === normalized) {
+        view.dispatch({ effects });
+        return;
+      }
+      let from = 0, oldEnd = current.length, newEnd = normalized.length;
+      while (from < oldEnd && from < newEnd && current[from] === normalized[from]) from++;
+      while (oldEnd > from && newEnd > from && current[oldEnd - 1] === normalized[newEnd - 1]) {
+        oldEnd--;
+        newEnd--;
+      }
+      view.dispatch({
+        changes: { from, to: oldEnd, insert: normalized.slice(from, newEnd) },
+        effects,
+        annotations: [external.of(true), Transaction.addToHistory.of(false)]
+      });
+    },
+    destroy: () => {if(disposed)return;disposed=true;closeOptions();view.destroy();}
+  };
+}
+export {
+  mountJsonCodeEditor
+};

package/dist/json-menu.js

@@ -0,0 +1,81 @@
+import {getJsonFieldContext,replaceFieldOption} from './json-options.js';
+let nextMenuId=0;
+
+/** Optional DOM menu; hosts may provide their own onOptions renderer instead. */
+export function mountJsonFieldMenu(parent,api,catalogs,left,top,onClose){
+  const doc=parent.ownerDocument,win=doc.defaultView,source=api.getValue(),selection=api.getSelection();
+  const context=getJsonFieldContext(source,selection[0],catalogs);
+  if(!context)return null;
+  const coordinates=api.coordinates();left??=coordinates.left;top??=coordinates.top;
+  const root=doc.createElement('div');root.className='json-field-menu';root.setAttribute('role','dialog');root.setAttribute('aria-label',`${context.label} options`);
+  root.style.cssText='position:fixed;z-index:10000;width:380px;max-width:calc(100vw - 16px);max-height:calc(100vh - 16px);overflow:auto;box-sizing:border-box;padding:12px;background:Canvas;color:CanvasText;border:1px solid GrayText;border-radius:8px;font:13px system-ui;box-shadow:0 8px 28px #0003';
+  const add=(tag,text,className,container=root)=>{const node=doc.createElement(tag);if(text!==undefined)node.textContent=text;if(className)node.className=className;container.append(node);return node;};
+  const heading=add('div',undefined,'json-field-heading');add('strong',context.label,undefined,heading);
+  const closeButton=add('button','×',undefined,heading);closeButton.type='button';closeButton.setAttribute('aria-label','Close options');
+  const search=add('input');search.type='search';search.placeholder='Search options…';search.autocomplete='off';search.setAttribute('role','combobox');search.setAttribute('aria-label',`Search ${context.label} options`);search.setAttribute('aria-expanded','true');
+  const isLayout=context.catalog==='layouts',relatedCount=context.options.filter(option=>option.related).length;
+  let similar=isLayout&&relatedCount>1;
+  const filters=isLayout?add('div',undefined,'json-field-filters'):null;
+  const similarButton=filters?add('button',`Similar (${relatedCount})`,undefined,filters):null;
+  const allButton=filters?add('button',`All layouts (${context.options.length})`,undefined,filters):null;
+  for(const button of [similarButton,allButton].filter(Boolean)){button.type='button';button.style.cssText='padding:6px;margin:4px 4px 4px 0';}
+  if(isLayout){search.placeholder='Search all layouts or placeholders…';add('p','Same types and counts first. Text and subtitle slots are compatible.','json-field-hint');}
+  const list=add('div',undefined,'json-field-options');list.setAttribute('role','listbox');list.setAttribute('aria-label',`Available ${context.label} options`);
+  let id;do{id=`opf-json-options-${++nextMenuId}`;}while(doc.getElementById(id));
+  list.id=id;search.setAttribute('aria-controls',id);list.style.cssText='max-height:280px;overflow:auto;margin-top:8px';
+  const error=add('p',undefined,'json-field-empty');error.setAttribute('role','alert');error.hidden=true;
+  if(isLayout){
+    const help=add('details',undefined,'json-field-catalog-help');add('summary','Where do these layouts come from?',undefined,help);
+    add('p','Standard OPF: included with OPF. Provided by app: extra records supplied by the host app. In this document: records in your JSON, which override matching IDs. External galleries are not automatically loaded.',undefined,help);
+  }
+  add('p',context.unloadedSource?'Using available records. External catalog URLs are not loaded here.':'Choose an option or press Escape to keep editing JSON.','json-field-footnote');
+  let selected=Math.max(0,context.options.findIndex(option=>option.value===context.value)),choices=[],disposed=false;
+  function close(restore=false){if(disposed)return;disposed=true;observer.disconnect();root.remove();doc.removeEventListener('pointerdown',outside);doc.removeEventListener('wheel',outside,true);doc.removeEventListener('touchmove',outside,true);win.removeEventListener('resize',resize);onClose();if(restore){api.focus();api.setSelection(...selection);}}
+  function outside(event){if(!root.contains(event.target))close();}
+  function resize(){close();}
+  function choose(option){
+    if(api.getValue()!==source){close();return;}
+    try{replaceFieldOption(context,option.value);api.replace(context.offset,context.offset+context.length,JSON.stringify(option.value));close();api.focus();}
+    catch(cause){error.hidden=false;error.textContent=cause.message;}
+  }
+  function highlight(){
+    for(const [index,node] of [...list.querySelectorAll('[role="option"]')].entries()){
+      node.classList.toggle('is-highlighted',index===selected);node.style.outline=index===selected?'2px solid Highlight':'';
+    }
+    const active=list.querySelector(`[data-option-index="${selected}"]`);if(active?.getAttribute('role')==='option'){search.setAttribute('aria-activedescendant',active.id);active.scrollIntoView({block:'nearest'});}else search.removeAttribute('aria-activedescendant');
+  }
+  function render(){
+    const query=search.value.trim().toLowerCase();
+    choices=context.options.filter(option=>query?`${option.label} ${option.value} ${option.description??''} ${option.placeholders??''}`.toLowerCase().includes(query):!similar||option.related);
+    similarButton?.setAttribute('aria-pressed',String(similar&&!query));allButton?.setAttribute('aria-pressed',String(!similar||Boolean(query)));
+    for(const button of [similarButton,allButton].filter(Boolean))button.style.outline=button.getAttribute('aria-pressed')==='true'?'2px solid Highlight':'';
+    list.replaceChildren();let group,container=list;
+    for(const [index,option] of choices.entries()){
+      if(isLayout&&option.layoutGroup!==group){group=option.layoutGroup;container=add('div',undefined,undefined,list);container.setAttribute('role','group');container.setAttribute('aria-label',group);const label=add('div',group,'json-field-group',container);label.setAttribute('aria-hidden','true');label.style.cssText='font-size:11px;font-weight:600;padding:8px 8px 4px;color:GrayText';}
+      const button=add('button',undefined,undefined,container);button.dataset.optionIndex=String(index);button.type='button';button.tabIndex=-1;button.id=`${id}-${index}`;button.setAttribute('role','option');button.setAttribute('aria-selected',String(option.value===context.value));button.style.cssText='display:block;text-align:left;width:100%;padding:8px;border:0;background:transparent;color:inherit';
+      const label=add('span',undefined,undefined,button);add('strong',option.label,undefined,label);if(option.value===context.value)add('span',' ✓',undefined,label);
+      if(option.placeholders){const summary=add('div',option.placeholders,'json-field-placeholders',button);summary.style.cssText='margin:4px 0';}
+      const meta=add('div',undefined,'json-field-meta',button);meta.style.cssText='display:flex;gap:12px;justify-content:space-between;flex-wrap:wrap';
+      add('code',String(option.value),undefined,meta);const origin=add('small',option.sourceLabel??option.source,undefined,meta);origin.title=option.sourceDescription??'';
+      if(option.description)add('p',option.description,undefined,button);
+      button.addEventListener('mouseenter',()=>{selected=index;highlight();});button.addEventListener('click',()=>choose(option));
+    }
+    if(!choices.length)add('p','No matching options. You can still type a custom value in the JSON.','json-field-empty',list);
+    if(similar&&!query&&relatedCount===1)add('p','No other available layouts share these placeholders. Try All layouts.','json-field-empty',list);
+    highlight();
+  }
+  search.addEventListener('input',()=>{selected=0;render();});
+  similarButton?.addEventListener('click',()=>{similar=true;search.value='';selected=0;render();});
+  allButton?.addEventListener('click',()=>{similar=false;search.value='';selected=0;render();});
+  root.addEventListener('keydown',event=>{
+    if(event.key==='Escape'){event.preventDefault();event.stopPropagation();close(true);}
+    else if(event.target===search&&['ArrowDown','ArrowUp'].includes(event.key)){event.preventDefault();selected=Math.max(0,Math.min(choices.length-1,selected+(event.key==='ArrowDown'?1:-1)));highlight();}
+    else if(event.target===search&&event.key==='Enter'&&choices[selected]){event.preventDefault();choose(choices[selected]);}
+  });
+  root.addEventListener('focusout',event=>{if(event.relatedTarget&&!root.contains(event.relatedTarget))close();});
+  closeButton.addEventListener('click',()=>close(true));doc.body.append(root);render();
+  function reposition(){const box=root.getBoundingClientRect();root.style.left=`${Math.max(8,Math.min(left,win.innerWidth-box.width-8))}px`;root.style.top=`${Math.max(8,Math.min(top,win.innerHeight-box.height-8))}px`;}
+  const observer=new win.ResizeObserver(reposition);observer.observe(root);reposition();
+  search.focus();doc.addEventListener('pointerdown',outside);doc.addEventListener('wheel',outside,{capture:true,passive:true});doc.addEventListener('touchmove',outside,{capture:true,passive:true});win.addEventListener('resize',resize);
+  return {destroy:()=>close()};
+}

package/dist/json-options.d.ts

@@ -0,0 +1,33 @@
+/** Already-loaded catalog records by kind. No remote catalog URLs are fetched. */
+export type JsonCatalogContext = Readonly<Record<string, readonly Record<string, unknown>[]>>;
+export type JsonOptionValue = string | number | boolean;
+export interface JsonFieldOption {
+  value: JsonOptionValue;
+  label: string;
+  description?: string;
+  source: 'Built-in catalog' | 'Loaded catalog' | 'Document catalog' | 'Schema' | 'Current value';
+  suggested?: boolean;
+  /** User-facing provenance; source remains stable for existing consumers. */
+  sourceLabel?: string;
+  sourceDescription?: string;
+  layoutGroup?: 'Current layout' | 'Same placeholders' | 'Compatible placeholders' | 'Different counts' | 'Other layouts' | 'Unspecified placeholders';
+  /** Declared placeholder types and counts, not a rendering guarantee. */
+  placeholders?: string;
+  related?: boolean;
+}
+export interface JsonFieldContext {
+  source: string;
+  path: (string | number)[];
+  /** Original-source UTF-16 token range, including surrounding JSON quotes. */
+  offset: number;
+  length: number;
+  value: JsonOptionValue;
+  label: string;
+  options: JsonFieldOption[];
+  catalog?: string;
+  unloadedSource: boolean;
+}
+/** Null for invalid JSON or a field with no categorical choices. */
+export declare function getJsonFieldContext(source: string, position: number, loadedCatalogs?: JsonCatalogContext): JsonFieldContext | null;
+/** Replace only the token. Hosts must reject a context whose source is stale. */
+export declare function replaceFieldOption(context: JsonFieldContext, value: JsonOptionValue): string;

package/dist/json-options.js

@@ -0,0 +1,156 @@
+import { catalogKinds, catalogSchemaNames, schemas, validateCatalogRecord, validatePresentation } from "@openpresentation/opf";
+import { getCatalogOptions } from "./index.js";
+import { schemaAtPath, schemaVariants } from "./schema.js";
+import { findNodeAtOffset, getNodePath, parseTree } from "jsonc-parser";
+function catalogFor(description) {
+    return catalogKinds.find(kind => description.includes(`catalogs.${kind}`)
+        || new RegExp(`\\b${kind}['’]? catalog`).test(description));
+}
+// Compare declared placeholders, including multiplicity. This describes a layout
+// contract, not a claim that arbitrary slide content will render without overflow.
+function layoutTypes(record) {
+    if (!Array.isArray(record?.placeholders))
+        return undefined;
+    return record.placeholders.map(p => p.type).sort();
+}
+function placeholderSummary(types) {
+    if (!types)
+        return "Placeholders not specified";
+    if (!types.length)
+        return "No placeholders";
+    const labels = { title: "Title", subtitle: "Subtitle", text: "Text", list: "List", picture: "Image", chart: "Chart", table: "Table", code: "Code", media: "Media" };
+    const order = ["title", "subtitle", "text", "list", "picture", "chart", "table", "code", "media"];
+    return [...new Set(types)].sort((a, b) => order.indexOf(a) - order.indexOf(b)).map(type => {
+        const count = types.filter(value => value === type).length;
+        return `${labels[type] ?? type}${count > 1 ? ` × ${count}` : ""}`;
+    }).join(" + ");
+}
+const sourceDetails = {
+    "Built-in catalog": ["Standard OPF", "Included with OPF and available offline."],
+    "Loaded catalog": ["Provided by app", "Additional records supplied to the preview by this app; these are not fetched from a URL."],
+    "Document catalog": ["In this document", "Defined in this document’s catalogs. Takes precedence over app and standard records with the same ID."],
+    "Current value": ["Custom value", "The current value is not in the available catalogs."],
+    "Schema": ["OPF option", "Allowed by the OPF schema."],
+};
+const layoutGroups = ["Current layout", "Same placeholders", "Compatible placeholders", "Different counts", "Other layouts", "Unspecified placeholders"];
+function describeOptions(choices, records, current, catalog) {
+    const currentRecord = records.get(String(current));
+    const currentTypes = layoutTypes(currentRecord);
+    const signature = (types) => JSON.stringify(types);
+    const compatible = (types) => types.map(type => type === "subtitle" ? "text" : type).sort();
+    for (const option of choices) {
+        const [label, description] = sourceDetails[option.source];
+        option.sourceLabel = label;
+        option.sourceDescription = description;
+        if (catalog !== "layouts")
+            continue;
+        const types = layoutTypes(option.value === current ? currentRecord : records.get(String(option.value)));
+        option.placeholders = placeholderSummary(types);
+        const same = types && currentTypes && signature(types) === signature(currentTypes);
+        const equivalent = types && currentTypes && signature(compatible(types)) === signature(compatible(currentTypes));
+        const sameKinds = types && currentTypes && signature([...new Set(compatible(types))]) === signature([...new Set(compatible(currentTypes))]);
+        option.layoutGroup = option.value === current ? "Current layout" : !types ? "Unspecified placeholders"
+            : same ? "Same placeholders" : equivalent ? "Compatible placeholders" : sameKinds ? "Different counts" : "Other layouts";
+        option.related = option.value === current || Boolean(same || equivalent);
+        option.suggested = Boolean(same || equivalent);
+    }
+    const priority = (option) => option.source === "Document catalog" ? 2 : option.source === "Loaded catalog" ? 1 : 0;
+    return choices.sort((a, b) => (catalog === "layouts"
+        ? layoutGroups.indexOf(a.layoutGroup) - layoutGroups.indexOf(b.layoutGroup)
+        : priority(b) - priority(a)) || a.label.localeCompare(b.label, "en", { numeric: true }) || String(a.value).localeCompare(String(b.value), "en"));
+}
+// The installed schema identifies fields; a document field merely named "layout"
+// inside arbitrary metadata is not mistaken for an OPF layout reference.
+export function getJsonFieldContext(source, position, loadedCatalogs = {}) {
+    let document;
+    try {
+        document = JSON.parse(source);
+    }
+    catch {
+        return null;
+    }
+    const root = parseTree(source);
+    if (!root)
+        return null;
+    let node = findNodeAtOffset(root, position, true);
+    if (node?.parent?.type === "property" && node.parent.children?.[0] === node)
+        node = node.parent.children[1];
+    if (node?.type === "object")
+        node = node.children?.find(property => property.children?.[0]?.value === "id")?.children?.[1];
+    if (!node || !["string", "number", "boolean"].includes(node.type))
+        return null;
+    const path = getNodePath(node);
+    if (!path.length)
+        return null;
+    const schema = schemaAtPath(document, path.map(String));
+    const variants = schemaVariants(schema);
+    const description = String(schema.description ?? "");
+    let catalog = catalogFor(description);
+    // Audience arrays inherit the catalog context from the array property.
+    if (!catalog && typeof path.at(-1) === "number")
+        catalog = catalogFor(String(schemaAtPath(document, path.slice(0, -1).map(String)).description ?? ""));
+    const options = new Map();
+    const records = new Map();
+    let unloadedSource = false;
+    if (catalog && typeof node.value === "string") {
+        const entries = document.catalogs;
+        const local = entries?.[catalog];
+        unloadedSource = Boolean(local?.source);
+        for (const option of getCatalogOptions(catalog)) {
+            records.set(option.id, option.record);
+            options.set(option.id, { value: option.id, label: option.label, description: typeof option.record.description === "string" ? option.record.description : undefined,
+                source: "Built-in catalog" });
+        }
+        for (const { value, source } of [...(Array.isArray(loadedCatalogs?.[catalog]) ? loadedCatalogs[catalog] : []).map(value => ({ value, source: "Loaded catalog" })),
+            ...(Array.isArray(local?.records) ? local.records : []).map(value => ({ value, source: "Document catalog" }))]) {
+            if (!value || typeof value !== "object")
+                continue;
+            const record = value;
+            if (typeof record.id !== "string")
+                continue;
+            // Inline records may omit the standalone document's $schema marker.
+            // Supply it only for validation; never change the authored record.
+            const schemaId = schemas[catalogSchemaNames[catalog]].$id;
+            if (!validateCatalogRecord(catalog, { $schema: schemaId, ...record }).valid) {
+                options.delete(record.id);
+                records.delete(record.id);
+                continue;
+            }
+            records.set(record.id, record);
+            options.set(record.id, { value: record.id, label: typeof record.name === "string" ? record.name : record.id,
+                description: typeof record.description === "string" ? record.description : undefined,
+                source });
+        }
+    }
+    else {
+        for (const variant of variants)
+            for (const value of variant.enum ?? []) {
+                if (["string", "number", "boolean"].includes(typeof value))
+                    options.set(JSON.stringify(value), { value, label: String(value), source: "Schema" });
+            }
+        if (node.type === "boolean" && variants.some(variant => variant.type === "boolean" && variant.const === undefined)) {
+            for (const value of [true, false])
+                options.set(String(value), { value, label: String(value), source: "Schema" });
+        }
+    }
+    if (!options.size)
+        return null;
+    const choices = [...options.values()];
+    if (!choices.some(option => option.value === node.value))
+        choices.unshift({ value: node.value, label: String(node.value), source: "Current value" });
+    describeOptions(choices, records, node.value, catalog);
+    return { source, path, offset: node.offset, length: node.length, value: node.value,
+        label: String(path.at(-1) === "id" || typeof path.at(-1) === "number" ? path.at(-2) : path.at(-1)), options: choices, catalog, unloadedSource };
+}
+export function replaceFieldOption(context, value) {
+    if (!context.options.some(option => option.value === value))
+        throw new Error("This choice is no longer available.");
+    const next = context.source.slice(0, context.offset) + JSON.stringify(value) + context.source.slice(context.offset + context.length);
+    const document = JSON.parse(next);
+    if (context.path.reduce((current, key) => current?.[key], document) !== value)
+        throw new Error("This field has a duplicate key. Resolve it in the JSON before choosing an option.");
+    const result = validatePresentation(document);
+    if (!result.valid && validatePresentation(JSON.parse(context.source)).valid)
+        throw new Error(result.errors[0]?.message ?? "This option is not valid here.");
+    return next;
+}

package/dist/json-source.js

@@ -0,0 +1,47 @@
+import {MapMode,StateEffect,StateField} from '@codemirror/state';
+import {invertedEffects} from '@codemirror/commands';
+import {textInputMap,preferredLineEnding} from './text-input.js';
+
+// CodeMirror uses LF positions internally. Keep authored source as a separate
+// field, and store only removed newline spellings in its existing undo history.
+export const setJsonSource=StateEffect.define();
+const restoreEndings=StateEffect.define({map:(endings,changes)=>{
+  const mapped=endings.map(({position,ending})=>({position:changes.mapPos(position,1,MapMode.TrackDel),ending})).filter(item=>item.position!==null);
+  return mapped.length?mapped:undefined;
+}});
+export const jsonSource=StateField.define({
+  create:state=>state.doc.toString(),
+  update(source,tr){
+    const explicit=tr.effects.findLast(effect=>effect.is(setJsonSource));
+    if(explicit){
+      if(textInputMap(explicit.value).text!==tr.newDoc.toString())throw new Error('JSON source and code-editor document must agree.');
+      return explicit.value;
+    }
+    if(tr.docChanged){
+      const map=textInputMap(source),ending=preferredLineEnding(source),changes=[];
+      tr.changes.iterChanges((from,to,_fromB,_toB,insert)=>changes.push({from:map.toSource(from),to:map.toSource(to),insert:insert.toString().replaceAll('\n',ending)}));
+      for(const change of changes.reverse())source=source.slice(0,change.from)+change.insert+source.slice(change.to);
+    }
+    const endings=[...new Map(tr.effects.filter(effect=>effect.is(restoreEndings)).flatMap(effect=>effect.value).map(item=>[item.position,item])).values()];
+    if(endings.length){
+      const map=textInputMap(source);
+      for(const {position,ending} of endings.sort((a,b)=>b.position-a.position)){
+        if(tr.newDoc.sliceString(position,position+1)!=='\n')continue;
+        source=source.slice(0,map.toSource(position))+ending+source.slice(map.toSource(position+1));
+      }
+    }
+    return source;
+  },
+});
+export const jsonSourceHistory=invertedEffects.of(tr=>{
+  if(!tr.docChanged)return [];
+  const source=tr.startState.field(jsonSource),map=textInputMap(source),endings=[];
+  tr.changes.iterChanges((from,to)=>{
+    const removed=tr.startState.doc.sliceString(from,to);
+    for(let index=removed.indexOf('\n');index!==-1;index=removed.indexOf('\n',index+1)){
+      const position=from+index;
+      endings.push({position,ending:source.slice(map.toSource(position),map.toSource(position+1))});
+    }
+  });
+  return endings.length?[restoreEndings.of(endings)]:[];
+});

package/dist/rich-text-input.js

@@ -1,4 +1,5 @@
 import {richTextContent, updateRichTextInput} from './rich-text.js';
+import {textInputMap} from './text-input.js';
 
 /** Native input owns keyboard/IME; caret and selection use the canonical SVG glyphs. */
 export function createRichTextInput(root, overlay, {path, value, getTarget, onInput, onCommit, onCancel, onFormat, onError}) {
@@ -9,7 +10,7 @@ export function createRichTextInput(root, overlay, {path, value, getTarget, onIn
   input.style.cssText='position:absolute;width:1px;padding:0;border:0;opacity:0;pointer-events:none;resize:none;overflow:hidden;z-index:3';
   marks.className='opf-rich-selection';marks.setAttribute('aria-hidden','true');marks.style.cssText='position:absolute;inset:0;pointer-events:none';
   actions.style.cssText='position:absolute;bottom:8px;left:8px;display:flex;gap:6px;pointer-events:auto;z-index:4';
-  for(const [label,action] of [['Format selection',()=>onFormat(input.selectionStart,input.selectionEnd)],['Done',onCommit]]) {
+  for(const [label,action] of [['Format selection',()=>{const map=currentMap();onFormat(map.toSource(input.selectionStart),map.toSource(input.selectionEnd));}],['Done',onCommit]]) {
     const button=doc.createElement('button');button.type='button';button.textContent=label;
     button.style.cssText='padding:6px 10px;background:#fff;color:#574774;border:1px solid #d5cce5;border-radius:5px';
     button.onmousedown=event=>event.preventDefault();button.onclick=action;actions.append(button);
@@ -17,10 +18,11 @@ export function createRichTextInput(root, overlay, {path, value, getTarget, onIn
   overlay.append(marks,input,actions);
   let current=structuredClone(value), composing=false, change=null, anchor=null, disposed=false, emptyAnchor=null;
   let history=[{value:structuredClone(current),start:0,end:input.value.length}], historyIndex=0, compositionBase=null;
+  const currentMap=()=>textInputMap(richTextContent(current));
   function remember() {
     history.splice(historyIndex+1);history.push({value:structuredClone(current),start:input.selectionStart,end:input.selectionEnd});historyIndex++;
   }
-  function fragments() { return [...(getTarget(path)?.querySelectorAll('text[data-opf-text-start]')??[])]; }
+  function fragments() { return [...(getTarget(path)?.querySelectorAll('text[data-opf-text-start],tspan[data-opf-text-start]')??[])]; }
   function rect(node,start,end) {
     const range=doc.createRange();range.setStart(node.firstChild,start);range.setEnd(node.firstChild,end);return range.getBoundingClientRect();
   }
@@ -45,7 +47,7 @@ export function createRichTextInput(root, overlay, {path, value, getTarget, onIn
   }
   function update() {
     if(disposed)return;marks.replaceChildren();
-    const origin=root.getBoundingClientRect(),start=input.selectionStart,end=input.selectionEnd;
+    const map=currentMap(),origin=root.getBoundingClientRect(),start=map.toSource(input.selectionStart),end=map.toSource(input.selectionEnd);
     const append=(box,caret=false)=>{
       const mark=doc.createElement('div');mark.className=caret?'opf-rich-caret':'opf-rich-range';
       mark.style.cssText=`position:absolute;left:${box.left-origin.left}px;top:${box.top-origin.top}px;width:${caret?1.5:box.width}px;height:${Math.max(12,box.height)}px;background:${caret?(box.color??'#6551ba'):'#8975d955'}`;
@@ -78,13 +80,13 @@ export function createRichTextInput(root, overlay, {path, value, getTarget, onIn
   function pointerDown(event) {
     if(event.button!==0||!getTarget(path)?.contains(event.target))return;
     event.preventDefault();event.stopPropagation();
-    anchor=event.shiftKey?input.selectionStart:nearest(event);input.focus({preventScroll:true});
-    const end=nearest(event);input.setSelectionRange(Math.min(anchor,end),Math.max(anchor,end),end<anchor?'backward':'forward');
+    const map=currentMap();anchor=event.shiftKey?map.toSource(input.selectionStart):nearest(event);input.focus({preventScroll:true});
+    const end=nearest(event);input.setSelectionRange(map.toInput(Math.min(anchor,end)),map.toInput(Math.max(anchor,end)),end<anchor?'backward':'forward');
     root.setPointerCapture(event.pointerId);update();
   }
   function pointerMove(event) {
-    if(anchor===null)return;event.preventDefault();const end=nearest(event);
-    input.setSelectionRange(Math.min(anchor,end),Math.max(anchor,end),end<anchor?'backward':'forward');update();
+    if(anchor===null)return;event.preventDefault();const end=nearest(event),map=currentMap();
+    input.setSelectionRange(map.toInput(Math.min(anchor,end)),map.toInput(Math.max(anchor,end)),end<anchor?'backward':'forward');update();
   }
   function pointerUp(event) {if(anchor!==null){anchor=null;if(root.hasPointerCapture(event.pointerId))root.releasePointerCapture(event.pointerId);}}
   function undo(direction) {

package/dist/rich-text-toolbar.js

@@ -47,7 +47,7 @@ export function createRichTextToolbar(root, {editor, report, beforeChange, onPro
   }
   function restore() {
     if (!selected) return;
-    const nodes=[...root.querySelectorAll('text[data-opf-text-start]')].filter(node=>node.closest('[data-opf-path]')?.getAttribute('data-opf-path')===selected.path);
+    const nodes=[...root.querySelectorAll('text[data-opf-text-start],tspan[data-opf-text-start]')].filter(node=>node.closest('[data-opf-path]')?.getAttribute('data-opf-path')===selected.path);
     const a=nodes.find(node=>+node.dataset.opfTextStart<=selected.start&&+node.dataset.opfTextEnd>selected.start);
     const b=nodes.findLast(node=>+node.dataset.opfTextStart<selected.end&&+node.dataset.opfTextEnd>=selected.end);
     if (!a?.firstChild || !b?.firstChild) return;
@@ -101,8 +101,8 @@ export function createRichTextToolbar(root, {editor, report, beforeChange, onPro
     }});
   function endpoint(node,offset) {
     if(node?.nodeType!==3) return null;
-    const element=node.parentElement?.closest('text[data-opf-text-start]');
-    if(!element||!root.contains(element)||element.hasAttribute('data-opf-code-role'))return null;
+    const element=node.parentElement?.closest('text[data-opf-text-start],tspan[data-opf-text-start]');
+    if(!element||!root.contains(element)||element.closest('[data-opf-code-role]'))return null;
     return {path:element.closest('[data-opf-path]')?.getAttribute('data-opf-path'),offset:Number(element.dataset.opfTextStart)+offset};
   }
   function selectionChanged() {

package/dist/rich-text.d.ts

@@ -8,5 +8,5 @@ export declare function richTextContent(value:string|TextRun[]):string;
 /** Nonempty UTF-16 range on grapheme boundaries; null removes an override. */
 export declare function formatRichTextRange(value:string|TextRun[],start:number,end:number,format:TextRunFormat):TextRun[];
 export declare function replaceRichTextRange(value:string|TextRun[],start:number,end:number,replacement:string):TextRun[];
-/** Preserve run metadata across a native input change, on grapheme boundaries. */
+/** Preserve run metadata and untouched source line endings. Change offsets use the textarea's LF-normalized UTF-16 text; inserted newlines follow the source's first ending. */
 export declare function updateRichTextInput(value:string|TextRun[],nextText:string,change?:{start:number;end:number;inputType?:string}):TextRun[];

package/dist/rich-text.js

@@ -1,4 +1,6 @@
-/** UTF-16 ranges match DOM Selection; boundaries must be whole graphemes. */
+import {textInputMap,preferredLineEnding} from './text-input.js';
+
+/** UTF-16 ranges match the source; boundaries must be whole graphemes. */
 export function richTextContent(value) {
   return runs(value).map(run => typeof run === 'string' ? run : run.text).join('');
 }
@@ -72,8 +74,9 @@ export function replaceRichTextRange(value, start, end, replacement) {
 
 /** Map a native plain-text input change back onto styled runs without flattening them. */
 export function updateRichTextInput(value, nextText, change) {
-  const previous = richTextContent(value);
   if (typeof nextText !== 'string') throw new TypeError('Input text must be a string.');
+  const source=richTextContent(value),mapping=textInputMap(source),previous=mapping.text;
+  nextText=nextText.replace(/\r\n|\r/g,'\n');
   if (previous === nextText) return structuredClone(runs(value));
   if (!nextText) return [piece(runs(value)[0] ?? "", "")];
   const segments = text => [...new Intl.Segmenter(undefined, {granularity:'grapheme'}).segment(text)].map(part => part.segment);
@@ -95,12 +98,12 @@ export function updateRichTextInput(value, nextText, change) {
     if (a >= 0 && b >= a && b <= previous.length && nextText.length >= left.length+right.length && nextText.startsWith(left) && nextText.endsWith(right)) {
       // Validate exact native selection boundaries before trusting their affinity.
       try {
-        range(value,a,b,true);
+        range(value,mapping.toSource(a),mapping.toSource(b),true);
         start=a;end=b;replacement=nextText.slice(left.length,nextText.length-right.length);
       } catch { /* Native deletion can split a cluster; use the whole-grapheme diff. */ }
     }
   }
-  const result = replaceRichTextRange(value,start,end,replacement), compact = [];
+  const result = replaceRichTextRange(value,mapping.toSource(start),mapping.toSource(end),replacement.replaceAll('\n',preferredLineEnding(source))), compact = [];
   const style = run => typeof run === 'string' ? null : Object.fromEntries(Object.entries(run).filter(([key]) => key !== 'text').sort(([a],[b]) => a.localeCompare(b)));
   for (const run of result) {
     const last = compact.at(-1);

package/dist/text-input.js

@@ -0,0 +1,33 @@
+/** Map textarea LF offsets to the original UTF-16 source, including CRLF pairs. */
+export function textInputMap(source) {
+  const offsets=[0];
+  for(let i=0;i<source.length;i++) {
+    if(source[i]==='\r'&&source[i+1]==='\n')i++;
+    offsets.push(i+1);
+  }
+  return {
+    text:source.replace(/\r\n|\r/g,'\n'),
+    toSource(offset) {
+      if(!Number.isInteger(offset)||offset<0||offset>=offsets.length)throw new RangeError('Input offset is outside the text.');
+      return offsets[offset];
+    },
+    toInput(offset) {
+      if(!Number.isInteger(offset)||offset<0||offset>source.length)throw new RangeError('Source offset is outside the text.');
+      let lo=0,hi=offsets.length-1;
+      while(lo<hi){const mid=Math.floor((lo+hi)/2);if(offsets[mid]<offset)lo=mid+1;else hi=mid;}
+      return lo;
+    },
+  };
+}
+
+export const preferredLineEnding=source=>/\r\n|\r|\n/.exec(source)?.[0]??'\n';
+
+/** Textareas normalize line endings; retain unchanged source bytes around an edit. */
+export function preserveTextLineEndings(original, input) {
+  const mapping=textInputMap(original),normalized=mapping.text,next=input.replace(/\r\n|\r/g,'\n');
+  if(normalized===next)return original;
+  let prefix=0,suffix=0;
+  while(prefix<normalized.length&&prefix<next.length&&normalized[prefix]===next[prefix])prefix++;
+  while(suffix<normalized.length-prefix&&suffix<next.length-prefix&&normalized[normalized.length-1-suffix]===next[next.length-1-suffix])suffix++;
+  return original.slice(0,mapping.toSource(prefix))+next.slice(prefix,next.length-suffix).replaceAll('\n',preferredLineEnding(original))+original.slice(mapping.toSource(normalized.length-suffix));
+}

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@openpresentation/opf-editor",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Embeddable local OPF editor primitives built on the deterministic renderer.",
   "license": "MIT",
   "type": "module",
   "private": false,
   "engines": {
-    "node": ">=20"
+    "node": "24.x"
   },
   "repository": {
     "type": "git",
@@ -69,26 +69,48 @@
     "./layout": {
       "types": "./dist/layout.d.ts",
       "default": "./dist/layout.js"
+    },
+    "./json-editor": {
+      "types": "./dist/json-editor.d.ts",
+      "default": "./dist/json-editor.js"
+    },
+    "./json-options": {
+      "types": "./dist/json-options.d.ts",
+      "default": "./dist/json-options.js"
     }
   },
   "types": "./dist/index.d.ts",
   "sideEffects": false,
   "scripts": {
     "build": "node scripts/build.mjs",
-    "typecheck": "node --check src/index.js && node --check src/react.js && node --check src/svelte.js && node --check scripts/build.mjs && node --check scripts/validate-package.mjs && node --check test/smoke.mjs && node --check test/component-smoke.mjs && node --check src/canvas.js && node --check src/canvas-fields.js && node --check test/canvas-fields.mjs && node --check test/browser-canvas.mjs && node --check src/transfer.js && node --check src/galleries.js && node --check examples/transfer-controls.js && node --check src/schema.js && node --check src/schema-inspector.js && node --check test/rich-table-browser.mjs && node --check test/styled-table.mjs && node --check test/styled-table-browser.mjs && node --check examples/pptx-controls.js && node --check scripts/build-playground.mjs && node --check test/playground-pptx.mjs",
-    "test": "npm run build && node test/smoke.mjs && node test/component-smoke.mjs && node test/canvas-fields.mjs && node test/transfer.mjs && node test/schema.mjs && node test/rich-text.mjs && node test/layout.mjs && node test/blocks.mjs && node test/styled-table.mjs",
+    "typecheck": "node --check src/index.js && node --check src/react.js && node --check src/svelte.js && node --check scripts/build.mjs && node --check scripts/validate-package.mjs && node --check test/smoke.mjs && node --check test/component-smoke.mjs && node --check src/canvas.js && node --check src/canvas-fields.js && node --check test/canvas-fields.mjs && node --check test/browser-canvas.mjs && node --check src/transfer.js && node --check src/galleries.js && node --check examples/transfer-controls.js && node --check src/schema.js && node --check src/schema-inspector.js && node --check test/rich-table-browser.mjs && node --check test/styled-table.mjs && node --check test/styled-table-browser.mjs && node --check examples/pptx-controls.js && node --check scripts/build-playground.mjs && node --check test/playground-pptx.mjs && node --check src/text-input.js && node --check src/rich-text.js && node --check src/rich-text-input.js && node --check test/rich-text.mjs && node --check test/rich-input-browser.mjs && node --check src/json-editor.js && node --check src/json-menu.js && node --check src/json-options.js && node --check src/json-source.js",
+    "test": "npm run build && node test/accepted-text.mjs && node test/smoke.mjs && node test/component-smoke.mjs && node test/canvas-fields.mjs && node test/transfer.mjs && node test/schema.mjs && node test/rich-text.mjs && node test/layout.mjs && node test/blocks.mjs && node test/styled-table.mjs && node test/json-source.mjs && node test/json-options.mjs",
     "validate": "node scripts/validate-package.mjs",
     "test:packed": "node test/packed-install.mjs",
     "prepack": "npm run build",
     "build:playground": "node scripts/build-playground.mjs",
     "test:playground": "npm run build:playground && node test/playground-pptx.mjs",
-    "test:code-browser": "node test/code-browser.mjs"
+    "test:code-browser": "node test/code-browser.mjs",
+    "test:metric-browser": "node test/metric-browser.mjs",
+    "test:rich-input-browser": "node test/rich-input-browser.mjs",
+    "test:json": "npm run build && node test/json-source.mjs && node test/json-options.mjs",
+    "test:json-browser": "node test/json-editor-browser.mjs"
   },
   "dependencies": {
-    "@openpresentation/opf": "^0.9.0"
+    "@codemirror/autocomplete": "6.20.3",
+    "@codemirror/commands": "6.11.0",
+    "@codemirror/lang-json": "6.0.2",
+    "@codemirror/language": "6.12.4",
+    "@codemirror/lint": "6.9.7",
+    "@codemirror/search": "6.7.2",
+    "@codemirror/state": "6.7.4",
+    "@codemirror/view": "6.43.11",
+    "@lezer/highlight": "1.2.3",
+    "@openpresentation/opf": "^0.10.0",
+    "jsonc-parser": "3.3.1"
   },
   "peerDependencies": {
-    "@openpresentation/opf-render": "^0.7.0"
+    "@openpresentation/opf-render": "^0.8.0"
   },
   "peerDependenciesMeta": {
     "@openpresentation/opf-render": {
@@ -96,8 +118,8 @@
     }
   },
   "devDependencies": {
-    "@openpresentation/opf-pptx": "0.7.0",
-    "@openpresentation/opf-render": "0.7.0",
+    "@openpresentation/opf-pptx": "0.8.0",
+    "@openpresentation/opf-render": "0.8.0",
     "esbuild": "0.28.2",
     "playwright": "1.63.0"
   }