@barocss/math-editor 0.2.1 → 0.5.0

package/ROADMAP.md

@@ -2,6 +2,143 @@
 
 This roadmap describes priorities, not release promises. The current package is an independent editing prototype. Production integration requires the reliability work below even if additional notation is implemented first.
 
+
+
+## Current focus: continuous editing — workspace, 2026-09-10
+
+The rendering pass is now the maintenance baseline. Further contour refinement
+is deferred; keep existing checks when notation or layout changes.
+
+EDIT-019 now runs through keyboard input, range wrapping, radical conversion,
+matrix input, five-step Undo/Redo, empty-root deletion and restoration, then a
+second typing/history chain without resetting the editor. React standalone block
+plus Quill/Tiptap/ProseMirror/Lexical/TinyMCE/CKEditor/Slate in-place block/inline and
+Editor.js/Gutenberg block pass (17 targets, 499 checkpoints). Host checks verify unchanged draft data,
+Save, reload/Restore, re-edit and Cancel. One-step host Undo/Redo passes where
+configured; the Editor.js demo has no host history integration. Inline also
+checks Enter commit without new paragraphs, right-boundary exit and prose
+continuation at the correct host position.
+
+Run `pnpm --filter @barocss/math-editor test:editing`. Timestamped reports include
+checkpoints, browser scope, fixture copy and source fingerprints. The Tiptap sample now separates document Restore from subsequent typing in host history;
+TinyMCE now keeps empty formulas visible with a localized placeholder. Its
+block/inline checks use an inline TinyMCE host; classic iframe mode is separate.
+All nine integration demos now pass this chain. Gutenberg uses the standalone
+provider demo; WordPress admin and other host configurations remain separate.
+Next: range clipboard and populated/grid deletion sequences. Real OS IME
+and clipboard remain deferred; this is not a release-wide certification.
+
+
+## Named-function and fraction spacing — workspace, 2026-09-10
+
+Named functions and fractions now share horizontal spacing with adjacent text.
+Repeated functions, parentheses after functions, products of functions and
+repeated fractions have paired editor/KaTeX comparisons. Named-function thin
+spacing remains in first and nested exponents. Fixed function glyph padding and
+fraction outer margins no longer accumulate across these expressions.
+
+Next: the remaining wrapper atom classes, longer mixed expressions, explicit
+spacing commands, and full painted-bound comparisons. Passing selected anchors
+does not imply whole-expression pixel equality.
+
+
+## Contextual operator layout — workspace, 2026-09-10
+
+The shared model-to-presentation pass now distinguishes display, text, script and
+scriptscript operator contexts. React and DOM use it for small glyphs, nested
+bound sizes and automatic side limits. Explicit limits remain supported.
+
+New comparisons cover numerator/denominator operators, one/two levels of
+superscripts, an operator inside another bound, inline/text fractions and an
+explicit stacked inline integral. Full ink alignment, all multi-operator mixtures
+and narrow-host/cross-browser checks remain separate work.
+
+## Radical and parenthesis outlines — workspace, 2026-09-10
+
+Root strokes and short/tall parenthesis contours now use KaTeX-derived SVG masks.
+Tall parentheses retain bounded end caps and extend the straight middle. The
+package includes these assets with their provenance and existing KaTeX MIT notice.
+This removes the old radical polygon without adding a KaTeX runtime dependency.
+
+Full KaTeX size-variant selection, vertical brace silhouettes, operators inside
+scripts and cross-browser geometry remain separate work. The renderer continues
+to reserve its existing editing boxes and caret hit areas.
+
+## LaTeX compatibility and nested-root layout — workspace, 2026-09-10
+
+- Fixed math-mode literal caret/tilde export while retaining text-run JSON semantics.
+- Protected complex optional root indices during export; all 55 structure kinds
+  now have KaTeX render and JSON round-trip regression checks in that slot.
+- Added clearance between nested radical rules and a browser gap measurement.
+- Still open: radical hook outlines, fence ink geometry, operators inside scripts,
+  explicit style combinations, broader interaction sequences and other browsers.
+
+These are workspace changes. Browser evidence remains in the source-only rendering
+ledger; a metric PASS does not mean complete visual parity or release certification.
+
+## Editing utilities — workspace, 2026-09-09
+
+Included in 0.4.0:
+
+- Native lexical-token input now matches rich React colors and offsets. Token-boundary navigation/deletion preserves surrounding text; composition retains the input until commit.
+- Explicit LaTeX insertion at the caret or range, exposed as `pasteLatex`, More tools → Paste as LaTeX, and Alt+Shift+V. Parsing/placement failures preserve the document. Ordinary paste stays literal.
+- Recent symbols/templates and favorites, with a shareable validated preference store. Preferences are separate from formula history; persistence belongs to the host.
+- Contextual fence, fraction/binomial size, and operator-bound placement controls. Existing contents, IDs and caret are preserved with one-step Undo.
+
+See [API and usage](API-SESSION.md#editing-utilities--workspace). No new LaTeX grammar or automatic algebraic transformation is added. Persistent vertical columns, broader browsers, performance budgets and accessibility remain open.
+
+## Scoped style customization — workspace, 2026-09-09
+
+Implemented: inherited CSS variables for UI/token colors, slot backgrounds,
+controls, toolbar density and floating menus. Both renderers retain per-editor
+palette values on suggestion/selection portals and follow live ancestor theme
+switches. Shared plugin panels/actions use the same palette; persisted host
+formula sizing remains document data. The site includes default/dark/monochrome,
+base-size and compact-spacing controls. See [Styling & themes](STYLING.md).
+
+
+## Selection-to-caret keyboard behavior — workspace, 2026-09-09
+
+A visible wrapping menu owns Up/Down in both renderers. The selected formula
+stays selected while the highlighted suggestion changes; Enter applies it.
+Left/Right returns to the ordered start/end of the selection. Shift+arrows
+continues to adjust the range. Alt+Up/Down remains supported. When the wrapping
+menu is closed, plain arrows restore the caret without changing the formula.
+
+## Matrix rectangles and transpose — workspace, 2026-09-09
+
+Both editing surfaces now distinguish cross-cell rectangles from text selection
+inside a cell. Drag between cells or Shift+click to select a rectangle. Select
+cells starts keyboard selection; Shift+arrows changes the focus corner. Copy/cut
+preserves nested formula trees; paste accepts matching rectangles or grows from
+a single cell within 20 × 20. One copied cell can fill a rectangle. Ragged TSV,
+invalid clipboard data, mismatched shapes and oversized results are rejected
+without changing the formula. Delete clears cells; Enter/Escape resumes editing.
+
+Transpose matrix moves the entire matrix, preserving cell IDs, nested caret,
+delimiters and one-step Undo. No numerical evaluation or new LaTeX grammar is
+introduced. See [the API contract](API-SESSION.md#matrix-cell-selections) for payloads
+and paste rules. Real OS clipboard and touch selection remain separate checks.
+
+## Native toolbar and selection parity — workspace, 2026-09-09
+
+Included in 0.4.0: More tools exposes searchable All symbols,
+templates, matrix/identity presets and symbol shortcuts. The active grid toolbar
+offers matrix row/column operations and delimiter changes, with row operations for
+aligned/cases. External toolbar handles now expose `setDisabled` alongside
+`setSession` and `destroy` for composition and draft lifecycle coordination.
+
+Native selection highlights now preserve partial text endpoints. A drag can begin
+inside the active input and continue across structures as a model range. Shift+arrow
+model ranges are already implemented; vertical range extension uses logical line
+offsets. The new work does not add LaTeX syntax.
+
+Remaining work includes persistent vertical preferred
+columns, and wider browser/accessibility coverage. English/Korean remain the complete
+bundled locale packs; additional complete packs remain open. Native OS IME validation
+is still deferred at the user's request. See [renderer parity](ADAPTERS.md#current-renderer-parity)
+and [validation](VALIDATION.md) for the current boundary and evidence.
+
 ## Remaining LaTeX priorities: workspace review, 2026-09-08
 
 These are proposals, not accepted import syntax. Complete each feature through the model, parser, exporter, suggestions and both editing surfaces before calling it supported.
@@ -53,7 +190,7 @@ Norms are implemented in the workspace. Triple and contour integrals are impleme
 | Host Enter/commit/cancel contract and modal suggestions | Implemented | Product selection/undo integration and real IME/browser matrix |
 | Layout lab: inline, next-block flow, popup draft/cancel/apply | Implemented | Integrate the actual Note node view first |
 | Note/Word/Site/Slide persistence adapters | Note workspace popup trial implemented | Validate other browsers and real host caret/undo workflows; Word/Site/Slide adapters and OMML conversion remain open |
-| Downloadable SVG/PNG output | Not implemented | Dedicated renderer/export contract, fonts and scaling |
+| Reusable library SVG/PNG output | Not implemented | Dedicated renderer/export contract, fonts and scaling; the website already provides sized PNG download/copy from its preview |
 
 See [Embedding](EMBEDDING.md) for existing Note/Word model boundaries. Note has a popup integration trial. The user confirmed that Note inline editing is resolved. This release focuses on math-editor; product-specific validation is tracked separately.
 
@@ -62,15 +199,15 @@ See [Embedding](EMBEDDING.md) for existing Note/Word model boundaries. Note has
 | Work | Status | Remaining gate |
 |---|---|---|
 | Framework-free session / public commands | Implemented | Host-wide undo integration, performance and document validation |
-| Native DOM surface / pure JS entry | Integration preview | Rich React selection, catalog and composition parity |
+| Native DOM surface / pure JS entry | Integration preview | Native discovery/context tools and precise pointer ranges implemented in workspace; token-level input/color is implemented; wider composition coverage remains |
 | Web Component / Vue / Svelte / Solid / React native wrappers | Implemented | Wider framework-version matrix and SSR/hydration strategy |
-| Optional and separately mounted toolbar | Implemented in native surface | Context-sensitive professional toolbar and symbol browser |
+| Optional and separately mounted toolbar | Implemented in native surface | Symbol browser, templates/presets and grid context controls added in workspace; broader context grouping and user customization remain |
 | Inline single-top-level-line policy | Implemented in native surface | Real product prose integration, baseline/keyboard exit UX |
 | External locale dictionary / aliases / fallback / direction | Implemented | Complete extra language packs and RTL audit |
 | ESM subpath distribution / optional framework peers | Implemented | Release approval, registry publication, bundle budgets |
 | Rich React renderer remains available | Preserved | Move main export only after measured parity |
 
-Next integration work: finish the native symbol panel and precise range highlights; unify token editing/composition behavior; add keyboard structural selection. Measure load/typing cost in host products; Note inline editing is already resolved. Do not add new notation to both renderers independently before shared behavior is stable. See [adapter parity and API](ADAPTERS.md).
+Next integration work: verify the new active-input parity across more browsers, extend browser/accessibility coverage, and measure load/typing cost in host products. The native symbol panel, precise range highlights, active-input cross-structure drag and Shift+arrow model selection are implemented in the workspace. Note inline editing is already resolved. Do not add new notation to both renderers independently before shared behavior is stable. See [adapter parity and API](ADAPTERS.md).
 
 ## Delivered baseline
 
@@ -86,8 +223,8 @@ Next integration work: finish the native symbol panel and precise range highligh
 | Work | Acceptance criteria |
 |---|---|
 | Real input-method matrix | macOS and Windows Korean composition, cancellation, blur and locale change preserve text and commit once; currently deferred by user request |
-| Keyboard model ranges | Shift+arrows extend/collapse across tokens and structures; typing replaces selection; undo restores a predictable caret |
-| Structural navigation | Predictable up/down movement in fractions, roots and scripts; direction and selection affinity covered by tests |
+| Keyboard model ranges — implemented | Shift+arrows extend/collapse across text and structures; typing replaces selection; wider browser/IME coverage and pixel-column vertical extension remain |
+| Structural navigation — implemented in workspace | Shared React/native Up/Down movement for fractions, scripts, indexed roots and operator slots; nearest rendered horizontal caret, inner-structure precedence and matrix columns covered by model tests. Persistent preferred-column state and wider browser coverage remain open |
 | Saved-document validation | Shape/duplicate-ID validation is implemented; version migration and host recovery remain |
 | Host session adapter | Enter/exit and save work in one target product; a single coherent undo path across host and formula |
 | Browser/accessibility coverage | Safari, Firefox and Windows Chromium; screen-reader names and suggestion announcements; touch selection and narrow layouts |
@@ -114,8 +251,8 @@ See the [LaTeX editing guide](LATEX-GUIDE.md) for supported examples and the nex
 | Feature | Acceptance criteria |
 |---|---|
 | Subset LaTeX import — implemented in workspace | Extend the documented grammar incrementally; preserve unsupported input without changing the existing formula |
-| Rectangular cell selection | Row/column geometry, copy/paste shape rules, partial destination handling and undo |
-| Matrix transformations | Transpose and delimiter changes preserve all cell contents and caret; no implicit numeric computation |
+| Rectangular cell selection — implemented in workspace | Cross-cell drag, Shift+click, keyboard expansion, shape-checked copy/paste, clear and one-step Undo; external clipboard/touch validation remains |
+| Matrix transformations — implemented in workspace | Delimiter changes and full-matrix transpose preserve cell contents, nested caret and Undo; selected-submatrix transforms and numeric computation are not included |
 | Drag matrix size picker | Accessible keyboard equivalent, touch behavior, 1–20 bounds and one-step insertion |
 | Multi-alignment and multiline wrapping | Explicit grouping semantics; do not flatten lines or move relation signs unexpectedly |
 | External clipboard compatibility | Verify custom-format survival and LaTeX fallback across target browsers and applications |
@@ -164,7 +301,7 @@ the npm version and deployed runtime artifact are unchanged.
 - [x] Vector, hat and overline accents with editable bodies and selection wrapping.
 - [x] Additional delimiters, mixed/invisible ends and overset/underset annotations.
 - [x] Over/under brace annotations with editable annotation/body slots.
-- [x] Explicit side-placement import/export (`\nolimits`); a dedicated toolbar switch remains open.
+- [x] Explicit side-placement import/export (`\nolimits`) and contextual toolbar placement controls.
 
 - [x] Workspace: `limit` condition/body model, LaTeX import/export, localized suggestions and React/native editing.
 - [x] Semantic function color for named/custom operators and the limit glyph.
@@ -188,10 +325,82 @@ Seven rich React/KaTeX comparisons are complete; production fixes are pending. P
 
 Spacing follow-up implemented: shared grid fence shapes, tighter grid/fraction/script/accent layouts, bounded nested fraction sizes, and a smaller boundary focus target. Chromium import/edit checks pass; the measured first-boundary expansion fell from 20px to 8px. Full recursive math-style sizing, additional browser/accessibility checks and eliminating all cursor-induced movement remain open.
 
-Workspace toolbar overflow is implemented: configurable structure-button limits and More/Fewer controls, rich React/native filtering, and always-visible history actions. Context-sensitive grouping and user-persisted toolbar customization remain future work.
+Workspace toolbar overflow is implemented: configurable structure-button limits and More/Fewer controls, rich React/native filtering, and always-visible history actions. Native symbol/template discovery and grid context controls are also implemented as described above. Broader context-sensitive grouping and user-persisted toolbar customization remain future work.
 
 Locale regression: misplaced alphabet/arrow messages moved inside `messages`; pack-shape/build validation and en/ko browser coverage added.
 
 ### 0.2.1
 
-Keyboard model selection with Shift+arrows and `{` cases discovery are implemented. The dedicated demo adds sized PNG download/copy and fit preview; image generation remains site-only. Pixel-column vertical selection and rectangular grid ranges remain future work.
+Keyboard model selection with Shift+arrows and `{` cases discovery are implemented. The dedicated demo adds sized PNG download/copy and fit preview; image generation remains site-only. Pixel-column vertical selection remains future work. Matrix cell rectangles and transpose are implemented in the workspace; aligned/cases retain structural ranges.
+
+## Tiptap / ProseMirror integration preview (2026-09-08)
+
+A separate private development package, `packages/math-editor-integrations`, now
+provides Tiptap 3 and ProseMirror 1 math nodes using the existing DOM editor. It
+supports direct editing in the text flow, optional panel editing, JSON/LaTeX storage,
+HTML clipboard round trips, Apply/Cancel, and host Undo. The sample runs from
+`apps/math-integrations` at port 5185.
+
+As of 2026-09-09, the integration preview covers nine hosts in one sample page.
+Site staging includes `/integrations/` and rendered integration documentation.
+The shared source package stays private; nine host-specific npm packages have
+separate Changesets and artifact preparation. The release set is core `0.4.0` and plugins `0.1.0`. The
+core and all nine plugins now use MIT, with a LICENSE file in each package.
+Plugin publication remains pending. See the [integration roadmap](../math-editor-integrations/ROADMAP.md),
+[validation record](../math-editor-integrations/VALIDATION.md), and
+[release guide](../math-editor-integrations/docs/RELEASING.md).
+
+## Radical conversions — workspace, 2026-09-09
+
+Implemented contextual square-root/indexed-root conversion suggestions in React
+and native DOM. The radicand tree and IDs are retained; conversion adds a selected
+index `2`. Square-root conversion accepts only an empty index or `2`. Changes
+participate in normal Undo/Redo and use English/Korean locale messages. Other
+structure conversions are not included in this step.
+
+## Editing scenario register — workspace, 2026-09-09
+
+[Editing scenarios](EDITING-SCENARIOS.md) defines EDIT-001 through EDIT-020,
+expected behavior, test mappings, environment scope and a run-record template.
+It distinguishes historical evidence from current verification. The EDIT-019
+sustained chain and source-fingerprinted runner were added on 2026-09-10. Other
+scenario assertions and CI/release enforcement remain separate work.
+
+## Rendering regression baseline — workspace, 2026-09-09
+
+[Rendering checks](RENDERING-TESTS.md) now defines executable size and position
+comparisons for fractional exponents/subscripts and a tall indexed-root base.
+React and native DOM share compact script-fraction rules. Empty non-grid slots
+now remove their wrapper with Delete or Backspace and retain other content.
+Next: paired scripts, multi-line collision, explicit style overrides and other
+notation families. Current checks do not implement an automated CI release gate.
+
+## Contextual structure footer — workspace, 2026-09-09
+
+Added query-independent radical actions, index editing, disabled explanations,
+F6/Escape access and embedding opt-out. EDIT-021 through EDIT-028 extend the
+scenario register with discovery, target, focus, locale, composition guard and
+lifecycle cases. Future work: context actions for additional structure families,
+explicit Tab-order assertions and broader framework/device coverage.
+
+## Inline-first fence transformations — workspace, 2026-09-09
+
+Implemented eight fence presentations through the existing suggestion list,
+Alt+Down discovery/reopening, nearest-wrapper targeting, retained caret/content
+and one-step conversion history. Optional footer controls support F6 and horizontal
+navigation. EDIT-029 through EDIT-032 add keyboard, cancellation, iframe, locale
+and no-toolbar coverage. Additional transformation families and the proposed
+optional radial menu remain future work; the list layout remains the default.
+
+## Horizontal text spacing — workspace, 2026-09-10
+
+Replaced fixed inter-token gaps with shared binary/relation/punctuation spacing,
+including unary-sign context and compact script rows. Removed per-token padding
+from mathematical glyph measurement. Empty expression inputs remain available;
+inactive structural caret boundaries are narrower. VIS-066 through VIS-073 add
+addition, equality, unary signs, parentheses, named functions, fractions,
+punctuation and script comparisons at 22 px and 36 px in React and native DOM.
+
+Next: longer expressions, complete atom classification across structure wrappers,
+named-function boundaries, explicit spacing commands and browser font differences.
+The source-only rendering ledger records measured limits and remaining work.

package/STYLING.md

@@ -0,0 +1,157 @@
+# Styling and themes
+
+The editor exposes CSS custom properties for presentation. Set them on a wrapper around an editor, or on a shared ancestor for multiple editors. This works with React, native JavaScript, the light-DOM Web Component, Vue, Svelte and Solid. No theme provider or additional runtime is required. Styling does not change the JSON model, exported LaTeX or undo history.
+
+Import the package stylesheet once, then add your application stylesheet:
+
+```js
+import '@barocss/math-editor/style.css';
+import './math-theme.css';
+```
+
+```css
+.product-math {
+  --me-font-size: 18px;
+  --me-accent: #6b4bb3;
+  --me-variable: #385ea1;
+  --me-number: #a65316;
+  --me-symbol: #8056ad;
+  --me-function: #147d77;
+  --me-surface-padding: 24px 16px;
+  --me-surface-min-height: 100px;
+  --me-toolbar-padding: 6px;
+  --me-control-radius: 4px;
+}
+```
+
+```tsx
+// Rich React editor. Native framework adapters use the same wrapper pattern.
+<div className="product-math">
+  <MathEditor onChange={(document, latex) => save(document, latex)} />
+</div>
+```
+
+```js
+// Native JavaScript. The wrapper may already carry application theme variables.
+const host = document.querySelector('.product-math');
+const editor = mountMathEditor(host, { onChange: save });
+host.style.setProperty('--me-font-size', '20px');
+// On unmount:
+editor.destroy();
+```
+
+```html
+<!-- Register with defineMathEditor() first. This component uses light DOM. -->
+<barocss-math-editor class="product-math" locale="en"></barocss-math-editor>
+```
+
+Try the website's **Theme**, **Math size** and **Compact spacing** controls in the [playground](https://math-editor.barocss.com/#playground). These are application examples, not required library presets.
+
+## Public CSS variables
+
+Unset variables preserve the existing default appearance. Some controls intentionally have slightly different default shades/radii; a supplied token unifies them. Set lengths such as the base font size in `px` or `rem` when the editor and its portal have different parents.
+
+| Variable | Controls | Default behavior |
+| --- | --- | --- |
+| `--me-font-size` | Base formula text and relative script sizes | `22px` in standalone editors |
+| `--me-ui-font-family` | Toolbars, menus and helper text | `system-ui, sans-serif` |
+| `--me-text` | UI text and neutral math glyphs | Dark green/gray |
+| `--me-muted` | Help text, line numbers, menu details | Muted gray/green |
+| `--me-accent` | Buttons, active borders, matrix selection | Green |
+| `--me-line` | Toolbar separators and control/menu borders | Pale gray/green |
+| `--me-background` | Editor root | Transparent |
+| `--me-panel-background` | Suggestion menus, symbol cards, inputs/selects in toolbars | White |
+| `--me-toolbar-background` | Main toolbar | Transparent |
+| `--me-subtle-background` | Symbol browser and grid tools | Pale neutral |
+| `--me-hover-background` | Toolbar hover | Pale green |
+| `--me-active-background` | Selected suggestion and active controls | Pale green |
+| `--me-variable` | Variable tokens, including focused inputs | Blue |
+| `--me-number` | Numeric tokens (`constant` token kind) | Brown/orange |
+| `--me-symbol` | Symbol tokens | Purple |
+| `--me-function` | Function/operator names and their legend | Teal |
+| `--me-input-background` | Editing slot background | Context-specific slot tint |
+| `--me-input-focus-background` | Focused/hovered slot background | Stronger context-specific tint |
+| `--me-selection-background` | Text and structural range selection | Blue |
+| `--me-selection-color` | Native selected input text | White |
+| `--me-focus-color` | Keyboard focus indicator | Blue |
+| `--me-radius` | Suggestion panel corners | `10px` |
+| `--me-control-radius` | Buttons and toolbar fields | `4px`–`7px` depending on control |
+| `--me-surface-padding` | Block editing area padding | `48px 32px` |
+| `--me-inline-padding` | Native inline area padding | `2px 4px`; plugin compact fields `0 2px` |
+| `--me-surface-min-height` | Block area minimum height | Standalone `190px`; plugin panels `60px` |
+| `--me-toolbar-padding` | Main toolbar padding | `12px` |
+| `--me-toolbar-gap` | Gap between main toolbar controls | `4px` |
+| `--me-line-gap` | Gap between top-level equation rows | `18px` |
+| `--me-menu-shadow` | Floating menu shadow | Soft dark shadow |
+| `--me-menu-z-index` | Suggestion menu stacking level | `1000` |
+
+Inline mode retains its content-driven minimum height. Explicit LaTeX sizing commands and specialty mathematical fonts retain their own metrics; the base-size token is not an image scaling API. Formula export/KaTeX rendering is owned by the consumer and does not inherit semantic editing colors automatically.
+
+## Dark and monochrome themes
+
+Define a theme in your own stylesheet. Supply foregrounds and backgrounds together so active inputs, selection and menus remain readable.
+
+```css
+.product-math[data-theme='dark'] {
+  color-scheme: dark;
+  --me-background: #18232c;
+  --me-text: #e5edf3;
+  --me-muted: #a4b5c2;
+  --me-line: #435565;
+  --me-panel-background: #202f3b;
+  --me-subtle-background: #243441;
+  --me-hover-background: #334857;
+  --me-active-background: #354e61;
+  --me-accent: #83d5bc;
+  --me-variable: #9ac7ff;
+  --me-number: #ffc28b;
+  --me-symbol: #d0b7ff;
+  --me-function: #7bddd5;
+  --me-input-background: #223444;
+  --me-input-focus-background: #334d63;
+  --me-selection-background: #436483;
+  --me-selection-color: #fff;
+  --me-focus-color: #9ac7ff;
+}
+
+.product-math[data-theme='mono'] {
+  --me-variable: #303740;
+  --me-number: #303740;
+  --me-symbol: #303740;
+  --me-function: #303740;
+  --me-input-background: #f1f2f4;
+  --me-input-focus-background: #e0e4e9;
+}
+```
+
+Change `data-theme`, an ancestor class, or inline custom properties without remounting. The semantic model remains intact even when all token colors match.
+
+## Suggestions, separate toolbars and iframes
+
+Suggestion and selection-wrapping menus usually mount under `document.body` or the nearest dialog. Both renderers copy the owning editor's resolved presentation tokens to these menus. Two editors can use different themes without applying a global `.me-suggestion-panel` rule. Ancestor attribute changes, window resizing and preferred color-scheme changes refresh the menu theme. Dynamic stylesheet replacement without those events is picked up on the next menu render/open; prefer changing a scoped class or custom property.
+
+Host integrations keep menus inside the math node's event boundary. They use the same glyphs, labels and details as the main React editor. Pointer movement highlights candidates; a stationary pointer does not replace keyboard choices when the list scrolls or redraws. Menu text does not inherit paragraph alignment or letter spacing. Ordinary scrolling text areas do not reduce the fixed menu's height; dialogs and clipping containers that establish a local containing block still constrain it. In a short dialog, the native menu hides its guidance before reducing the space for selectable rows.
+
+An independently mounted toolbar inherits from **its own host**. Put it under the same themed ancestor or apply the same theme class to the editor and toolbar containers. A toolbar shared between different themes does not automatically switch to the selected editor's theme.
+
+CSS does not cross document boundaries. For a TinyMCE classic iframe, load both core and plugin stylesheets using `content_css` and load your theme CSS into that iframe too. Apply the theme to its body or a wrapper within that document. Style a shared toolbar outside the iframe separately. The menu bridge uses the editor's owner document; it does not copy parent-page CSS into an iframe. See [TinyMCE integration](../math-editor-integrations/docs/TINYMCE.md).
+
+## Editor plugin chrome
+
+Import the chosen plugin's `style.css` alongside the core CSS. Shared plugin panels, Apply/Cancel buttons, size controls and hover states use the same `--me-*` palette. Additional host chrome variables are:
+
+| Variable | Controls |
+| --- | --- |
+| `--bme-inline-background` | Background behind an in-place math draft |
+| `--bme-action-color` | Text on the primary Apply button (default white) |
+| `--bme-error-color` | Draft validation messages |
+
+Formula size in host integrations is a **document attribute**: the plugin measures surrounding prose and combines it with the formula's saved percentage. Use the plugin's `fontSize` attribute/size controls for persisted math size. The internal `--bme-font-size` is computed from that value; setting a standalone `--me-font-size` on a wrapper does not override persisted host sizing.
+
+For dark plugin fields, also set `--bme-inline-background: #223444` and choose a readable `--bme-action-color` for your accent. Themes style editor UI, not the surrounding host editor's own menu bar or rendered formula HTML.
+
+## Custom toolbar and layout
+
+Use `toolbar: false` for editor-only embedding, a list of structure kinds to limit commands, or `toolbarMaxItems` for overflow. A completely custom toolbar can call `session.execute(...)`. See [embedding](EMBEDDING.md) and the [session API](API-SESSION.md).
+
+Treat internal `.me-*` and `.bme-*` layout selectors as implementation details. Prefer these variables over overriding fractions, scripts, radical paths, integral glyphs, or input positioning: those metrics are coordinated for editing and KaTeX comparison. Theme changes should be checked with keyboard focus, selections, suggestions and tall nested formulas, as well as at rest.

package/SUPPORT.md

@@ -46,7 +46,7 @@ See the [LaTeX editing guide](LATEX-GUIDE.md) for input examples and prioritized
 | Product | Lower limit, upper limit, body | `\prod_{i=1}^{n}x` | No evaluation |
 | Triple / contour integrals | Three editable slots; side bounds or explicit limits | `\iiint`, `\oint` | No computation; `\nolimits` supported in workspace |
 | Integral | Lower limit, upper limit, integrand | `\int_{a}^{b}x` | Differential entered as text; no integration engine |
-| Matrices / vectors | Editable nested cells; row/column changes | `matrix`, `pmatrix`, `bmatrix`, `Bmatrix`, `vmatrix`, `Vmatrix` | 1–20 rows and columns; no rectangular cell clipboard |
+| Matrices / vectors | Editable nested cells; row/column changes | `matrix`, `pmatrix`, `bmatrix`, `Bmatrix`, `vmatrix`, `Vmatrix` | 1–20 rows and columns; workspace rectangular clipboard and full-matrix transpose |
 | Aligned equations | Two columns, left side right-aligned and right side left-aligned | `aligned` | 1–20 rows, one alignment point; type the relation explicitly |
 | Cases | Expression and condition columns, left brace | `cases` | 1–20 rows; conditions accept math and literal text nodes |
 | Multiple document lines | Split/join top-level rows | `gathered` | No wrapping several document lines into one structure |
@@ -56,17 +56,19 @@ See the [LaTeX editing guide](LATEX-GUIDE.md) for input examples and prioritized
 | Area | Supported | Remaining boundary |
 |---|---|---|
 | Languages | Korean and English UI, demo, accessible names, hints and suggestions | Custom host labels require host translation |
+| Recent / favorites | Shared UI preference store for known symbols/templates, up to 12 recent and 100 favorites | Optional host persistence; no effect on formula JSON or Undo |
+| Presentation changes | Fence type, fraction/binomial size and operator limits from the contextual toolbar | Existing notation only; no arbitrary fonts or dimensions |
 | Discovery | All-symbol grid with English/Korean/glyph/LaTeX search, click to insert | Scroll through the complete 117-symbol catalog |
 | Line numbers | UI gutter for multiple top-level rows, optional prop | Excluded from math output and clipboard |
 | Aliases | English and Korean in both locales; longest symbolic trigger first | Substring matching with exact matches first; no natural-language parsing |
 | Native input | Active token only; composition draft held stable | Real OS IME validation deferred |
 | Roles | Variables, numeric literals, symbols, spaces | Lexical colors are not semantic declarations |
-| Selection | Partial text, drag across tokens/structures, whole document in preview | No keyboard Shift-arrow model expansion or rectangular cell selection |
+| Selection | Partial text, drag across tokens/structures, whole document in preview | Shift+arrow model ranges and workspace rectangular cell selection; touch/OS clipboard validation remains |
 | Wrapping | Fraction, root, power, subscript, parentheses, brackets, absolute value | One balanced row; cross-slot range expands to common structure |
-| Clipboard | Structured internal fragment plus LaTeX text; cut/paste replacement | External LaTeX is literal text; nested multiline paste rejected |
-| History | Undo/redo of model changes and caret, up to 100 prior states | No shared host undo adapter yet |
+| Clipboard | Structured internal fragment plus LaTeX text; cut/paste replacement | Ordinary paste is literal; explicit LaTeX insertion parses at the caret/range; nested multiline paste rejected |
+| History | Undo/redo of model changes and caret, up to 100 prior states | Shared host adapters commit one formula edit; per-host history support varies |
 | Deletion | Text boundaries, line join, structure unwrap, two-step filled-grid deletion | General structural deletion rules are still limited |
-| Serialization | Version-1 JSON document and change callback | No persistence service, saved-document validator or migrations |
+| Serialization | Version-1 JSON document and change callback | `parseMathDocument` validates shape and IDs; persistence and future version migrations remain host work |
 | Preview | Demo-only KaTeX view | Library renders its own editable presentation |
 | Accessibility | Localized labels, combobox suggestions, keyboard slot navigation | Not a complete mathematical screen-reader implementation |
 | Computation | None | No solving, simplification, units engine or collaboration |
@@ -75,9 +77,9 @@ See the [LaTeX editing guide](LATEX-GUIDE.md) for input examples and prioritized
 
 | Template / preset | Sizes | Discovery | Behavior |
 |---|---|---|---|
-| Empty matrix | 2×2, 3×3, 4×4 | `matrix`, `행`, `행렬`; matrix menu | Editable empty cells |
-| Identity matrix | 2×2, 3×3, 4×4 | `identity`, `단위`, `단위행렬`; matrix menu | Diagonal 1, other entries 0 |
-| Zero matrix | 2×2, 3×3, 4×4 | `zero`, `영행렬`; template menu | All entries 0, editable |
+| Empty matrix | 1–20 rows × 1–20 columns via size shortcuts; 2×2/3×3/4×4 menu presets | `matrix`, `행`, `행렬`; matrix menu | Editable empty cells |
+| Identity matrix | Square sizes 1–20 via size shortcuts; 2×2/3×3/4×4 menu presets | `identity`, `단위`, `단위행렬`; matrix menu | Diagonal 1, other entries 0 |
+| Zero matrix | 1–20 rows × 1–20 columns via size shortcuts; 2×2/3×3/4×4 templates | `zero`, `영행렬`; template menu | All entries 0, editable |
 | Column vector | 2×1, 3×1 | `vector`, `column`, `벡터`, `열벡터`; template menu | Empty editable column; existing generic matrix candidates may also match |
 | Quadratic formula | One expression | `quadratic`, `근의공식`; template menu | `x=(-b±√(b²−4ac))/(2a)` using fraction/root/power nodes; assumes a≠0 mathematically, does not enforce it |
 | Pythagorean theorem | One expression | `pythagorean`, `피타고라스`; template menu | `a²+b²=c²` using editable power nodes |
@@ -212,7 +214,7 @@ Catalog size: **117 symbols**.
 
 ## Renderer availability
 
-This formula catalog describes the shared model and the existing rich React editor. New native DOM/framework surfaces share the notation model but have a smaller interaction UI. See the [renderer parity table](ADAPTERS.md#current-renderer-parity) before choosing an adapter.
+This formula catalog describes the shared model and the existing rich React editor. Native DOM/framework surfaces share the notation model, token editing, discovery and presentation utilities; host integration policies remain separate. See the [renderer parity table](ADAPTERS.md#current-renderer-parity) before choosing an adapter.
 
 ### Combined scripts (workspace)
 
@@ -253,12 +255,12 @@ Type `quad` / `qquad` (or `간격` / `큰간격`) for an explicit gap. The caret
 
 Select an expression and choose a fence or annotation in the regular suggestion menu. Fences wrap the expression and resume after it. Annotations keep the selected expression in the body and focus the empty annotation slot. Nested fractions, scripts and other editable structures are allowed in both annotation slots. Backspace after a structure removes its wrapper while preserving its content; Undo restores it.
 
-All structured fences scale with their contents. Short angle notation normalizes to scalable `\left\langle…\right\rangle` on export. Supported physical ends are `(`, `)`, `[`, `]`, `{`, `}`, `⟨`, `⟩`, `|` and `.`. Plain punctuation stays literal unless imported with a structural command. Double norm bars, `\big`/`\Big`, `\overbrace` and `\underbrace` remain unsupported.
+All structured fences scale with their contents. Short angle notation normalizes to scalable `\left\langle…\right\rangle` on export. Supported physical ends are `(`, `)`, `[`, `]`, `{`, `}`, `⟨`, `⟩`, `|` and `.`. Plain punctuation stays literal unless imported with a structural command. Double norm bars and brace annotations are supported. Explicit `\big`/`\Big` sizing remains unsupported.
 
 
 ### Double integrals (workspace)
 
-`\iint_R f(x,y)` imports as `doubleIntegral` with exactly three slots: `[lower/domain, upper, body]`, matching integral navigation. Missing bounds remain editable empty slots. `\iint\limits` preserves the explicit placement directive. Export uses `\iint_{lower}^{upper}{body}`. Search `iint`, `이중적분` or `∬` to insert; Tab visits the domain, upper bound and body in order. The reported expression with `\rm dx \rm dy`, `\xi`, `\eta` and `\text{Area}` is covered by import/round-trip and browser editing fixtures. This is notation support, not numerical integration. Triple and contour integrals remain outside this addition.
+`\iint_R f(x,y)` imports as `doubleIntegral` with exactly three slots: `[lower/domain, upper, body]`, matching integral navigation. Missing bounds remain editable empty slots. `\iint\limits` preserves the explicit placement directive. Export uses `\iint_{lower}^{upper}{body}`. Search `iint`, `이중적분` or `∬` to insert; Tab visits the domain, upper bound and body in order. The reported expression with `\rm dx \rm dy`, `\xi`, `\eta` and `\text{Area}` is covered by import/round-trip and browser editing fixtures. This is notation support, not numerical integration. Triple and contour integrals are also supported.
 
 Fine spacing: `\,`, `\:`, `\;`, `\!` are preserved as zero-slot structures. Positive spacing expands and negative thin spacing contracts the next boundary; these are not editable text spaces.
 
@@ -276,6 +278,16 @@ Fine spacing: `\,`, `\:`, `\;`, `\!` are preserved as zero-slot structures. Posi
 
 ## Keyboard ranges and brace discovery (0.2.1)
 
-Shift+Left/Right extends or shrinks the same model range used by dragging. Structures are crossed as balanced units; copied and deleted ranges use existing model normalization. Shift+Up/Down extends to an adjacent top-level document line, using a logical text offset rather than pixel-based column matching; grid-cell rectangular selection is not added. Copy, cut, wrapping, deletion and Undo use the existing range behavior. IME composition and modifier shortcuts retain their existing handling.
+Shift+Left/Right extends or shrinks the same model range used by dragging. Structures are crossed as balanced units; copied and deleted ranges use existing model normalization. Shift+Up/Down extends to an adjacent top-level document line, using a logical text offset rather than pixel-based column matching; an active matrix-cell selection instead uses Shift+arrows to move its rectangular focus corner. Copy, cut, wrapping, deletion and Undo use the existing range behavior. IME composition and modifier shortcuts retain their existing handling.
+
+After a model selection, plain Left/Up restores the caret at its document-ordered
+start; Right/Down restores it at the end. The same rule applies to reverse drags
+and Shift+arrow selections, without consuming another character or changing the
+formula. Alt+Up/Down browses the wrapping suggestions while retaining the range;
+Enter applies a candidate. Ordinary input suggestions still use Up/Down.
 
 Typing `{` offers both paired braces and cases. Paired braces remain the first candidate; choose Cases explicitly to insert its editable grid.
+
+## Presentation customization
+
+CSS variables support scoped palettes, token colors, slot focus/selection, toolbar density and menu chrome in both renderers and all framework adapters. Portaled suggestions follow their owning editor. See [Styling & themes](STYLING.md); host integrations retain their own persisted formula-size attributes.