@barocss/math-editor 0.4.0 → 0.6.1

package/KEYBOARD.md

@@ -0,0 +1,41 @@
+# Keyboard reference
+
+Open **Keyboard & clipboard help** from the math toolbar, or press **F1 while the formula has focus**. This also works in a toolbar-free inline field. Some keyboards require Fn+F1. Close help to return to the previously focused input without editing the formula.
+
+Use Cmd on macOS and Ctrl on Windows/Linux. Alt is Option on macOS. The host and operating system can reserve keys; the field only handles its shortcuts while it has focus.
+
+| Context | Keys | Action |
+| --- | --- | --- |
+| Active input | Left / Right | Move the caret; repeated keydown continues across token and slot boundaries |
+| Active input, no suggestion menu | Up / Down | Move between supported structural slots or lines; repeated vertical movement retains the preferred column |
+| Editable slots | Tab / Shift+Tab | Next / previous slot |
+| Formula selection | Shift+Left / Right | Extend or shrink the selected range |
+| Active formula | Ctrl+Left / Right (Option+Left / Right on macOS) | Move by text units or whole math structures |
+| Active formula | Ctrl+Shift+Left / Right (Option+Shift+Left / Right on macOS) | Extend or shrink selection by text units or structures |
+| Matrix cell | Alt+Shift+Backspace | Delete the current column; Undo restores it |
+| Matrix cell | Alt+Shift+Up | Delete the current row; Undo restores it |
+| Nonempty math selection | `(`, `[`, `{`, `\|` | Wrap in parentheses, brackets, braces or absolute value |
+| Nonempty math selection | `/` | Use the selection as numerator; enter the denominator next |
+| Nonempty math selection | `^` / `_` | Use the selection as base; enter the exponent or subscript next |
+| Active formula | Alt+Down | Open suggestions, including transformations for the nearest supported structure |
+| Suggestions open | Up / Down, Enter | Choose and apply a suggestion |
+| Suggestions open | Escape | Dismiss suggestions before returning to ordinary navigation |
+| Active formula | Ctrl/Cmd+Z / Ctrl/Cmd+Shift+Z | Undo / Redo |
+| Selected range | Ctrl/Cmd+C / X | Copy / Cut |
+| Active formula | Ctrl/Cmd+V | Paste available editor data or literal text |
+| Active formula | Alt+Shift+V | Open Paste as LaTeX |
+| LaTeX paste panel | Ctrl/Cmd+Enter / Escape | Insert / close the panel |
+| Active formula | F1 | Open help |
+| Context footer available | F6 | Move focus between the input and contextual controls |
+
+## Enter depends on context
+
+An active suggestion normally receives Enter. Escape dismisses it first if you want a different action. Operand-only suggestions require navigation before Enter applies them, so ordinary Enter does not unexpectedly wrap an operand.
+
+In a block field, Enter follows the configured newline/commit policy. Shift+Enter bypasses suggestion acceptance and creates a row in a grid or a line at the outer block level. Inline fields do not create top-level formula lines. Their completion and boundary-exit behavior belongs to the embedding host.
+
+## Delete depends on context
+
+Backspace/Delete removes a selection. At a structure boundary it can unwrap retained contents. An empty slot can remove or reduce its enclosing structure. Populated grids require their grid selection/deletion policy so cells are not silently flattened. At the end of a top-level line, Delete joins the following line; Backspace at the next line's start joins backward. Undo restores the change.
+
+The direct wrapping keys apply only to a nonempty math selection. Literal text, matrix rectangles and multiline ranges retain their own rules. See [selection editing](LATEX-GUIDE.md#select-replace-and-wrap), [copy and paste](CLIPBOARD.md) and [practice exercises](https://math-editor.barocss.com/#tutorial).

package/LATEX-GUIDE.md

@@ -2,6 +2,8 @@
 
 This guide describes **version 0.2.0**, including bounded LaTeX import and editable notation. See [installation and API guides](README.md) for package usage and [the support contract](LATEX-SCOPE.md) for the exact grammar.
 
+Start with [practice exercises](GETTING-STARTED.md), [copy and paste](CLIPBOARD.md), or the [keyboard reference](KEYBOARD.md).
+
 ## Load and edit a formula
 
 In the demo, open **Import LaTeX**, enter a supported expression and apply it. Click a displayed slot to edit it. A successful import is undoable; a failed import preserves the existing formula and returns diagnostics.
@@ -58,7 +60,23 @@ Standard function names: `sin`, `cos`, `tan`, `cot`, `sec`, `csc`, `arcsin`, `ar
 
 Drag across a formula to select a model range. The regular suggestion list offers fraction, root, superscript, subscript, parentheses, brackets and absolute value. Click a candidate, or use arrow keys and Enter. Compound bases receive parentheses when wrapped in an exponent.
 
-Typing a printable character replaces the selected range and resumes editing. Backspace/Delete removes the selection. Undo restores content. Wrapping multiple top-level lines is disabled. In combined scripts, Backspace in an empty script removes that side while retaining the other script.
+With a nonempty math selection, these keys apply immediately without choosing a suggestion:
+
+| Key | Result | Caret after wrapping |
+| --- | --- | --- |
+| `(` | Parentheses | After the closing parenthesis |
+| `[` | Square brackets | After the closing bracket |
+| `{` | Braces | After the closing brace |
+| `\|` | Absolute value | After the closing bar |
+| `/` | Fraction with selection as numerator | Empty denominator |
+| `^` | Selection as the base of a power | Empty exponent |
+| `_` | Selection as the subscript base | Empty subscript |
+
+Compound power bases receive parentheses. Each wrap is one Undo step; subsequent typing is a separate edit. This works with mouse dragging, Shift+arrows and native input selections in React and DOM fields, including toolbar-free inline fields. The key handling is shared by the framework and host adapters through their renderer.
+
+Other printable characters replace the selection. Without a selection, the existing suggestion behavior stays unchanged; `{` can still offer braces and cases. Literal text slots retain text input. Ctrl/Cmd/Alt combinations and IME composition are not structural shortcuts. Multi-line selections remain selected and unchanged when a wrapping key is pressed. Rectangular matrix-cell selection retains its own typing behavior.
+
+Backspace/Delete removes the selection. Undo restores content. In combined scripts, Backspace in an empty script removes that side while retaining the other script.
 
 ## Text boundaries
 
@@ -68,7 +86,7 @@ The editor retains structure and canonical notation, not the exact original sour
 
 ## What should be added next?
 
-See the [prioritized LaTeX backlog](ROADMAP.md#remaining-latex-priorities-workspace-review-2026-09-08). Norm fences and additional integrals come first, followed by annotated braces and more accents. Fine spacing, styles and equation environments need explicit preservation policies. These are candidates, not current parser support.
+Norms, triple/contour integrals, brace annotations and additional accents are already supported. See the [current roadmap](ROADMAP.md#subsequent-milestones) for remaining work. New notation must keep the model, parser, keyboard editing and rendering aligned.
 
 Each addition needs a documented JSON shape, import/export round trips, unsupported-input diagnostics, actual per-character typing, cursor movement, selection, deletion and Undo tests in both renderers. See [roadmap](ROADMAP.md) for progress and [validation](VALIDATION.md) for tested coverage.
 
@@ -259,3 +277,35 @@ Typing `{` offers both paired braces and cases. Paired braces remain the first c
 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}`.
+
+## Boundary deletion and continued editing
+
+- At the outside right edge of a non-grid structure, Backspace removes the wrapper and retains its contents. At the outside left edge, Delete does the same and leaves the caret before the retained contents.
+- An empty non-grid slot can remove its wrapper with Backspace or Delete. Removing an empty root index or one empty paired-script slot retains the other structure parts.
+- Populated matrices, aligned equations and cases use a separate boundary selection before a second deletion removes the whole grid. Removing a wrapper never silently flattens a populated grid into text. A cell's ordinary text deletion remains local.
+- Backspace at the start of a top-level line joins the previous line. Delete at the end joins the next line. Undo restores the original structure and lines.
+- Repeated Up/Down movement retains its preferred horizontal position through shorter rows. Horizontal movement, typing and pointer placement reset that preference. Visible suggestions retain ownership of Up/Down; Escape dismisses them.
+- Shift+Enter bypasses suggestions. In a grid it inserts a row; in a block top-level expression it follows the newline policy. Inline mode remains one top-level line.
+- Invalid structured clipboard data leaves the formula unchanged and reports an error. Multiline paste is rejected in inline mode and inside nested math slots. Plain clipboard text remains literal; use the explicit LaTeX paste action for parsing.

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
 
@@ -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/README.md

@@ -2,11 +2,23 @@
 
 An embeddable math editor for writing LaTeX-compatible formulas. Edit expressions in place, select existing math, and wrap it in fractions, roots, powers or delimiters. The package includes a framework-independent model, a rich React editor, and a native DOM editor with framework adapters.
 
-**Release:** core **0.4.0**, with nine host editor plugins at **0.1.0**. This editor does not calculate, solve equations or parse arbitrary LaTeX.
+This editor does not calculate, solve equations or parse arbitrary LaTeX.
 
-## Editing additions in 0.4.0
+Selection shortcuts: highlight math and press `(`, `[`, `{`, `|`, `/`, `^` or `_` to wrap it immediately. Fractions focus the denominator; powers and subscripts focus their empty script. See [selection editing](LATEX-GUIDE.md#select-replace-and-wrap) for behavior and exceptions.
 
-The native renderer now edits one lexical token at a time, matching the main React field's role colors. New utilities provide **Paste as LaTeX** (Alt+Shift+V), **Recent & favorites** for symbols/templates, and contextual **bracket, fraction-size and limit-placement settings**. These utilities are included in 0.4.0. See [editing utilities and API](API-SESSION.md#editing-utilities--workspace).
+## Learn the editor
+
+Try the [interactive exercises](https://math-editor.barocss.com/#tutorial), read [copy and paste](https://math-editor.barocss.com/docs/clipboard.html), or open the [keyboard reference](https://math-editor.barocss.com/docs/keyboard.html). F1 opens help while a math field has focus, including toolbar-free inline fields.
+
+## Package ownership
+
+Each host plugin owns its source and version. Workspace apps import source without
+a prerequisite build; npm consumers receive generated runtime and declarations.
+The private common module is included in each plugin and is not installed separately.
+
+## Editing utilities
+
+The native renderer now edits one lexical token at a time, matching the main React field's role colors. New utilities provide **Paste as LaTeX** (Alt+Shift+V), **Recent & favorites** for symbols/templates, and contextual **bracket, fraction-size and limit-placement settings**. See [editing utilities and API](API-SESSION.md#editing-utilities--workspace).
 
 ## Packages
 
@@ -14,19 +26,19 @@ Choose the core package for a standalone math field. Choose one additional host
 
 | Package | Purpose | Formula placement | Release status |
 | --- | --- | --- | --- |
-| `@barocss/math-editor` | Math model, LaTeX import/export, editor, toolbar and framework adapters | Standalone, inline or multiline | 0.4.0; MIT |
-| `@barocss/math-editor-tiptap` | Tiptap node extension | Inline and block | 0.1.0; MIT |
-| `@barocss/math-editor-prosemirror` | ProseMirror schema, commands and node views | Inline and block | 0.1.0; MIT |
-| `@barocss/math-editor-lexical` | Lexical math node and registration | Inline and block | 0.1.0; MIT |
-| `@barocss/math-editor-editorjs` | Editor.js math Tool | Block | 0.1.0; MIT |
-| `@barocss/math-editor-tinymce` | TinyMCE plugin with in-place or panel editing | Inline and block | 0.1.0; MIT |
-| `@barocss/math-editor-ckeditor` | CKEditor 5 model objects and widgets | Inline and block | 0.1.0; MIT |
-| `@barocss/math-editor-quill` | Quill math embeds and registration | Inline and block | 0.1.0; MIT |
-| `@barocss/math-editor-slate` | Slate void elements and React rendering | Inline and block | 0.1.0; MIT |
-| `@barocss/math-editor-gutenberg` | WordPress Gutenberg math block | Block | 0.1.0; MIT |
-| `@barocss/math-editor-integrations` | Shared implementation used to build the nine host packages | Internal development | Private; not an install target |
-
-The host plugins require `@barocss/math-editor@^0.4.0`. The core and all nine host packages use the MIT license, with copyright attributed to barocss.com. Each package includes its own LICENSE file. Host SDKs retain their own licenses.
+| `@barocss/math-editor` | Math model, LaTeX import/export, editor, toolbar and framework adapters | Standalone, inline or multiline | MIT |
+| `@barocss/math-editor-tiptap` | Tiptap node extension | Inline and block | MIT |
+| `@barocss/math-editor-prosemirror` | ProseMirror schema, commands and node views | Inline and block | MIT |
+| `@barocss/math-editor-lexical` | Lexical math node and registration | Inline and block | MIT |
+| `@barocss/math-editor-editorjs` | Editor.js math Tool | Block | MIT |
+| `@barocss/math-editor-tinymce` | TinyMCE plugin with in-place or panel editing | Inline and block | MIT |
+| `@barocss/math-editor-ckeditor` | CKEditor 5 model objects and widgets | Inline and block | MIT |
+| `@barocss/math-editor-quill` | Quill math embeds and registration | Inline and block | MIT |
+| `@barocss/math-editor-slate` | Slate void elements and React rendering | Inline and block | MIT |
+| `@barocss/math-editor-gutenberg` | WordPress Gutenberg math block | Block | MIT |
+| `@barocss/math-editor-integrations` | Common data, draft UI, messages and styles; each host owns its plugin source | Internal development | Private; not an install target |
+
+Install the core with each host plugin; the package manifests declare compatible peer versions. The core and all nine host packages use the MIT license, with copyright attributed to barocss.com. Each package includes its own LICENSE file. Host SDKs retain their own licenses.
 
 Each host package exports its adapter, `/shared` helpers and `/style.css`. Load the core stylesheet as well. Gutenberg also exports `/data` for its stored-data codec. Install only the host package you use; there is no public all-host bundle. Formula placement, keyboard entry, history and clipboard behavior depend on the host.
 
@@ -52,16 +64,16 @@ Each guide covers installation, document replacement, saving and lifecycle clean
 
 See [framework adapters and inline/custom toolbar integration](https://math-editor.barocss.com/docs/adapters.html), [custom locales](https://math-editor.barocss.com/docs/localization.html), and [progress / roadmap](https://math-editor.barocss.com/docs/roadmap.html). The new native renderer has explicit parity gaps; existing React consumers keep their current UI.
 
-**Included in 0.4.0:** the native toolbar now includes searchable All symbols, templates, matrix presets and active-grid controls. Native ranges show exact partial-text highlights, and a drag can start in the active input and continue across structures. See [renderer parity](https://math-editor.barocss.com/docs/adapters.html#current-renderer-parity) for the remaining limits.
+The native toolbar includes searchable All symbols, templates, matrix presets and active-grid controls. Native ranges show exact partial-text highlights, and a drag can start in the active input and continue across structures. See [renderer parity](https://math-editor.barocss.com/docs/adapters.html#current-renderer-parity) for the remaining limits.
 
 For editor-only, external toolbar, LaTeX, preview, inline and popup compositions, see [Embedding](https://math-editor.barocss.com/docs/embedding.html) and the [layout examples](https://math-editor.barocss.com/layouts.html).
 
 ## Quick start
 
-Install version 0.4.0 from npm:
+Install the latest published version from npm:
 
 ```sh
-npm install @barocss/math-editor@0.4.0
+npm install @barocss/math-editor
 # For the rich React UI:
 npm install react react-dom
 ```
@@ -72,7 +84,6 @@ To develop the package and demo from this monorepo:
 
 ```sh
 pnpm install
-pnpm --filter @barocss/math-editor build
 pnpm --filter @barocss/math-demo dev
 # http://localhost:5184
 ```
@@ -152,12 +163,14 @@ Native passive text preserves these lexical colors; its whole active run still u
 | Grid | Shift+Enter | Insert a row |
 | Matrix | Shift+Space | Insert a column |
 | Grid | Alt+Shift+Up | Delete the current row |
-| Matrix | Alt+Shift+Left | Delete the current column |
+| Matrix | Alt+Shift+Backspace | Delete the current column |
 | Aligned / cases | Enter | Insert a row, unless applying a suggestion |
 | Just after a fraction/root/delimiter | Backspace | Unwrap, preserving contents |
 | Outer grid edge | Backspace / Delete | Delete empty grid; select filled grid first, press again to delete |
 | Preview surface | Cmd/Ctrl+A | Select the whole math document |
 | Active input | Cmd/Ctrl+A | Select the current input text: a React token or native logical run |
+| Editor | Ctrl+Left / Right (Mac: Option+Left / Right) | Move to a lexical unit boundary; cross a fraction/root/fence as one structure |
+| Editor | Same modifier + Shift+Left / Right | Extend or shrink selection by lexical units and structures |
 | Editor | Shift+Left / Right | Extend or shrink the model range across text and balanced structures |
 | Editor | Shift+Up / Down | Extend the model range across top-level lines using logical offsets |
 | Preview surface | Enter / F2 | Enter editing |
@@ -165,7 +178,9 @@ Native passive text preserves these lexical colors; its whole active run still u
 | Model selection | Backspace / Delete | Delete selection |
 | Editor | Cmd/Ctrl+Z / Cmd/Ctrl+Shift+Z | Undo / redo |
 
-Vertical arrows use the nearest inner structure before an enclosing grid, then fall back to another equation line. Paired scripts can move along their shared column; a base moves up to its superscript and down to its subscript. Suggestions retain arrow-key priority. Composition, literal text and noncollapsed text selections do not trigger structural movement. React and native surfaces share this behavior.
+Unit movement stays within the current variable or number until its edge, then crosses an adjacent structure intact. From a nested slot edge it exits the enclosing structure. An unshifted unit arrow collapses an existing selection to its ordered edge. It does not change LaTeX or add undo entries. Matrix rectangle selection keeps its existing arrow behavior.
+
+Vertical arrows use the nearest inner structure before an enclosing grid, then fall back to another equation line. Paired scripts can move along their shared column; a base moves up to its superscript and down to its subscript. Visible suggestions retain Up/Down priority, including after Shift+arrow or drag selection. Enter applies the highlighted wrapper to the selected content; Left/Right restores the caret, and Shift+arrows adjusts the range. Composition, literal text and noncollapsed text selections do not trigger structural movement. React and native surfaces share this behavior.
 
 The framework-free `moveVertical(state, direction, geometry?)` helper is exported from `/core`. Without rendered geometry, it selects the first text run in the target slot and clamps the current offset. At a lexical token boundary, rendered geometry distinguishes the previous token's end from the next token's start. Each move uses the current caret's horizontal position; a preferred column is not retained across repeated moves through shorter rows. Shift+arrow selection remains a separate operation.
 
@@ -206,7 +221,7 @@ pnpm --filter @barocss/math-demo build
 pnpm --filter @barocss/math-demo test:e2e
 ```
 
-The demo consumes package exports from `dist`; rebuild the package before browser tests. Browser tests use Playwright Chromium and start port 5184 if needed. Actual OS Korean IME tests remain deferred at the user's request.
+The demo consumes workspace source exports and does not require a package build. Release checks use `publishConfig.exports` and inspect the packed JavaScript and declarations. Browser tests use Playwright Chromium and start port 5184 if needed. Actual OS Korean IME tests remain deferred at the user's request.
 
 - [Symbol / English / Korean name table](https://math-editor.barocss.com/docs/symbols.html)
 - [LaTeX editing guide and upcoming notation](https://math-editor.barocss.com/docs/latex-guide.html)
@@ -344,9 +359,90 @@ These operations are available in both renderers and the framework-free
 
 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](https://math-editor.barocss.com/docs/styling.html) for the public variables, dark/monochrome examples, shared toolbars and iframe/plugin sizing.
 
+Nested fractions and scripts have a `14px` editing minimum. Set
+`--me-min-font-size: 16px` on your editor wrapper for a larger minimum, or `0px`
+for unmodified TeX size ratios. Inline rows grow to contain elevated scripts;
+allow the host line height to grow too. This display setting does not change
+the saved LaTeX. See [STYLING.md](./STYLING.md) for the size policy.
+
+For complex fractions, try `--me-font-size: 26px` with
+`--me-min-font-size: 16px`. Keep the preview/export size separate. In the website
+playground, use **Math size → 26px**; visual text-editor popups also offer zoom.
+
 ## License
 
 MIT License. Copyright (c) 2026 barocss.com.
 
 The npm package includes the full license in `LICENSE`. Bundled KaTeX fonts retain
 their separate copyright and MIT notice in `src/fonts/LICENSE-KaTeX.txt`.
+
+### Change an existing radical
+
+Place the caret inside a square root and choose **Change to Indexed root** in
+the suggestions. The radicand, including nested structures, stays intact. The
+new index is `2` and is selected so you can immediately type `3`, `n`, or another
+index. The explicit choice creates one Undo step.
+
+**Change to Square root** is available inside an indexed root with an empty
+index or index `2`. Other indices must be edited first; conversion does not
+discard them. The nearest enclosing radical is the target. Conversion choices
+do not consume the text used to search, and an unselected conversion does not
+intercept Enter. Both React and native DOM integrations support this behavior.
+
+Empty non-grid slots support Delete and Backspace directly. Removing the wrapper
+keeps other slot content and can be undone. See [Rendering checks](RENDERING-TESTS.md)
+for editor/KaTeX comparison fixtures and the current visual verification scope.
+
+### Contextual structure tools
+
+While the caret is inside a radical, the optional editor footer shows its current type,
+conversion action and, for indexed roots, **Edit index**. No search text is needed.
+Dismissing suggestions leaves the footer available. An unavailable conversion
+stays disabled with an explanation. F6 moves focus to the tools; Escape returns
+to input. The footer hides outside the radical, on blur, or during model selection.
+
+Set `contextTools={false}` on rich React, or `contextTools: false` in native DOM
+options, to hide this footer. Native framework wrappers accept the same option.
+The Web Component uses `context-tools="false"`. This setting does not remove
+conversion suggestions. See [Editing scenarios](EDITING-SCENARIOS.md) EDIT-021
+through EDIT-028 for acceptance criteria and pending coverage.
+
+### Change brackets from suggestions
+
+Place the caret inside brackets and press **Alt+Down** (Option+Down on macOS).
+The existing suggestion list opens with a transformation selected. Use Up/Down
+and Enter to change the surrounding brackets; Escape closes the list unchanged.
+“Change brackets” preserves the enclosed formula and caret, unlike an action
+that wraps text in a new pair. Available pairs include parentheses, brackets,
+braces, angle brackets, absolute value, norm and both half-open intervals.
+
+This works in inline fields with `toolbar: false` and `contextTools: false`.
+Automatic contextual suggestions do not consume Enter until you navigate them.
+The optional footer also offers bracket buttons via F6, Left/Right and Enter.
+Nested roots and fences share a nearest-wrapper target. See EDIT-029 through
+EDIT-032 in [Editing scenarios](EDITING-SCENARIOS.md).
+
+### Prime notation (workspace)
+
+The symbol catalog supports `\prime`. LaTeX imports such as `f^{\prime}(x)`,
+`f^\prime(x)` and `f^{\prime\prime}(x)` use editable superscript slots and
+preserve the prime count on export. Bare `\prime` is a symbol; use a superscript
+for derivative notation. Apostrophe shorthand such as `f'(x)` remains accepted.
+The editor does not compare answers. Hosts own question-specific suggestions and grading.
+
+## Development validation
+
+The [editing scenarios](https://math-editor.barocss.com/docs/editing-scenarios.html)
+define expected input, selection, deletion, history and host behavior. The
+[validation report](https://math-editor.barocss.com/docs/validation.html) records
+what was actually checked, including browser and host limits.
+
+From a source checkout, start both math demo servers and run
+`node scripts/check-math-editor.mjs`. This checks the model, actual editing,
+framework/host lifecycle, selected KaTeX geometry and documentation build.
+Workspace changes and a passing check do not imply that npm or the site has
+already been published. See the changesets and release guide before publishing.
+
+## Text editor plugins
+
+CodeMirror 6, CodeMirror 5, and Monaco have separate source-editing adapters. A VS Code extension uses a Webview beside the document. See the [text editor guide](./TEXT-EDITORS.md) for package names, setup, source-preservation rules, and validation scope. WGSL/GLSL editing is separate.

package/RELEASING.md

@@ -1,31 +1,116 @@
 # Releasing math editor
 
-The source stays in this monorepo. Release only `@barocss/math-editor`; framework subpaths share its version. The initial release is **0.1.0**, public, on the **latest** npm tag.
+See [Editing scenarios](EDITING-SCENARIOS.md) for stable scenario IDs, acceptance criteria, coverage gaps and per-run reporting.
+
+
+The source stays in this monorepo. The local batch release includes
+`@barocss/math-editor`, nine public rich-text plugins and four text packages
+(`math-editor-text`, `math-editor-codemirror6`, `math-editor-codemirror5`,
+`math-editor-monaco`, all under `@barocss`). All use MIT, public npm
+access and the `latest` tag. Framework adapters are core subpaths and share the
+core version. The private integration workspace and other products are excluded.
+
+Versions remain independent; a batch release does not force every package to change.
+VS Code is a separate VSIX/Marketplace release and is not published by this npm command.
 
 ## Local release
 
 ```sh
 # Repository root. Login is handled by npm, never by storing credentials in the repository.
-npm login
-pnpm release:math:prepare
-# After reviewing changes and browser validation:
+npm login --registry=https://registry.npmjs.org/
+# After reviewing versions, changelogs and browser validation:
 pnpm release:math
 ```
 
-Both commands check formatting, types and unit tests, clean/build the package, create a temporary tarball and verify all package entry points. The publish command sends only that verified tarball to the public npm registry. It never runs recursive publishing. `pnpm release` is an alias for this math-only workflow. npm may request account authentication or 2FA during publishing.
+This one command runs core formatting/type/unit checks,
+integration type/unit checks, builds, package validation and release-tool tests. It verifies the core
+entry points and each plugin's packed declarations, runtime imports and required
+files. It then runs **one `pnpm -r publish` command** for the fourteen allowed names.
+`pnpm release` is an alias for this workflow.
+
+Only the inspected package contents enter a generated workspace under
+`output/math-batch-releases/release-*/`. Wrapper manifests use
+`publishConfig.directory` to point at those contents. They give pnpm an explicit
+core-first dependency order without adding dependencies to the published plugin
+manifests. Publish lifecycle scripts are disabled because validation and builds
+already ran. Git checks are disabled only for this generated workspace.
+
+pnpm checks npm and skips package versions that already exist. It packs the
+inspected contents again, so the final archive checksum can differ from the
+preparation archive. The batch is not an atomic registry transaction. npm may
+still request authentication for individual packages; one command does not
+guarantee one authentication prompt.
+
+For checks without publishing:
+
+```sh
+# Build and inspect all fourteen packages. No registry publication.
+pnpm release:math:prepare
+# Also exercise recursive publishing with npm's dry-run flag.
+# This can read registry metadata; it does not upload packages.
+pnpm release:math:dry-run
+```
+
+`release.json` records the candidate versions, artifact hashes and command status.
+On success, `pnpm-publish-summary.json` lists newly published packages; versions
+skipped by pnpm are absent. A dry-run summary is not evidence of publication.
+If publishing fails, preserve the report and check each candidate version on npm.
+pnpm 8 may not write its summary after a partial failure. Resolve any uncertain
+results before running the batch again; never use `--force` to retry.
 
 Before releasing UI changes, also run `pnpm --filter @barocss/math-demo test:e2e` and the demo build. Verify the intended package name/version and changelog. A version already published to npm must never be reused. The repository's release workflow is manual validation only; it does not publish on main pushes.
 
 ## Subsequent versions
 
-1. Run `pnpm changeset`, select only `@barocss/math-editor`, and write a user-facing change summary.
+1. Run `pnpm changeset`, select the affected math core and/or public plugins, and write a user-facing change summary.
 2. Use patch for compatible fixes and minor for features. During 0.x development, clearly identify breaking API changes in a minor release. Reserve 1.0.0 for the agreed stable API.
-3. Run `pnpm version:math`. It runs Changesets in a temporary math-only workspace and copies back only this package manifest/changelog, preventing dependent product version bumps. The consumed changeset summary is retained in CHANGELOG.md.
+3. Run `pnpm version:math:plan` to preview the core, nine rich-text plugin and four text-package versions. Run `pnpm version:math` to apply that plan. Changesets runs in a temporary math-only workspace and copies back only affected math manifests/changelogs. Unrelated product changesets remain untouched. Review plugin peer-range changes before publishing.
 4. Review and commit the version/changelog and any dependency/lockfile changes with the implementation. Run release validation, then publish locally.
-5. Record a package-specific Git tag such as `math-editor-v0.1.1` on the release commit, and update the site with the matching package version.
+5. Record package-specific Git tags on the release commit, and update the site with the matching package version. The batch command does not create commits or tags.
 
-The first 0.1.0 changelog is seeded explicitly; do not add a version-bump changeset just to publish the initial version. Avoid `pnpm version-packages` for a math-only release because that command processes the entire workspace plan.
+The scoped Changesets configuration only promotes peer dependents when the new
+version leaves their supported range. Widen a compatible peer range explicitly
+and add a patch changeset; incompatible range changes still require release review.
+
+Text tarballs are installed with the packed core into a temporary consumer using
+`npm install --offline --ignore-scripts --legacy-peer-deps`. Host SDKs come from the
+local installation. Strict public declaration checks and runtime import checks run
+there. This validates package contents and local installation, not npm availability
+or a fresh registry peer installation. Monaco interaction is covered by browser QA.
+See [text editor validation](../../apps/math-text-demo/test/README.md) for native
+IME and physical mobile checks that remain open.
+
+Versioning is separate from publishing. Repeating a publish command must not create
+another version. Avoid `pnpm version-packages` and unfiltered `pnpm -r publish`
+for a math-only release because they can include other products.
+
+The [host release guide](../math-editor-integrations/docs/RELEASING.md) lists the
+nine plugins and explains changes to shared implementation. For an explicit
+core-only release, use `pnpm version:math:core`,
+`pnpm release:math:core:prepare` and `pnpm release:math:core`.
 
 ## Website
 
-`apps/math-demo` remains the site source. The intended static deployment repository is `barocss/math-editor-site`, with GitHub Pages at `math-editor.barocss.com`. Website deployment is separate from npm publication; page-only changes do not require a package version bump. Keep the displayed version and built editor version in sync. Successful npm publication alone does not mean the site or DNS has been configured.
+`apps/math-demo` remains the site source. The static deployment repository is
+`barocss/math-editor-site`, with GitHub Pages at `math-editor.barocss.com`.
+Build the site directly from workspace source:
+
+```sh
+pnpm build:math:site
+```
+
+This builds the main site and the nine-plugin integration sample without a core
+tarball, package `dist` build, npm login, registry lookup or publication check.
+Workspace package exports resolve local source, including the private common
+module. No package version bump is required to rebuild or deploy the site.
+`release.json` records `source: "workspace-source"` and the local package versions
+as metadata; those versions do not claim that the packages are published.
+
+For an explicit package-artifact check, the previous command remains available:
+
+```sh
+pnpm release:math:site /path/to/barocss-math-editor.tgz
+```
+
+Both commands print the prepared static site directory and do not deploy it.
+Website deployment and npm publication are independent operations.

package/RENDERING-TESTS.md

@@ -0,0 +1,79 @@
+# Rendering regression checks
+
+Compare the editor with KaTeX using the same exported LaTeX, base font size and
+display mode. Keep [editing scenarios](EDITING-SCENARIOS.md) for input behavior;
+this guide defines the visual checks for EDIT-017. KaTeX is the reference image,
+not an editable DOM replacement.
+
+## Three checks for each fixture
+
+1. **Model/output:** the editable tree exports the intended LaTeX and KaTeX accepts it.
+2. **Geometry:** compare relative positions, font sizes and gaps. Absolute page
+   coordinates are not comparable across different containers.
+3. **Visual review:** save the editor, active-input and KaTeX images together.
+   Check curves, stroke thickness, baselines and clipping. Numerical checks alone
+   do not establish that the two images look equivalent.
+
+The active input, measuring element and passive glyph must use the same font
+metrics. A cursor or hover background must not move a fraction or hide a fence.
+Wait for `document.fonts.ready`. Disable preview fit scaling for comparison and
+set the KaTeX root's computed font size to the editor's base size; matching the
+parent container's font size is not sufficient.
+
+## Initial executable fixtures
+
+Run `apps/math-integrations/tests/rendering-regression-check.js` through the
+existing Playwright CLI browser workflow with the local site on port 5184.
+The file is an async `(page) => ...` fixture, not a standalone Node script.
+Omit its final semicolon when passing the function to `run-code`.
+
+| Fixture | LaTeX | Renderers / sizes |
+| --- | --- | --- |
+| `indexed-root-power` | `\left(\sqrt[20]{ab}\right)^{\frac{2}{3}}` | Rich React and native DOM; 22px and 36px |
+| `fraction-power` | `x^{\frac{2}{3}}` | Rich React and native DOM; 22px and 36px |
+| `fraction-subscript` | `x_{\frac{2}{3}}` | Rich React and native DOM; 22px and 36px |
+
+The 12 combinations currently assert:
+
+- Fraction terms use half of the base font size and match KaTeX's computed term
+  size within 0.1px. This applies to these implicit-style fixtures, not every
+  explicit `\dfrac` or `\tfrac` expression.
+- The exponent is above the base and the subscript is below it.
+- The fraction center's vertical offset from the base glyph center differs from
+  KaTeX by less than 0.25em. This is a regression threshold, not pixel equality.
+- The gap from the base box to its fraction script is between 0 and 0.25em.
+- Activating a numerator retains its font size, and typing retains focus.
+- The formula does not produce a KaTeX error.
+
+Screenshots are saved as
+`output/playwright/{renderer}-{fixture}-{size}-{editor|katex|active}.png`.
+The returned metrics include editor and reference coordinates. Preserve them
+with the source fingerprint, browser version and screenshot pairs for a run.
+These filenames are overwritten on rerun; archive them if they are used as a
+release baseline. Do not update an accepted baseline simply to hide a failure.
+
+## Why the first correction is bounded
+
+Script fractions previously retained body-sized minimum row heights and spacing.
+They now have compact terms and rows. A simple base uses a small script offset;
+a tall structured base uses an offset proportional to the fraction height.
+Empty boundary nodes reserve only a narrow passive cursor position.
+
+This fixes the initial cases without changing the JSON model. It is not a
+complete TeX layout engine. Remaining comparison fixtures should cover paired
+scripts, nested fractions in both slots, explicit style overrides, multi-line
+collision, large operators, fences, accents and narrow host containers.
+
+As those fixtures grow, consolidate script levels, the math axis, baseline and
+stroke metrics into shared layout rules. Avoid extending a list of formula-
+specific CSS exceptions without a failing fixture and reference measurement.
+Both renderers must use the same rule, and every new notation feature needs
+an editor/KaTeX comparison in passive and active states.
+
+## Release use
+
+Run changed fixtures during development. Run the rendering set and applicable
+editing scenarios against release candidate artifacts before publishing. The
+current fixture uses workspace sources and Chromium; it does not certify packed
+packages, all host containers, Firefox/WebKit or OS IME behavior. CI scheduling
+and automatic screenshot-diff approval are not implemented by this guide.