@barocss/math-editor 0.5.0 → 0.6.1

package/RELEASING.md

@@ -4,12 +4,14 @@ See [Editing scenarios](EDITING-SCENARIOS.md) for stable scenario IDs, acceptanc
 
 
 The source stays in this monorepo. The local batch release includes
-`@barocss/math-editor` and the nine public host plugins. All use MIT, public npm
+`@barocss/math-editor`, nine public rich-text plugins and four text packages
+(`math-editor-text`, `math-editor-codemirror6`, `math-editor-codemirror5`,
+`math-editor-monaco`, all under `@barocss`). All use MIT, public npm
 access and the `latest` tag. Framework adapters are core subpaths and share the
 core version. The private integration workspace and other products are excluded.
 
-The published baseline is core **0.4.0** and host plugins **0.1.0**. Later versions
-remain independent; a batch release does not force every package to change.
+Versions remain independent; a batch release does not force every package to change.
+VS Code is a separate VSIX/Marketplace release and is not published by this npm command.
 
 ## Local release
 
@@ -20,10 +22,10 @@ npm login --registry=https://registry.npmjs.org/
 pnpm release:math
 ```
 
-This one command runs release-tool tests, core formatting/type/unit checks,
-integration type/unit checks, builds and package validation. It verifies the core
+This one command runs core formatting/type/unit checks,
+integration type/unit checks, builds, package validation and release-tool tests. It verifies the core
 entry points and each plugin's packed declarations, runtime imports and required
-files. It then runs **one `pnpm -r publish` command** for the ten allowed names.
+files. It then runs **one `pnpm -r publish` command** for the fourteen allowed names.
 `pnpm release` is an alias for this workflow.
 
 Only the inspected package contents enter a generated workspace under
@@ -42,7 +44,7 @@ guarantee one authentication prompt.
 For checks without publishing:
 
 ```sh
-# Build and inspect all ten packages. No registry publication.
+# Build and inspect all fourteen packages. No registry publication.
 pnpm release:math:prepare
 # Also exercise recursive publishing with npm's dry-run flag.
 # This can read registry metadata; it does not upload packages.
