@barocss/math-editor 0.4.0 → 0.6.1

package/ROADMAP.md

@@ -1,8 +1,163 @@
 # Math editor roadmap
 
-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.
+## Learning and discoverability — implemented, 2026-09-13
 
+- Five interactive site exercises use their own field and validate normalized formula models: correction, fraction wrapping, power, root conversion and LaTeX insertion.
+- Beginner, clipboard and keyboard guides are in the documentation navigation. Outdated claims that norms/integrals/brace annotations were still planned were removed from the LaTeX guide.
+- Localized F1/toolbar help works in React and native fields, including toolbar-free inline. Closing restores native input selection. Custom controls can use `showHelp()`; separate native toolbars connect with `onHelp`.
+- EDIT-035 and the extended 17-target host chain pass; see [validation](VALIDATION.md).
 
+Possible later convenience work: configurable key bindings with host-conflict rules, and selection-only image export. These are not implemented by the help API. Prioritize demonstrated input problems and platform validation before adding more notation.
+
+## Completed milestone: reliable editing of supported notation — 2026-09-13
+
+Complete an uninterrupted formula workflow: **input → select → wrap or transform → navigate → delete → copy/paste → undo/redo → save → reopen and edit**. The JSON tree, exported LaTeX, visible notation and active caret must agree at each relevant checkpoint.
+
+This section defines the current work and its completion criteria. The dated records below are historical evidence; their old “next” and “awaiting release” statements do not define current priority or publication status. Dates describe verification runs, not release promises.
+
+### Starting baseline
+
+- EDIT-019: 17 standalone/integration targets, 499 continuous-editing checkpoints.
+- EDIT-033: 63 selection-shortcut cases, 510 checkpoints, including 21 comparisons of actual edited output with KaTeX.
+- EDIT-034: React block and native DOM block/inline, 131 held-arrow checkpoints.
+- Rendering: 91 formulas, 330 renderer/mode/size combinations. These are selected geometry checks, not complete pixel or behavior coverage.
+- Core: 1,677 tests in 42 files at the latest recorded run.
+
+See [validation](VALIDATION.md) and [editing scenarios](EDITING-SCENARIOS.md). The starting counts above are historical; the closure results below supersede them.
+
+### Execution order and bounded deliverables
+
+All six batches are **complete for the environment and checks stated here**. The local gate passed 1,736 core tests, 113 editing cases / 4,311 checkpoints and 330 KaTeX comparisons. Strict type checks, core build and site/docs build passed. [Validation](VALIDATION.md) contains the per-suite evidence. The CI workflow is configured and its entry point passed locally; remote execution and publishing remain separate actions.
+
+| Order | Batch | Scope | Completion check |
+| --- | --- | --- | --- |
+| 1 | Structure and grid deletion | EDIT-006/015: Backspace and Delete inside/outside empty and populated structures; selected ranges; matrix, cases and alignment rows/cells | Define the expected action before implementation. Preserve all content not explicitly deleted. One Undo restores the exact tree and a valid caret. Follow deletion with typing and Redo. |
+| 2 | Range interchange | EDIT-007/015: text plus nested structures; copy, cut and paste within/across instances; matrix rectangles; supported LaTeX fallback; malformed and mismatched payloads | Preserve selected structure and unselected content. Cut is undoable. Rejected paste changes nothing. Distinguish controlled clipboard-event checks from actual system clipboard verification. |
+| 3 | Lines and keyboard navigation | EDIT-012/013/016/034: line split/merge; cases/alignment row edits; matrix traversal; repeat keys; vertical movement; suggestion navigation | Preserve the preferred horizontal caret position across repeated vertical movement where geometry permits. Menus own their documented keys. Inline Enter follows the host contract and creates no formula line. |
+| 4 | Selection and transformations | EDIT-002–005/021–033: direct wrapping, suggestion-based conversion, nearest nested target, Escape and continued input without a toolbar | Current supported transformations remain discoverable by keyboard. They preserve operands, use the intended slot and support one-step Undo. Do not add new notation as a prerequisite. |
+| 5 | Host lifecycle | EDIT-008–011/018/019: extend current host chains with the completed operations; Apply/Cancel; storage reload; read-only; multiple instances; teardown | Draft operations do not modify stored host content. Apply creates one host history event where supported. Reopened formulas remain editable. Menus and listeners do not survive instance destruction. |
+| 6 | Consolidated verification and release checks | Run the required suites on the same candidate source; update scenario status, support limits, docs and release notes; connect the required checks to CI | Checks fail on regressions or missing required results, retain reports/screenshots and work without a developer-specific absolute CLI path. No required in-scope scenario remains unrun or failed. Publishing is a separate action. |
+
+For each batch: reproduce → specify the expected tree/caret → add a failing case → fix the shared behavior → compare editor/KaTeX → rerun affected scenarios → record evidence. Rerun the complete geometry set when shared layout rules change. Keep every discovered regression as a stable scenario.
+
+### Structure and visual comparison contract
+
+1. Cover every currently supported structure kind in the catalog with a populated edit and an empty-slot/boundary case where applicable. Shared structural families may share fixtures, but each catalog kind must map to coverage or an explicit non-applicable reason.
+2. Keep the existing catalog-driven parser/exporter combination checks. Add browser combinations by behavior: structure in a fraction slot, a script, a radical/fence, an operator bound, or a grid cell. Include repeated siblings, compound operands, mixed text/math and at least three nested structural levels. This is a finite representative matrix, not every possible expression.
+3. For changed flows, compare **the LaTeX produced by actual editing**, not only a separately imported formula. Verify the expected JSON structure independently; a visually correct preview cannot excuse lost or misplaced model content.
+4. Compare idle and focused states at 22px and 36px, with matching KaTeX display mode. Check baseline/relative positions, script and index size, fences/radicals, operator bounds, horizontal spacing, clipping and input-induced movement.
+5. Retain the existing metric thresholds: font difference ≤ 0.1px, relative vertical-center difference ≤ 0.25em, active-position change ≤ 0.2em, and horizontal difference ≤ 0.25em where comparable anchors are defined. These proxies are not complete glyph-ink measurements. Add a check when a visible defect is outside the measured anchors; do not relax thresholds to hide it.
+6. Review screenshots of changed notation. Reject obscured symbols, overlapping slots, clipped content or a position that suggests the wrong mathematical attachment, even if a measured probe passes. Record intentional differences for empty slots, focus backgrounds and caret hit areas. Exact pixel equality with KaTeX is not a milestone requirement.
+
+Detailed comparison tables and screenshots stay in the source-only rendering ledger. Public guides describe supported behavior and limitations.
+
+### Environments included in this milestone
+
+- Automated editing and visual acceptance: desktop Chromium on macOS, with the recorded browser and font versions.
+- Core surfaces: React block and native DOM block/inline. Smoke-check Pure JS, Web Component, Vue, Svelte and Solid wrappers for focus, option updates, independent instances and teardown; shared DOM passes alone do not certify wrapper lifecycle.
+- Existing host configurations: Tiptap, ProseMirror, Lexical, Quill, Slate, TinyMCE inline host and CKEditor ClassicEditor in their current block/inline math demos; Editor.js and Gutenberg standalone in block mode. Run the relevant chain in each host that supports the operation.
+- Editor.js host history is not configured in the current demo. Formula history is required; do not count host Undo as passed. Gutenberg RichText inline math and additional host configurations are outside this scope.
+- English/Korean labels and custom-locale fallback must remain valid. Include a narrow desktop container to check clipping and suggestion placement, without claiming touch support.
+
+### Closure rule
+
+Close this milestone only when all six batches have executable coverage, the required checks pass on the candidate source, and no known in-scope content-loss, blocked-input, incorrect-structure or visual-attachment defect remains. Each result must identify its scenario, renderer/mode, source fingerprint and observed limitation. A test count alone is not completion evidence.
+
+If a new defect is within this contract, fix and rerun before closure. If it requires a new notation family, platform or product, record it in the later queue instead of silently expanding the milestone. “Complete” refers to this bounded milestone, not all TeX or every device.
+
+### Subsequent milestones
+
+| Next stage | Work deferred from the current milestone |
+| --- | --- |
+| Platform validation | Safari, Firefox, Windows Chromium, real Korean IME, actual OS/application clipboard exchange, touch/mobile input and screen-reader verification. The earlier deferral of real OS input testing remains explicit; synthetic checks do not replace it. |
+| Library operating contract | Versioned JSON migration/recovery, measured document-size/depth and performance budgets, supported host-version policy and broader installed-host configurations such as TinyMCE iframe and WordPress admin. |
+| Demand-led expansion | Additional LaTeX environments/style declarations, reviewed language packs, new editor integrations and optional radial suggestions. Require a concrete input/editing use case first. |
+
+Full TeX documents, arbitrary macros/packages, symbolic computation, collaboration and a paper-writing service are separate products or projects. They are not required to finish this editor milestone.
+
+## Historical implementation records
+
+The following entries preserve past decisions and dated evidence. Use the completed milestone and subsequent milestones above for current scope.
+
+## Direct selection shortcuts — workspace, 2026-09-13
+
+Implemented immediate range wrapping for `(`, `[`, `{`, `|`, `/`, `^` and `_` in both renderers. Selection content, script/fraction caret placement and one-step Undo use the existing model operation. Other characters still replace selections. Unselected input and literal text retain their current behavior.
+
+Validation: EDIT-033 passes 63 cases / 510 checkpoints; geometry passes 91 formulas / 330 combinations after correcting fraction sizing and spacing. EDIT-019 still passes 17 targets / 499 checkpoints.
+
+EDIT-033 adds a repeatable browser suite for keyboard, native and dragged selections. VIS-080–093 add block/inline KaTeX position comparisons for the resulting formulas. Continue running editing and rendering checks together when shortcuts or notation change. Ambiguous keys such as `<` (relation, angle bracket, arrow prefix) and word commands such as `sqrt` remain suggestions.
+
+## 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
 
