@barocss/math-editor 0.2.1 → 0.5.0

package/ADAPTERS.md

@@ -79,7 +79,7 @@ import { MathEditorSurface } from '@barocss/math-editor/react';
 <MathEditorSurface locale="en" mode="inline" toolbar={false} onChange={save} />
 ```
 
-Keep `MathEditor` for the existing full editor, including the symbol browser and richer selection UI. `MathEditorSurface` uses the new native renderer and options. They share document formats, not a live history instance. Do not assume feature parity; see below.
+`MathEditor` keeps the rich React renderer and token-level active input. `MathEditorSurface` uses the native renderer and session options. The workspace native toolbar now includes the symbol browser, templates and grid context controls described below; these additions are included in 0.4.0. The renderers share document formats but own separate history instances. See the remaining differences below.
 
 ## Web Component
 
@@ -141,20 +141,24 @@ The directive reads its accessor in a reactive effect and cleans up with `onClea
 
 | Capability | Existing React `MathEditor` | Native surface and all wrappers |
 |---|---|---|
-| 13 structure kinds / 90 symbol suggestions / templates | Yes | Same model and suggestion catalog |
+| Structure, symbol and template catalog | Yes | Same model and suggestion catalog |
+| Suggestion and selection menu presentation | Glyph, name, detail and keyboard guidance | Same presentation in the 0.4.0 release; options scroll independently of the host |
 | Multiline block, grids and grid keyboard commands | Yes | Implemented; representative Chromium coverage |
 | Single top-level row inline policy | No dedicated prop | Yes |
 | Separately mounted/custom toolbar | Not a session API | Yes |
 | English/Korean/custom locale registry | Yes | Yes |
