Contracts and edge cases

Platform spec article

Contracts and edge cases

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 capabilities

  Emission gating contract

Purpose

State MUST/SHOULD rules for escape framing, capability gating, and the v1 conformance-tested CSI subset.

Canonical references

• Feature hub: ANSI escape model
• Sequence tables: design model and repository ANSI.md
• Color downgrade: Console capabilities

Detailed behavior

Normative requirements

ID	Requirement
ANSI-001	Ansi.Escape.Esc() must return exactly one U+001B code unit.
ANSI-002	Csi(body, finalByte) must produce ESC[ + body + finalByte with no capability filtering (test and composition primitive).
ANSI-003	EmitCsi, EmitOsc, EmitDec, and builders whose IntoSequence calls WhenEnabled must return "" when Console.Capabilities.ShouldEmitAnsi() is false.
ANSI-004	PrivateMode(mode, enable) must encode ESC[?{mode}h or ESC[?{mode}l.
ANSI-005	DecSaveCursor / DecRestoreCursor must emit ESC 7 and ESC 8 respectively (single-byte suffix, no bracket).
ANSI-006	OscSequence(payload) must terminate with BEL (0x07).
ANSI-007	SgrBuilder RGB helpers must downgrade per EffectiveColorModel before calling EmitCsi (see Console capabilities).
ANSI-008	Golden tests listed in verification and traceability must match byte-for-byte output when emission is enabled.

Conformance-tested CSI final bytes (v1)

Final	Builder surface	Example
m	Ansi.Sgr, Ansi.StyleChain	ESC[1;31m
A–G, H, f	Ansi.Cursor	ESC[2J via Ansi.Erase uses J/K
J, K	Ansi.Erase	ESC[2J, ESC[2K
h, l	Ansi.Escape.PrivateMode, Ansi.Screen	ESC[?1049h

Sequences present in ANSI.md but without a corelib builder or golden test are informative until added to this table.

Edge cases

• Piped stdout: When stdout is not a TTY and FORCE_COLOR is unset, styled helpers must emit no escapes (ANSI-003); plain System.Output.Write still writes bytes.
• Partial terminal support: Terminals may ignore italic, blink, or truecolor; downgrade reduces garbled output but cannot guarantee visual fidelity.
• Multiplexers (tmux, screen): Alternate-buffer and private-mode sequences may behave differently; corelib does not special-case multiplexers in v1.
• Keyboard redefinition (ESC[{code};{string}p): Not implemented; documented in ANSI.md for historical completeness only.
• Erase without cursor move: After ESC[2K, callers should emit \r if the cursor must sit at column 1 (see design model).

Non-goals (v1)

Verification

Each ANSI-* row maps to AnsiEscapeTests.bd / AnsiSgrGoldenTests.bd or capability tests — verification and traceability.

Related topics

• Flow and algorithm

• Console markup format — must use builders, not raw ESC in markup

• DCS string handling

• Full xterm private-mode catalog

• Host-specific WIN32 console APIs beyond Platform.* extern stubs