@barocss/math-editor 0.4.0 → 0.5.0

package/API-SESSION.md

@@ -323,3 +323,13 @@ Choose the change appropriate to the target:
 `default` removes the explicit metadata. `setMathPresentation(state, id, change)` is the pure equivalent. Unsupported changes or stale IDs return the original state; the session command returns false. This is presentation editing of existing syntax, not algebraic conversion or general TeX styling.
 
 Toolbars expose `closePanels()` to dismiss their nonmodal utilities without editing the formula. `onOpenPanel` and `onPasteLatex` are optional mounting callbacks for a host that coordinates its own utility panels. Built-in surfaces keep only one utility/discovery panel open at a time.
+
+### Keyboard access to transformations
+
+In React and native DOM fields, **Alt+Down** opens or reopens suggestions and
+selects the first available contextual transformation. Up/Down browses and Enter
+applies; Escape dismisses. On macOS, Alt is the Option key. Root and bracket
+transformations preserve the existing operand. The shortcut works with
+`toolbar: false` and `contextTools: false`, including inline mode. Normal text
+input continues to use the standard suggestion ordering; a context-only menu
+requires navigation before Enter can apply a change instead of a host commit.

package/API-WEB-COMPONENT.md

@@ -126,3 +126,5 @@ Persist the `MathDocument` passed to `onChange`; LaTeX is derived output and is
 Keep the mount host empty. The editor owns its descendants; framework rendering into the same host can destroy caret and composition state. Use one editing surface per session. Destroy the renderer on teardown; a session supplied by the host remains the host's responsibility.
 
 See [session and DOM API](API-SESSION.md) for exact options, commands, events and cleanup, and [renderer differences](ADAPTERS.md#current-renderer-parity) before choosing a native wrapper over the rich React editor.
+
+Set `context-tools="false"` to hide the contextual structure footer. Changing this attribute updates the mounted editor. Conversion suggestions remain available.

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # @barocss/math-editor
 
+## 0.5.0
+
+### Minor Changes
+
+- Show query-independent radical tools below the active editing surface. Include conversion, index editing, disabled explanations, F6/Escape focus navigation, en/ko labels and a contextTools opt-out (context-tools for Web Components). Preserve model history and hide stale context during range selection or blur.
+- Add contextual bracket transformations to suggestions, with Alt+Down discovery and keyboard acceptance in inline fields without toolbar or footer. Preserve contents, caret and history; target the nearest root/fence and reject stale actions. Include optional footer bracket controls and localized keyboard guidance.
+- Add contextual suggestions to convert a square root to an indexed root while preserving the radicand. Select the new index `2` for immediate editing. Allow conversion back to a square root only for an empty index or `2`. Include English/Korean labels and shared behavior in React and native DOM integrations.
+
+### Patch Changes
+
+- Resolve operator presentation from mathematical slot context in React and native
+  DOM editors. Use text/script-size glyphs and side limits inside fractions and
+  scripts, preserve explicit limit placement, and apply smaller nested bounds.
+  Add context-resolution unit tests and KaTeX glyph-width/font/position checks.
+- Align named-function and fraction boundaries with mathematical spacing in React
+  and native DOM. Remove repeated function glyph padding and fixed fraction outer
+  margins. Preserve thin function spacing in script styles and omit it before plain
+  opening parentheses.
+- Use bundled KaTeX math faces for variables, upright symbols and display operators. Remove artificial integral skew, scale delimiter widths, and preserve curved over/underbrace ends with licensed KaTeX SVG slices. Refine radical sizing, root-index placement, matrix columns and integral limit spacing in both editable and passive views.
+
+  Extend the source-only geometry audit with opt-in horizontal-position checks, font asset fingerprints, explicit font loading and multiple-integral/long-brace cases. Retain the KaTeX MIT attribution for bundled assets.
+
+- Use shared mathematical spacing for text runs in React and native DOM. Distinguish
+  unary signs from binary operators, space relations and punctuation, and suppress
+  these gaps inside scripts. Remove excess glyph padding and reduce inactive caret
+  boundary width while preserving empty input targets.
+- Use small operator glyphs and side limits in inline mode. Reduce nested script
+  size, adjust radicals inside superscripts, and preserve curved end caps on very
+  tall parentheses. Extend source-only KaTeX comparisons to large fences, deep
+  nesting, and actual inline mode.
+- Fix KaTeX-compatible export and import for literal caret and tilde characters in
+  math text runs. Protect complex root-index arguments without changing JSON
+  structure. Add clearance between nested radical rules and extend rendering
+  regression checks.
+- Use KaTeX-derived SVG contours for radicals and short/tall parentheses. Keep
+  existing editing boxes while improving tapered strokes and curved ends. Include
+  the outline assets and attribution in the package, and extend visual comparison
+  fixtures to simple roots and short parentheses.
+- Correct the size, height and spacing of fraction terms used as scripts. Add editor/KaTeX geometry and screenshot fixtures for fractional powers and subscripts. Allow Delete and Backspace inside empty non-grid slots to remove their wrapper while retaining other content and Undo support.
+- Match ordinary script and root-index font scales more closely to KaTeX in passive and active editing. Add a source-only rendering audit with per-formula measurements, screenshots and a tracked difference ledger.
+- Keep formula selections intact when Up/Down navigates a visible wrapping suggestion menu. Enter applies the highlighted wrapper to the selected content. Left/Right still restores the caret, and Shift+arrows extends the selection. Apply the same behavior to React and native DOM fields used by host integrations.
+- Align nested fraction terms, matrix rows, annotations and operator limits more closely with KaTeX. Scale large and contour integral geometry with the configured font size. Preserve explicit display-fraction sizes and positions inside scripts. Use matching input and passive-text metrics to retain edit positions.
+
+  Expand the source-only geometry audit to 33 formulas, including two font sizes, React and DOM rendering, active typing checks and a local image comparison gallery.
+
+## 0.4.1
+
+### Patch Changes
+
+- Move each host implementation, tests and host-specific styles into its own plugin
+  package. Keep only shared data, draft-field UI and messages in the private common
+  package. Preserve the public entry points and stored formula format.
+
+  Declare ProseMirror as Tiptap's public dependency instead of bundling a second
+  copy of its host implementation. Keep host SDKs and the math core external, and
+  include common helpers and declarations within each published artifact.
+
+  Resolve workspace imports from source without a prior build. Use publishConfig
+  entry-point overrides for the core and all public plugins, and verify staged npm
+  artifacts against their generated runtime and declaration paths.
+
 ## 0.4.0
 
 ### Minor Changes

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/IMPLEMENTATION.md

@@ -265,3 +265,98 @@ operations needs a new model version or parser command.
 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/LATEX-GUIDE.md

@@ -259,3 +259,25 @@ 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}`.

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

@@ -1,8 +1,17 @@
 # @barocss/math-editor
 
+See [Editing scenarios](EDITING-SCENARIOS.md) for stable scenario IDs, acceptance criteria, coverage gaps and per-run reporting.
+
+
 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.
+
+## Packaging changes in 0.4.1
+
+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 additions in 0.4.0
 
@@ -14,19 +23,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.
 
@@ -58,10 +67,10 @@ For editor-only, external toolbar, LaTeX, preview, inline and popup compositions
 
 ## Quick start
 
-Install version 0.4.0 from npm:
+Install version 0.4.1 from npm:
 
 ```sh
-npm install @barocss/math-editor@0.4.0
+npm install @barocss/math-editor@0.4.1
 # For the rich React UI:
 npm install react react-dom
 ```
@@ -72,7 +81,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
 ```
@@ -165,7 +173,7 @@ 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.
+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 +214,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)
@@ -350,3 +358,49 @@ 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).