@@ -62,10 +64,22 @@ Before releasing UI changes, also run `pnpm --filter @barocss/math-demo test:e2e
 
 1. Run `pnpm changeset`, select the affected math core and/or public plugins, and write a user-facing change summary.
 2. Use patch for compatible fixes and minor for features. During 0.x development, clearly identify breaking API changes in a minor release. Reserve 1.0.0 for the agreed stable API.
-3. Run `pnpm version:math:plan` to preview the core and nine plugin versions. Run `pnpm version:math` to apply that plan. Changesets runs in a temporary math-only workspace and copies back only affected math manifests/changelogs. Unrelated product changesets remain untouched. Review plugin peer-range changes before publishing.
+3. Run `pnpm version:math:plan` to preview the core, nine rich-text plugin and four text-package versions. Run `pnpm version:math` to apply that plan. Changesets runs in a temporary math-only workspace and copies back only affected math manifests/changelogs. Unrelated product changesets remain untouched. Review plugin peer-range changes before publishing.
 4. Review and commit the version/changelog and any dependency/lockfile changes with the implementation. Run release validation, then publish locally.
 5. Record package-specific Git tags on the release commit, and update the site with the matching package version. The batch command does not create commits or tags.
 
+The scoped Changesets configuration only promotes peer dependents when the new
+version leaves their supported range. Widen a compatible peer range explicitly
+and add a patch changeset; incompatible range changes still require release review.
+
+Text tarballs are installed with the packed core into a temporary consumer using
+`npm install --offline --ignore-scripts --legacy-peer-deps`. Host SDKs come from the
+local installation. Strict public declaration checks and runtime import checks run
+there. This validates package contents and local installation, not npm availability
+or a fresh registry peer installation. Monaco interaction is covered by browser QA.
+See [text editor validation](../../apps/math-text-demo/test/README.md) for native
+IME and physical mobile checks that remain open.
+
 Versioning is separate from publishing. Repeating a publish command must not create
 another version. Avoid `pnpm version-packages` and unfiltered `pnpm -r publish`
 for a math-only release because they can include other products.

package/ROADMAP.md

@@ -1,8 +1,91 @@
 # 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
 
@@ -404,3 +487,25 @@ 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.

package/VALIDATION.md

@@ -1,5 +1,88 @@
 # Validation report
 
+## Readability, geometry and navigation — release preparation, 2026-09-14
+
+This candidate includes a configurable editing minimum, line clearance for
+scripts, fraction descendant sizing, nested fence/radical fixes, token/structure
+movement and selection, and visual text-popup zoom. The learning and styling
+guides now recommend a 26px editing base for complex fractions, with a separate
+preview/export size and an optional 16px nested minimum.
+
+- Core regression checks: 1,743 unit tests passed; core and demo type checks passed.
+- Focused browser checks: minimum-size editing, nested fences, script radicals,
+  keyboard movement/selection, and visual popup zoom. Detailed scope and limits
+  are recorded in the source-only records below.
+- English/Korean site guidance explains the larger editing size. Public keyboard
+  help now documents Ctrl/Option movement and selection and the matrix column
+  deletion shortcut change.
+- Historical full rendering and continuous-editing results below were obtained
+  before this candidate. They are not a fresh all-suite pass for the new size
+  policy. Exact curves/spacing and broader browser/platform QA remain open.
+- This section records preparation, not npm publication or site deployment.
+
+Source evidence: `test/rendering/STATUS.md`, `test/rendering/READABILITY.md`,
+`test/editing/TOKEN-NAVIGATION.md`, and
+`packages/math-editor-text/test/VISUAL-ZOOM.md` in the repository.
+
+## Learning and keyboard help — workspace, 2026-09-13
+
+- EDIT-035: **4 results / 40 checkpoints passed**: five model-checked tutorial exercises, wrong-answer/reset/close behavior, unchanged playground, toolbar help, Korean labels, and F1 lifecycle on React block/native block/native inline. [Evidence](../../output/playwright/editing-scenarios/2026-09-13T12-33-34-456Z/REPORT.md).
+- EDIT-019: **17 targets / 549 checkpoints passed**, including F1/Escape before the full continuous editing and host persistence chain. [Evidence](../../output/playwright/editing-scenarios/2026-09-13T12-31-33-614Z/REPORT.md).
+- Core: **1,736 tests / 43 files**, core/demo type checks, package build and site build passed.
+- Rendering: **330 PASS / 0 DIFF / 0 ERROR**, source stable. [Gallery](../../output/playwright/rendering-audit/2026-09-13T12-31-34-393Z/GALLERY.html). The new styles target help and the tutorial; mathematical geometry thresholds are unchanged.
+
+The first toolbar-help check exposed native selection collapse after closing help; selection restoration now passes immediate wrapping and continued input. A separate toolbar now uses explicit `onHelp` ownership instead of guessing a target field. The tutorial's LaTeX readout is not an extra live status region. English semantic locale-key checks pass.
+
+The consolidated CI entry point now includes the learning suite. These are local Chromium/macOS results. Actual OS F1/Fn routing, screen readers and system clipboard exchange remain unverified. No npm/site publication was performed.
+
+## Supported-notation editing milestone — workspace, 2026-09-13
+
+The bounded milestone in [the roadmap](ROADMAP.md) passed its local gate. This is a workspace result; no package version or publication status changed.
+
+- Core: **1,736 tests in 43 files**, strict core and browser-fixture type checks, and package build passed.
+- Editing: **113 cases / 4,311 checkpoints** across 11 suites. All suites used identical source fingerprints, which still matched the candidate after execution.
+- Rendering: **91 formulas / 330 PASS, 0 DIFF, 0 ERROR**. Existing thresholds were retained. Rendering sources matched the editing candidate. Twenty-one direct-shortcut cases also compare actual edited output with KaTeX.
+- Main site/docs production build passed. The repository-owned runner and CI workflow use `node scripts/check-math-editor.mjs`. Workflow YAML and runner syntax passed; remote GitHub Actions execution is not claimed.
+
+| Suite | Cases | Checkpoints | Result |
+| --- | ---: | ---: | --- |
+| EDIT-006 | 3 | 2766 | [PASS](../../output/playwright/editing-scenarios/2026-09-13T11-56-52-074Z/REPORT.md) |
+| EDIT-007 | 4 | 76 | [PASS](../../output/playwright/editing-scenarios/2026-09-13T11-57-55-776Z/REPORT.md) |
+| EDIT-013 | 2 | 10 | [PASS](../../output/playwright/editing-scenarios/2026-09-13T11-58-09-267Z/REPORT.md) |
+| EDIT-016 | 2 | 28 | [PASS](../../output/playwright/editing-scenarios/2026-09-13T11-58-21-145Z/REPORT.md) |
+| EDIT-018 | 8 | 60 | [PASS](../../output/playwright/editing-scenarios/2026-09-13T11-58-33-699Z/REPORT.md) |
+| EDIT-018-options | 5 | 30 | [PASS](../../output/playwright/editing-scenarios/2026-09-13T11-58-46-765Z/REPORT.md) |
+| EDIT-017-narrow | 3 | 12 | [PASS](../../output/playwright/editing-scenarios/2026-09-13T11-58-58-829Z/REPORT.md) |
+| EDIT-029 | 3 | 156 | [PASS](../../output/playwright/editing-scenarios/2026-09-13T11-59-12-733Z/REPORT.md) |
+| EDIT-034 | 3 | 131 | [PASS](../../output/playwright/editing-scenarios/2026-09-13T11-59-30-658Z/REPORT.md) |
+| EDIT-033 | 63 | 510 | [PASS](../../output/playwright/editing-scenarios/2026-09-13T11-59-45-550Z/REPORT.md) |
+| EDIT-019 | 17 | 532 | [PASS](../../output/playwright/editing-scenarios/2026-09-13T12-00-17-841Z/REPORT.md) |
+
+[Consolidated evidence](../../output/playwright/math-editor-milestone/2026-09-13/REPORT.md) · [Rendering gallery](../../output/playwright/rendering-audit/2026-09-13T12-01-09-133Z/GALLERY.html)
+
+Corrections include forward structure deletion, joining the following line, preferred vertical column retention, malformed clipboard rejection, multiline-paste rejection in React single-line fields, consistent Shift+Enter behavior and horizontal scrolling inside narrow inline hosts. English and Korean include the new invalid-clipboard message.
+
+Clipboard checks use controlled ClipboardEvents/DataTransfer. Read-only is toggled without pointer blur to isolate the host state transition; clicking outside may intentionally apply a draft first. Editor.js data is checked after re-enabling because it cannot save while read-only. Its demo has no host Undo integration. Svelte option updates use its action API; the framework sample also covers actual Svelte mount/unmount.
+
+Scope is desktop Chromium 152 on macOS with KaTeX 0.16.28. Safari, Firefox, Windows, real OS IME/clipboard, touch, screen readers, TinyMCE iframe and an installed WordPress admin are separate validation work. Geometry uses selected anchors and screenshot review, not complete pixel equality.
+
+## Held arrow navigation — workspace validation, 2026-09-13
+
+- React and native DOM now read the live input selection before keydown handling. Delayed selection events no longer leave token/slot boundary checks one key repeat behind.
+- EDIT-034: 3 renderer/mode targets passed 131 checkpoints with repeated keydown and one final keyup. Both horizontal directions, fraction slots, held Shift selection, collapse, continued input and Undo are covered.
+- EDIT-033: 63 cases / 510 checkpoints passed, including 21 actual edited-output comparisons with KaTeX.
+- EDIT-019: all 17 standalone/integration targets passed 499 continuous editing checkpoints.
+- Core: 1,677 tests / 42 files, type checking and package build passed. Evidence is linked from the source-only editing test README. This change is not published yet.
+
+## Selection shortcuts — workspace validation, 2026-09-13
+
+- Core: 1,677 tests / 42 files passed; type checking passed.
+- EDIT-033: 63 cases / 510 checkpoints passed in Chromium. React block and native DOM block/inline each cover keyboard, native input and dragged selections, seven wrapping keys, continued typing and Undo/Redo.
+- Geometry: 91 formulas / 330 combinations passed after fixing fraction term sizing and spacing. The same thresholds apply.
+- Twenty-one keyboard cases also compare the actual edited output with KaTeX using the existing font-size and vertical-position thresholds.
+- EDIT-019: all 17 standalone/integration targets passed 499 continuous editing checkpoints after the layout correction.
+- Browser artifacts and measured rendering limits remain in the source-only editing/rendering ledgers. OS IME, other browser engines and the previously excluded host configurations remain separate work.
+
 ## Inline fence transformation suggestions — workspace, 2026-09-09
 
 Core: **584 tests in 36 files passed**. Core type checking and the main site/docs
@@ -698,3 +781,22 @@ This is local Chromium evidence. OS IME, Safari/Firefox, installed WordPress and
   collaboration, native OS IME/clipboard, Firefox/WebKit, touch, accessibility
   and performance remain separate targets. Editor.js/Gutenberg are block tools;
   no inline mode is claimed for them.
+
+## Text editor integrations — 2026-09-13
+
+- Source-range tests: 31 passing cases (`packages/math-editor-text/test/ranges.test.ts`).
+- macOS Chromium browser adapters: 52 passing checkpoints across CodeMirror 6, CodeMirror 5, and Monaco. Includes nested root editing, display Enter, read-only changes, conflicting source, unsupported syntax, code exclusion, and Korean popup labels.
+- VS Code 1.103.1 Extension Host: four command-opening checks and eight Webview Apply/Cancel/Undo/Redo checks across Markdown and LaTeX. A disposable copy uses a test-only DOM input driver; no test driver ships in the VSIX.
+- Evidence: `output/playwright/math-text/`. Browser script: `apps/math-text-demo/test/editing.browser.js`. VS Code runner: `pnpm --filter barocss-math-editor test:extension`.
+- Remaining coverage: Firefox/Safari, Windows/Linux shortcuts, screen readers, VS Code web/remote hosts, and custom Markdown/TeX dialect resolvers.
+
+## Direct source completion and example guides — 2026-09-13
+
+- Shared source unit coverage: 37 passing checks, including range detection, fraction/root argument positions, rectangular matrices, symbol aliases, canonical export spellings and localized completion labels.
+- Browser source completion: 42 checks across CodeMirror 5, CodeMirror 6 and Monaco. Covers command-only replacement, focus retention, one-step Undo/Redo, forward argument navigation, scrolling, explicit catalog opening, incomplete source, read-only state and visual-popup fallback.
+- Additional source layout checks: 9 across the three hosts, covering indexed roots, reverse argument navigation, KaTeX preview placement and composition-event suspension. Synthetic composition events test gating; this is not a complete OS IME certification.
+- Existing visual-popup browser suite: 52 checkpoints still pass.
+- Example guides: 12 pages, including all nine document editors, with installation instructions and links checked against rendered HTML documentation.
+- Text packages, main site and integration site build successfully. Main and integration bundles retain existing large-chunk warnings.
+- Scripts: `apps/math-text-demo/test/source.browser.js`, `source-layout.browser.js`, `example-guides.browser.js`. Evidence is under `output/playwright/math-text/`.
+- This does not establish Firefox/Safari, Windows/Linux, screen-reader or VS Code source-completion support. No npm or site publication was performed for this change.

package/dist/dom/caret-geometry.js

@@ -21,7 +21,7 @@ export function renderedCaretGeometry(surface) {
             ? affinity === 'forward'
                 ? candidates.at(-1)
                 : candidates[0]
-            : candidates.find((item) => item.querySelector('.me-input')) ?? candidates[0];
+            : (candidates.find((item) => item.querySelector('.me-input')) ?? candidates[0]);
         const mirror = run?.querySelector('.me-measure');
         if (!run || !mirror)
             return;

package/dist/dom/help.d.ts

@@ -0,0 +1,5 @@
+import { type MathLocale } from '../i18n.js';
+/** Route a toolbar request to its owning field, including fields inside an iframe. */
+export declare function requestMathHelp(control: HTMLElement): void;
+/** Shared help UI. It does not execute model commands or read the clipboard. */
+export declare function attachMathHelp(root: HTMLElement, locale: () => MathLocale): () => void;