@barocss/math-editor 0.2.1 → 0.4.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,64 @@ 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.

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

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @barocss/math-editor
 
+## 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

package/EMBEDDING.md

@@ -100,3 +100,7 @@ The browser tests cover panel synchronization without extra change events, singl
 Note opts into the shared `LatexEditor` visual mode with `MathEditorSurface`. Existing tex-only atoms load through `parseLatex`; unsupported input stays in the original source editor. Visual draft changes produce `tex` plus JSON-encoded `mathDocument`. `setMathSource` validates the structure, source equality and inline policy, then applies one host transaction. Cancellation writes nothing. Direct source changes clear stale structure, while font/alignment-only edits retain it.
 
 Other products must use the same [import scope](LATEX-SCOPE.md) and core parser. Do not add product-specific regex conversions. Existing Word OMML and Site/Slide ownership boundaries still need their own host adapters; the Note trial does not integrate those products automatically.
+
+## 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/IMPLEMENTATION.md

@@ -28,8 +28,10 @@ Navigation does not create a document history entry. Locale changes do not remou
 | `tokens.ts` | Lexical variable/numeric/symbol segmentation and boundary affinity |
 | `math-editor.tsx` | Native input lifecycle, IME, pointer hit testing, selection UI, keyboard routing and portal |
 | `range.ts` | Endpoint ordering, balanced selection resolution, slicing, insertion, wrapping and clipboard validation |
+| `matrix-range.ts` | Transient cell rectangles, clipboard shape validation, fresh subtree IDs, atomic paste/clear and full-matrix transpose |
 | `matrix.ts` | Innermost grid lookup, row/column changes, delimiters and grid navigation |
 | `lines.ts` | Top-level line split/join and vertical navigation |
+| `vertical-navigation.ts`, `dom/caret-geometry.ts` | Shared structural Up/Down movement and optional measurements of rendered insertion points |
 | `suggestions.ts` | Longest symbolic triggers, bilingual aliases, candidates and acceptance |
 | `symbols.ts` | Glyph, message key, search aliases, symbolic triggers and LaTeX mapping |
 | `templates.ts` | Fresh editable template trees and insertion through the range model |
@@ -60,6 +62,8 @@ Passive tokens render as spans. Only the active token renders an input. A hidden
 
 During composition, the token partition and input element are held stable. Suggestions are visible but disabled. Enter and arrows remain with the IME; parent handlers do not receive editing keystrokes. On composition end, the complete text is committed as one history change and tokenization resumes. Synthetic composition tests are not a substitute for actual OS input-method validation.
 
+`moveVertical` walks slot ancestors from the inside out: fractions, scripts, indexed roots, annotations and operator bounds precede enclosing grids and document lines. Grid targets stay in the same column. Both keyboard handlers pass caret measurements from the existing hidden mirrors; React token offsets are translated back to their logical text run. The target is the nearest horizontal insertion point in the requested direction, with vertical distance breaking ties. Paired scripts and operator bounds also consider their base/body, so movement can follow their shared script column. Missing layout uses the first target text run with a clamped UTF-16 offset, avoiding surrogate splits. Navigation preserves the document and undo history. It does not add persistent preferred-column state or change Shift+arrow selection.
+
 ## Ranges and transformations
 
 `MathRange` has anchor/focus points identified by logical text ID and UTF-16 offset. `resolveRange` orders them in document traversal order and finds the deepest shared row. Endpoints in different slots expand to a balanced common structure; endpoints on different document lines produce multiple row slices.
@@ -175,7 +179,7 @@ The parser accepts a bare brace body and creates an empty annotation. Export alw
 
 ## 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 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 also expose symbol search, templates and presets behind More tools; both renderers provide contextual matrix controls and cell selection/transpose. The layout wraps naturally on narrow screens; this is not a guaranteed single-row toolbar.
 
 ```tsx
 <MathEditor toolbar={['fraction', 'root', 'superscript', 'matrix']}
@@ -214,7 +218,7 @@ Each is a structure with a unique `id` and exactly one MathRow in `slots: [body]
 
 All limit-family, sum/product and integral nodes accept a single `\limits` or `\nolimits` immediately after the command, before scripts. The optional `limits` field is now boolean: omitted means default, `true` is stacked placement, `false` is side placement. Both explicit values survive JSON validation, copying and LaTeX export. Repeated/conflicting directives are rejected. Existing `limits: true` remains valid; older package builds do not accept `false` or the new limit kinds.
 
