@barocss/math-editor 0.4.0 → 0.5.0

package/RELEASING.md

@@ -1,31 +1,102 @@
 # Releasing math editor
 
-The source stays in this monorepo. Release only `@barocss/math-editor`; framework subpaths share its version. The initial release is **0.1.0**, public, on the **latest** npm tag.
+See [Editing scenarios](EDITING-SCENARIOS.md) for stable scenario IDs, acceptance criteria, coverage gaps and per-run reporting.
+
+
+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
+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.
 
 ## Local release
 
 ```sh
 # Repository root. Login is handled by npm, never by storing credentials in the repository.
-npm login
-pnpm release:math:prepare
-# After reviewing changes and browser validation:
+npm login --registry=https://registry.npmjs.org/
+# After reviewing versions, changelogs and browser validation:
 pnpm release:math
 ```
 
-Both commands check formatting, types and unit tests, clean/build the package, create a temporary tarball and verify all package entry points. The publish command sends only that verified tarball to the public npm registry. It never runs recursive publishing. `pnpm release` is an alias for this math-only workflow. npm may request account authentication or 2FA during publishing.
+This one command runs release-tool tests, core formatting/type/unit checks,
+integration type/unit checks, builds and package validation. 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.
+`pnpm release` is an alias for this workflow.
+
+Only the inspected package contents enter a generated workspace under
+`output/math-batch-releases/release-*/`. Wrapper manifests use
+`publishConfig.directory` to point at those contents. They give pnpm an explicit
+core-first dependency order without adding dependencies to the published plugin
+manifests. Publish lifecycle scripts are disabled because validation and builds
+already ran. Git checks are disabled only for this generated workspace.
+
+pnpm checks npm and skips package versions that already exist. It packs the
+inspected contents again, so the final archive checksum can differ from the
+preparation archive. The batch is not an atomic registry transaction. npm may
+still request authentication for individual packages; one command does not
+guarantee one authentication prompt.
+
+For checks without publishing:
+
+```sh
+# Build and inspect all ten 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.
+pnpm release:math:dry-run
+```
+
+`release.json` records the candidate versions, artifact hashes and command status.
+On success, `pnpm-publish-summary.json` lists newly published packages; versions
+skipped by pnpm are absent. A dry-run summary is not evidence of publication.
+If publishing fails, preserve the report and check each candidate version on npm.
+pnpm 8 may not write its summary after a partial failure. Resolve any uncertain
+results before running the batch again; never use `--force` to retry.
 
 Before releasing UI changes, also run `pnpm --filter @barocss/math-demo test:e2e` and the demo build. Verify the intended package name/version and changelog. A version already published to npm must never be reused. The repository's release workflow is manual validation only; it does not publish on main pushes.
 
 ## Subsequent versions
 
