@barocss/math-editor 0.2.1 → 0.5.0

package/EDITING-SCENARIOS.md

@@ -0,0 +1,174 @@
+# Editing scenarios
+
+Use this document to manage editing behavior. [Supported features](SUPPORT.md)
+lists notation; this register describes what a person does with that notation.
+[Validation](VALIDATION.md) stores dated execution evidence. Neither the number
+of features nor the number of unit tests proves that an editing flow works.
+
+## Status and ownership
+
+Keep each scenario ID stable. Add the ID to the browser fixture that exercises
+it and to a bug report when that flow fails. The person changing the behavior
+updates its expected result, test mapping and execution record in the same change.
+The release owner reviews unresolved cases before publishing.
+
+| Status | Meaning |
+| --- | --- |
+| Recorded | A dated run is recorded for the stated scope. This is not a pass for every adapter or a future build. |
+| Rerun | Related browser checks exist, but this register does not certify the full scenario on the current source. |
+| Extend | Some assertions exist; additional browser steps or checks are required. |
+| Manual | Requires a person or device. No automated pass is claimed. |
+
+P0 covers loss of content, blocked input, invalid output and host persistence.
+P1 covers discoverability, navigation and presentation. P2 covers additional
+platform coverage. A known P0 failure blocks release for the affected scope.
+An unrun or unsupported case must never be counted as passed.
+
+## Scenario register
+
+Start each case with a fresh editor unless the steps specify saved content.
+Use actual key presses for typing and actual pointer movement for drag cases.
+`Cmd` applies on macOS; `Ctrl` applies on Windows/Linux. Do not substitute a
+programmatic value assignment for a focus or typing assertion.
+
+| ID | Priority / flow | Steps | Required result | Status / test mapping |
+| --- | --- | --- | --- | --- |
+| EDIT-001 | P0 — Continuous input | Enter `4ab+12`, one key at a time. Pause after `4`. Resume while suggestions are visible. Move left, insert `x`, then delete it. | Each key appears once. The input retains focus. Numbers and variables remain in order; no key changes host prose. | Rerun — `quill-typing-check.js`, `typing-check.js`, `token-paste-check.js` |
+| EDIT-002 | P0 — Operand wrapping | Type `4ab`. Choose absolute value for the `ab` operand. Continue typing after the structure. Repeat with parentheses, fraction and root. | `ab` remains inside the chosen structure; `4` remains outside. The cursor reaches the intended slot or following boundary. No operand disappears. | Rerun — `operand-size-check.js`; `suggestions.test.ts` |
+| EDIT-003 | P0 — Selected suggestion | Type `abcd`. Select `cd` with Shift+Left twice. Use Down/Up, choose root, then Enter. Repeat with mouse drag. | The range stays selected while options change. Only `cd` is wrapped. The input receives focus after acceptance. | Rerun — `selection-suggestions-check.js`. Recorded 2026-09-09 for React and nine hosts before radical suggestions were added; rerun after suggestion changes. |
+| EDIT-004 | P0 — Return to a caret | Select part of `abcd`, press Left or Right, then type `q`. Repeat with a selection that includes a fraction. In the native field, dismiss the menu with Escape before testing Up/Down collapse. | Left uses the ordered start; Right uses the ordered end. Typing inserts at that edge instead of replacing the old range. A fraction boundary does not enter the wrong slot. | Rerun — `selection-collapse-check.js`, `tinymce-inline-check.js` |
+| EDIT-005 | P0 — Radical conversion | Load `\sqrt{x+1}`. Choose Change to Indexed root. Replace the selected `2` with `3`. Return to the radicand, then edit the index to `2` and convert back. Undo and Redo. | The radicand and nested nodes survive. Index `2` is selected on conversion. Index `3` cannot be silently discarded. One conversion is one Undo step. | Recorded, partial scope — `root-transform-check.js` (React/Quill, pointer and keyboard acceptance, 2026-09-09); `root-transform.test.ts` (Undo/Redo and nested trees). Browser Undo/Redo and the other hosts still need a run. |
+| EDIT-006 | P0 — Structure deletion | Create a fraction, scripts, aligned equations and cases. Test Backspace/Delete at inner and outer boundaries with empty and populated slots. Undo each deletion. | Behavior matches the documented boundary rule. Populated grid cells are not silently merged or lost. Undo restores content and structure. | Extend — `empty-slot-deletion-check.js` recorded React/DOM Delete, Backspace and Undo for empty roots, fractions, exponents and root indices on 2026-09-09. Grid and populated-boundary checks remain separate: `grid-deletion.test.ts`, `native-parity-check.js`. |
+| EDIT-007 | P0 — Copy and paste a range | Select text plus a nested fraction. Copy, move the caret, paste, then cut and Undo. Repeat across two editor instances. | The selected structure is preserved; unselected content stays unchanged. Cut can be undone. A rejected paste leaves the document unchanged. | Extend — `native-parity-check.js`, `token-paste-check.js`, `range.test.ts`; real OS clipboard coverage remains separate. |
+| EDIT-008 | P0 — LaTeX import failure | Import `\frac{x}{y}+z`. Edit `x`. Attempt an unsupported command and malformed braces. Cancel, then reopen. | Valid input is editable. Invalid or unsupported input reports a diagnostic and retains the previous formula. Cancel does not replace host content. | Rerun — `latex-paste-host-check.js`, `latex-insertion.test.ts`, `latex.test.ts` |
+| EDIT-009 | P0 — Apply, Cancel and history | Open an existing host formula. Edit and Cancel. Reopen, edit and Apply. Run host Undo and Redo. | Cancel leaves the stored host data unchanged. Apply creates one host history operation. Host serialization contains formula data, not input/menu DOM. | Rerun — host fixtures, including `tinymce-inline-check.js`, `quill-composition-check.js`, `ckeditor-check.js` |
+| EDIT-010 | P0 — Save and reopen | Edit nested content, Apply, Save and Restore. Reload the stored host document and reopen the formula. | Structure, LaTeX and configured presentation survive. The formula is editable after restoration. Do not claim persistence from a preview-only check. | Rerun — `unified-check.js` and host-specific fixtures; record each supported storage format. |
+| EDIT-011 | P0 — Host boundary and read-only | Move from prose into an inline formula with a boundary arrow. Edit, exit and continue prose. Switch the host to read-only with a draft open. | Math key events do not edit prose. Read-only closes or disables the draft according to the host contract and prevents new mutations. | Rerun — `shared-boundary-check.js`, `host-check.js`, host-specific fixtures |
+| EDIT-012 | P1 — Suggestion scrolling | Type `matrix`. Park the pointer over a menu item. Press Down repeatedly with pauses; reverse with Up. Test near the bottom of the viewport and in an iframe. | Each press moves one option. The selected option stays visible. The list does not jump back; the page and host do not scroll unexpectedly. | Rerun — `suggestion-arrow-check.js`, `suggestion-menu-clipping-check.js`, `iframe-field-check.js` |
+| EDIT-013 | P1 — Nested navigation | Enter `x_i^2`, a fraction inside a root, and a limit. Move with Left/Right, Up/Down and Tab at every slot boundary. | The nearest structure owns vertical movement when no suggestion menu is active. Selection and caret positions remain valid. | Rerun — `react-vertical-check.js`, `vertical-check.js`, `vertical-navigation.test.ts` |
+| EDIT-014 | P1 — Rectangular matrix | Type `3x7` and accept the matrix. Fill cells; add/delete rows and columns. Test `1x2` and `2x1` boundaries. | Dimensions match the request. Existing cells retain their content. Cursor movement follows the resulting grid. | Rerun — `matrix-size-shortcut-check.js`, `matrix.test.ts`, `native-tools-host-check.js` |
+| EDIT-015 | P0 — Matrix range editing | Select a cell rectangle. Copy/paste, clear, Undo and transpose. Test a mismatched or oversized paste. | Cell boundaries and nested structures survive. Invalid operations leave the matrix unchanged. Draft operations do not create host history entries. | Rerun — `matrix-range-check.js`, `matrix-range-host-check.js`, `matrix-range.test.ts` |
+| EDIT-016 | P1 — Lines, alignment and cases | Create two lines. Insert aligned equations and cases; add a row and edit both columns. Try Enter in inline mode. | Block layouts retain their rows. Inline mode does not create an extra formula line. Enter follows the configured host commit policy. | Extend — `typing-check.js`, `lines.test.ts`, `equation.test.ts`, `embedding.test.ts`; add a combined browser flow. |
+| EDIT-017 | P1 — Preview agreement | Edit a nested root, scripts, tall fences, integrals with limits, and a chemical formula. Compare exported LaTeX in KaTeX at a matched base size. Repeat with the input active. | Mathematical structure agrees. Baselines, fences, indices and limits remain readable. Focus backgrounds and hit areas do not obscure notation. | Recorded metric baseline — 77 formulas / 288 React/DOM mode-size comparisons passed on 2026-09-10. See the source-only `test/rendering/STATUS.md` ledger. Selected metrics and active-input checks do not certify every glyph or every editing flow. |
+| EDIT-018 | P1 — Language and multiple instances | Switch en/ko with a draft open. Open another editor and its suggestions. Repeat with a registered custom locale. | Labels resolve, formulas do not change, focus and menus stay with the right instance, and search aliases use the locale fallback rules. | Rerun — `plugins-locale-check.js`, `shared-symbol-tools-check.js`, `locale-discovery.test.ts` |
+| EDIT-019 | P0 — Long edit session | Build a fraction, wrap a selection, convert a radical, insert a matrix, undo five steps, redo five, Apply, Save and reopen. Repeat without resetting the page. | No stuck focus, lost selection, duplicated operation or draft leakage. All checkpoints retain the expected formula. | Recorded, scoped — `test/editing/continuous.browser.js`, run with `pnpm --filter @barocss/math-editor test:editing`. React standalone block, Quill/Tiptap/ProseMirror/Lexical/TinyMCE/CKEditor/Slate in-place block/inline, and Editor.js/Gutenberg block passed on 2026-09-10 (17 targets, 499 checkpoints); includes two uninterrupted formula history chains and host Apply/Save/reload/Restore/Cancel. Editor.js has no host history integration, so document Undo/Redo remains unverified there. Inline additionally verifies Enter commit without new paragraphs, right-boundary exit, prose caret position and host Undo. TinyMCE uses its inline host, CKEditor uses ClassicEditor, and Gutenberg uses the standalone provider demo. Other configurations and native OS input remain unverified by this run. |
+| EDIT-020 | P2 — Native IME and clipboard | On a real OS, compose Korean text, move the caret, use suggestions, cancel composition and paste with the system clipboard. | Composed text appears once; composition keys do not apply suggestions or host commands prematurely. Clipboard data is preserved according to the documented formats. | Manual — previously deferred by the user. Synthetic composition/DataTransfer checks do not certify OS behavior. |
+
+## Contextual structure tools
+
+These scenarios specify the footer independently from the suggestion list. The
+footer has a single target: the nearest enclosing radical or fence. It is shown only
+while that editor is active, outside literal text and model/matrix selections.
+Native text selection within the active slot is allowed, including the selected
+index produced by conversion.
+
+| ID | Priority / flow | Steps | Required result | Coverage |
+| --- | --- | --- | --- | --- |
+| EDIT-021 | P1 — Discover without search | Click inside a root. Put the caret at the start of its text. Dismiss suggestions with Escape. Move outside the root. | Footer shows the current structure and conversion even with no query or no open suggestions. Leaving the radical hides it. | `context-tools-check.js` |
+| EDIT-022 | P0 — Footer conversion and index edit | Convert a root using the footer. Replace selected index `2` with `3`. Click the radicand, choose Edit index, type `2`, convert back and Undo. | Content survives, index editing selects the existing index, a non-square index blocks reverse conversion with a visible reason, and Undo restores the structure. | `context-tools-check.js` |
+| EDIT-023 | P0 — Keyboard-only footer | From input, press F6, Escape, F6 and Enter. Tab between available buttons. | F6 enters tools; Escape returns to the same input. Button activation edits the intended structure. Keys do not reach host prose. Tab uses native button order. | F6/Escape/Enter recorded in `context-tools-check.js`; explicit Tab-order assertion remains to add. |
+| EDIT-024 | P0 — Nearest nested target | Open `\sqrt[3]{a+\sqrt{x}}`. Move between `a` and `x`. | Footer identifies the outer indexed root at `a` and inner square root at `x`. Index editing targets the corresponding root. | `context-tools-options-check.js`, `root-transform.test.ts` |
+| EDIT-025 | P1 — Locale without model changes | Show tools, change en to ko, then edit the index. | Structure name, actions, disabled reason and keyboard hint update together. Stored formula content is unchanged by locale selection. | `context-tools-options-check.js`; direct document equality on locale switch remains to add. |
+| EDIT-026 | P0 — Scope and focus | Create a model range, collapse it, blur the field, reopen, then destroy the instance. Repeat focus navigation inside an iframe. | Range mode does not show stale caret actions. Collapse restores context; blur hides it; destroy removes it. Focus stays in the iframe's own document. | `context-tools-check.js`, `context-tools-options-check.js` |
+| EDIT-027 | P0 — Composition guard | Dispatch composition start and end in the native field with context visible. | Actions are disabled during composition and resume afterward. This guard test is not OS IME certification. | Synthetic coverage in `context-tools-options-check.js`; real OS behavior remains EDIT-020. |
+| EDIT-028 | P1 — Embedding opt-out | Set `contextTools: false`, then update to true. Repeat with `context-tools="false"` on a Web Component. | Footer hides without changing the formula or removing suggestion-based conversions. Attribute updates take effect without remounting. | Visibility/update coverage in `context-tools-options-check.js`; per-framework wrapper smoke checks remain to add. |
+
+## Inline transformation suggestions
+
+The suggestion list is the primary keyboard entry point for structural changes.
+It remains available when both toolbar and context footer are hidden. Alt+Down
+opens or reopens suggestions and highlights the first available transformation;
+Up/Down browses, Enter applies, and Escape dismisses without editing the formula.
+Automatic context-only suggestions require navigation before Enter can apply them,
+so an inline host's commit key is not silently replaced.
+
+| ID | Priority / scenario | Steps | Expected result | Coverage |
+| --- | --- | --- | --- | --- |
+| EDIT-029 | P0 — Fence suggestions in inline fields | Type inside parentheses. Press Alt+Down, Enter, then continue typing. Repeat after dismissing the menu. | The list distinguishes changing a fence from wrapping an operand. Existing content and caret are preserved; the menu does not take DOM focus. | `fence-suggestions-check.js`, `context-tools.test.ts` |
+| EDIT-030 | P0 — Browse, cancel and Undo | Open changes, browse with Up/Down, cancel with Escape. Reopen, apply, type, then undo typing and conversion separately. | Browsing and cancellation do not change the formula. Conversion makes one history entry. | `fence-suggestions-check.js` |
+| EDIT-031 | P0 — Nearest wrapper and all fence pairs | Change each of eight fence types. Test nested fractions, roots, mixed delimiters and stale targets. Use F6/Left/Right/Enter if the optional footer is enabled. | Only the nearest supported wrapper changes. Slot IDs, content and caret remain stable. Explicit left/right metadata is removed when selecting a standard pair. | `context-tools.test.ts`, `fence-context-check.js`; browser nested targeting in EDIT-032 |
+| EDIT-032 | P0 — No-toolbar inline iframe | Hide toolbar/footer in an inline iframe field. Change an inner fence with suggestions, switch ko/en and continue typing. Destroy the editor. | The complete workflow works without auxiliary UI. Locale changes leave the document unchanged. Focus uses the iframe document; teardown removes suggestions. | `fence-inline-options-check.js`; installed host/browser breadth remains separate validation work |
+
+Execution scope is recorded in [Validation](VALIDATION.md). A mapped case may
+still contain pending assertions, as stated in the Coverage column.
+
+Browser fixture names above refer to `apps/math-integrations/tests/`. Unit fixture
+names refer to `packages/math-editor/test/`. A mapping identifies related coverage,
+not an assertion that every step already exists in that file. Extend cases need
+explicit browser assertions before they can receive a full pass.
+
+## Test environments
+
+Record renderer, adapter, mode and browser separately. An integration using the
+native DOM field does not prove the rich React field, and an iframe can have its
+own focus, event and CSS failures.
+
+| Layer | Required scope when that layer changes |
+| --- | --- |
+| Shared model / suggestions | Unit checks plus affected editing scenarios on rich React and native DOM. |
+| Framework adapter | The affected adapter: pure JS, Web Component, Vue, Svelte, Solid, or React wrapper. Record the actual renderer used. |
+| Host integration | Every affected host. Shared field changes need the nine-host smoke set: Tiptap, ProseMirror, Lexical, Editor.js, TinyMCE, CKEditor, Quill, Slate, Gutenberg. |
+| Mode / container | Inline and block where supported; TinyMCE classic iframe as well as inline. Editor.js and Gutenberg block-only scenarios are N/A for inline tests. |
+| Browser | Record Chromium, Firefox or WebKit explicitly. Current Chromium evidence does not cover the other engines. |
+| Build source | Workspace source for development; packed artifacts for release checks. Neither implies the other. |
+
+## Per-run record
+
+Append detailed evidence to [Validation](VALIDATION.md), using this template.
+Record an immutable revision when possible. For an uncommitted workspace, record
+that fact and save the tested patch or a source fingerprint with the run artifacts.
+A date alone does not identify the tested code.
+
+```text
+Run ID: edit-YYYYMMDD-NN
+Scenario IDs:
+Source: commit / workspace fingerprint / package versions and archive hashes
+Fixture revision:
+Renderer and host:
+Mode and container:
+Browser, OS, locale:
+Input formula and steps:
+Expected result:
+Observed result:
+Outcome: PASS / FAIL / BLOCKED / NOT RUN / N/A
+Evidence: log, screenshot pair, trace or recorded host data
+Remaining steps and excluded environments:
+Issue / follow-up:
+```
+
+A scenario passes only when all required assertions pass in the recorded scope.
+For partial coverage, report the passing steps and keep the rest unverified.
+Do not convert historical validation totals into a current release pass.
+
+## Change workflow
+
+1. Assign a scenario ID to each editing bug before changing its behavior.
+2. Reproduce the smallest failing input sequence. Capture the caret, selection,
+   highlighted suggestion, document and host data where relevant.
+3. Add or update a regression fixture with the same ID. Check the final model,
+   cursor/focus and history behavior, not only whether an element is visible.
+4. Implement the change. Run its model tests, affected browser scenarios and the
+   nearest negative case. Compare editor/KaTeX output when notation changes.
+5. Record the result and its scope. Mark related scenarios for rerun if later
+   changes touch their input, selection, suggestions, history or host handling.
+6. Before release, run the applicable P0 cases against the release candidate and
+   check packed imports. Any excluded host/browser must be stated explicitly.
+
+The Markdown register is the source of truth for scope and acceptance criteria.
+The browser fixtures contain executable assertions. The validation report holds
+run evidence. The documentation site renders this register; it does not execute
+the browser checks. Automated release enforcement is not implemented by this
+register alone.
+
+## Next work
+
+1. Maintain the EDIT-019 baseline across all nine integration demos and React
+   standalone block. Extend it separately to TinyMCE iframe, WordPress admin and
+   other host configurations. Preserve exact checkpoints and host-history assertions.
+2. Add missing browser steps for EDIT-006, EDIT-007 and EDIT-016. Include negative
+   cases and real host Undo/Redo rather than testing only model transformations.
+3. Reuse the EDIT-019 runner pattern for additional scenario IDs. It already
+   records source fingerprints and fails on changed source or failed assertions.
+   CI/release enforcement remains separate work.
+4. Schedule Firefox/WebKit and real OS IME/clipboard coverage separately. Keep
+   manual requirements visible without representing synthetic events as a substitute.

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,119 @@ 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.
+
+### Contextual radical conversions
+
+`findStateSuggestions(state, locale, caret?)` augments text search with the nearest
+enclosing radical's conversion actions. `transformRootId` binds an action to that
+structure; `acceptSuggestion` validates the current target before conversion and
+does not remove the query. `root-transform.ts` clones the document, preserves the
+radicand tree and structure ID, and updates the slots. Converting to an indexed
+root adds a selected index `2`; converting to a square root rejects any nonempty
+index other than `2`. Both renderers use this shared path and their normal history
+commit mechanism. Context-only actions require pointer acceptance or arrow-key
+selection before Enter can apply them.
+
+### Empty-slot deletion and script fractions
+
+`unwrapEmptySlot` removes a non-grid wrapper from inside a truly empty slot.
+Both Delete and Backspace call it before boundary-specific deletion. The other
+slots are retained; an empty root index collapses to a square root, and an empty
+paired script preserves the other script. A populated row or ordinary structural
+boundary is not an empty slot. Grid cells keep their shape and their existing
+explicit deletion controls. The edit uses the normal history commit.
+
+Fractional script presentation uses compact row heights and term metrics in both
+renderers. See [Rendering checks](RENDERING-TESTS.md) for the bounded geometry
+comparison and remaining layout work.
+
+### Query-independent context footer
+
+`rootEditingContext(state)` derives the nearest radical, conversion availability
+and index caret from the model. React and DOM render the same actions below the
+surface. The footer does not use suggestion text, dismissal or candidate indices.
+Transformations use `transformRoot` and normal history; Edit index only moves
+and selects the caret. Model/matrix selections and blur hide context actions.
+F6 and Escape are handled within the editor to retain host/iframe focus. Native
+composition disables footer actions without replacing the composing input.
+
+### Shared fence transformations
+
+`structureEditingContext` selects the nearest supported radical or fence and
+excludes literal text. `findStateSuggestions` adds fence transformations before
+operand-wrapping actions, while retaining explicit symbol/command matches first.
+`transformFenceId` distinguishes metadata changes from new structure insertion.
+Acceptance validates the current target before preserving content, IDs and caret.
+
+React and native DOM handle Alt+Down before modifier-key fallthrough. The shortcut
+reopens a dismissed list and arms the first context action. Normal contextual
+menus still require navigation before Enter overrides host commit behavior.
+The footer is optional; suggestions do not depend on its visibility.
+
+
+## Contextual operator layout
+
+`src/math-layout.ts` derives display, text, script and scriptscript contexts from
+model slots on each render. It does not mutate or persist presentation metadata.
+Fractions reduce the style of their terms; scripts reduce their labels; indexed
+root indices use scriptscript style. Explicit fraction styles reset that context. Aligned cells enter display style; matrix and cases cells enter text style.
+
+Both React and native DOM consume the same row/operator map. Operator attributes
+select the large or small font and side or stacked limits. Explicit limits remain
+authoritative. Scoped row attributes keep a nested operator body at its own size
+while reducing its bounds. This replaces the inline-only CSS decision, which
+could not identify operators inside fractions or nested scripts.
+
+The current CSS application is scoped to operators. Other structures still use
+their existing layout rules; this is not a complete TeX layout engine.
+
+### Horizontal text spacing
+
+`math-spacing.ts` computes spacing between lexical runs without changing the
+saved document, token boundaries or caret offsets. Both renderers use the same
+values. Common binary operators use 4 mu, relations use 5 mu and punctuation
+uses 3 mu before the next atom (18 mu = 1 em). Neighboring atoms distinguish
+unary signs from binary operators. Binary, relation and punctuation gaps are
+suppressed in script and scriptscript rows.
+
+Measuring spans use glyph width instead of adding padding to every math token.
+Literal text fields retain their text layout. Named-function fields use unpadded glyph measurement. Inactive model
+boundaries use 1 px; empty expression slots and the active boundary keep their
+existing input hit areas. Other structure interiors and full TeX atom classification are separate work. These rules do not provide a complete
+TeX horizontal layout engine.
+
+
+### Named functions and fraction boundaries
+
+Named functions and fractions participate in the same horizontal-spacing pass as
+text runs. A named function uses a thin gap next to an ordinary atom or another
+named function, and no gap before a plain opening parenthesis. These thin gaps
+remain in script styles at the corresponding reduced font size. Binary and
+relation gaps still disappear in scripts. Fractions contribute an ordinary atom
+and receive their external gap once, rather than adding fixed margins on both
+sides. The function name's measuring span adds no glyph padding.
+
+The spacing map contains structure IDs for these two families and token-offset
+keys for text. Other structure families keep their existing outer layout. This
+change does not alter LaTeX output, JSON, selection offsets or editing commands.

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,34 @@ 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).
+
+### Change a radical while editing
+
+Inside `\sqrt{x}`, choose **Change to Indexed root** in the suggestions. The
+result is `\sqrt[2]{x}` with `2` selected for replacement. The content under the
+radical is preserved. An indexed root with an empty index or `2` offers **Change
+to Square root**. Other indices must be edited before that conversion is offered.
+This editing operation does not change the LaTeX grammar or JSON model schema.
+
+
+## Literal caret/tilde and complex root indices
+
+A literal `^` or `~` in a model text run exports as `\char"005E{}` or
+`\char"007E{}`. These spellings render in KaTeX math mode and load back into the
+same text run. The importer also accepts `\textasciicircum{}` and
+`\textasciitilde{}` as input aliases. Inside `\text{...}`, text-mode escaping
+remains unchanged. General TeX `\char` codes are not supported.
+
+An index containing braces or brackets is grouped when exported. For example,
+`\sqrt[{x^2}]{y}` and `\sqrt[{\left[a\right]}]{y}` keep the optional index
+argument intact. Grouping does not add a JSON node or remove editable structure.
+Simple indices continue to export as `\sqrt[3]{x}`.

