@barocss/math-editor 0.1.0 → 0.2.0

package/ADAPTERS.md

@@ -1,5 +1,12 @@
 # Framework adapters and embedding
 
+## Framework-specific API guides
+
+[Pure JavaScript](API-JAVASCRIPT.md) · [React](API-REACT.md) · [Web Component](API-WEB-COMPONENT.md) · [Vue 3](API-VUE.md) · [Svelte](API-SVELTE.md) · [Solid](API-SOLID.md) · [Session and DOM API](API-SESSION.md)
+
+Each guide covers installation, a complete integration, document replacement, saving, lifecycle cleanup and host limitations.
+
+
 ## Distribution architecture
 
 One ESM npm package exposes independent entry points. This keeps document types, commands and clipboard formats on one version. Six separate npm packages are unnecessary until independently versioned adapters are useful.
@@ -147,7 +154,7 @@ The directive reads its accessor in a reactive effect and cleans up with `onClea
 | Composition candidate preview | Disabled choices while composing | Menu hidden while composing |
 | Keyboard model ranges / OS IME matrix / full accessibility audit | Pending | Pending |
 
-The native renderer is an integration preview, not a replacement of the rich React editor. Completing parity before switching the main entry is the next release gate. Trusted document loading still needs schema/ID validation. LaTeX is export-only; plain-text paste is not a LaTeX parser.
+The native renderer is an integration preview, not a replacement of the rich React editor. Completing parity before switching the main entry is the next release gate. Use `parseMathDocument` to validate schema and IDs before trusted document loading. Bounded LaTeX import is available through `importLatex`; ordinary plain-text paste remains literal.
 
 ## Local verification and packaging
 
@@ -160,7 +167,7 @@ pnpm --filter @barocss/math-demo test:e2e
 pnpm --filter @barocss/math-demo build
 # Inspect a tarball locally; this does not publish:
 pnpm --dir packages/math-editor pack --pack-destination /tmp/math-editor-package
-node packages/math-editor/scripts/check-package.mjs /tmp/math-editor-package/barocss-math-editor-0.1.0.tgz
+node packages/math-editor/scripts/check-package.mjs /tmp/math-editor-package/barocss-math-editor-0.2.0.tgz
 ```
 
 Release work still includes package ownership/versioning, an explicit release decision, supported-browser and framework-version CI, bundle budgets and renderer parity. No registry publication has been performed.
@@ -168,3 +175,25 @@ Release work still includes package ownership/versioning, an explicit release de
 ## Independent outputs and host completion
 
 The DOM entry also exports `mountMathLatex` and `mountMathPreview`. See [Embedding](EMBEDDING.md) for the four-surface composition contract, native `enterBehavior`/`onCommit`/`onCancel`, popup draft handling and Note-style next-block creation. The rich React editor adds `toolbar`, `toolbarEnd` and `showTokenLegend`; its dedicated single-line/host-completion API remains the native `MathEditorSurface`.
+
+## Compact and filtered toolbars (workspace)
+
+Toolbars initially show up to eight structure buttons. More tools / Fewer tools toggles the remainder without changing the formula or history. Rich React also places matrix presets, templates and symbol shortcuts in the expanded section; Undo, Redo and `toolbarEnd` stay visible. Native toolbars contain structure buttons and history only and show a toggle when needed. The layout wraps naturally on narrow screens; this is not a guaranteed single-row toolbar.
+
+```tsx
+<MathEditor toolbar={['fraction', 'root', 'superscript', 'matrix']}
+  toolbarMaxItems={3} />
+```
+
+```js
+mountMathEditor(host, session, {
+  toolbar: ['fraction', 'root', 'norm'],
+  toolbarMaxItems: 2,
+});
+mountMathToolbar(toolbarHost, session, {
+  kinds: ['fraction', 'root', 'norm'],
+  maxItems: 2,
+});
+```
+
+`toolbar: false` hides the toolbar. A structure array filters its structure buttons only: it does not disable those structures in suggestions, parsing or the model, and does not filter React's auxiliary template/symbol controls. `toolbarMaxItems` (independent toolbar: `maxItems`) is a nonnegative count; zero initially hides all structure buttons behind More. A sufficiently large count shows all selected structure buttons initially. Expanded state belongs to the mounted toolbar and is not saved in the math document. The rich React `toolbar` array and compact behavior are available in 0.2.0.

