Bidi Chat Direction

Direction and isolation decisions for RIGHT-TO-LEFT TEXT IN A STREAMING CHAT UI -- computed so a caller can commit to a rendering choice that is STILL CORRECT once the rest of the reply arrives, or be told plainly that it cannot yet know and should hold neutral. No DOM, no rendering, no markup parsing: you hand it text and facts, it hands back a verdict and why.

THE SILENT FAILURE. A chat UI renders tokens as they stream in, before the reply is complete. With right-to-left languages this goes wrong in ways that never throw, never fail a test that only checks the FINAL render, and are easy to dismiss as a rendering quirk -- because the finished message looks fine. The bug only exists in the seconds while it was still arriving, which is also the only time the user is watching.

DIRECTION FLIPS MID-STREAM. The Unicode Bidirectional Algorithm's own rule for picking a paragraph's default direction (UAX #9, rule P2) scans for the FIRST strong character of type L, AL or R. A reply that opens with a quoted English name and continues in Arabic therefore renders left-to-right until the first Arabic letter arrives, then jumps. Nothing is wrong with either render; they simply disagree.

SO IT IS ALLOWED TO HOLD NEUTRAL. The verdict distinguishes a direction that is DECIDED from one that is merely the best guess from the bytes so far, which is the distinction a streaming caller actually needs -- committing early is what produces the flip.

Cites UAX #9 by section and rule throughout, so a disagreement can be taken up with the specification rather than with this package.

VERIFIED: 174 tests, measured by running the suite.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function scanFirstStrong(text: string): FirstStrongScanResult;
  export function wrapWithIsolate(text: string, control: IsolateControl): string;
  export function decideMessageDirection(segments: readonly TextSegment[]): MessageDirectionDecision;
  export function decideParagraphDirection(text: string): ParagraphDirectionDecision;
  export function decideStreamingDirection(textSoFar: string): StreamingDirectionDecision;
  export function decideSegment(segment: TextSegment, context?: SegmentContext): SegmentDecision;
  export function decideSegments(segments: readonly TextSegment[], context?: SegmentContext): SegmentDecision[];
  export function isCuratedRtlLetter(codePoint: number): boolean;
  export function classifyStrong(codePoint: number): Direction | null;

  export type FirstStrongScanResult = FirstStrongScanFound | FirstStrongScanNotFound;
  export type Direction = 'ltr' | 'rtl';
  export type DirectionVerdict = Direction | 'undetermined';
  export type IsolateControl = 'none' | 'LRI' | 'RLI' | 'FSI';
  export type NoStrongReason = 'no-strong-seen' | 'open-isolate-at-end';
  export type SegmentKind = 'prose' | 'code' | 'neutral';