@@ -27,11 +182,11 @@ base-size and compact-spacing controls. See [Styling & themes](STYLING.md).
 
 ## Selection-to-caret keyboard behavior — workspace, 2026-09-09
 
-Both renderers now restore the caret when a plain arrow follows a Shift+arrow or
-pointer model selection. Left/Up uses the ordered start; Right/Down uses the end.
-Typing continues at that position without replacing the former range. Wrapping
-suggestions remain selectable with Alt+Up/Down or the pointer. The operation does
-not change the formula or create Undo entries.
+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
 
@@ -277,3 +432,80 @@ 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.
+
+## Text editor integrations — 2026-09-13
+
+- Implemented: optional direct LaTeX completion and caret preview for the three browser adapters; keyboard template navigation and source-preserving command insertion.
+- Implemented: grouped Examples navigation and per-example installation, usage and guide links.
+- Remaining: VS Code native source completion, wider platform/assistive-technology validation, and custom TeX dialect completion.
+
+- Implemented: shared LaTeX source-range discovery and draft popup; separate CodeMirror 6, CodeMirror 5, and Monaco packages.
+- Implemented: VS Code Edit Formula and Insert Formula commands, Webview UI, and VSIX build. VS Code 1.103.1 desktop command and Webview round-trip checks passed.
+- Added: workspace-source examples, English/Korean popup messages, source conflict protection, unchanged-source preservation, and one-step host undo.
+- Next: host syntax-tree resolvers for additional Markdown/TeX dialects, rebasing non-overlapping source edits, multi-caret policy, and broader VS Code platform QA.
+- Separate project: typed WGSL/GLSL expression editing. No shader parser is used by these adapters.
+- Publication: the four browser text packages are in the math release allowlist. The VS Code extension remains a separate release.
+
+## Editing readability and navigation — 2026-09-14
+
+- Added a configurable 14px editing minimum and extra line space for raised scripts.
+- Corrected fraction descendant sizes, nested fence alignment and radical geometry in scripts.
+- Added lexical/structural movement and selection: Ctrl+arrows, or Option+arrows on macOS, with Shift to select.
+- Added 100/125/150% visual text-popup zoom; default 125%, with a saved browser preference.
+- Documented a 26px editing base and optional 16px minimum for complex formulas. Output size stays separate.
+- Remaining: exact glyph contours/spacing, the full updated rendering audit, cross-editor suggestion dismissal, and wider browser/platform checks. Focused browser checks are recorded in the source rendering ledger; historical all-suite PASS results are not evidence for the new size policy.

