Editing scenarios

Current milestone evidence — 2026-09-13

The supported-notation milestone passed 113 cases / 4,311 checkpoints on the current candidate. Use validation for exact reports and scope. Run all required suites through node scripts/check-math-editor.mjs with both demo servers running.

This table records the bounded milestone. The full register below also includes wider variations, optional tools and platform checks; a suite pass does not certify every variation of a numbered scenario. Real OS clipboard/IME remains manual. Existing historical mappings are retained where a narrower suite does not replace them.

Use this document to manage editing behavior. Supported features lists notation; this register describes what a person does with that notation. Validation stores dated execution evidence. Neither the number of features nor the number of unit tests proves that an editing flow works.

Status and ownership

Keep each scenario ID stable. Add the ID to the browser fixture that exercises it and to a bug report when that flow fails. The person changing the behavior updates its expected result, test mapping and execution record in the same change. The release owner reviews unresolved cases before publishing.

P0 covers loss of content, blocked input, invalid output and host persistence. P1 covers discoverability, navigation and presentation. P2 covers additional platform coverage. A known P0 failure blocks release for the affected scope. An unrun or unsupported case must never be counted as passed.

Scenario register

Start each case with a fresh editor unless the steps specify saved content. Use actual key presses for typing and actual pointer movement for drag cases. Cmd applies on macOS; Ctrl applies on Windows/Linux. Do not substitute a programmatic value assignment for a focus or typing assertion.

Contextual structure tools

These scenarios specify the footer independently from the suggestion list. The footer has a single target: the nearest enclosing radical or fence. It is shown only while that editor is active, outside literal text and model/matrix selections. Native text selection within the active slot is allowed, including the selected index produced by conversion.

Inline transformation suggestions

The suggestion list is the primary keyboard entry point for structural changes. It remains available when both toolbar and context footer are hidden. Alt+Down opens or reopens suggestions and highlights the first available transformation; Up/Down browses, Enter applies, and Escape dismisses without editing the formula. Automatic context-only suggestions require navigation before Enter can apply them, so an inline host's commit key is not silently replaced.

Execution scope is recorded in Validation. A mapped case may still contain pending assertions, as stated in the Coverage column.

Browser fixture names above refer to apps/math-integrations/tests/. Unit fixture names refer to packages/math-editor/test/. A mapping identifies related coverage, not an assertion that every step already exists in that file. Extend cases need explicit browser assertions before they can receive a full pass.

Test environments

Record renderer, adapter, mode and browser separately. An integration using the native DOM field does not prove the rich React field, and an iframe can have its own focus, event and CSS failures.

Per-run record

Append detailed evidence to Validation, using this template. Record an immutable revision when possible. For an uncommitted workspace, record that fact and save the tested patch or a source fingerprint with the run artifacts. A date alone does not identify the tested code.

Run ID: edit-YYYYMMDD-NN
Scenario IDs:
Source: commit / workspace fingerprint / package versions and archive hashes
Fixture revision:
Renderer and host:
Mode and container:
Browser, OS, locale:
Input formula and steps:
Expected result:
Observed result:
Outcome: PASS / FAIL / BLOCKED / NOT RUN / N/A
Evidence: log, screenshot pair, trace or recorded host data
Remaining steps and excluded environments:
Issue / follow-up:

A scenario passes only when all required assertions pass in the recorded scope. For partial coverage, report the passing steps and keep the rest unverified. Do not convert historical validation totals into a current release pass.

Change workflow

1. Assign a scenario ID to each editing bug before changing its behavior.
2. Reproduce the smallest failing input sequence. Capture the caret, selection, highlighted suggestion, document and host data where relevant.
3. Add or update a regression fixture with the same ID. Check the final model, cursor/focus and history behavior, not only whether an element is visible.
4. Implement the change. Run its model tests, affected browser scenarios and the nearest negative case. Compare editor/KaTeX output when notation changes.
5. Record the result and its scope. Mark related scenarios for rerun if later changes touch their input, selection, suggestions, history or host handling.
6. Before release, run the applicable P0 cases against the release candidate and check packed imports. Any excluded host/browser must be stated explicitly.

The Markdown register is the source of truth for scope and acceptance criteria. The browser fixtures contain executable assertions. The validation report holds run evidence. The documentation site renders this register; it does not execute the browser checks. Automated release enforcement is not implemented by this register alone.

Next work

The supported-notation milestone is complete for its recorded desktop Chromium scope. Keep the 11 editing suites and full rendering audit as regression checks for subsequent changes.

1. Validate Safari, Firefox and Windows Chromium, then real OS IME/clipboard and assistive input.
2. Verify additional installed-host configurations, including TinyMCE iframe and WordPress admin.
3. Define JSON migration/recovery and measured document-size/depth/performance budgets.
4. Expand an editing scenario when a concrete defect or use case requires it. Compare the expected JSON tree and caret with actual edited output and KaTeX. Do not expand notation only to increase a feature count.

These are subsequent milestones. No pass is claimed for them by the current reports. Keep geometry reports in the source-only rendering ledger.

Direct selection wrapping — EDIT-033

