Console controls

Platform spec feature

Console controls

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 (2)

1. 0040-character-cell-layout Character-cell layout only Accepted

   Console controls operate on cell grid, not pixels.

   Context

   Terminal UI in corelib targets TTY character grids.

   Decision

   Rule	Detail
   Coordinates	Rows/columns in character cells
   Graphics	Pixel graphics are out of scope

   Consequences

   Layout helpers align with Console.ConsoleSize and resize events.

   Verification anchors

   Console control tests under packages/console.

   Open full ADR page

2. 0041-livetick-caller-owned-loop LiveTick caller-owned redraw loop Accepted

   Periodic redraw uses LiveTick; callers own fiber/channel loops.

   Context

   Corelib should not embed a full UI framework inside controls.

   Decision

   Rule	Detail
   Tick	LiveTick drives periodic redraw
   Loop	Callers compose fibers/channels around tick

   Consequences

   Interactive samples pair LiveTick with concurrency package channels.

   Verification anchors

   Console controls examples and tests.

   Open full ADR page

Articles

• Contracts and edge cases Layout and redraw requirements for console controls. article Standard Reviewed Thu May 21
• Design model Control tree, render context, and character-grid layout. article Standard Reviewed Thu May 21
• Examples Panel and progress bar render patterns. article Standard Reviewed Thu May 21
• Flow and algorithm Frame render and live tick loop. article Standard Reviewed Thu May 21
• Verification and traceability Control layout tests and module paths. 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 terminal events

  Resize triggers re-layout

What this feature specifies

Console.Controls provides character-cell layout primitives: Panel, VerticalStack / HorizontalStack, ProgressBar, Frame, and LiveTick integration. Rendering produces escape sequences for cursor save/restore, erase, and bounded redraw regions.

Contract statement

• Controls must query Console.QuerySize() (or injected size) before layout.
• Full-frame redraw should use DEC save/restore (ESC 7 / ESC 8) around the composed buffer.
• Render output must respect ShouldEmitAnsi(); plain mode emits text layout without motion sequences.
• Controls must not introduce new syscalls; writes go through Console I/O streams.

Implementation anchors

• compiler/corelib/packages/console/src/Console/Controls/
• Tests: ControlsFrameTests.bd, ControlsPanelTests.bd, ControlsProgressBarTests.bd, ControlsLayoutTests.bd

Decisions

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

Articles

• Character-cell layout onlyConsole controls operate on cell grid, not pixels.
• Contracts and edge casesLayout and redraw requirements for console controls.
• Design modelControl tree, render context, and character-grid layout.
• ExamplesPanel and progress bar render patterns.
• Flow and algorithmFrame render and live tick loop.
• Verification and traceabilityControl layout tests and module paths.