package/STYLING.md

@@ -49,11 +49,27 @@ Try the website's **Theme**, **Math size** and **Compact spacing** controls in t
 
 ## Public CSS variables
 
+For complex fractions, start with a **26px editing base** instead of enlarging
+only the numerator or denominator. Use a **16px minimum** if nested text remains
+hard to read. Keep the KaTeX preview/export size separate from editing size:
+
+```css
+.product-math {
+  --me-font-size: 26px;
+  --me-min-font-size: 16px;
+}
+```
+
+복잡한 분수는 편집 기본 크기를 **26px**, 중첩 글자의 최소 크기를 **16px**로
+설정해 보세요. KaTeX 미리보기와 이미지 출력 크기는 앱에서 별도로 설정합니다.
+수식이 커지면 줄 높이도 늘어날 수 있도록 호스트 영역의 고정 높이를 피하세요.
+
 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-min-font-size` | Minimum editing glyph/input size, including nested fractions and scripts | `14px`; `0px` disables the floor |
 | `--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 |
@@ -85,7 +101,18 @@ Unset variables preserve the existing default appearance. Some controls intentio
 | `--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.
+Inline mode retains its content-driven minimum height. The editor reserves extra line space when scripts extend beyond the row. The host must allow this height to grow instead of clipping the editor into a fixed-height line.
+
+Nested math uses TeX size ratios with a readable `14px` floor. The same floor applies to glyphs, measuring spans and focused inputs, so fractions and fences grow with their contents. Explicit small LaTeX styles are also subject to this editing floor. To use a larger minimum:
+
+```css
+.product-math {
+  --me-font-size: 22px;
+  --me-min-font-size: 16px;
+}
+```
+
+Set `--me-min-font-size: 0px` for unmodified TeX size ratios, for example in a typography comparison. Use a nonnegative length in `px` or `rem`. The floor changes editing layout only; it does not add sizing commands to LaTeX, change history, or enlarge suggestion menu labels. Formula export/KaTeX rendering is owned by the consumer and does not inherit this floor or semantic editing colors automatically. The base-size token is not an image scaling API.
 
 ## Dark and monochrome themes
 

package/TEXT-EDITORS.md

@@ -0,0 +1,157 @@
+# LaTeX editing in text editors
+
+The browser text-editor adapters support a visual popup and optional LaTeX source completion with a formula preview. They do not replace the host's text model. WGSL and GLSL expression editing is a separate project.
+
+## Available implementations
+
+| Package or extension | Editing surface | Lifecycle |
+| --- | --- | --- |
+| `@barocss/math-editor-text` | Shared range scanner and DOM popup | Explicit controller cleanup |
+| `@barocss/math-editor-codemirror6` | Caret popup, Alt+Enter | CodeMirror 6 view plugin |
+| `@barocss/math-editor-codemirror5` | Caret popup, Alt+Enter | Attachment with `destroy()` |
+| `@barocss/math-editor-monaco` | Caret popup, Alt+Enter | Attachment and editor disposal |
+| Barocss Math Editor for VS Code | Webview beside the document | VS Code extension lifecycle |
+
+[Open the browser examples](../text-editors.html). The three examples import individual workspace packages directly from source. Published package exports target their own build artifacts. The new packages start at 0.1.0; npm and Marketplace publication are separate steps.
+
+## CodeMirror 6
+
+```sh
+npm install @barocss/math-editor @barocss/math-editor-text @barocss/math-editor-codemirror6 @codemirror/state @codemirror/view @codemirror/commands
+```
+
+```ts
+import { mathEditor } from '@barocss/math-editor-codemirror6';
+import '@barocss/math-editor/style.css';
+import '@barocss/math-editor-text/style.css';
+
+// Add to your EditorState extensions alongside the host's history extension.
+const extension = mathEditor({
+  locale: 'en',
+  syntax: 'markdown',
+  onError: message => { statusElement.textContent = message; },
+});
+```
+
+For CodeMirror 5 and Monaco, import `attachMathEditor` from the corresponding package and pass the host editor instance. The return value has `open()` and `destroy()`. CodeMirror 5 also has `refresh()`; call it after changing host options such as read-only mode. CodeMirror 6 exports the `openMathEditor(view)` command for custom controls. CodeMirror 5 uses its own package because its API differs from CodeMirror 6. Monaco applications retain their normal worker configuration.
+
+
+## Direct LaTeX input
+
+[Try source completion](../text-editors.html?mode=source). Choose **LaTeX completion** on the example page. The visual popup remains the default for existing integrations.
+
+Pass `sourceEditing` to the CodeMirror 5, CodeMirror 6, or Monaco adapter. An empty object enables completion without a preview. To show a preview, install KaTeX separately and supply a renderer:
+
+```sh
+npm install katex
+```
+
+```ts
+import katex from 'katex';
+import 'katex/dist/katex.min.css';
+import '@barocss/math-editor/style.css';
+import '@barocss/math-editor-text/style.css';
+
+const options = {
+  locale: 'en',
+  sourceEditing: {
+    renderPreview(latex, element, displayMode) {
+      katex.render(latex, element, {
+        displayMode,
+        throwOnError: true,
+        trust: false,
+        maxExpand: 1000,
+      });
+    },
+  },
+};
+// CodeMirror 6: mathEditor(options), included in EditorState extensions.
+// CodeMirror 5 / Monaco: attachMathEditor(editor, options).
+```
+
+| Action | Result |
+| --- | --- |
+| Type `\frac`, `\sqrt`, or another command inside a detected math range | Show localized catalog suggestions below the caret |
+| Place the caret after `a`, `4ab`, or `x_i^2` | Offer fractions, roots, scripts and fences that retain the operand |
+| Select a complete expression inside one math range | Preview the selection and offer source-preserving wrappers after drag release |
+| Ctrl+Space inside a math range | Open the catalog without typing a command |
+| Up / Down with suggestions open | Choose a candidate without moving the source caret |
+| Enter or Tab after choosing a suggestion | Apply the selected command or operand wrapper and enter its next argument |
+| Tab / Shift+Tab after insertion | Move through template arguments; this takes priority over operand wrapping suggestions |
+| Tab after the last argument | Exit the inserted template |
+| Escape | Dismiss source tools without changing source or collapsing its selection |
+| Alt+Enter | Open the existing visual editor |
+
+The preview sits above the caret when space permits. Incomplete syntax displays a short status instead of changing the source or blocking typing. The renderer is optional and is owned by the host. It must render only trusted UI; when using KaTeX, keep `trust: false` for document content.
+
+Completion uses the math-editor catalog and serializer to create an **isolated insertion**. It does not parse or normalize the surrounding formula. For example, `\rightarrow` suggestions may insert the catalog's equivalent `\to ` spelling. A trailing space terminates a control word so it cannot absorb the following variable. Operand wrapping fills a catalog template with the original variable/number run and simple scripts, without reserializing the source. For example, `4ab` becomes `\frac{4ab}{}` and the caret enters the denominator. Existing-structure transformations remain visual-editor actions.
+
+Automatic operand and selection menus do not preselect an action. Until you choose an item with Up/Down, Enter and Tab retain their normal host behavior. Typing a command or explicitly opening Ctrl+Space still preselects a completion.
+
+Selection mode shows the selected source and keyboard hints in a fixed menu header. Up/Down keeps the native selection; Enter/Tab or a click wraps exactly that range. Shift+Arrow continues to adjust the selection. The shared core parser validates selected expressions without serializing them. Split command names, unbalanced groups, literal text, cross-formula selections and ordinary document text do not get math wrapping suggestions.
+
+A position-aware lexical scan distinguishes command names, operand spans, comments, and braced text/environment names. Completing `\fr|ac{a}{b}` replaces the complete command name while preserving the arguments. Text and comments do not offer math wrappers. This is not a full TeX semantic parser: custom macros and arbitrary compound-expression boundaries are not inferred. Source mode accepts whitespace beside paired delimiters, including the trailing space inserted after a symbol command. The default visual-import scanner remains strict.
+
+The shared dropdown keeps focus in the host and applies changes through the host edit/history API. It handles navigation keys only while its suggestions or template navigation are active. IME composition suspends suggestions. Read-only state, selection outside the math range, and host disposal remove the tools. Multi-caret completion, arbitrary TeX macro completion, and full snippet-language syntax are not supported. Argument navigation ends after leaving the template, undoing its insertion, or replacing across its argument boundaries.
+
+`latexCompletions(query, locale)` is also exported from `@barocss/math-editor-text`. Each result includes `id`, `label`, `glyph`, `insert`, and UTF-16 `stops` relative to `insert`. A host can use this data in its own native completion provider instead of enabling the supplied dropdown. The `messages` option includes `suggestions`, `preview`, and `incomplete`; suggestion labels use the core locale catalog.
+
+This source-completion mode applies to the three browser adapters. The VS Code extension currently retains its separate visual Webview workflow.
+
+## User workflow
+
+1. Place the caret within `$…$`, `$$…$$`, `\(…\)`, or `\[…\]`. Alternatively, select a bare LaTeX expression.
+2. Press Alt+Enter (Option+Enter on macOS) or click **Edit formula**.
+3. Edit the draft. Math suggestions and clipboard controls operate inside the popup.
+4. Apply to replace the formula contents. Cancel to preserve the original.
+5. Continue in the host text editor. Undo once to reverse the applied edit.
+
+Opening the affordance never steals focus. An unchanged Apply does not normalize the original or add an undo entry. Changed formulas use the core serializer, which can normalize commands and whitespace inside the edited range. Existing dollar/backslash delimiters and surrounding prose remain intact. Leading/trailing whitespace inside the delimiters is preserved, including blank lines and indentation. For example, `$$\nx+1\n$$` becomes `$$\ny+1\n$$` after changing `x` to `y`. Newly serialized rows retain the source CRLF/LF convention; one-line display formulas remain one line.
+
+While the popup is open, move the source caret to another formula to switch its contents. This does not take focus from the source editor. Moving outside math hides the popup; entering another formula shows it again. Unapplied drafts survive formula switches while the source version is unchanged. Apply changes only the current formula. If other drafts remain, Apply or Cancel first shows a warning. The explicit discard button finishes the session; returning to another formula keeps its draft. Repeated Enter/Escape does not confirm discarding.
+
+## Source safety and limitations
+
+The default scanner skips ordinary Markdown code fences, inline code, indented code lines, and HTML comments. LaTeX mode skips percent line comments and common `\verb`, `verbatim`, `lstlisting`, and `minted` literal constructs. It supports a bounded set of equation, alignment, cases, and matrix environments. Detection is followed by the core LaTeX parser; unsupported syntax cannot overwrite the source. Complete environment ranges can be normalized when edited.
+
+The scanner is not a full Markdown/TeX parser. Hosts with custom macros, custom literal environments, or nested Markdown containers should provide `resolveRange(source, selection)` using their syntax tree. A return value of `undefined` disables automatic fallback for that position. Source offsets are UTF-16 positions.
+
+Any source edit or document switch invalidates an open draft, including edit-then-undo. External changes while editing in the popup still block Apply. Returning to the source caret reloads its current formula from the new source. Old-version drafts are not restored or rebased. Read-only documents reject Apply. Multiple selections are rejected. Multi-caret batch editing and concurrent-edit rebasing are not implemented.
+
+## Localization and styling
+
+`locale` controls the math editor. The popup includes English and Korean dictionaries. `messages` overrides individual popup labels for additional locales. Register core locale messages separately for mathematical suggestions and controls.
+
+The popup exposes `--me-text-background`, `--me-text-foreground`, `--me-text-border`, `--me-text-muted`, `--me-text-accent`, and `--me-text-on-accent`. Import both the core and text popup styles.
+
+## VS Code
+
+The extension supplies **Barocss: Edit Formula** and **Barocss: Insert Formula**. It uses a Webview and the public VS Code document API, not the internal Monaco DOM. In Markdown and LaTeX documents, Alt+Enter opens editing; users can change that binding in VS Code.
+
+Build and package from the workspace:
+
+```sh
+pnpm --filter barocss-math-editor type-check
+pnpm --filter barocss-math-editor package
+```
+
+Install the generated VSIX through **Extensions: Install from VSIX**. Desktop Extension Host validation and Marketplace publication must be checked separately from browser adapter tests.
+
+## Validation scenarios
+
+| Scenario | Expected result |
+| --- | --- |
+| Caret enters a formula | Edit affordance appears without taking focus |
+| Apply `x` → `y` | Only the formula contents change |
+| Undo / Redo | One host history step restores/reapplies the edit |
+| Cancel | Original text and history remain unchanged |
+| Apply unchanged draft | Exact original source remains |
+| Source edited while popup is open | Conflict shown; newer source preserved |
+| Unsupported command | Error shown; source preserved |
+| Caret in Markdown code | No automatic formula popup |
+| Read-only host | No source edit allowed |
+| Host destroyed | Popup and listeners removed |
+
+Browser scenario source: `apps/math-text-demo/test/editing.browser.js`. Range tests: `packages/math-editor-text/test/ranges.test.ts`.
+
+When wrapping a compound source expression in an exponent, visible parentheses preserve its scope: selecting `a+b` inserts `{\left(a+b\right)}^{}`. A single variable, number, or already grouped structure does not receive redundant parentheses. Source text inside the base remains unchanged.