@openpresentation/opf-editor 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenPresentation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,147 @@
+# OPF Editor
+
+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.
+
+## Scope
+
+- Package: `@openpresentation/opf-editor`
+- Repository: `OpenPresentation/opf-editor`
+- License: MIT
+- Compatibility target: `@openpresentation/opf`
+- Renderer relationship: built on `@openpresentation/opf-render` trace output
+- Headless JSON edit bindings for renderer trace attributes
+- Structured catalog controls that only commit known catalog IDs
+- JSON Patch state transitions with inverse patches for undo/redo
+- Optional DOM controls plus React and Svelte bindings in separate embeddable entry points
+
+## Runtime Policy
+
+The package runtime must stay local and deterministic:
+
+- No hosted service in the critical path
+- No telemetry or hidden analytics
+- No commercial SDK dependency in the critical path
+- No required network calls
+- Host applications own auth, storage, queues, analytics, collaboration, branding, and product workflow
+
+## Development
+
+```sh
+npm ci
+npm run build
+npm run typecheck
+npm test
+npm run validate
+```
+
+## Headless Editing
+
+```js
+import {
+  createEditorSession,
+  createSvgTraceBinding
+} from "@openpresentation/opf-editor";
+import { renderSvg } from "@openpresentation/opf-render";
+
+const editor = createEditorSession(opfDocument, { rejectInvalid: true });
+const svg = renderSvg(editor.document, { trace: true });
+
+preview.innerHTML = svg;
+const binding = createSvgTraceBinding(preview.querySelector("svg"), editor, {
+  onSelect(selection) {
+    inspector.open({
+      path: selection.path,
+      value: selection.value,
+      commit(value) {
+        binding.commit(selection.element, value);
+      }
+    });
+  }
+});
+```
+
+Every change returns JSON Patch operations plus inverse operations:
+
+```js
+const change = editor.set("slides.0.title", "Quarterly plan");
+
+change.patches;
+// [{ op: "replace", path: "/slides/0/title", value: "Quarterly plan" }]
+
+change.inversePatches;
+// [{ op: "replace", path: "/slides/0/title", value: "Old title" }]
+
+editor.undo();
+editor.redo();
+```
+
+`createSvgTraceBinding` only reads `data-opf-path`; it does not require a hosted service, a second renderer, storage, analytics, auth, or product chrome. Host applications decide how selected paths appear in their own inspector UI.
+
+## Catalog Controls
+
+Catalog helpers commit catalog IDs from the OPF catalog registry instead of accepting freeform incompatible values:
+
+```js
+import {
+  createCatalogSelect,
+  getCatalogOptions
+} from "@openpresentation/opf-editor";
+
+getCatalogOptions("themes").map((option) => option.id);
+
+const themeSelect = createCatalogSelect(editor, {
+  path: "design.theme",
+  catalogKind: "themes",
+  label: "Theme"
+});
+
+toolbar.append(themeSelect);
+```
+
+Invalid IDs throw before they reach the document. Existing object-form references keep their sibling override fields and replace only `id`.
+
+## 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.
+
+```jsx
+import { createOPFReactComponents } from "@openpresentation/opf-editor/react";
+
+const { OPFTextInput, OPFCatalogSelect } = createOPFReactComponents(React);
+
+function Inspector({ editor }) {
+  return (
+    <>
+      <OPFTextInput editor={editor} path="slides.0.title" label="Slide title" />
+      <OPFCatalogSelect editor={editor} path="design.theme" catalogKind="themes" label="Theme" />
+    </>
+  );
+}
+```
+
+## Optional Svelte Bindings
+
+Svelte bindings are isolated under `@openpresentation/opf-editor/svelte` as actions. They bind host-owned controls, so the package does not ship product chrome or require the Svelte runtime in the core entry point.
+
+```svelte
+<script>
+  import { opfCatalogSelect, opfTextInput } from "@openpresentation/opf-editor/svelte";
+
+  export let editor;
+</script>
+
+<input use:opfTextInput={{ editor, path: "slides.0.title", label: "Slide title" }} />
+<select use:opfCatalogSelect={{ editor, path: "design.theme", catalogKind: "themes", label: "Theme" }} />
+```
+
+## Release Lane
+
+Public npm package publication is handled by `.github/workflows/release.yml` with npm provenance.
+
+Required first-publish setup:
+
+1. An npm owner for the `@openpresentation` scope must run the first publish or reserve/grant the `@openpresentation/opf-editor` package.
+2. Configure npm Trusted Publishing for GitHub repository `OpenPresentation/opf-editor` and workflow `.github/workflows/release.yml`.
+3. Publish by creating a GitHub Release or manually running the Release workflow after CI passes.
+
+This repo does not require an npm automation token when Trusted Publishing is configured.

package/dist/index.d.ts

