Flow and algorithm

Platform spec article

Flow and algorithm

Back to ANSI escape model ◎ Open feature in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (4)

1. 0001-dec-save-restore-cursor DEC save/restore cursor pair Accepted

   Normative cursor save/restore uses DEC sequences, not SCO.

   Context

   Authors need portable cursor stacking without SCO-specific CSI variants in typed builders.

   Decision

   Rule	Detail
   Save/restore	DEC ESC 7 / ESC 8 is the normative pair
   SCO	CSI s / CSI u are not required in v1 typed builders

   Consequences

   Typed Ansi.Cursor helpers emit DEC only; raw Csi may still be used in tests.

   Verification anchors

   AnsiEscapeTests.bd; ANSI.md tables.

   Open full ADR page

2. 0002-capability-gating-strips-ansi Capability gating strips ANSI Accepted

   Styled emission must respect ShouldEmitAnsi and non-TTY hosts.

   Context

   Programs must not leak escapes to pipes, log files, or NO_COLOR environments.

   Decision

   Rule	Detail
   Gating	User-visible styled output must pass Ansi.Escape.WhenEnabled
   Tests	Ungated Csi remains for golden tests

   Consequences

   When ShouldEmitAnsi() is false, gated builders return empty strings.

   Verification anchors

   AnsiEscapeTests.bd; console capability integration.

   Open full ADR page

3. 0003-sgr-color-downgrade-ladder SGR color downgrade ladder Accepted

   Truecolor sequences downgrade via EffectiveColorModel.

   Context

   Terminals differ in color depth; emitting unsupported 38;2 breaks dumb hosts.

   Decision

   Rule	Detail
   Ladder	truecolor → 256 → basic per EffectiveColorModel
   Policy	Callers do not pick per-sequence models manually

   Consequences

   SGR builders consult capability probes before emitting RGB CSI.

   Verification anchors

   AnsiSgrGoldenTests.bd; CapabilitiesTests.bd.

   Open full ADR page

4. 0004-osc-bel-termination-v1 OSC BEL termination in v1 Accepted

   OSC payloads terminate with BEL, not ST.

   Context

   OSC framing varies across terminals; v1 picks one terminator for golden tests.

   Decision

   Rule	Detail
   Terminator	BEL (0x07) in v1
   ST	ESC termination is not required

   Consequences

   OSC helpers emit BEL-terminated sequences only until a future ADR extends ST.

   Verification anchors

   AnsiEscapeTests.bd; Ansi.Osc sources.

   Open full ADR page

Articles

• Contracts and edge cases MUST/SHOULD rules for escape emission and supported sequence subsets. article Standard Reviewed Thu May 21
• Design model ESC/CSI/OSC taxonomy and normative control-character tables for terminal output. article Standard Reviewed Thu May 21
• Examples Representative escape composition and gated emission patterns. article Standard Reviewed Thu May 21
• Flow and algorithm How escape bytes are composed, gated, and written to stdout. article Standard Reviewed Thu May 21
• Verification and traceability Golden tests and source anchors for ANSI escape framing. article Standard Reviewed Thu May 21

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKfeature · 3 SpecSection(s) · 1 H2 heading(s)

Section id	Required	Found
what-this-feature-specifies	yes	yes
implementation-anchors	yes	yes

Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).

Related spec docs

• Feature
  ANSI escape model

  Parent feature hub

• Feature
  Console I/O streams

  Write path to stdout

Purpose

Describe how escape bytes are composed, gated by capabilities, and written to stdout.

Canonical references

• Tables: design model
• Requirements: contracts and edge cases
• Write path: Console I/O streams / flow and algorithm

Detailed behavior

Emission pipeline

flowchart LR
  markup[Console.Format or Ansi builders]
  gate[Ansi.Escape.WhenEnabled]
  bytes[UTF-8 string]
  out[System.Output.Write / WriteLine]
  markup --> gate --> bytes --> out

1. Compose — Fluent builders (Cursor, Erase, Sgr) accumulate parameter strings; JoinArgs inserts ; between SGR parameters without trailing separators.
2. Frame — Csi / PrivateMode / DecSaveCursor / OscSequence produce raw escape strings (ungated).
3. Gate — WhenEnabled returns "" or the sequence based on ShouldEmitAnsi() (stdout TTY + color policy).
4. Deliver — Higher layers (Console.FormatLine, controls renderers) pass the final string to Console I/O streams helpers.

SGR color downgrade algorithm

When SgrBuilder.FgRgb / BgRgb runs:

1. Capabilities.ProbeStdout() reads TTY and environment flags.
2. EffectiveColorModel selects TrueColor, Indexed256, or Basic16 (or forces basic when color is stripped).
3. Parameter bytes are chosen:
   • TrueColor → 38;2;r;g;b / 48;2;r;g;b
   • Indexed256 → 38;5;n / 48;5;n via RgbTo256Index
   • Basic → nearest 30–37 / 40–47 via RgbToBasicForeground / RgbToBasicBackground
4. IntoPrefix calls EmitCsi(openArgs, "m"); ApplyTo appends text and ResetSuffix (ESC[0m gated).

Builder concatenation

Ansi.Cursor.CursorBuilder appends fragments in call order, then IntoSequence applies a single gate at the end. Multiple CSI operations in one string are valid because terminals process them left-to-right.

Test-only ungated paths

Verification

CapabilitiesTests.bd asserts empty gated output when ANSI disabled; golden tests use ungated CsiSequence for framing only.

Related topics

• Examples
• Console controls — frame save/restore around render

Conformance tests call CsiSequence and PrivateMode directly to assert framing without depending on TTY state. Production markup must use EmitCsi or builders that call WhenEnabled.