-| Active input granularity | Lexical token | Whole logical text run |
-| Variable/constant/symbol colors | Editing and preview | Preview segments; active run uses one color |
-| Pointer range, structural clipboard, wrapping | Rich implementation | Initial implementation; whole-run visual highlight |
-| Drag starting inside the active input across structures | Yes | Pending; start in preview |
-| Searchable all-symbol panel, matrix context toolbar | Yes | Pending; suggestions/core commands available |
-| 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. Use `parseMathDocument` to validate schema and IDs before trusted document loading. Bounded LaTeX import is available through `importLatex`; ordinary plain-text paste remains literal.
+| Active input granularity | Lexical token | Lexical token (workspace) |
+| Variable/constant/symbol colors | Editing and preview | Editing and preview (workspace); named functions retain their own color |
+| Pointer range, structural clipboard, wrapping | Yes | Exact partial-text highlights included in 0.4.0 |
+| Drag starting inside the active input across structures | Yes | Implemented in workspace; local input selection becomes a model range after leaving the input |
+| Searchable all-symbol panel, templates and matrix presets | Yes | Available through More tools in 0.4.0 |
+| Matrix rectangles, shape-checked clipboard and transpose | Implemented in workspace | Implemented in workspace |
+| Active grid row/column and delimiter controls | Yes | Implemented in workspace; aligned/cases expose row controls |
+| Shift+arrow model ranges | Yes | Yes; vertical extension uses logical line offsets |
+| Composition candidate preview | Disabled choices while composing | Menu hidden and toolbar mutations disabled while composing |
+| OS IME matrix / full accessibility audit | Deferred / pending | Deferred / pending |
+
+The native renderer remains an integration preview. Its active input now covers one lexical token, with model offsets mapped across token boundaries. Composition keeps that input stable until commit. A persistent preferred column for vertical navigation, and a full accessibility/browser audit remain open. Complete English/Korean packs are bundled; additional complete packs and native OS IME validation remain deferred work. The new toolbar and selection UI use existing model operations and add no LaTeX syntax. Use `parseMathDocument` to validate schema and IDs before trusted document loading. Bounded LaTeX import is available through `importLatex`; ordinary plain-text paste remains literal. The workspace adds explicit `pasteLatex` and Alt+Shift+V insertion, recent/favorite items, and contextual presentation controls; see [editing utilities](API-SESSION.md#editing-utilities--workspace).
 
 ## Local verification and packaging
 
@@ -178,7 +182,9 @@ The DOM entry also exports `mountMathLatex` and `mountMathPreview`. See [Embeddi
 
 ## 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.
+Toolbars initially show up to eight structure buttons. More tools / Fewer tools toggles the expanded section without changing the formula or history. In the workspace, native More tools also exposes the searchable All symbols panel, templates, 2×2/3×3/4×4 matrix and identity presets, and symbol shortcuts. It remains available when every selected structure button already fits. Undo and Redo stay visible; rich React also retains its `toolbarEnd` slot. The layout wraps on narrow screens.
+
+The native grid toolbar follows the active caret: matrices expose row/column insertion and deletion plus delimiter selection; aligned/cases expose row operations. A text or model selection disables these grid mutations. These native toolbar additions are included in 0.4.0. See [the session toolbar API](API-SESSION.md#independent-toolbar-and-outputs) for attaching, disabling and destroying an external toolbar.
 
 ```tsx
 <MathEditor toolbar={['fraction', 'root', 'superscript', 'matrix']}
@@ -186,7 +192,8 @@ Toolbars initially show up to eight structure buttons. More tools / Fewer tools
 ```
 
 ```js
-mountMathEditor(host, session, {
+mountMathEditor(host, {
+  session,
   toolbar: ['fraction', 'root', 'norm'],
   toolbarMaxItems: 2,
 });
@@ -196,4 +203,8 @@ mountMathToolbar(toolbarHost, session, {
 });
 ```
 
-`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.
+`toolbar: false` hides the toolbar. A structure array filters visible structure buttons. The workspace native toolbar also filters templates by all their structure kinds and limits matrix presets/context controls to allowed grid kinds; symbol search remains available. Rich React's auxiliary controls retain their existing behavior. Toolbar filtering does not restrict suggestions, parsing or the model. `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; the native discovery/context additions are included in 0.4.0.
+
+## Style customization
+
+Use inherited CSS variables for colors, slot backgrounds, typography, toolbar density and menu appearance. Scoped themes also follow portaled suggestions in both renderers. See [Styling & themes](STYLING.md) for the public variables, dark/monochrome examples, shared toolbars and iframe/plugin sizing.

package/API-JAVASCRIPT.md

@@ -5,7 +5,7 @@ Use this integration for vanilla JavaScript, custom application shells and imper
 ## Install
 
 ```sh
-npm install @barocss/math-editor@0.2.1
+npm install @barocss/math-editor@0.4.0
 ```
 
 ## Mount a complete editor

package/API-REACT.md

@@ -10,7 +10,7 @@ React offers two components. Choose intentionally: they share document structure
 ## Install
 
 ```sh
-npm install @barocss/math-editor@0.2.1 react react-dom
+npm install @barocss/math-editor@0.4.0 react react-dom
 ```
 
 ## Rich editor
@@ -200,3 +200,7 @@ Import validates the whole expression and host `multiline`/`excludedStructures`
 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.
+
+## Workspace editing utilities
+
+The rich editor and native surface now share explicit LaTeX insertion, recent/favorite items and contextual presentation controls. `MathEditorHandle.pasteLatex(source)` inserts at the caret/range; `importLatex` still replaces the whole formula. Supply a `preferences` store from `createMathPreferences()` to share favorites across editor instances. The default is instance-local memory. See the [full utility API and keyboard behavior](API-SESSION.md#editing-utilities--workspace).

package/API-SESSION.md

@@ -1,6 +1,6 @@
 # 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).
+This reference applies to pure JavaScript, `MathEditorSurface`, Web Component, Vue, Svelte and Solid native integrations. The base session/DOM API is available in 0.2.0; the native discovery/context toolbar, `setDisabled` and precise pointer-selection changes below are additions in 0.4.0. Rich React `MathEditor` owns separate history and has its own [props](API-REACT.md).
 
 ## Imports
 
@@ -21,20 +21,75 @@ import '@barocss/math-editor/style.css';
 
 | Method | Contract |
 |---|---|
-| `getSnapshot()` | Copy containing `state`, optional `range`, `locale`, `mode`, `canUndo`, `canRedo`, `latex` |
+| `getSnapshot()` | Copy containing `state`, optional `range` / `matrixRange`, `locale`, `mode`, `canUndo`, `canRedo`, `latex` |
 | `subscribe(listener)` | Listener receives `(snapshot, documentChanged)`; returns unsubscribe |
-| `execute(command)` | Boolean result; text/structure/template/newline/undo/redo |
+| `execute(command)` | Boolean result; text/structure/template/newline/undo/redo and matrix selection/clear/transpose |
 | `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 |
+| `selectMatrixRange(range?)` | Validate and set/clear a cell rectangle; clear structural range, emit non-document change; false leaves state unchanged |
+| `copyMatrix()` | Copy selected cells as `MathMatrixFragment`, or undefined |
+| `pasteMatrix(fragment)` | Paste at the selected rectangle or active matrix cell as one edit; false leaves document, selection and history unchanged |
 | `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 |
+| `copy()` | `MathFragment` for structural range; matrix rectangle becomes a single-matrix fragment; otherwise 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.
 
+## Matrix cell selections
+
+Available in 0.4.0. `MathRange` and `MathMatrixRange` are
+mutually exclusive. `select(caret)`, document changes, load and Undo/Redo clear cell
+selection. Selecting cells does not emit a document change or create history.
+
+```ts
+import { createMathSession } from '@barocss/math-editor/core';
+
+const session = createMathSession({ document: savedDocument });
+// Assume a loaded matrix has three columns; select rows 1–2, columns 2–3.
+session.selectMatrixRange({ matrixId, anchor: 1, focus: 5 });
+const cells = session.copyMatrix();
+// Move to another matrix/cell or select its destination rectangle first.
+if (cells && !session.pasteMatrix(cells)) {
+  // The destination shape or 20 × 20 bound rejected this paste; no partial write.
+}
+session.execute({ type: 'matrix-select' }); // Current cell, ready for Shift+arrows.
+session.execute({ type: 'matrix-select', all: true });
+session.execute({ type: 'matrix-clear' });
+session.execute({ type: 'matrix-transpose' }); // Entire selected/active matrix.
+```
+
+`MathMatrixRange` is `{ matrixId: string, anchor: number, focus: number }`.
+Endpoints are zero-based row-major cell indices. Reversed endpoints work; bounds
+are derived from row and column coordinates, not the linear span between indices.
+`MathMatrixFragment` is `{ version: 1, columns, cells: MathRow[], environment }`.
+Its `cells` are row-major and may contain any supported nested formula.
+
+| Destination | Paste behavior |
+| --- | --- |
+| Caret in a matrix or one selected cell | Replace whole cells from that anchor; grow/pad the matrix up to 20 × 20 |
+| Larger selected rectangle | Require matching dimensions; a single copied cell fills every selected cell |
+| Different rectangle dimensions, invalid payload or size overflow | Return false with no write, selection change or history entry |
+| Outside a matrix in the browser UI | Insert the copied rectangle as a new matrix through its normal math-fragment fallback |
+
+Pasting keeps the destination delimiter, preserves unselected cells, and assigns
+fresh IDs recursively to inserted content. Typing over a cell selection clears
+its contents and inserts text into the upper-left cell. Delete/Cut clear contents
+without deleting rows or columns. Enter/Escape resumes editing; Shift+arrows
+extends the rectangle. Transpose reorders the entire matrix, retaining existing
+cell IDs, delimiter and nested caret. Each content operation takes one Undo.
+
+Browser clipboard handlers write `MATH_MATRIX_CLIPBOARD_TYPE`
+(`application/x-barocss-math-matrix+json`), the existing math fragment MIME, and
+plain LaTeX. Read external matrix payloads with `parseMatrixFragment`; normal
+`parseFragment` remains the structural clipboard parser. `paste(fragment)` does
+not overwrite a cell rectangle: use `pasteMatrix` for that operation. Tab-separated
+spreadsheet data inside a matrix is treated as cell text, not interpreted LaTeX.
+Clipboard formats can be stripped by other applications; OS interoperability is
+a separate check. Neither selection nor clipboard metadata changes MathDocument v1.
+
 ## Commands
 
 ```ts
@@ -46,7 +101,7 @@ 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.
+These examples assume an existing session. `kind` accepts the exported `StructureKind`; see the [structure catalog](JSON-MODEL.md) for the current kinds and slot contracts. 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)
 
@@ -57,19 +112,32 @@ These examples assume an existing session. Structure kinds: `fraction`, `root`,
 | `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 |
+| `menuAvoidElements` | Workspace: optional callback returning host controls the suggestion menu should avoid; measured in their current position when the menu opens or moves |
 | `locale`, `mode` | Configure locale/mode; same defaults as session |
 | `toolbar` | Boolean or readonly structure kind list; block defaults on, inline off |
+| `toolbarMaxItems` | Initially visible structure buttons; defaults to eight; More tools reveals the expanded controls |
 | `showLineNumbers` | Whether UI-only multiline gutter is displayed |
 | `enterBehavior` | `newline` or `commit`; block defaults newline, inline commit |
 | `onChange(document, latex)` | Committed document changes |
+| `onRender()` | Workspace: final DOM/caret notification, including focus and selection-only updates; no automatic model write |
 | `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.
 
+`onRender` runs synchronously after the native surface/menu update, before host mutation observers reconcile their selections. It can also run during initial mounting, before `mountMathEditor` returns. Hosts can inspect the current input and schedule caret restoration; avoid issuing commands or calling `focus()` from the callback, which can trigger another render. This notification is distinct from `onChange` and does not imply a document or history change. It is available in 0.4.0.
+
+Notifications are suppressed during composition and after teardown. A notification does not guarantee that an input is focused. Any deferred caret restoration should check that its input is still connected and focused, so a later callback cannot revive a closed draft or steal focus from another control.
+
 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.
 
+For a compact draft, pass `menuAvoidElements: () => [actionsElement]` to keep
+suggestions clear of Apply, Cancel and tool-expansion controls. The callback can
+return elements added after mounting. Placement remains constrained by the
+viewport and clipping ancestors; the menu scrolls when the available gap is short.
+This option changes presentation only and adds no model data.
+
 ## Saving without caret-only writes
 
 ```ts
@@ -84,10 +152,43 @@ If a server persists changes asynchronously, debounce/serialize writes and handl
 
 ## 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()`.
+`mountMathToolbar(host, sessionOrNull, { kinds?, maxItems?, locale?, onExecute? })` mounts a toolbar whose current workspace handle exposes:
+
+| Method | Contract |
+|---|---|
+| `setSession(sessionOrNull)` | Switch the active draft subscription; `null` disables mutations; switching/detaching closes symbol search |
+| `setDisabled(boolean)` | Disable mutations while keeping the session attached; disabling closes symbol search; restore with `false` after composition |
+| `destroy()` | Remove the toolbar, its panels and session subscription |
+
+`maxItems` defaults to eight. `locale` supplies labels before a session is attached; an active session supplies its own locale. Use `onExecute: () => editor.focus()` to return focus after a successful command. Opening or searching the symbol browser leaves focus in that browser. The toolbar uses the session's caret/range even when the math input has blurred.
+
+The workspace More tools section exposes the full symbol catalog with search, templates, matrix/identity presets and symbol shortcuts. `kinds` filters structure buttons, templates containing excluded kinds, and grid presets/context controls; it does not limit model or parser support. Active matrices provide row/column operations and delimiter selection; aligned/cases provide row operations. Grid mutations are disabled while text or a model range is selected. The symbol panel stays inside its toolbar host, and Escape closes it without requesting host Cancel.
+
+An internally mounted toolbar is disabled during native formula composition. Hosts mounting an independent toolbar must coordinate composition with `setDisabled`, or temporarily detach with `setSession(null)`. Host integrations also own containment: keep the toolbar and its panels inside the declared `toolbarHost` so an outside-click handler does not commit the draft while browsing. See [adapter embedding](ADAPTERS.md) for lifecycle ownership.
+
+`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.
 
+The website's sized PNG download/copy controls belong to its preview renderer. They are not native DOM/session image-export methods; a reusable library SVG/PNG export API remains future work.
+
+## Native selection behavior
+
+Shift+Left/Right extends or shrinks a model range; Shift+Up/Down extends across top-level lines using logical offsets. In the workspace, passive highlights cover exact selected text endpoints. Dragging within the active input keeps native text selection; crossing its boundary can extend a model range across structures. Structural normalization remains unchanged: a `MathRange` crossing fraction slots or matrix cells selects their common structure. Cross-cell pointer gestures instead create a separate `MathMatrixRange` in the workspace; see the matrix selection contract above.
+
+After a model selection, plain Left/Up restores the caret at its document-ordered
+start; Right/Down restores it at the end. The same rule applies to reverse drags
+and Shift+arrow selections, without consuming another character or changing the
+formula. Alt+Up/Down browses the wrapping suggestions while retaining the range;
+Enter applies a candidate. Ordinary input suggestions still use Up/Down.
+
+The first Escape dismisses a selection's wrapping suggestions while preserving
+the selection and draft. A subsequent Escape reaches the host Cancel callback.
+Changing the selection or beginning a new pointer gesture makes suggestions
+available again.
+
+The active native input still edits a whole logical text run with one role color. Passive runs retain lexical colors. The cell-selection work adds full-matrix transpose through existing model structures; no new LaTeX grammar is needed. Native OS IME validation and additional complete locale packs remain deferred; see [renderer parity](ADAPTERS.md#current-renderer-parity) for remaining limits.
+
 ## 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.
@@ -161,3 +262,74 @@ if (!result.ok) {
 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.
+
+## Editing utilities — workspace
+
+These additions are included in 0.4.0. Earlier releases do not provide these APIs.
+
+### LaTeX insertion
+
+`session.pasteLatex(source)` inserts at the current caret or replaces the selected model range. It returns `LatexInsertionResult`: success includes the parsed document and resulting state; failure includes source offsets and diagnostics. It creates one Undo entry, leaves the caret after the inserted fragment, and generates fresh IDs. It does not reset history or replace the entire document. `importLatex(source)` continues to replace the whole formula.
+
+```ts
+const result = session.pasteLatex(String.raw`\frac{a}{b} + x_i^2`);
+if (!result.ok) console.log(result.diagnostics);
+```
+
+Empty input, unsupported syntax, multiline insertion inside a nested slot or inline session, structures in literal text, and matrix-rectangle targets are rejected without changing document, caret, selection or history. Ordinary clipboard paste is still literal. More tools → Paste as LaTeX opens a nonmodal source field. Alt+Shift+V opens it even when the toolbar is hidden; Ctrl/Cmd+Enter inserts and Escape closes. The UI accepts a user paste and does not read the system clipboard automatically.
+
+The pure `insertLatex(state, source, range?, options?)` helper supplies the same behavior without a session. The rich React `MathEditorHandle.pasteLatex` method applies the same helper with its multiline/excluded-structure policy.
+
+### Recent items and favorites
+
+`createMathPreferences(saved?)` creates a UI-only store. Each session has `session.preferences`; pass an existing store in `createMathSession({ preferences })` to share it. An internally owned native session also accepts mount-only `DOMMathEditorOptions.preferences`. Rich React accepts `preferences` as a prop.
+
+```ts
+import { createMathPreferences, createMathSession } from '@barocss/math-editor/core';
+
+const preferences = createMathPreferences();
+const first = createMathSession({ preferences });
+const second = createMathSession({ preferences });
+preferences.toggleFavorite('symbol-α');
+preferences.toggleFavorite('template-quadratic');
+const saved = preferences.getSnapshot(); // { version: 1, recent: [], favorites: [...] }
+const restored = createMathPreferences(saved);
+```
+
+The default store lives in memory. The host can serialize `getSnapshot()` and use `subscribe(listener)` to persist changes; unsubscribe when finished. No localStorage, cookies, network calls or user identity are implicit. `record(id)` moves a known item to the front of the 12-entry recent list. `toggleFavorite(id)` adds/removes a favorite, bounded to 100. `clearRecent()` clears recents. Unknown IDs are ignored; restored lists are validated and deduplicated. These actions do not change formula JSON, document change callbacks or Undo.
+
+More tools → Recent & favorites supplies search, All/Recent/Favorites filters and separate star buttons. Symbol/template selections are recorded; arbitrary typed text and full imported formulas are not stored. Toolbar template filters still apply. A preference store can outlive an individual editor.
+
+### Contextual presentation settings
+
+Place the caret inside a fence, fraction/binomial, or supported limit/sum/product/integral. The toolbar displays settings for the nearest applicable structure. Nested contents, IDs and caret remain unchanged. A structural or matrix range disables these settings.
+
+```ts
+import { activePresentation } from '@barocss/math-editor/core';
+const target = activePresentation(session.getSnapshot().state);
+if (target) session.execute({
+  type: 'presentation', id: target.id, change: { mathStyle: 'text' },
+});
+```
+
+Choose the change appropriate to the target:
+
+| Change | Accepted values | Applies to |
+| --- | --- | --- |
+| `fence` | `parentheses`, `brackets`, `braces`, `angle`, `absolute`, `norm`, `openClosed`, `closedOpen` | Structural fences; changes both ends together |
+| `mathStyle` | `default`, `display`, `text` | Fractions and binomials |
+| `limits` | `default`, `above-below`, `side` | Supported limit, sum/product and integral variants |
+
+`default` removes the explicit metadata. `setMathPresentation(state, id, change)` is the pure equivalent. Unsupported changes or stale IDs return the original state; the session command returns false. This is presentation editing of existing syntax, not algebraic conversion or general TeX styling.
+
+Toolbars expose `closePanels()` to dismiss their nonmodal utilities without editing the formula. `onOpenPanel` and `onPasteLatex` are optional mounting callbacks for a host that coordinates its own utility panels. Built-in surfaces keep only one utility/discovery panel open at a time.
+
+### Keyboard access to transformations
+
+In React and native DOM fields, **Alt+Down** opens or reopens suggestions and
+selects the first available contextual transformation. Up/Down browses and Enter
+applies; Escape dismisses. On macOS, Alt is the Option key. Root and bracket
+transformations preserve the existing operand. The shortcut works with
+`toolbar: false` and `contextTools: false`, including inline mode. Normal text
+input continues to use the standard suggestion ordering; a context-only menu
+requires navigation before Enter can apply a change instead of a host commit.

package/API-SOLID.md

@@ -5,7 +5,7 @@ The `mathEditor` directive mounts the native editor, updates options in a reacti
 ## Install
 
 ```sh
-npm install @barocss/math-editor@0.2.1 solid-js
+npm install @barocss/math-editor@0.4.0 solid-js
 ```
 
 ## Complete component

package/API-SVELTE.md

@@ -5,7 +5,7 @@
 ## Install
 
 ```sh
-npm install @barocss/math-editor@0.2.1 svelte
+npm install @barocss/math-editor@0.4.0 svelte
 ```
 
 ## Complete component

package/API-VUE.md

@@ -5,7 +5,7 @@ The `vMathEditor` directive mounts the native DOM editor. It is not a Vue compon
 ## Install
 
 ```sh
-npm install @barocss/math-editor@0.2.1 vue
+npm install @barocss/math-editor@0.4.0 vue
 ```
 
 ## Complete component

package/API-WEB-COMPONENT.md

@@ -5,7 +5,7 @@ Use the custom element with plain HTML or a framework that can pass DOM properti
 ## Install and register
 
 ```sh
-npm install @barocss/math-editor@0.2.1
+npm install @barocss/math-editor@0.4.0
 ```
 
 ```js
@@ -126,3 +126,5 @@ Persist the `MathDocument` passed to `onChange`; LaTeX is derived output and is
 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.
+
+Set `context-tools="false"` to hide the contextual structure footer. Changing this attribute updates the mounted editor. Conversion suggestions remain available.

package/CHANGELOG.md

@@ -1,5 +1,111 @@
 # @barocss/math-editor
 
+## 0.5.0
+
+### Minor Changes
+
+- Show query-independent radical tools below the active editing surface. Include conversion, index editing, disabled explanations, F6/Escape focus navigation, en/ko labels and a contextTools opt-out (context-tools for Web Components). Preserve model history and hide stale context during range selection or blur.
+- Add contextual bracket transformations to suggestions, with Alt+Down discovery and keyboard acceptance in inline fields without toolbar or footer. Preserve contents, caret and history; target the nearest root/fence and reject stale actions. Include optional footer bracket controls and localized keyboard guidance.
+- Add contextual suggestions to convert a square root to an indexed root while preserving the radicand. Select the new index `2` for immediate editing. Allow conversion back to a square root only for an empty index or `2`. Include English/Korean labels and shared behavior in React and native DOM integrations.
+
+### Patch Changes
+
+- Resolve operator presentation from mathematical slot context in React and native
+  DOM editors. Use text/script-size glyphs and side limits inside fractions and
+  scripts, preserve explicit limit placement, and apply smaller nested bounds.
+  Add context-resolution unit tests and KaTeX glyph-width/font/position checks.
+- Align named-function and fraction boundaries with mathematical spacing in React
+  and native DOM. Remove repeated function glyph padding and fixed fraction outer
+  margins. Preserve thin function spacing in script styles and omit it before plain
+  opening parentheses.
+- Use bundled KaTeX math faces for variables, upright symbols and display operators. Remove artificial integral skew, scale delimiter widths, and preserve curved over/underbrace ends with licensed KaTeX SVG slices. Refine radical sizing, root-index placement, matrix columns and integral limit spacing in both editable and passive views.
+
+  Extend the source-only geometry audit with opt-in horizontal-position checks, font asset fingerprints, explicit font loading and multiple-integral/long-brace cases. Retain the KaTeX MIT attribution for bundled assets.
+
+- Use shared mathematical spacing for text runs in React and native DOM. Distinguish
+  unary signs from binary operators, space relations and punctuation, and suppress
+  these gaps inside scripts. Remove excess glyph padding and reduce inactive caret
+  boundary width while preserving empty input targets.
+- Use small operator glyphs and side limits in inline mode. Reduce nested script
+  size, adjust radicals inside superscripts, and preserve curved end caps on very
+  tall parentheses. Extend source-only KaTeX comparisons to large fences, deep
+  nesting, and actual inline mode.
+- Fix KaTeX-compatible export and import for literal caret and tilde characters in
+  math text runs. Protect complex root-index arguments without changing JSON
+  structure. Add clearance between nested radical rules and extend rendering
+  regression checks.
+- Use KaTeX-derived SVG contours for radicals and short/tall parentheses. Keep
+  existing editing boxes while improving tapered strokes and curved ends. Include
+  the outline assets and attribution in the package, and extend visual comparison
+  fixtures to simple roots and short parentheses.
+- Correct the size, height and spacing of fraction terms used as scripts. Add editor/KaTeX geometry and screenshot fixtures for fractional powers and subscripts. Allow Delete and Backspace inside empty non-grid slots to remove their wrapper while retaining other content and Undo support.
+- Match ordinary script and root-index font scales more closely to KaTeX in passive and active editing. Add a source-only rendering audit with per-formula measurements, screenshots and a tracked difference ledger.
+- Keep formula selections intact when Up/Down navigates a visible wrapping suggestion menu. Enter applies the highlighted wrapper to the selected content. Left/Right still restores the caret, and Shift+arrows extends the selection. Apply the same behavior to React and native DOM fields used by host integrations.
+- Align nested fraction terms, matrix rows, annotations and operator limits more closely with KaTeX. Scale large and contour integral geometry with the configured font size. Preserve explicit display-fraction sizes and positions inside scripts. Use matching input and passive-text metrics to retain edit positions.
+
+  Expand the source-only geometry audit to 33 formulas, including two font sizes, React and DOM rendering, active typing checks and a local image comparison gallery.
+
+## 0.4.1
+
+### Patch Changes
+
+- Move each host implementation, tests and host-specific styles into its own plugin
+  package. Keep only shared data, draft-field UI and messages in the private common
+  package. Preserve the public entry points and stored formula format.
+
+  Declare ProseMirror as Tiptap's public dependency instead of bundling a second
+  copy of its host implementation. Keep host SDKs and the math core external, and
+  include common helpers and declarations within each published artifact.
+
+  Resolve workspace imports from source without a prior build. Use publishConfig
+  entry-point overrides for the core and all public plugins, and verify staged npm
+  artifacts against their generated runtime and declaration paths.
+
+## 0.4.0
+
+### Minor Changes
+
+- Exclude JavaScript and declaration source maps from the npm package. Verify their absence alongside the MIT license and runtime entry points during release preparation.
+
+- Unify native token editing and role colors with the rich React editor. Preserve token-boundary navigation, deletion and composition in framework and host adapters.
+
+  Add explicit LaTeX insertion at the caret or selection through `pasteLatex` and a nonmodal paste form. Add shareable recent/favorite symbol and template preferences, plus contextual bracket, fraction-size and operator-limit controls. Preserve formula contents, IDs and undo boundaries, and document the APIs and unreleased scope in English and Korean UI packs.
+
+## 0.3.0
+
+### Minor Changes
+
+- Recognize matrix dimensions such as `2x1`, `1x2`, `3x7` and `4x4` as suggestion shortcuts, including uppercase `X` and `×`. Support 1–20 rows and 1–20 columns. Offer matching empty and zero matrices, with identity matrices only for square sizes. Focus the first cell after insertion and keep row-order Tab editing. Preserve the typed expression until a candidate is accepted, keep surrounding terms, and restore the shortcut in one Undo.
+
+- Match native suggestion and selection menus to the rich React presentation, with larger glyphs, descriptions, localized guidance and one scrollable options list. Short host panels prioritize selectable rows; keyboard navigation keeps the host page stationary.
+
+- Add rectangular matrix-cell selection to both editing surfaces. Drag between cells or Shift-click to select a rectangle; use Select cells and Shift+arrows for keyboard selection. Copy/cut preserves nested formulas and writes a matrix clipboard payload alongside the existing fragment and LaTeX formats. Paste validates dimensions before applying, grows from a single-cell anchor within 20 × 20, and supports tab-separated cell text.
+
+  Add full-matrix transpose while preserving cell IDs, delimiters and nested caret positions. Cell paste, clear, cut and transpose are single history edits. Expose the selection and transformations through the framework-free session/core APIs, with English/Korean controls and updated documentation.
+
+- Add native toolbar symbol search, editable formula templates, matrix presets and contextual row, column and delimiter controls. Keep additional tools behind More, preserve custom structure filters, and support composition disabling for independently mounted toolbars.
+
+  Highlight exact selected text segments and allow selection to extend from the active input across formula structures. Preserve ordinary native input selection, Shift-drag anchors, iframe document ownership, clipboard behavior and structural Undo.
+
+- Add structural Up/Down navigation in the React and native DOM editors. Fractions,
+  scripts, indexed roots, annotations, grids, and equation lines choose a nearby
+  rendered caret position. The core `moveVertical` helper also works without a DOM.
+
+  Allow a separately mounted math toolbar to attach to the active editor through
+  `setSession(session)` and detach with `setSession(null)`. A detached toolbar keeps
+  its labels and disables editing commands.
+
+- Expose inherited CSS variables for editor colors, token colors, slot backgrounds, toolbar density and menu appearance. Keep per-editor themes on portaled suggestion and selection menus, including live theme switches and iframe documents. Add a styling guide and website theme/size/density examples without changing formula data or LaTeX output.
+
+### Patch Changes
+
+- Preserve keyboard suggestion navigation while the mouse rests over the list. Highlight a pointer candidate only on actual mouse movement, so menu redraws cannot restore the previous choice or scroll position. Notify host adapters after pointer highlighting to preserve the native input caret during Quill reconciliation.
+- Keep suggestion menus at their normal size inside scrolling host editors such as CKEditor and Quill. Respect transformed containers and dialog boundaries, isolate menu text alignment from the host document, and highlight pointer candidates without resetting list scroll.
+- Use the embedding document for native editor elements, suggestion menus, range measurements, and event listeners. This keeps typing, toolbar controls, selection, and scrolling menus working inside same-origin iframe editors such as the WordPress block editor.
+- Avoid a DOM Range exception when clicking an empty caret slot in the native DOM editor, including embedded Tiptap and ProseMirror math editing.
+- Preserve operands when partial structure suggestions follow a coefficient, including absolute values, roots, fractions, and fences. Keep native suggestion-list scrolling from rebuilding the list and resetting its position; scroll keyboard-selected options into view.
+- Restore the input caret when a plain arrow follows a Shift+arrow or dragged model selection. Left/Up collapses to the document-ordered start and Right/Down to the end, without changing the formula or host history. Apply the same behavior in both renderers. Use Alt+Up/Down to navigate wrapping suggestions while retaining a selection; Enter and pointer selection remain available.
+
 ## 0.2.1
 
 ### Patch Changes