# Pattern formatting

Regex Tools includes a deliberately narrow, local ECMAScript formatter. It
canonicalizes representations that can be changed without inventing a visual
layout:

- an unescaped literal `/` becomes `\/`, making the pattern safe to copy into
  an ECMAScript regex literal;
- raw NUL and control code units become fixed-width `\xNN` or their canonical
  short escape (`\t`, `\n`, `\v`, `\f`, `\r`);
- raw U+2028 and U+2029 line separators become `\u2028` and `\u2029`;
- legacy escaped raw controls are replaced as one parser-reported literal
  token, so the formatter does not introduce an extra backslash.

Existing explicit escape spellings, groups, alternatives, quantifiers, inline
flags and literal whitespace are otherwise preserved byte for byte. ECMAScript
regex whitespace is normally significant, so the tool does not insert
indentation, line breaks or comments and does not claim to be a structural
pretty-printer. The transform is idempotent.

## Eligibility

Formatting requires the exact current, accepted, non-recovered syntax snapshot
from the bundled `@eslint-community/regexpp` provider. Transformations are
derived from the provider's literal-token ranges rather than from a heuristic
text scan. A stale parse, malformed pattern, partial provider or any
non-ECMAScript profile is reported as unavailable and is never silently
rewritten.

## Mandatory validation before apply

The preview cannot be applied directly. Regex Tools first:

1. reparses source and candidate independently and checks capture numbering,
   names, repetition and parent-capture shape;
2. compiles and runs the source and candidate in separate actual ECMAScript
   engine workers against the current subject and replacement;
3. compares exact normalized match, capture and replacement output, including
   the engine identity;
4. reruns every enabled unit test whose flavour, version, pattern, flags and
   engine options exactly match the active source snapshot, and compares both
   semantic output and assertion outcome.

A compile rejection, one-sided timeout, crash, worker error, cancellation,
truncated result, engine-identity change, incomplete test suite or semantic
difference blocks application. Matching fixed timeouts are comparable only for
an exact unit-test pair; two timeouts on the current interactive snapshot are
inconclusive. If no unit test is applicable, the UI says so and still requires
the current subject/replacement gate.

Validation is bounded to 1,000 tests, the normal worker/input limits and a
60-second aggregate test wall budget. A test is not started unless its complete
configured timeout still fits that budget. The user must explicitly confirm
the exact validated candidate before the Apply button is enabled.

Passing these gates is strong, reproducible evidence for the current snapshot
and exact tests. It is not a mathematical proof of equivalence for every
possible subject.