package/API-JAVASCRIPT.md

@@ -0,0 +1,157 @@
+# Pure JavaScript API guide
+
+Use this integration for vanilla JavaScript, custom application shells and imperative editor hosts. Neither `/core` nor `/dom` imports React. Examples assume an ESM bundler such as Vite; the package does not provide a global script/IIFE build.
+
+## Install
+
+```sh
+npm install @barocss/math-editor@0.2.0
+```
+
+## Mount a complete editor
+
+Create `<div id="formula"></div><pre id="latex"></pre>` in your page, then run this module after those elements exist:
+
+```js
+import { createMathSession } from '@barocss/math-editor/core';
+import { mountMathEditor } from '@barocss/math-editor/dom';
+import '@barocss/math-editor/style.css';
+
+const host = document.querySelector('#formula');
+const output = document.querySelector('#latex');
+if (!(host instanceof HTMLElement) || !output) throw new Error('Missing editor host');
+
+const session = createMathSession({ locale: 'en', mode: 'block' });
+const editor = mountMathEditor(host, {
+  session,
+  toolbar: true,
+  onChange(document, latex) {
+    localStorage.setItem('formula', JSON.stringify(document));
+    output.textContent = latex;
+  },
+});
+editor.focus();
+
+// Call when your route/component is removed.
+function dispose() {
+  editor.destroy();
+  session.destroy();
+}
+```
+
+Creating a session is optional: without `session`, the renderer creates and owns one, accessible as `editor.session`. In that case `editor.destroy()` also releases the owned session.
+
+## Open, update and execute
+
+```js
+// savedDocument must have been validated by your host.
+session.load(savedDocument); // resets undo history
+editor.update({ locale: 'ko', toolbar: false });
+session.execute({ type: 'text', value: 'α' });
+session.execute({ type: 'structure', kind: 'fraction' });
+session.execute({ type: 'undo' });
+const snapshot = session.getSnapshot();
+console.log(snapshot.latex, snapshot.canUndo);
+```
+
+These snippets continue the mounted example. `defaultValue`, `session` and `menuHost` are read at mount; use `load()` rather than changing `defaultValue`. `update()` merges options: pass `false` explicitly to hide a toolbar.
+
+## External toolbar
+
+Create a separate `#tools` element. It can sit beside the document or in a floating panel:
+
+```js
+import { mountMathToolbar } from '@barocss/math-editor/dom';
+const toolsHost = document.querySelector('#tools');
+if (!(toolsHost instanceof HTMLElement)) throw new Error('Missing toolbar host');
+const tools = mountMathToolbar(toolsHost, session, {
+  kinds: ['fraction', 'root', 'superscript'],
+  onExecute: () => editor.focus(),
+});
+// Include this in dispose(), before destroying editor/session:
+// tools.destroy();
+```
+
+A toolbar kind list controls the visible buttons, not which structures may exist in a document. Validate the final model if your product supports only a subset.
+
+## Inline and popup hosting
+
+Set `mode: 'inline'` for a single top-level row and `toolbar: false` for an editor-only surface. Inline equations may still be tall, for example fractions or matrices. Inline Enter first accepts a suggestion; otherwise it invokes `onCommit(snapshot)` or `onExit(1)`. `onExit(-1 | 1)` asks your host to restore its caret before/after the equation.
+
+For a popup, create a draft session from a copy of the original document. Commit `session.getSnapshot().state.document` only after Apply. Cancel destroys the draft without modifying the original. Set `menuHost` to your modal element if your modal's focus trap needs suggestion menus inside it. See the complete [popup composition](EMBEDDING.md).
+
+## Common mistakes
+
+- Importing the package root in a React-free application: use `/core` and `/dom` instead.
+- Mounting before an element exists or re-mounting on each keystroke.
+- Saving every `subscribe` callback: caret and locale changes also emit; check `documentChanged`.
+- Treating LaTeX output as a source document or a computation API.
+
+## Complete modal: Apply, Cancel and focus restoration
+
+This function creates its own native dialog and draft. Call it from a user action with a trusted document. It resolves to a new document on Apply, or `undefined` on Cancel. No host document changes while typing. Block mode permits multiline formulas; use inline mode only when the source is single-row.
+
+```js
+import { createMathSession } from '@barocss/math-editor/core';
+import { mountMathEditor } from '@barocss/math-editor/dom';
+import '@barocss/math-editor/style.css';
+
+export function editFormula(original) {
+  const previousFocus = document.activeElement;
+  const dialog = document.createElement('dialog');
+  const title = document.createElement('h2');
+  title.textContent = 'Edit formula';
+  const titleId = `formula-${crypto.randomUUID()}`;
+  title.id = titleId;
+  dialog.setAttribute('aria-labelledby', titleId);
+  const host = document.createElement('div');
+  const apply = document.createElement('button');
+  const cancel = document.createElement('button');
+  apply.textContent = 'Apply';
+  cancel.textContent = 'Cancel';
+  apply.type = cancel.type = 'button';
+  dialog.append(title, host, cancel, apply);
+  document.body.append(dialog);
+  const session = createMathSession({ document: original, locale: 'en' });
+
+  return new Promise(resolve => {
+    let finished = false;
+    const finish = accepted => {
+      if (finished) return;
+      finished = true;
+      const result = accepted ? session.getSnapshot().state.document : undefined;
+      editor.destroy();
+      session.destroy();
+      dialog.close();
+      dialog.remove();
+      if (previousFocus instanceof HTMLElement && previousFocus.isConnected)
+        previousFocus.focus();
+      resolve(result);
+    };
+    const editor = mountMathEditor(host, {
+      session,
+      menuHost: dialog,
+      onCancel: () => finish(false),
+    });
+    apply.addEventListener('click', () => finish(true));
+    cancel.addEventListener('click', () => finish(false));
+    dialog.addEventListener('cancel', event => {
+      event.preventDefault();
+      finish(false);
+    });
+    dialog.addEventListener('close', () => finish(false));
+    dialog.showModal();
+    editor.focus();
+  });
+}
+```
+
+Use `const next = await editFormula(currentDocument); if (next) commitToHost(next);` in your host's click handler. `currentDocument` and `commitToHost` belong to your application. Commit as one host undo transaction. For route teardown while a modal is open, close the dialog before removing its DOM so the `close` handler releases the draft.
+
+## Persistence and ownership
+
+Persist the `MathDocument` passed to `onChange`; LaTeX is derived output and is not an editable round-trip format. The package does not parse arbitrary LaTeX. Validate externally supplied JSON before loading it: loading assumes a trusted, structurally valid document with unique IDs. There is no server save or collaboration transport built in.
+
+Keep the mount host empty. The editor owns its descendants; framework rendering into the same host can destroy caret and composition state. Use one editing surface per session. Destroy the renderer on teardown; a session supplied by the host remains the host's responsibility.
+
+See [session and DOM API](API-SESSION.md) for exact options, commands, events and cleanup, and [renderer differences](ADAPTERS.md#current-renderer-parity) before choosing a native wrapper over the rich React editor.

package/API-REACT.md

@@ -0,0 +1,202 @@
+# React API guide
+
+React offers two components. Choose intentionally: they share document structure, but do not share a live session or renderer.
+
+| Component | Use it for | State ownership |
+|---|---|---|
+| `MathEditor` | Rich symbol browser, token editing and selection tools | Internal React history; `defaultValue` is mount-only |
+| `MathEditorSurface` | Native inline mode, external session/tools, host commit/cancel | DOM renderer with optional host-owned `MathSession` |
+
+## Install
+
+```sh
+npm install @barocss/math-editor@0.2.0 react react-dom
+```
+
+## Rich editor
+
+```tsx
+import { MathEditor } from '@barocss/math-editor/react';
+import { createMathDocument, type MathDocument } from '@barocss/math-editor/core';
+import '@barocss/math-editor/style.css';
+
+export function Formula({ id, saved, onSave }: {
+  id: string;
+  saved?: MathDocument;
+  onSave: (document: MathDocument, latex: string) => void;
+}) {
+  return <MathEditor
+    key={id}
+    locale="en"
+    defaultValue={saved ?? createMathDocument()}
+    onChange={onSave}
+    showTokenLegend={false}
+    label="Formula editor"
+  />;
+}
+```
+
+Changing `saved` alone does not replace the document. Change `key` when opening a different document; do not change it on every save. There is no controlled `value` prop or `session` prop on this component. `onChange` reports committed model edits, not IME drafts.
+
+## Rich component props in 0.2.0
+
+| Prop | Default / behavior |
+|---|---|
+| `defaultValue` | Optional `MathDocument`, read once |
+| `locale` | `ko`; locale changes preserve history |
+| `toolbar` | `true`; hides/shows all rich toolbar panels |
+| `toolbarEnd` | Optional React content appended to tools |
+| `showTokenLegend` | `true` |
+| `showLineNumbers` | `true`; UI-only multiline gutter |
+| `label` | Localized default accessible group label |
+| `onChange(document, latex)` | Save the document; LaTeX is derived |
+| `onExit(direction)` | Host focus restoration request, `-1` or `1` |
+
+Version 0.2.0 supports `excludedStructures` and `multiline` on the rich component, plus configurable `toolbar` kinds and `toolbarMaxItems`.
+
+## Native surface
+
+```tsx
+import { MathEditorSurface } from '@barocss/math-editor/react';
+import type { MathDocument } from '@barocss/math-editor/core';
+import '@barocss/math-editor/style.css';
+
+export function InlineFormula({ onSave, onExit }: {
+  onSave: (document: MathDocument, latex: string) => void;
+  onExit: (direction: -1 | 1) => void;
+}) {
+  return <MathEditorSurface
+    locale="en"
+    mode="inline"
+    toolbar={false}
+    onChange={onSave}
+    onCommit={() => onExit(1)}
+    onExit={onExit}
+  />;
+}
+```
+
+`MathEditorSurface` accepts [DOM options](API-SESSION.md), plus `className`. It mounts/destroys through React effects and updates mutable options. `defaultValue`, `session` and `menuHost` remain mount-only. For external commands, provide one stable session; `session.load(document)` opens a different trusted document and resets history. The host must clean up its own subscriptions and external toolbar/session. Avoid sharing a session across simultaneous surfaces.
+
+## SSR and popup behavior
+
+The native surface mounts on the client through an effect. Keep browser storage and DOM access in client lifecycle code. In server-component frameworks, put the integration in a client component; package import safety does not imply server-rendered editable content or hydration support.
+
+For a popup, hold a draft in component state or a draft session. `onChange` should update that draft, not persist to the host document. Apply commits it; Cancel unmounts it. Use a fresh `key` each time a new original is opened. Keep host undo separate and create one host transaction on Apply.
+
+## Common mistakes
+
+- Passing `value`, `onCommit`, `mode` or `session` to rich `MathEditor`: use the native surface for those native options.
+- Mirroring each `onChange` into a new component key, destroying undo and IME state.
+- Assuming rich and native components have identical symbol/selection tools.
+
+## Complete React modal with an isolated rich-editor draft
+
+The parent supplies a trusted document and receives one Apply callback. Typing and Cancel never call `onApply`. Render a fresh instance for each editing request (for example, a monotonically increasing request key). This uses the supported component API.
+
+```tsx
+import { useEffect, useRef } from 'react';
+import { MathEditor } from '@barocss/math-editor/react';
+import type { MathDocument } from '@barocss/math-editor/core';
+import '@barocss/math-editor/style.css';
+
+export function FormulaDialog({ original, onApply, onClose }: {
+  original: MathDocument;
+  onApply: (document: MathDocument) => void;
+  onClose: () => void;
+}) {
+  const dialog = useRef<HTMLDialogElement>(null);
+  const draft = useRef(structuredClone(original));
+  const finished = useRef(false);
+  useEffect(() => {
+    const element = dialog.current!;
+    const previous = document.activeElement;
+    element.showModal();
+    return () => {
+      element.close();
+      if (previous instanceof HTMLElement && previous.isConnected) previous.focus();
+    };
+  }, []);
+  function finish(apply: boolean) {
+    if (finished.current) return;
+    finished.current = true;
+    if (apply) onApply(structuredClone(draft.current));
+    onClose(); // Parent unmounts this component.
+  }
+  return <dialog ref={dialog} aria-label="Edit formula"
+    onCancel={event => { event.preventDefault(); finish(false); }}>
+    <MathEditor defaultValue={original} locale="en" showTokenLegend={false}
+      onChange={document => { draft.current = document; }} />
+    <button type="button" onClick={() => finish(false)}>Cancel</button>
+    <button type="button" onClick={() => finish(true)}>Apply</button>
+  </dialog>;
+}
+```
+
+`onApply` is a synchronous host-state commit in this example. If saving requires a server request, keep a pending/error state, disable duplicate Apply, and close only after success. Do not replace `defaultValue` on every keystroke.
+
+## Native React surface with Undo, Redo and document switching
+
+This is an alternative to the rich modal. The stable session is created once per mounted component; loading a different trusted `source` resets its history. Keep `source` stable while saving: do not feed each emitted document back into it.
+
+```tsx
+import { useEffect, useState } from 'react';
+import { MathEditorSurface } from '@barocss/math-editor/react';
+import { createMathSession, type MathDocument } from '@barocss/math-editor/core';
+import '@barocss/math-editor/style.css';
+
+export function SessionFormula({ source }: { source: MathDocument }) {
+  const [session] = useState(() => createMathSession({ document: source, locale: 'en' }));
+  const [snapshot, setSnapshot] = useState(() => session.getSnapshot());
+  useEffect(() => {
+    const unsubscribe = session.subscribe(next => setSnapshot(next));
+    setSnapshot(session.getSnapshot());
+    return () => { unsubscribe(); session.destroy(); };
+  }, [session]);
+  useEffect(() => { session.load(source); }, [session, source]);
+  return <>
+    <button disabled={!snapshot.canUndo}
+      onClick={() => session.execute({ type: 'undo' })}>Undo</button>
+    <button disabled={!snapshot.canRedo}
+      onClick={() => session.execute({ type: 'redo' })}>Redo</button>
+    <MathEditorSurface session={session} locale="en" />
+    <pre>{snapshot.latex}</pre>
+  </>;
+}
+```
+
+## Persistence and ownership
+
+Persist the `MathDocument` passed to `onChange`; LaTeX is derived output; the bounded loader supports the documented round-trip subset. The package does not parse arbitrary LaTeX. Validate externally supplied JSON before loading it: loading assumes a trusted, structurally valid document with unique IDs. There is no server save or collaboration transport built in.
+
+Keep the mount host empty. The editor owns its descendants; framework rendering into the same host can destroy caret and composition state. Use one editing surface per session. Destroy the renderer on teardown; a session supplied by the host remains the host's responsibility.
+
+See [session and DOM API](API-SESSION.md) for exact options, commands, events and cleanup, and [renderer differences](ADAPTERS.md#current-renderer-parity) before choosing a native wrapper over the rich React editor.
+
+
+## Undoable LaTeX import (0.2.0)
+
+```tsx
+import { useRef } from 'react';
+import { MathEditor, type MathEditorHandle } from '@barocss/math-editor';
+
+function Editor() {
+  const api = useRef<MathEditorHandle>(null);
+  return <>
+    <button onClick={() => {
+      const result = api.current?.importLatex(String.raw`\frac{a}{b}`);
+      if (result && !result.ok) console.log(result.diagnostics);
+    }}>Load example</button>
+    <MathEditor apiRef={api} />
+  </>;
+}
+```
+
+Import validates the whole expression and host `multiline`/`excludedStructures` restrictions before committing. Success fires `onChange` and creates one undo step; failure leaves content and history unchanged. It refuses replacement during active composition. `MathEditorSurface` uses `session.importLatex` instead. See [LaTeX scope](LATEX-SCOPE.md) for supported grammar and limits.
+
+
+## Rich editor embedded in a document (workspace)
+
+Use `autoFocus`, `toolbar={false}`, `showTokenLegend={false}`, `showLineNumbers={false}` and `enterBehavior="commit"` for an in-place rich editor. Keep `onChange` in a local draft, commit that draft in `onCommit`, and discard it in `onCancel`. Suggestions and selection wrapping take priority over Enter; Escape closes suggestions before requesting cancellation. IME composition reserves its keys. `Shift+Enter` retains normal line/grid behavior subject to `multiline`.
+
+Wrap the editor in a non-editable island when embedding inside contenteditable. The host must exclude nested events, selections and renderer mutations from its own text pipeline. Do not save a host transaction for every math keystroke. Set `--me-font-size` on the wrapper to scale token previews and inputs together; its default is22px.

package/API-SESSION.md

@@ -0,0 +1,163 @@
+# Session and native DOM API reference
+
+This reference applies to pure JavaScript, `MathEditorSurface`, Web Component, Vue, Svelte and Solid native integrations in 0.2.0. Rich React `MathEditor` owns separate history and has its own [props](API-REACT.md).
+
+## Imports
+
+```ts
+import { createMathSession, createMathDocument } from '@barocss/math-editor/core';
+import { mountMathEditor, mountMathToolbar, mountMathLatex, mountMathPreview }
+  from '@barocss/math-editor/dom';
+import '@barocss/math-editor/style.css';
+```
+
+## createMathSession(options)
+
+| Option | Type | Default |
+|---|---|---|
+| `document` | Trusted `MathDocument` | Empty document |
+| `locale` | Registered locale string | `ko` |
+| `mode` | `block` or `inline` | `block` |
+
+| Method | Contract |
+|---|---|
+| `getSnapshot()` | Copy containing `state`, optional `range`, `locale`, `mode`, `canUndo`, `canRedo`, `latex` |
+| `subscribe(listener)` | Listener receives `(snapshot, documentChanged)`; returns unsubscribe |
+| `execute(command)` | Boolean result; text/structure/template/newline/undo/redo |
+| `apply(state)` | Apply `MathState`; returns false for invalid inline multiline state |
+| `select(caret)` | Set `MathCaret`, clear structural range, emit non-document change |
+| `selectRange(range?)` | Set/clear `MathRange`, emit non-document change |
+| `configure({ locale?, mode? })` | Keep document/history; throws on multiline-to-inline change |
+| `load(document)` | Open trusted document and reset history/range; emits document change |
+| `copy()` | `MathFragment` for structural range, or undefined |
+| `paste(fragment)` | Boolean result; rejects multiline in inline mode |
+| `destroy()` | Release subscribers; host must also destroy renderers/tools |
+
+A snapshot's `state` contains `document` and `caret`. Never mutate a snapshot expecting it to affect the session. Use a command or `apply` instead. `false` is also returned for undo/redo when no history change occurs; it is not always an error.
+
+## Commands
+
+```ts
+session.execute({ type: 'text', value: 'x + α' });
+session.execute({ type: 'structure', kind: 'fraction' });
+session.execute({ type: 'template', id: 'quadratic' });
+session.execute({ type: 'newline' });
+session.execute({ type: 'undo' });
+session.execute({ type: 'redo' });
+```
+
+These examples assume an existing session. Structure kinds: `fraction`, `root`, `superscript`, `subscript`, `parentheses`, `brackets`, `absolute`, `sum`, `product`, `integral`, `matrix`, `aligned`, `cases`. A selected structural range can only wrap in supported wrapping kinds. Use exported grid helpers plus `apply()` for grid resizing; there is no `execute({ type: 'resizeMatrix' })` command.
+
+## mountMathEditor(host, options)
+
+`host` must be a real HTMLElement. Mount on the client, once per surface.
+
+| Option | Contract |
+|---|---|
+| `session` | Host session; mount-only; survives renderer destruction |
+| `defaultValue` | Trusted document for an internally created session; mount-only |
+| `menuHost` | Suggestion portal HTMLElement; mount-only; nearest native dialog or body by default |
+| `locale`, `mode` | Configure locale/mode; same defaults as session |
+| `toolbar` | Boolean or readonly structure kind list; block defaults on, inline off |
+| `showLineNumbers` | Whether UI-only multiline gutter is displayed |
+| `enterBehavior` | `newline` or `commit`; block defaults newline, inline commit |
+| `onChange(document, latex)` | Committed document changes |
+| `onCommit(snapshot)` | Host completion request; no automatic save or block creation |
+| `onCancel()` | Escape after dismissing suggestions/grid state; host decides whether to close |
+| `onExit(direction)` | Host caret handoff, `-1` before or `1` after |
+
+Return value: `{ session, focus(), update(options), destroy() }`. `update` accepts mutable options only and merges them. Locale updates preserve history. Do not pass a fresh session to `update`; recreate the renderer if changing ownership.
+
+Inline mode means one top-level row, not a fixed visual height. It rejects newline commands and multiline paste and throws when loading multiline documents. Enter accepts suggestions first; grid keyboard operations have their own priority. CSS alone cannot establish these model constraints.
+
+## Saving without caret-only writes
+
+```ts
+const unsubscribe = session.subscribe((snapshot, documentChanged) => {
+  if (!documentChanged) return;
+  localStorage.setItem('formula', JSON.stringify(snapshot.state.document));
+});
+// On teardown: unsubscribe(); editor.destroy(); session.destroy();
+```
+
+If a server persists changes asynchronously, debounce/serialize writes and handle failed saves in your host. The library does not resolve write races or validate arbitrary documents returned by a server.
+
+## Independent toolbar and outputs
+
+`mountMathToolbar(host, session, { kinds?, onExecute? })` exposes `destroy()`. Use `onExecute: () => editor.focus()` to return keyboard focus after choosing a tool. `mountMathLatex(host, session)` renders derived LaTeX and returns `destroy()`.
+
+`mountMathPreview(host, session, { render(host, snapshot) })` delegates rendering to your application. `render` may return a cleanup function. The math-editor package does not ship KaTeX as a runtime requirement; import your chosen renderer separately. All output handles must be destroyed when their hosts are removed.
+
+## Reusable browser-storage adapter with restore and error reporting
+
+This adapter avoids writes for caret changes, debounces edits, flushes on page hide, and removes its listeners on teardown. Restore runs before subscribing so opening saved content does not immediately write it back. It does not validate documents itself: supply your application's schema validator as `decode`, which must throw for invalid or unsupported JSON. Use a different key per document. Call `dispose()` before changing the session's document/key.
+
+```ts
+import type { MathDocument } from '@barocss/math-editor/core';
+import { createMathSession } from '@barocss/math-editor/core';
+
+type Session = ReturnType<typeof createMathSession>;
+export function attachBrowserStorage(
+  session: Session,
+  key: string,
+  decode: (json: unknown) => MathDocument,
+  onError: (error: unknown) => void,
+) {
+  // Invoke on the client only. Storage may be unavailable or full.
+  try {
+    const stored = localStorage.getItem(key);
+    if (stored !== null) session.load(decode(JSON.parse(stored)));
+  } catch (error) { onError(error); }
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let pending: MathDocument | undefined;
+  function flush() {
+    clearTimeout(timer);
+    timer = undefined;
+    if (!pending) return;
+    try {
+      localStorage.setItem(key, JSON.stringify(pending));
+      pending = undefined;
+    } catch (error) { onError(error); }
+  }
+  const unsubscribe = session.subscribe((snapshot, documentChanged) => {
+    if (!documentChanged) return;
+    pending = snapshot.state.document;
+    clearTimeout(timer);
+    timer = setTimeout(flush, 300);
+  });
+  window.addEventListener('pagehide', flush);
+  return {
+    flush,
+    dispose() {
+      unsubscribe();
+      window.removeEventListener('pagehide', flush);
+      flush();
+    },
+  };
+}
+```
+
+The host owns validation because it knows supported structures, size limits and schema versions. Do not replace `decode` with a TypeScript cast. Page-hide flushing is best effort, not a guarantee against crashes; localStorage is not cross-device persistence or multi-tab conflict resolution. Display `onError` failures and offer a retry via `flush()`.
+
+## Failure and compatibility boundaries
+
+- All adapters are ESM; no CommonJS/global-script API is promised.
+- Loading expects trusted structured JSON; arbitrary LaTeX parsing and evaluation are not supported.
+- Native and rich React editing UX differ; see [the parity table](ADAPTERS.md#current-renderer-parity).
+- One session is not a concurrent multi-user collaboration engine.
+- Host UI, permissions, persistence, clipboard environment restrictions and SSR boundaries remain the integrator's responsibility.
+
+
+## LaTeX import (0.2.0)
+
+```ts
+const result = session.importLatex(String.raw`\frac{a}{b}`);
+if (!result.ok) {
+  // No mutation or subscription notification. Retain the caller's source.
+  console.log(result.diagnostics);
+}
+```
+
+This operation replaces the current formula in one undo step; redo restores the imported formula. Inline sessions reject multiple top-level lines before modifying state. All framework adapters using a session share this API; Web Components expose it as `element.session.importLatex(source)`.
+
+For state-independent inspection, use `parseLatex(source, { multiline?, excludedStructures? })` from `/core`. For opening a different saved document, validate JSON with `parseMathDocument` and call `session.load`. Loading deliberately resets history, importing does not. See [the exact syntax contract](LATEX-SCOPE.md); arbitrary LaTeX macros are not supported. These APIs are available in 0.2.0.

package/API-SOLID.md

@@ -0,0 +1,90 @@
+# Solid API guide
+
+The `mathEditor` directive mounts the native editor, updates options in a reactive effect and tears down through Solid's owner cleanup.
+
+## Install
+
+```sh
+npm install @barocss/math-editor@0.2.0 solid-js
+```
+
+## Complete component
+
+```tsx
+import { createSignal } from 'solid-js';
+import { mathEditor } from '@barocss/math-editor/solid';
+import '@barocss/math-editor/style.css';
+
+// Preserve the value import used by the JSX directive transform.
+void mathEditor;
+export function Formula() {
+  const [locale, setLocale] = createSignal('en');
+  const [latex, setLatex] = createSignal('');
+  return <>
+    <button onClick={() => setLocale(locale() === 'en' ? 'ko' : 'en')}>Language</button>
+    <div use:mathEditor={{
+      locale: locale(),
+      mode: 'inline',
+      toolbar: false,
+      onChange(document, output) {
+        setLatex(output);
+        // Persist document through your application here.
+      },
+    }} />
+    <pre>{latex()}</pre>
+  </>;
+}
+```
+
+The adapter augments Solid's JSX `Directives` type. Keep the directive import as a runtime value, and compile this with Solid's JSX transform, not the React transform.
+
+## Reactive options and sessions
+
+The directive reads an accessor in `createEffect`, so a signal read in its options updates the renderer. It mounts once; `defaultValue`, `session` and `menuHost` stay mount-only. There is no controlled document prop.
+
+Create an external `createMathSession()` once in the component body when you need commands, undo state or an external toolbar. Pass it as `session`, use `session.load(validatedDocument)` to open another document, and register your own subscription/session cleanup with `onCleanup`. Do not create sessions in reactive option expressions.
+
+## Host lifecycle
+
+The directive calls `editor.destroy()` on cleanup. It cannot clean up arbitrary host event listeners or save subscriptions. Its host must remain an empty DOM element in your JSX because the editor owns descendants. DOM mounting is client-only; use the framework's client-only boundary when integrating into an SSR route.
+
+For inline or popup integration, use the native `mode`, `enterBehavior`, `onCommit`, `onCancel` and `onExit` options described in the shared API. Those notifications do not automatically create the next prose block or close a modal.
+
+## History, templates and saved-document restoration
+
+This complete component keeps the session outside reactive effects, subscribes to snapshots, and releases the subscription on teardown. Save is in-memory; Restore opens that snapshot and clears undo history.
+
+```tsx
+import { createSignal, onCleanup } from 'solid-js';
+import { mathEditor } from '@barocss/math-editor/solid';
+import { createMathSession, createMathDocument } from '@barocss/math-editor/core';
+import '@barocss/math-editor/style.css';
+
+void mathEditor;
+export function FormulaWithHistory() {
+  let saved = createMathDocument('x');
+  const session = createMathSession({ document: saved, locale: 'en' });
+  const [snapshot, setSnapshot] = createSignal(session.getSnapshot());
+  const unsubscribe = session.subscribe(next => setSnapshot(next));
+  onCleanup(() => { unsubscribe(); session.destroy(); });
+  return <>
+    <button disabled={!snapshot().canUndo}
+      onClick={() => session.execute({ type: 'undo' })}>Undo</button>
+    <button disabled={!snapshot().canRedo}
+      onClick={() => session.execute({ type: 'redo' })}>Redo</button>
+    <button onClick={() => session.execute({ type: 'template', id: 'quadratic' })}>Quadratic formula</button>
+    <button onClick={() => { saved = session.getSnapshot().state.document; }}>Save</button>
+    <button onClick={() => session.load(saved)}>Restore saved</button>
+    <div use:mathEditor={{ session, locale: 'en' }} />
+    <pre>{snapshot().latex}</pre>
+  </>;
+}
+```
+
+## Persistence and ownership
+
+Persist the `MathDocument` passed to `onChange`; LaTeX is derived output and is not an editable round-trip format. The package does not parse arbitrary LaTeX. Validate externally supplied JSON before loading it: loading assumes a trusted, structurally valid document with unique IDs. There is no server save or collaboration transport built in.
+
+Keep the mount host empty. The editor owns its descendants; framework rendering into the same host can destroy caret and composition state. Use one editing surface per session. Destroy the renderer on teardown; a session supplied by the host remains the host's responsibility.
+
+See [session and DOM API](API-SESSION.md) for exact options, commands, events and cleanup, and [renderer differences](ADAPTERS.md#current-renderer-parity) before choosing a native wrapper over the rich React editor.