Unicode Bidirectional Algorithm (UAX #9): Levels, Runs and Logical Text

Bidirectional text has one logical code-point sequence and an independently resolved visual order. UAX #9 defines a Unicode algorithm for organizing left-to-right and right-to-left text into resolved levels and display runs. A screenshot showing reversed visual positions does not mean the underlying string was reversed.

Separate logical storage order from display order

A paragraph containing Arabic, Latin letters, digits and punctuation is normally stored in logical reading order. Rendering engines resolve directionality so the visible glyphs follow the applicable bidirectional behavior. Editing APIs, search and serialization must preserve the original sequence unless an explicit transformation is intended.

Writing Arabic letters in reverse Unicode order to make a preview look correct is a data error. That approach breaks copy/paste, cursor navigation and downstream search. The correct solution is a suitable paragraph base direction and appropriate isolation of embedded runs.

Character directional classes are inputs

UAX #9 assigns bidirectional classes such as L, R, AL, EN, AN, NSM, neutral classes and formatting controls. A character's script alone is not a reliable shortcut for its bidi class: digits and punctuation have distinct resolution rules.

Strong characters help determine direction in their context; weak and neutral characters are resolved using surrounding runs and algorithmic rules. A naive renderer that merely reverses all right-to-left characters will mishandle Arabic digits, punctuation and nested Latin phrases.

Determine paragraph direction before resolving runs

A paragraph has a base embedding level determined by a higher-level protocol, an explicit direction or a first-strong-style default where appropriate. CSS and HTML provide higher-level mechanisms for choosing base direction; the underlying Unicode algorithm then resolves directional behavior.

The base level affects how neutral characters align and how mixed content wraps. As a result, the exact same scalar sequence can display differently when inserted into a left-to-right paragraph versus a right-to-left block without any change in stored data.

Embedding and override controls require care

Unicode has explicit directional formatting characters that affect embedding levels and overrides. Historically, controls such as U+202A LEFT-TO-RIGHT EMBEDDING and U+202E RIGHT-TO-LEFT OVERRIDE have been used to influence ordering. Unbalanced or unexpected overrides can create confusing or deceptive displays.

For newly generated isolated fragments, UAX #9 recommends isolate-based mechanisms in appropriate contexts. Do not insert RLO just to force alignment of a mixed-script username. In security-sensitive displays, make invisible formatting controls inspectable and enforce a documented identifier policy.

Isolates prevent context leakage

U+2066 LEFT-TO-RIGHT ISOLATE, U+2067 RIGHT-TO-LEFT ISOLATE and U+2068 FIRST STRONG ISOLATE establish isolate contexts, closed by U+2069 POP DIRECTIONAL ISOLATE. These let inserted text be treated as an independent directional unit for surrounding resolution.

In HTML, <bdi> or elements with appropriate direction and isolation can often express this intent more safely than inserting literal controls into stored text. The right choice depends on whether markup or plain text is being produced. Isolates affect display behavior but should not be stripped blindly from legitimate multilingual input.

Numbers and neutrals produce surprising punctuation

European digits embedded inside Arabic prose often remain readable left-to-right while the enclosing run flows right-to-left. Colons, parentheses, slash characters and spaces can take direction from context, producing results that appear to move punctuation unexpectedly.

A test fixture should contain identifiers, dates, currency strings, email addresses and punctuation next to both Latin and Arabic or Hebrew text. Check the full paragraph and its base direction rather than evaluating a punctuation character in isolation.

Line wrapping applies after bidi level resolution

Paragraph-level resolution and line-by-line visual reordering are related but distinct stages in UAX #9. Text engines commonly use resolved levels to reorder runs within each displayed line after line breaks are determined. Separate lines can exhibit different visual boundaries.

Do not reorder code points in storage according to one line layout; wrapping width, font metrics and device scale can change where lines break. A sequence that is correct at desktop width must remain logically intact when reflowed on a narrow screen.

Mirroring is not reversing strings

Some paired punctuation can have mirrored glyph presentation in right-to-left contexts. Unicode bidi mirroring properties and font/rendering behavior support this without changing the actual scalar values of the original parentheses or brackets.

A copied opening parenthesis should remain the same encoded character even if its visible shape appears mirrored. Inspect code points and embedding levels when diagnosing a problem rather than relying on screenshots of paired symbols.

Make the bidi process testable

Store fixtures with the exact scalar stream, paragraph base direction, isolate boundaries and expected display behavior. Verify logical copy output, native selection and cursor movement. Add visual tests for neutrals, nested numbers and wraps.

For deeper conformance, use Unicode's BidiTest.txt and BidiCharacterTest.txt data for the chosen Unicode version. Capture the Unicode version and layout implementation; correctness should be assessed against the relevant algorithm, not an aesthetic expectation derived from English text.

Reproducible example and limits of the measurement

The following specimen demonstrates the specific concept in a controlled source or browser context. It is not a substitute for fully exercising the target application with the appropriate language, platform input method and real user data. Distinguish textual transformations from display-only differences.

const content = 'مرحبا ABC 123';
console.log([...content].map(ch =>
  'U+'+ch.codePointAt(0).toString(16).toUpperCase()));
// Logical code-point order stays unchanged across LTR and RTL containers.
// Markup context can choose a base direction:
// <p dir="rtl">مرحبا <bdi>ABC 123</bdi></p>
// Do not reverse() the stored string to simulate UAX #9.

Write down what is supposed to remain stable: the encoded byte stream, the Unicode scalar sequence, the selected locale, the logical reading order or just the user-facing meaning. These are different test assertions and should never be replaced by a single screenshot comparison.

Interoperability evidence matrix

Environment-specific output should be classified separately from violations of a normative Unicode algorithm or protocol. When locale or font support differs, explain the fallback explicitly rather than claiming the source text became invalid.

Validation approach and common false positives

1. Paragraph base: Prepare the controlled fixture LTR vs RTL. Record its Unicode scalar sequence and the environment, including browser or application version, selected locale and data format. The expected interpretation is: may affect neutrals and visual run order. Compare observed output with this contract rather than only its visual appearance.
2. Strong character: Prepare the controlled fixture L, R, AL. Record its Unicode scalar sequence and the environment, including browser or application version, selected locale and data format. The expected interpretation is: influences surrounding resolution. Compare observed output with this contract rather than only its visual appearance.
3. Digits: Prepare the controlled fixture EN, AN. Record its Unicode scalar sequence and the environment, including browser or application version, selected locale and data format. The expected interpretation is: have context-sensitive weak-type resolution. Compare observed output with this contract rather than only its visual appearance.
4. Isolates: Prepare the controlled fixture LRI/RLI/FSI/PDI. Record its Unicode scalar sequence and the environment, including browser or application version, selected locale and data format. The expected interpretation is: contain directional influence. Compare observed output with this contract rather than only its visual appearance.
5. Mirroring: Prepare the controlled fixture paired punctuation. Record its Unicode scalar sequence and the environment, including browser or application version, selected locale and data format. The expected interpretation is: glyph appearance can change without scalar change. Compare observed output with this contract rather than only its visual appearance.

Build regression fixtures from actual user workflows as well as simple scalar vectors. Include logical text order, non-BMP symbols, mixed direction, combining sequences, and clipboard transitions as appropriate. Test both a positive path and an edge case that could falsify a simplified implementation.

Common misinterpretations

• Separate logical storage order from display order: If the output differs, isolate whether the source data, parsing rules, locale metadata, selection behavior or rendering layer caused it. Avoid changing input text until the defect has been reproduced at a specific boundary.
• Character directional classes are inputs: If the output differs, isolate whether the source data, parsing rules, locale metadata, selection behavior or rendering layer caused it. Avoid changing input text until the defect has been reproduced at a specific boundary.
• Determine paragraph direction before resolving runs: If the output differs, isolate whether the source data, parsing rules, locale metadata, selection behavior or rendering layer caused it. Avoid changing input text until the defect has been reproduced at a specific boundary.
• Embedding and override controls require care: If the output differs, isolate whether the source data, parsing rules, locale metadata, selection behavior or rendering layer caused it. Avoid changing input text until the defect has been reproduced at a specific boundary.
• Isolates prevent context leakage: If the output differs, isolate whether the source data, parsing rules, locale metadata, selection behavior or rendering layer caused it. Avoid changing input text until the defect has been reproduced at a specific boundary.

A consistent technical diagnosis names the responsible layer and preserves the original specimen for an independent rerun. Content identity, typography, locale formatting and application input policy are not interchangeable.

Primary standards and API documentation

Use the normative sources below to resolve terminology and algorithmic requirements. APIs and Unicode standards may evolve: record relevant versions and be careful not to generalize a single browser's optional behavior as a universal requirement.

• Unicode Bidirectional Algorithm UAX #9. Consult this standard or primary API reference for the relevant definitions, error cases, conformance details and implementation boundaries.
• Unicode Character Database UAX #44. Consult this standard or primary API reference for the relevant definitions, error cases, conformance details and implementation boundaries.
• W3C Arabic & Hebrew on Web. Consult this standard or primary API reference for the relevant definitions, error cases, conformance details and implementation boundaries.
• Unicode Security UTS #39. Consult this standard or primary API reference for the relevant definitions, error cases, conformance details and implementation boundaries.
• WHATWG HTML dir attribute. Consult this standard or primary API reference for the relevant definitions, error cases, conformance details and implementation boundaries.

Related published research

Part of the Multilingual Text & Input Systems virtual silo. These published references explain adjacent concepts without creating duplicate category URLs:

• invisible characters text editors
• text selection grapheme clusters
• cursor movement complex text