ANSI escape model

Platform spec feature

ANSI escape model

Back to Terminal and console ◎ Open 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

• Area
  Terminal and console

  Parent area

• Feature
  Console capabilities

  Gates emission via ShouldEmitAnsi

• Feature
  Console I/O streams

  Bytes written after escape composition

What this feature specifies

Normative terminal escape framing for corelib_console: how Ansi.Escape, Ansi.Cursor, Ansi.Erase, Ansi.Sgr, Ansi.Screen, and Ansi.Osc compose bytes that terminals interpret. Tables in the design model article match repository ANSI.md; this hub states package boundaries and emission rules shared with Console capabilities.

Contract statement

• ESC is ASCII U+001B (decimal 27). Implementations must use a single-byte ESC; language-specific \e escapes are informative only.
• CSI sequences must use the form ESC [ + parameter bytes + final byte (semicolon-separated numeric parameters; optional spaces may appear between parameters and are ignored when parsing).
• Private CSI modes use ? before parameters and final byte h (set) or l (reset).
• DEC single-character sequences (ESC 7 / ESC 8 save/restore cursor) are the preferred save/restore form; SCO ESC[s / ESC[u are not required in v1.
• User-visible emission must pass through Ansi.Escape.WhenEnabled (or builders that call it) so non-TTY and NO_COLOR hosts receive empty styled output, not raw escapes.
• Sequences marked de-facto in ANSI.md but not implemented in corelib may be emitted only via raw Csi/OscSequence helpers; they are not conformance-tested until listed in contracts and edge cases.

Implementation anchors

• compiler/corelib/packages/console/src/Ansi/
• Informative aggregate reference: repository root ANSI.md
• Golden tests: compiler/corelib/beskid_corelib/tests/corelib_tests/src/console/AnsiEscapeTests.bd, AnsiSgrGoldenTests.bd

Decisions

No open decisions. Closed choices are normative ADRs under adr/ (D-CORE-TERM-0001 … D-CORE-TERM-0004); use the reader ADRs tab for expandable detail.

Articles

• DEC save/restore cursor pairNormative cursor save/restore uses DEC sequences, not SCO.
• Contracts and edge casesMUST/SHOULD rules for escape emission and supported sequence subsets.
• Design modelESC/CSI/OSC taxonomy and normative control-character tables for terminal output.
• ExamplesRepresentative escape composition and gated emission patterns.
• Flow and algorithmHow escape bytes are composed, gated, and written to stdout.
• Verification and traceabilityGolden tests and source anchors for ANSI escape framing.