package/LATEX-MODEL.md

@@ -288,3 +288,15 @@ Type `xrightarrow`, `xleftarrow`, or search for “labeled arrow” / “설명
 `\begin{equation*} ... \end{equation*}` imports its body into the existing root math row. It creates no new node kind and adds no suggestion item. Export emits the body without the environment wrapper. Nested supported structures remain editable. Missing/mismatched endings and unsupported commands fail atomically.
 
 Numbered `equation`, `\tag` and `\label` are not supported: the model cannot preserve numbering or references. Use `equation*` only when formula-only import is intended. `align`, `split` and `array` remain open.
+
+
+### Protected root indices and literal characters
+
+| Model content | Canonical LaTeX | Import result |
+| --- | --- | --- |
+| Text run containing `^` | `\char"005E{}` | Same text run, not a superscript |
+| Text run containing `~` | `\char"007E{}` | Same text run, not an accent |
+| `indexedRoot` with a structured index | `\sqrt[{…}]{…}` | Same index and radicand slots; protective braces add no model node |
+
+Literal text groups keep their existing text-mode escapes. Only the two character
+codes above are supported; this does not implement arbitrary TeX character codes.

package/LATEX-SCOPE.md

@@ -19,7 +19,7 @@ The first product target is Note: open an existing supported LaTeX formula in a
 | Import for editing | `parseLatex` and the editor model | Parser succeeds and every resulting node remains editable |
 | Export LaTeX | `toLatex` | Supported model produces valid presentation output |
 