-1. Run `pnpm changeset`, select only `@barocss/math-editor`, and write a user-facing change summary.
+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`. It runs Changesets in a temporary math-only workspace and copies back only this package manifest/changelog, preventing dependent product version bumps. The consumed changeset summary is retained in CHANGELOG.md.
+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.
 4. Review and commit the version/changelog and any dependency/lockfile changes with the implementation. Run release validation, then publish locally.
-5. Record a package-specific Git tag such as `math-editor-v0.1.1` on the release commit, and update the site with the matching package version.
+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.
+
+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.
 
-The first 0.1.0 changelog is seeded explicitly; do not add a version-bump changeset just to publish the initial version. Avoid `pnpm version-packages` for a math-only release because that command processes the entire workspace plan.
+The [host release guide](../math-editor-integrations/docs/RELEASING.md) lists the
+nine plugins and explains changes to shared implementation. For an explicit
+core-only release, use `pnpm version:math:core`,
+`pnpm release:math:core:prepare` and `pnpm release:math:core`.
 
 ## Website
 
-`apps/math-demo` remains the site source. The intended static deployment repository is `barocss/math-editor-site`, with GitHub Pages at `math-editor.barocss.com`. Website deployment is separate from npm publication; page-only changes do not require a package version bump. Keep the displayed version and built editor version in sync. Successful npm publication alone does not mean the site or DNS has been configured.
+`apps/math-demo` remains the site source. The static deployment repository is
+`barocss/math-editor-site`, with GitHub Pages at `math-editor.barocss.com`.
+Build the site directly from workspace source:
+
+```sh
+pnpm build:math:site
+```
+
+This builds the main site and the nine-plugin integration sample without a core
+tarball, package `dist` build, npm login, registry lookup or publication check.
+Workspace package exports resolve local source, including the private common
+module. No package version bump is required to rebuild or deploy the site.
+`release.json` records `source: "workspace-source"` and the local package versions
+as metadata; those versions do not claim that the packages are published.
+
+For an explicit package-artifact check, the previous command remains available:
+
+```sh
+pnpm release:math:site /path/to/barocss-math-editor.tgz
+```
+
+Both commands print the prepared static site directory and do not deploy it.
+Website deployment and npm publication are independent operations.

package/RENDERING-TESTS.md

@@ -0,0 +1,79 @@
+# Rendering regression checks
+
+Compare the editor with KaTeX using the same exported LaTeX, base font size and
+display mode. Keep [editing scenarios](EDITING-SCENARIOS.md) for input behavior;
+this guide defines the visual checks for EDIT-017. KaTeX is the reference image,
+not an editable DOM replacement.
+
+## Three checks for each fixture
+
+1. **Model/output:** the editable tree exports the intended LaTeX and KaTeX accepts it.
+2. **Geometry:** compare relative positions, font sizes and gaps. Absolute page
+   coordinates are not comparable across different containers.
+3. **Visual review:** save the editor, active-input and KaTeX images together.
+   Check curves, stroke thickness, baselines and clipping. Numerical checks alone
+   do not establish that the two images look equivalent.
+
+The active input, measuring element and passive glyph must use the same font
+metrics. A cursor or hover background must not move a fraction or hide a fence.
+Wait for `document.fonts.ready`. Disable preview fit scaling for comparison and
+set the KaTeX root's computed font size to the editor's base size; matching the
+parent container's font size is not sufficient.
+
+## Initial executable fixtures
+
+Run `apps/math-integrations/tests/rendering-regression-check.js` through the
+existing Playwright CLI browser workflow with the local site on port 5184.
+The file is an async `(page) => ...` fixture, not a standalone Node script.
+Omit its final semicolon when passing the function to `run-code`.
+
+| Fixture | LaTeX | Renderers / sizes |
+| --- | --- | --- |
+| `indexed-root-power` | `\left(\sqrt[20]{ab}\right)^{\frac{2}{3}}` | Rich React and native DOM; 22px and 36px |
+| `fraction-power` | `x^{\frac{2}{3}}` | Rich React and native DOM; 22px and 36px |
+| `fraction-subscript` | `x_{\frac{2}{3}}` | Rich React and native DOM; 22px and 36px |
+
+The 12 combinations currently assert:
+
+- Fraction terms use half of the base font size and match KaTeX's computed term
+  size within 0.1px. This applies to these implicit-style fixtures, not every
+  explicit `\dfrac` or `\tfrac` expression.
+- The exponent is above the base and the subscript is below it.
+- The fraction center's vertical offset from the base glyph center differs from
+  KaTeX by less than 0.25em. This is a regression threshold, not pixel equality.
+- The gap from the base box to its fraction script is between 0 and 0.25em.
+- Activating a numerator retains its font size, and typing retains focus.
+- The formula does not produce a KaTeX error.
+
+Screenshots are saved as
+`output/playwright/{renderer}-{fixture}-{size}-{editor|katex|active}.png`.
+The returned metrics include editor and reference coordinates. Preserve them
+with the source fingerprint, browser version and screenshot pairs for a run.
+These filenames are overwritten on rerun; archive them if they are used as a
+release baseline. Do not update an accepted baseline simply to hide a failure.
+
+## Why the first correction is bounded
+
+Script fractions previously retained body-sized minimum row heights and spacing.
+They now have compact terms and rows. A simple base uses a small script offset;
+a tall structured base uses an offset proportional to the fraction height.
+Empty boundary nodes reserve only a narrow passive cursor position.
+
+This fixes the initial cases without changing the JSON model. It is not a
+complete TeX layout engine. Remaining comparison fixtures should cover paired
+scripts, nested fractions in both slots, explicit style overrides, multi-line
+collision, large operators, fences, accents and narrow host containers.
+
+As those fixtures grow, consolidate script levels, the math axis, baseline and
+stroke metrics into shared layout rules. Avoid extending a list of formula-
+specific CSS exceptions without a failing fixture and reference measurement.
+Both renderers must use the same rule, and every new notation feature needs
+an editor/KaTeX comparison in passive and active states.
+
+## Release use
+
+Run changed fixtures during development. Run the rendering set and applicable
+editing scenarios against release candidate artifacts before publishing. The
+current fixture uses workspace sources and Chromium; it does not certify packed
+packages, all host containers, Firefox/WebKit or OS IME behavior. CI scheduling
+and automatic screenshot-diff approval are not implemented by this guide.

package/ROADMAP.md

@@ -4,6 +4,78 @@ This roadmap describes priorities, not release promises. The current package is
 
 
 
+## Current focus: continuous editing — workspace, 2026-09-10
+
+The rendering pass is now the maintenance baseline. Further contour refinement
+is deferred; keep existing checks when notation or layout changes.
+
+EDIT-019 now runs through keyboard input, range wrapping, radical conversion,
+matrix input, five-step Undo/Redo, empty-root deletion and restoration, then a
+second typing/history chain without resetting the editor. React standalone block
+plus Quill/Tiptap/ProseMirror/Lexical/TinyMCE/CKEditor/Slate in-place block/inline and
+Editor.js/Gutenberg block pass (17 targets, 499 checkpoints). Host checks verify unchanged draft data,
+Save, reload/Restore, re-edit and Cancel. One-step host Undo/Redo passes where
+configured; the Editor.js demo has no host history integration. Inline also
+checks Enter commit without new paragraphs, right-boundary exit and prose
+continuation at the correct host position.
+
+Run `pnpm --filter @barocss/math-editor test:editing`. Timestamped reports include
+checkpoints, browser scope, fixture copy and source fingerprints. The Tiptap sample now separates document Restore from subsequent typing in host history;
+TinyMCE now keeps empty formulas visible with a localized placeholder. Its
+block/inline checks use an inline TinyMCE host; classic iframe mode is separate.
+All nine integration demos now pass this chain. Gutenberg uses the standalone
+provider demo; WordPress admin and other host configurations remain separate.
+Next: range clipboard and populated/grid deletion sequences. Real OS IME
+and clipboard remain deferred; this is not a release-wide certification.
+
+
+## Named-function and fraction spacing — workspace, 2026-09-10
+
+Named functions and fractions now share horizontal spacing with adjacent text.
+Repeated functions, parentheses after functions, products of functions and
+repeated fractions have paired editor/KaTeX comparisons. Named-function thin
+spacing remains in first and nested exponents. Fixed function glyph padding and
+fraction outer margins no longer accumulate across these expressions.
+
+Next: the remaining wrapper atom classes, longer mixed expressions, explicit
+spacing commands, and full painted-bound comparisons. Passing selected anchors
+does not imply whole-expression pixel equality.
+
+
+## Contextual operator layout — workspace, 2026-09-10
+
+The shared model-to-presentation pass now distinguishes display, text, script and
+scriptscript operator contexts. React and DOM use it for small glyphs, nested
+bound sizes and automatic side limits. Explicit limits remain supported.
+
+New comparisons cover numerator/denominator operators, one/two levels of
+superscripts, an operator inside another bound, inline/text fractions and an
+explicit stacked inline integral. Full ink alignment, all multi-operator mixtures
+and narrow-host/cross-browser checks remain separate work.
+
+## Radical and parenthesis outlines — workspace, 2026-09-10
+
+Root strokes and short/tall parenthesis contours now use KaTeX-derived SVG masks.
+Tall parentheses retain bounded end caps and extend the straight middle. The
+package includes these assets with their provenance and existing KaTeX MIT notice.
+This removes the old radical polygon without adding a KaTeX runtime dependency.
+
+Full KaTeX size-variant selection, vertical brace silhouettes, operators inside
+scripts and cross-browser geometry remain separate work. The renderer continues
+to reserve its existing editing boxes and caret hit areas.
+
+## LaTeX compatibility and nested-root layout — workspace, 2026-09-10
+
+- Fixed math-mode literal caret/tilde export while retaining text-run JSON semantics.
+- Protected complex optional root indices during export; all 55 structure kinds
+  now have KaTeX render and JSON round-trip regression checks in that slot.
+- Added clearance between nested radical rules and a browser gap measurement.
+- Still open: radical hook outlines, fence ink geometry, operators inside scripts,
+  explicit style combinations, broader interaction sequences and other browsers.
+
+These are workspace changes. Browser evidence remains in the source-only rendering
+ledger; a metric PASS does not mean complete visual parity or release certification.
+
 ## Editing utilities — workspace, 2026-09-09
 
 Included in 0.4.0:
@@ -27,11 +99,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 +349,58 @@ 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.