Select math by Shift+arrows, dragging, or native input selection. Press (, [, {, |, /, ^ or _ without accepting a suggestion. Check retained content, the new caret slot, continued typing, one-step wrapping Undo and Redo. Include reversed and cross-slot selections, literal text, composition guards and multi-line rejection.

Run pnpm --filter @barocss/math-editor test:editing --suite=shortcuts. The dedicated browser fixture covers React block and native DOM block/inline (63 cases). Core tests cover nested ranges and negative cases. OS IME remains a separate scenario. Geometry fixtures VIS-080–093 compare the resulting notation against KaTeX at 22px and 36px, including active input.

Held arrow navigation — EDIT-034

Hold Left or Right through a number, an operator and a variable. Every repeated keydown must use the current input caret. Token and structure boundaries must respond before keyup. Repeat the check through fraction numerator and denominator slots, in both directions. Then hold Shift+Left, collapse the range with Right, type and Undo. Caret movement must preserve the formula and must not emit a document change.

Run pnpm --filter @barocss/math-editor test:editing --suite=arrows. The fixture covers React block and native DOM block/inline. It sends repeated real browser keydown events with one final keyup, and records every focused input and caret offset. Browser-generated key repeat covers the editor event path; physical keyboard repeat timing remains OS-controlled.

Learning and help — EDIT-035

Run pnpm --filter @barocss/math-editor test:editing --suite=learning.

Complete the five practice tasks with keyboard input: correction, selection-to-fraction, power, nearest root conversion and explicit LaTeX insertion. Reject a wrong answer; verify reset/close behavior and an unchanged playground. Pass criteria compare normalized model trees, not merely the rendered string. Test English and Korean help, toolbar access and F1 in React/native block and native inline fields. Closing must restore native selection, permit immediate wrapping/typing and preserve Undo. Destroying a field must remove open help.

The continuous host suite also opens/closes help before its existing editing chain. This tests the host draft boundary separately from standalone focus checks. Native OS F1/Fn routing and screen-reader behavior remain separate device checks.

Direct caret typing — EDIT-036

Run pnpm --filter @barocss/math-editor test:editing --suite=typing.

Type x^2, x_2, 4ab/2, and a+b/2 without selecting a suggestion. Check the operand boundary, the active input slot, continued typing, Undo and Redo. Include both script orders, nested fractions, an existing parenthesized structure, and empty bases. Compare the actual edited expression with KaTeX. The fixture covers React block and DOM block/inline. Unit tests cover modifiers, literal text, composition guards and key repeat. This keyboard check does not certify native mobile keyboards or OS IME composition.

EDIT-036 also covers a_3^2 followed by +1, and a^2_3 followed by +1. The opposite script must stay anchored as the active script grows. Both script rows share the start edge, with horizontal attachment compared against KaTeX (36 total browser cases).

EDIT-037 — Replace an existing symbol at the caret

• Place the caret before and after ℝ in a+ℝ+b. Related number sets must appear first.
• Choose ℤ with Down and Enter. Only ℝ changes. The input keeps focus.
• Continue typing on the same side of the symbol. Undo typing, undo replacement, then redo replacement.
• Compare the updated LaTeX and KaTeX preview. Repeat with React, native DOM block and native DOM inline.
• Catalog unit coverage checks both sides of every non-ASCII symbol, related ordering, localized labels, whitespace boundaries and stale/selected targets.

Run node packages/math-editor/test/editing/run.mjs --suite=symbols with the demo server running.

EDIT-038 — Prioritize related letter symbols

• Type r or R: show ℝ, then ρ, before right arrows. Keep the typed letter until acceptance.
• Press Enter to choose ℝ; verify LaTeX, KaTeX preview, focus and Undo.
• Repeat in React, DOM block and DOM inline. Run the browser runner with --suite=ranking.
• Unit checks cover English/Korean, other number-set initials, explicit symbol names and arrow shortcuts.

EDIT-039 — Require a choice for passive symbol suggestions

• Open an existing ℝ. Press Enter without choosing: retain the symbol and use the field/host Enter policy.
• Press Down to select the first candidate, then Enter: replace the symbol without also committing the host.
• Move away and return, or dismiss with Escape: the old choice must not be reused. Alt+Down can explicitly reopen and select the first action.
• Check direct pointer acceptance, Undo, and existing typed-letter acceptance. Repeat in React, DOM block and DOM inline.
• Run the browser runner with --suite=choice, alongside --suite=symbols and --suite=ranking.

EDIT-040 — Direct fence typing

• Type (x)y, [x]y, {x}y, |x|y and ([x])y. Verify the inner content, outside continuation, focus, Undo/Redo and generated KaTeX preview.
• Start an empty fence with each ASCII opening key, press Backspace and continue typing. No empty wrapper remains.
• Open an imported half-open interval and close with its actual right delimiter.
• Unit coverage additionally checks norm/angle key events, caret-middle and nested-slot guards, mismatched closers, escaped input, modifiers, composition and repeat suppression.
• Run the editing runner with --suite=fences (33 browser cases). Unicode key-event support does not imply that paste or OS character pickers synthesize those key events.