-KaTeX display support does **not** imply editable import support. For example, KaTeX can display annotations such as underbraces that the editor cannot yet import. Unsupported notation must fail without a partial conversion.
+KaTeX display support does **not** imply editable import support. For example, a host can configure KaTeX macros that the editor does not import. Unsupported notation must fail without a partial conversion.
 
 ## V1 grammar
 
@@ -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)
 
@@ -261,3 +261,12 @@ Type `xrightarrow`, `xleftarrow`, or search for “labeled arrow” / “설명
 `\begin{equation*} ... \end{equation*}` imports its body into the existing root math row. It creates no new node kind and adds no suggestion item. Export emits the body without the environment wrapper. Nested supported structures remain editable. Missing/mismatched endings and unsupported commands fail atomically.
 
 Numbered `equation`, `\tag` and `\label` are not supported: the model cannot preserve numbering or references. Use `equation*` only when formula-only import is intended. `align`, `split` and `array` remain open.
+
+
+## Compatibility corrections — 2026-09-10
+
+Math-mode caret and tilde text runs export with bounded `\char"005E{}` and
+`\char"007E{}` commands. Text-mode aliases remain accepted and literal text-group
+escaping is unchanged. Arbitrary character codes remain unsupported.
+Complex root indices export inside a protective group, preserving their existing
+JSON slots. See [the LaTeX guide](LATEX-GUIDE.md#literal-carettilde-and-complex-root-indices).

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.
-
-