@@ -0,0 +1,178 @@
+export declare const packageName = "@openpresentation/opf-editor";
+
+export declare const releaseLane: Readonly<{
+  githubRepository: "OpenPresentation/opf-editor";
+  npmPackage: "@openpresentation/opf-editor";
+  compatibilityPackage: "@openpresentation/opf";
+  rendererPackage: "@openpresentation/opf-render";
+}>;
+
+export declare const runtimePolicy: Readonly<{
+  hostedServiceInCriticalPath: false;
+  telemetry: false;
+  commercialSdkInCriticalPath: false;
+  requiredNetworkCalls: false;
+  deterministicLocalExecution: true;
+}>;
+
+export type JsonPatchOperation =
+  | { op: "add"; path: string; value: unknown }
+  | { op: "replace"; path: string; value: unknown }
+  | { op: "remove"; path: string };
+
+export interface OPFValidationSummary {
+  valid: boolean;
+  errors: unknown[];
+  result: unknown;
+}
+
+export interface EditorSnapshot {
+  document: unknown;
+  validation: OPFValidationSummary;
+  canUndo: boolean;
+  canRedo: boolean;
+  undoDepth: number;
+  redoDepth: number;
+}
+
+export interface EditorChange {
+  document: unknown;
+  patches: JsonPatchOperation[];
+  inversePatches?: JsonPatchOperation[];
+  redoPatches?: JsonPatchOperation[];
+  validation: OPFValidationSummary;
+}
+
+export interface EditorEvent {
+  type: "patch" | "undo" | "redo";
+  patches: JsonPatchOperation[];
+  inversePatches?: JsonPatchOperation[];
+  redoPatches?: JsonPatchOperation[];
+  validation: OPFValidationSummary;
+  meta?: Record<string, unknown>;
+  snapshot: EditorSnapshot;
+}
+
+export interface EditorSession {
+  readonly document: unknown;
+  readonly validation: OPFValidationSummary;
+  readonly canUndo: boolean;
+  readonly canRedo: boolean;
+  snapshot(): EditorSnapshot;
+  subscribe(listener: (event: EditorEvent) => void): () => void;
+  get(path: string | string[], fallback?: unknown): unknown;
+  set(path: string | string[], value: unknown, meta?: Record<string, unknown>): EditorChange;
+  setCatalog(path: string | string[], catalogKind: string, id: string, meta?: Record<string, unknown>): EditorChange;
+  applyPatch(operations: JsonPatchOperation[], meta?: Record<string, unknown>): EditorChange;
+  undo(meta?: Record<string, unknown>): EditorChange | null;
+  redo(meta?: Record<string, unknown>): EditorChange | null;
+}
+
+export interface CreateEditorSessionOptions {
+  validate?: (document: unknown) => unknown;
+  rejectInvalid?: boolean;
+}
+
+export interface CatalogOption {
+  id: string;
+  label: string;
+  record: Record<string, unknown>;
+}
+
+export interface CatalogOptionsInput {
+  presentation?: { catalogs?: Record<string, unknown> } | Record<string, unknown>;
+  catalogs?: Record<string, unknown>;
+  catalogSources?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface SvgTraceBinding {
+  elements: unknown[];
+  getPath(element: unknown): string;
+  getValue(elementOrPath: unknown, fallback?: unknown): unknown;
+  select(element: unknown, sourceEvent?: unknown): SvgTraceSelection;
+  commit(elementOrPath: unknown, value: unknown, meta?: Record<string, unknown>): EditorChange;
+  destroy(): void;
+}
+
+export interface SvgTraceSelection {
+  path: string;
+  pointer: string;
+  value: unknown;
+  element: unknown;
+  editor: EditorSession;
+  sourceEvent?: unknown;
+}
+
+export interface SvgTraceBindingOptions {
+  selector?: string;
+  interactive?: boolean;
+  onSelect?: (selection: SvgTraceSelection) => void;
+}
+
+export interface TextInputOptions {
+  path: string;
+  label?: string;
+  multiline?: boolean;
+  type?: string;
+  document?: { createElement(tagName: string): any };
+}
+
+export interface CatalogSelectOptions extends CatalogOptionsInput {
+  path: string;
+  catalogKind: string;
+  label?: string;
+  document?: { createElement(tagName: string): any };
+}
+
+export declare class OPFEditorError extends Error {
+  readonly code: string;
+  readonly details: Record<string, unknown>;
+  readonly path?: unknown;
+  readonly issues?: unknown[];
+  constructor(code: string, message: string, details?: Record<string, unknown>);
+}
+
+export declare function splitOpfPath(path: string | string[]): string[];
+
+export declare function opfPathToJsonPointer(path: string | string[]): string;
+
+export declare function jsonPointerToOpfPath(pointer: string): string;
+
+export declare function getValueAtPath(document: unknown, path: string | string[], fallback?: unknown): unknown;
+
+export declare function hasValueAtPath(document: unknown, path: string | string[]): boolean;
+
+export declare function createValuePatch(document: unknown, path: string | string[], value: unknown): JsonPatchOperation[];
+
+export declare function applyJsonPatch(document: unknown, operations: JsonPatchOperation[]): unknown;
+
+export declare function invertJsonPatch(document: unknown, operations: JsonPatchOperation[]): JsonPatchOperation[];
+
+export declare function validateOpfDocument(document: unknown, validator?: (document: unknown) => unknown): OPFValidationSummary;
+
+export declare function createEditorSession(input: unknown, options?: CreateEditorSessionOptions): EditorSession;
+
+export declare function createSvgTraceBinding(
+  root: { querySelectorAll(selector: string): Iterable<unknown>; matches?: (selector: string) => boolean },
+  editor: EditorSession,
+  options?: SvgTraceBindingOptions
+): SvgTraceBinding;
+
+export declare function getCatalogRecords(catalogKind: string, options?: CatalogOptionsInput): Record<string, unknown>[];
+
+export declare function getCatalogOptions(catalogKind: string, options?: CatalogOptionsInput): CatalogOption[];
+
+export declare function assertCatalogId(catalogKind: string, id: string, options?: CatalogOptionsInput): string;
+
+export declare function setCatalogId(
+  editor: EditorSession,
+  path: string | string[],
+  catalogKind: string,
+  id: string,
+  meta?: CatalogOptionsInput
+): EditorChange;
+
+export declare function createTextInput(editor: EditorSession, options: TextInputOptions): any;
+
+export declare function createCatalogSelect(editor: EditorSession, options: CatalogSelectOptions): any;

package/dist/index.js

@@ -0,0 +1,709 @@
+import {
+  catalogKinds,
+  catalogs as bundledCatalogs,
+  validatePresentation
+} from "@openpresentation/opf";
+
+export const packageName = "@openpresentation/opf-editor";
+
+export const releaseLane = Object.freeze({
+  githubRepository: "OpenPresentation/opf-editor",
+  npmPackage: "@openpresentation/opf-editor",
+  compatibilityPackage: "@openpresentation/opf",
+  rendererPackage: "@openpresentation/opf-render"
+});
+
+export const runtimePolicy = Object.freeze({
+  hostedServiceInCriticalPath: false,
+  telemetry: false,
+  commercialSdkInCriticalPath: false,
+  requiredNetworkCalls: false,
+  deterministicLocalExecution: true
+});
+
+const DATA_OPF_PATH = "data-opf-path";
+const COMPONENT_ATTR = "data-opf-component";
+const SELECT_EVENT = "opfselect";
+const MISSING = Symbol("opf-editor.missing");
+
+export class OPFEditorError extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = "OPFEditorError";
+    this.code = code;
+    this.details = details;
+    if (details.path) this.path = details.path;
+    if (details.issues) this.issues = details.issues;
+  }
+}
+
+export function splitOpfPath(path) {
+  if (Array.isArray(path)) return path.map((segment) => String(segment));
+  if (typeof path !== "string") {
+    throw new OPFEditorError("invalid-path", "OPF path must be a string or segment array.", { path });
+  }
+  if (path === "") return [];
+  if (path.startsWith("/")) return parseJsonPointer(path);
+  return path.split(".").filter(Boolean);
+}
+
+export function opfPathToJsonPointer(path) {
+  const segments = splitOpfPath(path);
+  if (!segments.length) return "";
+  return `/${segments.map(escapePointerSegment).join("/")}`;
+}
+
+export function jsonPointerToOpfPath(pointer) {
+  return parseJsonPointer(pointer).join(".");
+}
+
+export function getValueAtPath(document, path, fallback) {
+  const value = readAtPath(document, splitOpfPath(path));
+  return value === MISSING ? fallback : value;
+}
+
+export function hasValueAtPath(document, path) {
+  return readAtPath(document, splitOpfPath(path)) !== MISSING;
+}
+
+export function createValuePatch(document, path, value) {
+  const pointer = normalizePatchPath(path);
+  return [
+    {
+      op: hasValueAtPath(document, pointer) ? "replace" : "add",
+      path: pointer,
+      value: clone(value)
+    }
+  ];
+}
+
+export function applyJsonPatch(document, operations) {
+  assertPatchOperations(operations);
+  let next = clone(document);
+  for (const operation of operations) {
+    next = applyJsonPatchOperation(next, normalizeOperation(operation));
+  }
+  return next;
+}
+
+export function invertJsonPatch(document, operations) {
+  assertPatchOperations(operations);
+  let current = clone(document);
+  const inverse = [];
+
+  for (const operation of operations.map(normalizeOperation)) {
+    const previous = readAtPath(current, parseJsonPointer(operation.path));
+    if (operation.op !== "add" && previous === MISSING) {
+      throw new OPFEditorError("patch-path-missing", `Cannot invert ${operation.op} for missing path ${operation.path}.`, {
+        path: operation.path,
+        operation
+      });
+    }
+    const addReplacedObjectValue = operation.op === "add" && previous !== MISSING && !pathParentIsArray(current, operation.path);
+    const inversePath = operation.op === "add" ? insertedPathForAdd(operation.path, previous, current) : operation.path;
+
+    current = applyJsonPatchOperation(current, operation);
+
+    if (addReplacedObjectValue) {
+      inverse.unshift({ op: "replace", path: operation.path, value: clone(previous) });
+    } else if (operation.op === "add") {
+      inverse.unshift({ op: "remove", path: inversePath });
+    } else if (operation.op === "replace") {
+      inverse.unshift({ op: "replace", path: operation.path, value: clone(previous) });
+    } else if (operation.op === "remove") {
+      inverse.unshift({ op: "add", path: operation.path, value: clone(previous) });
+    }
+  }
+
+  return inverse;
+}
+
+export function validateOpfDocument(document, validator = validatePresentation) {
+  const result = validator(document);
+  const valid = Boolean(result?.valid);
+  return {
+    valid,
+    errors: Array.isArray(result?.errors) ? result.errors : [],
+    result
+  };
+}
+
+export function createEditorSession(input, options = {}) {
+  let document = parseInput(input);
+  let validation = validateOpfDocument(document, options.validate ?? validatePresentation);
+  const undoStack = [];
+  const redoStack = [];
+  const listeners = new Set();
+  const rejectInvalid = Boolean(options.rejectInvalid);
+
+  function emit(event) {
+    const snapshot = editor.snapshot();
+    for (const listener of listeners) listener({ ...event, snapshot });
+  }
+
+  function commitPatch(operations, meta = {}) {
+    assertPatchOperations(operations);
+    const patches = operations.map(normalizeOperation);
+    const before = document;
+    const inversePatches = invertJsonPatch(before, patches);
+    const next = applyJsonPatch(before, patches);
+    const nextValidation = validateOpfDocument(next, options.validate ?? validatePresentation);
+
+    if ((meta.rejectInvalid ?? rejectInvalid) && !nextValidation.valid) {
+      throw new OPFEditorError("invalid-opf-edit", "OPF edit produced an invalid document.", {
+        issues: nextValidation.errors,
+        patches
+      });
+    }
+
+    document = next;
+    validation = nextValidation;
+    undoStack.push({ patches: clonePatchOperations(patches), inversePatches, meta });
+    redoStack.length = 0;
+    emit({
+      type: "patch",
+      patches: clonePatchOperations(patches),
+      inversePatches: clonePatchOperations(inversePatches),
+      validation,
+      meta
+    });
+
+    return {
+      document: clone(document),
+      patches: clonePatchOperations(patches),
+      inversePatches: clonePatchOperations(inversePatches),
+      validation
+    };
+  }
+
+  const editor = {
+    get document() {
+      return clone(document);
+    },
+    get validation() {
+      return validation;
+    },
+    get canUndo() {
+      return undoStack.length > 0;
+    },
+    get canRedo() {
+      return redoStack.length > 0;
+    },
+    snapshot() {
+      return {
+        document: clone(document),
+        validation,
+        canUndo: undoStack.length > 0,
+        canRedo: redoStack.length > 0,
+        undoDepth: undoStack.length,
+        redoDepth: redoStack.length
+      };
+    },
+    subscribe(listener) {
+      if (typeof listener !== "function") {
+        throw new OPFEditorError("invalid-listener", "Editor listener must be a function.");
+      }
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    get(path, fallback) {
+      return getValueAtPath(document, path, fallback);
+    },
+    set(path, value, meta = {}) {
+      return commitPatch(createValuePatch(document, path, value), {
+        ...meta,
+        path: normalizePatchPath(path)
+      });
+    },
+    setCatalog(path, catalogKind, id, meta = {}) {
+      return setCatalogId(editor, path, catalogKind, id, meta);
+    },
+    applyPatch: commitPatch,
+    undo(meta = {}) {
+      const entry = undoStack.pop();
+      if (!entry) return null;
+      document = applyJsonPatch(document, entry.inversePatches);
+      validation = validateOpfDocument(document, options.validate ?? validatePresentation);
+      redoStack.push(entry);
+      emit({
+        type: "undo",
+        patches: clonePatchOperations(entry.inversePatches),
+        redoPatches: clonePatchOperations(entry.patches),
+        validation,
+        meta
+      });
+      return {
+        document: clone(document),
+        patches: clonePatchOperations(entry.inversePatches),
+        redoPatches: clonePatchOperations(entry.patches),
+        validation
+      };
+    },
+    redo(meta = {}) {
+      const entry = redoStack.pop();
+      if (!entry) return null;
+      document = applyJsonPatch(document, entry.patches);
+      validation = validateOpfDocument(document, options.validate ?? validatePresentation);
+      undoStack.push(entry);
+      emit({
+        type: "redo",
+        patches: clonePatchOperations(entry.patches),
+        inversePatches: clonePatchOperations(entry.inversePatches),
+        validation,
+        meta
+      });
+      return {
+        document: clone(document),
+        patches: clonePatchOperations(entry.patches),
+        inversePatches: clonePatchOperations(entry.inversePatches),
+        validation
+      };
+    }
+  };
+
+  return editor;
+}
+
+export function createSvgTraceBinding(root, editor, options = {}) {
+  assertElementRoot(root);
+  assertEditorSession(editor);
+
+  const selector = options.selector ?? `[${DATA_OPF_PATH}]`;
+  const elements = traceElements(root, selector);
+  const listeners = [];
+
+  function select(element, sourceEvent) {
+    const path = opfPathForElement(element);
+    const detail = {
+      path,
+      pointer: opfPathToJsonPointer(path),
+      value: editor.get(path),
+      element,
+      editor,
+      sourceEvent
+    };
+
+    options.onSelect?.(detail);
+    dispatchOpfEvent(element, SELECT_EVENT, detail);
+    return detail;
+  }
+
+  function commit(elementOrPath, value, meta = {}) {
+    const path = typeof elementOrPath === "string" ? elementOrPath : opfPathForElement(elementOrPath);
+    return editor.set(path, value, {
+      ...meta,
+      source: meta.source ?? "svg-trace"
+    });
+  }
+
+  for (const element of elements) {
+    element.setAttribute?.("data-opf-bound", "true");
+    if (options.interactive !== false) {
+      ensureInteractiveTraceElement(element);
+
+      const onClick = (event) => select(element, event);
+      const onKeydown = (event) => {
+        if (event.key === "Enter" || event.key === " ") {
+          event.preventDefault?.();
+          select(element, event);
+        }
+      };
+
+      element.addEventListener?.("click", onClick);
+      element.addEventListener?.("keydown", onKeydown);
+      listeners.push([element, "click", onClick], [element, "keydown", onKeydown]);
+    }
+  }
+
+  return {
+    elements,
+    getPath: opfPathForElement,
+    getValue(elementOrPath, fallback) {
+      return editor.get(typeof elementOrPath === "string" ? elementOrPath : opfPathForElement(elementOrPath), fallback);
+    },
+    select,
+    commit,
+    destroy() {
+      for (const [element, type, listener] of listeners) {
+        element.removeEventListener?.(type, listener);
+      }
+      listeners.length = 0;
+      for (const element of elements) element.removeAttribute?.("data-opf-bound");
+    }
+  };
+}
+
+export function getCatalogRecords(catalogKind, options = {}) {
+  assertCatalogKind(catalogKind);
+  const presentationCatalog = options.presentation?.catalogs?.[catalogKind];
+  const explicitCatalog = options.catalogs?.[catalogKind] ?? options.catalogSources?.[catalogKind];
+
+  return firstRecords(presentationCatalog)
+    ?? firstRecords(explicitCatalog)
+    ?? firstRecords(bundledCatalogs[catalogKind])
+    ?? [];
+}
+
+export function getCatalogOptions(catalogKind, options = {}) {
+  return getCatalogRecords(catalogKind, options).map((record) => ({
+    id: record.id,
+    label: catalogLabel(record),
+    record
+  }));
+}
+
+export function assertCatalogId(catalogKind, id, options = {}) {
+  assertCatalogKind(catalogKind);
+  if (typeof id !== "string" || id.length === 0) {
+    throw new OPFEditorError("invalid-catalog-id", "Catalog control values must be non-empty catalog IDs.", {
+      catalogKind,
+      id
+    });
+  }
+
+  const optionsById = new Set(getCatalogOptions(catalogKind, options).map((option) => option.id));
+  if (!optionsById.has(id)) {
+    throw new OPFEditorError("unknown-catalog-id", `Unknown ${catalogKind} catalog ID: ${id}.`, {
+      catalogKind,
+      id
+    });
+  }
+
+  return id;
+}
+
+export function setCatalogId(editor, path, catalogKind, id, meta = {}) {
+  assertEditorSession(editor);
+  const catalogId = assertCatalogId(catalogKind, id, {
+    presentation: meta.presentation ?? editor.document,
+    catalogs: meta.catalogs,
+    catalogSources: meta.catalogSources
+  });
+  const current = editor.get(path);
+  const value = catalogReferenceValue(current, catalogId);
+  const { catalogs, catalogSources, presentation, ...commitMeta } = meta;
+  return editor.set(path, value, {
+    ...commitMeta,
+    catalogKind,
+    catalogId,
+    source: commitMeta.source ?? "catalog-control"
+  });
+}
+
+export function createTextInput(editor, options) {
+  assertEditorSession(editor);
+  const documentRef = resolveDomDocument(options?.document);
+  const input = documentRef.createElement(options?.multiline ? "textarea" : "input");
+  const path = options?.path;
+  if (!path) throw new OPFEditorError("missing-path", "Text input requires an OPF path.");
+
+  input.setAttribute(COMPONENT_ATTR, "text-input");
+  input.setAttribute(DATA_OPF_PATH, path);
+  if (!options?.multiline) input.setAttribute("type", options?.type ?? "text");
+  if (options?.label) input.setAttribute("aria-label", options.label);
+
+  const updateValue = () => {
+    const nextValue = editor.get(path, "");
+    input.value = nextValue === undefined || nextValue === null ? "" : String(nextValue);
+  };
+  const onInput = () => {
+    editor.set(path, input.value, { source: "text-input" });
+  };
+  const unsubscribe = editor.subscribe(updateValue);
+
+  input.addEventListener?.("input", onInput);
+  input.destroy = () => {
+    input.removeEventListener?.("input", onInput);
+    unsubscribe();
+  };
+  updateValue();
+  return input;
+}
+
+export function createCatalogSelect(editor, options) {
+  assertEditorSession(editor);
+  const documentRef = resolveDomDocument(options?.document);
+  const select = documentRef.createElement("select");
+  const path = options?.path;
+  const catalogKind = options?.catalogKind;
+  if (!path) throw new OPFEditorError("missing-path", "Catalog select requires an OPF path.");
+  assertCatalogKind(catalogKind);
+
+  select.setAttribute(COMPONENT_ATTR, "catalog-select");
+  select.setAttribute(DATA_OPF_PATH, path);
+  select.setAttribute("data-opf-catalog-kind", catalogKind);
+  if (options?.label) select.setAttribute("aria-label", options.label);
+
+  for (const option of getCatalogOptions(catalogKind, {
+    ...options,
+    presentation: options?.presentation ?? editor.document
+  })) {
+    const optionElement = documentRef.createElement("option");
+    optionElement.value = option.id;
+    optionElement.textContent = option.label;
+    select.appendChild(optionElement);
+  }
+
+  const updateValue = () => {
+    const current = editor.get(path);
+    select.value = typeof current === "object" && current ? current.id : current ?? "";
+  };
+  const onChange = () => {
+    setCatalogId(editor, path, catalogKind, select.value, {
+      catalogs: options?.catalogs,
+      catalogSources: options?.catalogSources,
+      presentation: options?.presentation,
+      source: "catalog-select"
+    });
+  };
+  const unsubscribe = editor.subscribe(updateValue);
+
+  select.addEventListener?.("change", onChange);
+  select.destroy = () => {
+    select.removeEventListener?.("change", onChange);
+    unsubscribe();
+  };
+  updateValue();
+  return select;
+}
+
+function parseInput(input) {
+  if (typeof input === "string") {
+    try {
+      return JSON.parse(input);
+    } catch (error) {
+      throw new OPFEditorError("invalid-json", "OPF input is not valid JSON.", {
+        cause: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
+
+  if (input instanceof Uint8Array) {
+    return parseInput(new TextDecoder().decode(input));
+  }
+
+  if (input && typeof input === "object") return clone(input);
+
+  throw new OPFEditorError("invalid-input", "OPF input must be a parsed object, JSON string, or Uint8Array.");
+}
+
+function clone(value) {
+  if (value === undefined) return undefined;
+  return JSON.parse(JSON.stringify(value));
+}
+
+function clonePatchOperations(operations) {
+  return operations.map((operation) => clone(operation));
+}
+
+function escapePointerSegment(segment) {
+  return String(segment).replaceAll("~", "~0").replaceAll("/", "~1");
+}
+
+function unescapePointerSegment(segment) {
+  return segment.replaceAll("~1", "/").replaceAll("~0", "~");
+}
+
+function parseJsonPointer(pointer) {
+  if (pointer === "") return [];
+  if (typeof pointer !== "string" || !pointer.startsWith("/")) {
+    throw new OPFEditorError("invalid-json-pointer", "JSON Patch paths must be JSON Pointers.", { path: pointer });
+  }
+  return pointer.slice(1).split("/").map(unescapePointerSegment);
+}
+
+function normalizePatchPath(path) {
+  return typeof path === "string" && path.startsWith("/") ? path : opfPathToJsonPointer(path);
+}
+
+function normalizeOperation(operation) {
+  if (!operation || typeof operation !== "object") {
+    throw new OPFEditorError("invalid-patch-operation", "JSON Patch operation must be an object.", { operation });
+  }
+  if (!["add", "replace", "remove"].includes(operation.op)) {
+    throw new OPFEditorError("unsupported-patch-operation", `Unsupported JSON Patch operation: ${operation.op}.`, {
+      operation
+    });
+  }
+  const normalized = {
+    op: operation.op,
+    path: normalizePatchPath(operation.path)
+  };
+  if (operation.op !== "remove") normalized.value = clone(operation.value);
+  return normalized;
+}
+
+function assertPatchOperations(operations) {
+  if (!Array.isArray(operations)) {
+    throw new OPFEditorError("invalid-patch", "JSON Patch must be an array of operations.", { operations });
+  }
+}
+
+function readAtPath(document, segments) {
+  let current = document;
+  for (const segment of segments) {
+    if (Array.isArray(current)) {
+      if (segment === "-") return MISSING;
+      const index = Number(segment);
+      if (!Number.isInteger(index) || index < 0 || index >= current.length) return MISSING;
+      current = current[index];
+    } else if (current && typeof current === "object" && Object.prototype.hasOwnProperty.call(current, segment)) {
+      current = current[segment];
+    } else {
+      return MISSING;
+    }
+  }
+  return current;
+}
+
+function applyJsonPatchOperation(document, operation) {
+  const segments = parseJsonPointer(operation.path);
+  if (segments.length === 0) {
+    if (operation.op === "remove") return undefined;
+    return clone(operation.value);
+  }
+
+  const next = clone(document);
+  const parent = readAtPath(next, segments.slice(0, -1));
+  const key = segments.at(-1);
+
+  if (parent === MISSING || parent === null || typeof parent !== "object") {
+    throw new OPFEditorError("patch-parent-missing", `Patch parent does not exist for ${operation.path}.`, {
+      path: operation.path,
+      operation
+    });
+  }
+
+  if (Array.isArray(parent)) applyArrayOperation(parent, key, operation);
+  else applyObjectOperation(parent, key, operation);
+
+  return next;
+}
+
+function insertedPathForAdd(path, previous, document) {
+  if (previous !== MISSING || !path.endsWith("/-")) return path;
+  const parentPath = path.slice(0, -2);
+  const parent = readAtPath(document, parseJsonPointer(parentPath));
+  if (!Array.isArray(parent)) return path;
+  return `${parentPath}/${parent.length}`;
+}
+
+function pathParentIsArray(document, path) {
+  const segments = parseJsonPointer(path);
+  if (segments.length === 0) return false;
+  const parent = readAtPath(document, segments.slice(0, -1));
+  return Array.isArray(parent);
+}
+
+function applyArrayOperation(parent, key, operation) {
+  const index = key === "-" ? parent.length : Number(key);
+  if (!Number.isInteger(index) || index < 0 || index > parent.length) {
+    throw new OPFEditorError("invalid-array-index", `Invalid array index in patch path ${operation.path}.`, {
+      path: operation.path,
+      operation
+    });
+  }
+
+  if (operation.op === "add") {
+    parent.splice(index, 0, clone(operation.value));
+    return;
+  }
+
+  if (index >= parent.length) {
+    throw new OPFEditorError("patch-path-missing", `Patch path does not exist: ${operation.path}.`, {
+      path: operation.path,
+      operation
+    });
+  }
+
+  if (operation.op === "replace") parent[index] = clone(operation.value);
+  else parent.splice(index, 1);
+}
+
+function applyObjectOperation(parent, key, operation) {
+  if (operation.op === "add") {
+    parent[key] = clone(operation.value);
+    return;
+  }
+
+  if (!Object.prototype.hasOwnProperty.call(parent, key)) {
+    throw new OPFEditorError("patch-path-missing", `Patch path does not exist: ${operation.path}.`, {
+      path: operation.path,
+      operation
+    });
+  }
+
+  if (operation.op === "replace") parent[key] = clone(operation.value);
+  else delete parent[key];
+}
+
+function assertElementRoot(root) {
+  if (!root || typeof root !== "object" || typeof root.querySelectorAll !== "function") {
+    throw new OPFEditorError("invalid-root", "SVG trace binding requires a root element with querySelectorAll.");
+  }
+}
+
+function assertEditorSession(editor) {
+  if (!editor || typeof editor.get !== "function" || typeof editor.set !== "function" || typeof editor.subscribe !== "function") {
+    throw new OPFEditorError("invalid-editor", "Expected an editor session created by createEditorSession.");
+  }
+}
+
+function traceElements(root, selector) {
+  const elements = Array.from(root.querySelectorAll(selector));
+  if (typeof root.matches === "function" && root.matches(selector)) elements.unshift(root);
+  return elements;
+}
+
+function opfPathForElement(element) {
+  const path = element?.getAttribute?.(DATA_OPF_PATH);
+  if (!path) throw new OPFEditorError("missing-opf-path", "Element does not have a data-opf-path attribute.");
+  return path;
+}
+
+function ensureInteractiveTraceElement(element) {
+  if (!element.hasAttribute?.("tabindex")) element.setAttribute?.("tabindex", "0");
+  if (!element.hasAttribute?.("role")) element.setAttribute?.("role", "button");
+}
+
+function dispatchOpfEvent(element, type, detail) {
+  if (typeof element.dispatchEvent !== "function" || typeof globalThis.CustomEvent !== "function") return;
+  element.dispatchEvent(new CustomEvent(type, { bubbles: true, detail }));
+}
+
+function assertCatalogKind(catalogKind) {
+  if (!catalogKinds.includes(catalogKind)) {
+    throw new OPFEditorError("unknown-catalog-kind", `Unknown OPF catalog kind: ${catalogKind}.`, {
+      catalogKind
+    });
+  }
+}
+
+function firstRecords(value) {
+  if (Array.isArray(value)) return value.filter(isCatalogRecord);
+  if (Array.isArray(value?.records)) return value.records.filter(isCatalogRecord);
+  return null;
+}
+
+function isCatalogRecord(record) {
+  return Boolean(record && typeof record === "object" && typeof record.id === "string");
+}
+
+function catalogLabel(record) {
+  return String(record.name ?? record.title ?? record.label ?? record.id);
+}
+
+function catalogReferenceValue(current, id) {
+  if (current && typeof current === "object" && !Array.isArray(current)) {
+    return { ...current, id };
+  }
+  return id;
+}
+
+function resolveDomDocument(documentRef) {
+  const resolved = documentRef ?? globalThis.document;
+  if (!resolved || typeof resolved.createElement !== "function") {
+    throw new OPFEditorError("missing-document", "DOM components require a document-like object.");
+  }
+  return resolved;
+}

package/dist/react.d.ts

@@ -0,0 +1,31 @@
+import type { EditorSession, CatalogOption } from "./index.js";
+
+export interface OPFTextInputProps {
+  editor: EditorSession;
+  path: string;
+  label?: string;
+  multiline?: boolean;
+  inputProps?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface OPFCatalogSelectProps {
+  editor: EditorSession;
+  path: string;
+  catalogKind: string;
+  label?: string;
+  catalogOptions?: CatalogOption[];
+  selectProps?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export declare function createOPFReactComponents(React: {
+  createElement: (...args: unknown[]) => unknown;
+  useSyncExternalStore?: (...args: unknown[]) => unknown;
+  useState?: (...args: unknown[]) => unknown;
+  useEffect?: (...args: unknown[]) => unknown;
+}): {
+  useEditorSnapshot(editor: EditorSession): unknown;
+  OPFTextInput(props: OPFTextInputProps): unknown;
+  OPFCatalogSelect(props: OPFCatalogSelectProps): unknown;
+};

package/dist/react.js

@@ -0,0 +1,94 @@
+import {
+  getCatalogOptions,
+  getValueAtPath,
+  setCatalogId
+} from "./index.js";
+
+export function createOPFReactComponents(React) {
+  if (!React || typeof React.createElement !== "function") {
+    throw new TypeError("createOPFReactComponents requires a React-compatible object.");
+  }
+
+  function useEditorSnapshot(editor) {
+    if (typeof React.useSyncExternalStore === "function") {
+      return React.useSyncExternalStore(
+        (notify) => editor.subscribe(notify),
+        () => editor.snapshot(),
+        () => editor.snapshot()
+      );
+    }
+
+    const [snapshot, setSnapshot] = React.useState(editor.snapshot());
+    React.useEffect(() => editor.subscribe(() => setSnapshot(editor.snapshot())), [editor]);
+    return snapshot;
+  }
+
+  function OPFTextInput({
+    editor,
+    path,
+    label,
+    multiline = false,
+    inputProps = {},
+    ...props
+  }) {
+    const snapshot = useEditorSnapshot(editor);
+    const value = getValueAtPath(snapshot.document, path, "");
+    const tag = multiline ? "textarea" : "input";
+    return React.createElement(tag, {
+      ...props,
+      ...inputProps,
+      "aria-label": label ?? props["aria-label"] ?? inputProps["aria-label"],
+      "data-opf-component": "text-input",
+      "data-opf-path": path,
+      type: multiline ? undefined : props.type ?? inputProps.type ?? "text",
+      value: value === undefined || value === null ? "" : String(value),
+      onChange(event) {
+        inputProps.onChange?.(event);
+        props.onChange?.(event);
+        if (!event.defaultPrevented) editor.set(path, event.currentTarget.value, { source: "react-text-input" });
+      }
+    });
+  }
+
+  function OPFCatalogSelect({
+    editor,
+    path,
+    catalogKind,
+    label,
+    catalogOptions,
+    selectProps = {},
+    ...props
+  }) {
+    const snapshot = useEditorSnapshot(editor);
+    const value = getValueAtPath(snapshot.document, path, "");
+    const currentId = value && typeof value === "object" ? value.id : value;
+    const options = catalogOptions ?? getCatalogOptions(catalogKind, { presentation: snapshot.document });
+
+    return React.createElement(
+      "select",
+      {
+        ...props,
+        ...selectProps,
+        "aria-label": label ?? props["aria-label"] ?? selectProps["aria-label"],
+        "data-opf-component": "catalog-select",
+        "data-opf-catalog-kind": catalogKind,
+        "data-opf-path": path,
+        value: currentId ?? "",
+        onChange(event) {
+          selectProps.onChange?.(event);
+          props.onChange?.(event);
+          if (!event.defaultPrevented) {
+            setCatalogId(editor, path, catalogKind, event.currentTarget.value, { source: "react-catalog-select" });
+          }
+        }
+      },
+      options.map((option) => React.createElement("option", { key: option.id, value: option.id }, option.label))
+    );
+  }
+
+  return {
+    useEditorSnapshot,
+    OPFTextInput,
+    OPFCatalogSelect
+  };
+}

package/dist/svelte.d.ts

@@ -0,0 +1,29 @@
+import type { CatalogOptionsInput, EditorSession, SvgTraceBindingOptions } from "./index.js";
+
+export interface OPFTextInputActionParams {
+  editor: EditorSession;
+  path: string;
+  label?: string;
+}
+
+export interface OPFCatalogSelectActionParams extends CatalogOptionsInput {
+  editor: EditorSession;
+  path: string;
+  catalogKind: string;
+  label?: string;
+}
+
+export interface OPFTraceActionParams extends SvgTraceBindingOptions {
+  editor: EditorSession;
+}
+
+export interface SvelteAction {
+  update(params: unknown): void;
+  destroy(): void;
+}
+
+export declare function opfTextInput(node: any, params: OPFTextInputActionParams): SvelteAction;
+
+export declare function opfCatalogSelect(node: any, params: OPFCatalogSelectActionParams): SvelteAction;
+
+export declare function opfTrace(node: any, params: OPFTraceActionParams): SvelteAction;

package/dist/svelte.js

@@ -0,0 +1,112 @@
+import {
+  createSvgTraceBinding,
+  getCatalogOptions,
+  setCatalogId
+} from "./index.js";
+
+export function opfTextInput(node, params) {
+  let cleanup = () => {};
+
+  function connect(nextParams) {
+    cleanup();
+    const { editor, path, label } = nextParams;
+    node.setAttribute?.("data-opf-component", "text-input");
+    node.setAttribute?.("data-opf-path", path);
+    if (label) node.setAttribute?.("aria-label", label);
+
+    const sync = () => {
+      const value = editor.get(path, "");
+      node.value = value === undefined || value === null ? "" : String(value);
+    };
+    const onInput = () => editor.set(path, node.value, { source: "svelte-text-input" });
+    const unsubscribe = editor.subscribe(sync);
+
+    node.addEventListener?.("input", onInput);
+    sync();
+    cleanup = () => {
+      node.removeEventListener?.("input", onInput);
+      unsubscribe();
+    };
+  }
+
+  connect(params);
+
+  return {
+    update: connect,
+    destroy() {
+      cleanup();
+    }
+  };
+}
+
+export function opfCatalogSelect(node, params) {
+  let cleanup = () => {};
+
+  function connect(nextParams) {
+    cleanup();
+    const { editor, path, catalogKind, label } = nextParams;
+    node.setAttribute?.("data-opf-component", "catalog-select");
+    node.setAttribute?.("data-opf-path", path);
+    node.setAttribute?.("data-opf-catalog-kind", catalogKind);
+    if (label) node.setAttribute?.("aria-label", label);
+    replaceOptions(node, getCatalogOptions(catalogKind, {
+      catalogs: nextParams.catalogs,
+      catalogSources: nextParams.catalogSources,
+      presentation: nextParams.presentation ?? editor.document
+    }));
+
+    const sync = () => {
+      const value = editor.get(path);
+      node.value = value && typeof value === "object" ? value.id : value ?? "";
+    };
+    const onChange = () => setCatalogId(editor, path, catalogKind, node.value, {
+      catalogs: nextParams.catalogs,
+      catalogSources: nextParams.catalogSources,
+      presentation: nextParams.presentation,
+      source: "svelte-catalog-select"
+    });
+    const unsubscribe = editor.subscribe(sync);
+
+    node.addEventListener?.("change", onChange);
+    sync();
+    cleanup = () => {
+      node.removeEventListener?.("change", onChange);
+      unsubscribe();
+    };
+  }
+
+  connect(params);
+
+  return {
+    update: connect,
+    destroy() {
+      cleanup();
+    }
+  };
+}
+
+export function opfTrace(node, params) {
+  let binding = createSvgTraceBinding(node, params.editor, params);
+
+  return {
+    update(nextParams) {
+      binding.destroy();
+      binding = createSvgTraceBinding(node, nextParams.editor, nextParams);
+    },
+    destroy() {
+      binding.destroy();
+    }
+  };
+}
+
+function replaceOptions(node, options) {
+  while (node.firstChild) node.removeChild(node.firstChild);
+
+  const documentRef = node.ownerDocument ?? globalThis.document;
+  for (const option of options) {
+    const optionElement = documentRef.createElement("option");
+    optionElement.value = option.id;
+    optionElement.textContent = option.label;
+    node.appendChild(optionElement);
+  }
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@openpresentation/opf-editor",
+  "version": "0.0.1",
+  "description": "Embeddable local OPF editor primitives built on the deterministic renderer.",
+  "license": "MIT",
+  "type": "module",
+  "private": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OpenPresentation/opf-editor.git"
+  },
+  "bugs": {
+    "url": "https://github.com/OpenPresentation/opf-editor/issues"
+  },
+  "homepage": "https://github.com/OpenPresentation/opf-editor#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
+    },
+    "./svelte": {
+      "types": "./dist/svelte.d.ts",
+      "default": "./dist/svelte.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "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",
+    "test": "npm run build && node test/smoke.mjs && node test/component-smoke.mjs",
+    "validate": "node scripts/validate-package.mjs",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@openpresentation/opf": "^0.2.2"
+  },
+  "peerDependencies": {
+    "@openpresentation/opf-render": ">=0.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@openpresentation/opf-render": {
+      "optional": true
+    }
+  }
+}