-Placement is currently selected through imported LaTeX/model metadata, not a dedicated toolbar switch. Imported side conditions remain editable; normal limit suggestions use default placement. This is 0.2.0 functionality.
+Placement is selected through imported LaTeX/model metadata or the workspace contextual toolbar. Imported side conditions remain editable; normal limit suggestions use default placement. This is 0.2.0 functionality.
 
 ## Fine mathematical spacing (workspace)
 
@@ -240,3 +244,24 @@ Reuse the existing two-slot structures with optional `mathStyle: 'display' | 'te
 ## Labeled arrows
 
 The `xrightarrow` and `xleftarrow` structures have two slots in upper/lower order. Parse the optional lower bracket before the required upper argument, then store in model order. Render the generic slots in three CSS grid rows, with a pseudo-element shaft and a fixed-size head in the middle row. Labels drive grid width; the decoration cannot intercept pointer events. These commands are inserted through the shared catalog and do not require a separate dialog.
+
+## Cell selection and grid transformations
+
+`MathMatrixRange` is separate from `MathRange`: `{ matrixId, anchor, focus }` uses
+row-major cell indices and resolves to a rectangle. Neither selection is persisted.
+Cross-cell pointers use the nearest shared matrix ancestor; within-cell pointers
+retain text/structure selection. The DOM renderer keeps selection in MathSession;
+rich React owns its view state and calls the same pure matrix operations.
+
+Clipboard data has its own bounded matrix MIME payload, plus a regular math
+fragment and LaTeX fallback. Incoming cells receive fresh IDs recursively. Paste
+validates all dimensions before cloning or writing the destination; unselected
+cells and the destination delimiter survive. Transpose reorders existing slots
+and changes `columns`; preserving IDs keeps a nested caret valid. None of these
+operations needs a new model version or parser command.
+
+## Shared editing utilities — workspace
+
+Native text rows are tokenized with the same `tokenizeMathText`/`tokenIndexAt` rules as rich React. Every rendered run retains its model ID and UTF-16 token start/end. Input events replace only that token's slice. Pointer/keyboard offsets are translated to model coordinates; boundary deletion joins neighboring text without discarding it. IME preedit updates the stable input/mirror and is committed before re-tokenizing. Literal text/operator names remain one input.
+
+`latex-insertion.ts` parses before applying a range insertion. `preferences.ts` owns validated UI lists independently of formula sessions/history. `presentation.ts` changes only supported metadata while preserving subtree IDs and caret. The nonmodal native panels are reused by React wrappers, so diagnostics and favorites use one implementation. Host clipboard boundaries stay intact and no system clipboard reads are implicit.

package/JSON-MODEL.md

@@ -244,6 +244,7 @@ This has two top-level lines and exports as `gathered`. A two-row matrix inside
 | `MathCaret` | Text node `id`, UTF-16 `start`/`end`, optional affinity | No |
 | `MathState` | `{ document, caret }` while editing | No; save its `document` |
 | `MathRange` | Structural selection endpoints | No |
+| `MathMatrixRange` | `{ matrixId, anchor, focus }` with row-major cell indices; transient rectangular selection | No |
 | `MathHistory` | Past/present/future editing states | No |
 | `MathFragment` | Clipboard `{ version: 1, rows: MathRow[] }` | No; different envelope from a document |
 | Host `tex` / `mathDocument` attributes | Product-specific storage container | No; the host may store serialized document JSON alongside derived LaTeX |

package/LATEX-GUIDE.md

@@ -43,6 +43,7 @@ Typing LaTeX into an ordinary editor slot is not the same as importing it. Use t
 
 ## Type with suggestions
 
+- In the 0.4.0 release, enter a matrix size as `rows x columns` without spaces. `2x1` creates two rows and one column, `1x2` creates one row and two columns, and `3x7` creates three rows and seven columns. Each dimension must be an integer from 1 to 20, without leading zeros. Uppercase `X` and `×` also work. Suggestions offer an empty matrix and a zero matrix; square sizes additionally offer an identity matrix. Enter accepts the highlighted candidate and focuses its first cell; Tab moves through cells in row order. Space or Escape keeps the original text. These are editor shortcuts, not LaTeX commands; accepted matrices export as the usual `bmatrix` environment.
 - Type `nthroot`, `nroot` or `n제곱근` and choose Indexed root. Enter the index, press Tab, then enter the radicand. A selected expression can be wrapped; it becomes the radicand and the index receives focus.
 - Type `text` or `텍스트`, choose Text and write the description. Tab returns to math input. Mathematical suggestions are disabled inside literal text.
 - Type a function name such as `sin`, `cos`, `log` or `ln`, then select its suggestion. Accept the suggestion before typing the argument; plain `log` remains variable text until converted.
@@ -249,6 +250,12 @@ Numbered `equation`, `\tag` and `\label` are not supported: the model cannot pre
 
 ## Keyboard ranges and brace discovery (0.2.1)
 
-Shift+Left/Right extends or shrinks the same model range used by dragging. Structures are crossed as balanced units; copied and deleted ranges use existing model normalization. Shift+Up/Down extends to an adjacent top-level document line, using a logical text offset rather than pixel-based column matching; grid-cell rectangular selection is not added. Copy, cut, wrapping, deletion and Undo use the existing range behavior. IME composition and modifier shortcuts retain their existing handling.
+Shift+Left/Right extends or shrinks the same model range used by dragging. Structures are crossed as balanced units; copied and deleted ranges use existing model normalization. Shift+Up/Down extends to an adjacent top-level document line, using a logical text offset rather than pixel-based column matching; an active matrix-cell selection instead uses Shift+arrows to move its rectangular focus corner. Copy, cut, wrapping, deletion and Undo use the existing range behavior. IME composition and modifier shortcuts retain their existing handling.
 
 Typing `{` offers both paired braces and cases. Paired braces remain the first candidate; choose Cases explicitly to insert its editable grid.
+
+## Insert or adjust existing math — workspace
+
+Use **Paste as LaTeX** in More tools, or **Alt+Shift+V**, to paste a source fragment at the current caret or selected range. Ctrl/Cmd+Enter inserts it; unsupported input stays in the source field with a diagnostic. Ordinary paste retains its existing literal-text behavior.
+
+When the caret is inside a structure, the toolbar can change its bracket pair, fraction/binomial display size, or operator limit placement. These actions preserve contents and support one-step Undo. Recent & favorites keeps frequently used symbols/templates available without searching again. See [editing utilities](API-SESSION.md#editing-utilities--workspace).

package/LATEX-SCOPE.md

@@ -69,7 +69,7 @@ Empty editable slots are valid import data, even if a host requires a nonempty f
 | `\newcommand`, `\def`, packages, labels, references, document preambles | No macro expansion or document-level TeX processing |
 | `\input`, URLs, HTML or trust-enabled renderer commands | Never execute or resolve resources |
 
-New syntax enters this table only with a model mapping, export policy, positive/negative fixtures and editor tests. Additional delimiters and overset/underset annotations are implemented in the workspace. Wider accents, under/over braces and explicit delimiter sizes remain future candidates. See the [editing guide and expansion priorities](LATEX-GUIDE.md); these are not implemented support.
+New syntax enters this table only with a model mapping, export policy, positive/negative fixtures and editor tests. Additional delimiters and overset/underset annotations are implemented in the workspace. The additional accents and under/over braces documented below are implemented; explicit delimiter sizes remain a future candidate. See the [editing guide and expansion priorities](LATEX-GUIDE.md); these are not implemented support.
 
 ## API and failure behavior
 
@@ -214,7 +214,7 @@ Each is a structure with a unique `id` and exactly one MathRow in `slots: [body]
 
 All limit-family, sum/product and integral nodes accept a single `\limits` or `\nolimits` immediately after the command, before scripts. The optional `limits` field is now boolean: omitted means default, `true` is stacked placement, `false` is side placement. Both explicit values survive JSON validation, copying and LaTeX export. Repeated/conflicting directives are rejected. Existing `limits: true` remains valid; older package builds do not accept `false` or the new limit kinds.
 
-Placement is currently selected through imported LaTeX/model metadata, not a dedicated toolbar switch. Imported side conditions remain editable; normal limit suggestions use default placement. This is 0.2.0 functionality.
+Placement is selected through imported LaTeX/model metadata; the workspace now also provides contextual toolbar controls. Imported side conditions remain editable; normal limit suggestions use default placement. This is 0.2.0 functionality.
 
 ## Fine mathematical spacing (workspace)
 

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 BaroCSS contributors
+Copyright (c) 2026 barocss.com
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -19,5 +19,3 @@ 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.
-
-