Console terminal events

Platform spec feature

Console terminal events

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

1. 0050-channel-vs-onresize-delivery Channel vs OnResize delivery Accepted

   Cross-fiber resize uses Channel; same-fiber uses OnResize hub.

   Context

   Resize notifications must integrate with fiber concurrency without OS-thread callbacks.

   Decision

   Rule	Detail
   Cross-fiber	PollResize → Channel<ConsoleMessage>
   Same-fiber	OnResize event hub

   Consequences

   No separate OS-thread callback API in v1.

   Verification anchors

   ConsoleMessageChannelTests.bd.

   Open full ADR page

2. 0051-columns-lines-env-fallback COLUMNS/LINES env fallback Accepted

   Env size parsing is best-effort discrete table in v1.

   Context

   Not all hosts expose Winsize ioctl; env vars are a portable fallback.

   Decision

   Rule	Detail
   Order	Winsize ioctl then COLUMNS/LINES
   Parse	Discrete table, not full integer grammar in v1

   Consequences

   Odd env values may clamp or ignore per contracts article.

   Verification anchors

   Platform/Terminal.bd tests.

   Open full ADR page

3. 0052-silent-resize-send-failure Silent resize Send failure Accepted

   Failed resize Channel Send is silent in v1 poll loops.

   Context

   UI loops should not crash when consumers drop resize messages.

   Decision

   Rule	Detail
   EVT-002	Failed Send on resize is silent in v1
   Future	May gain diagnostics in a later ADR

   Consequences

   Poll loops continue after dropped resize notifications.

   Verification anchors

   ConsoleMessageChannelTests.bd; EVT-002 traceability.

   Open full ADR page

Articles

• Contracts and edge cases Resize polling and delivery requirements. article Standard Reviewed Thu May 21
• Design model ConsoleMessage variants and resize notification surfaces. article Standard Reviewed Thu May 21
• Examples Subscribing to resize via channel or event hub. article Standard Reviewed Thu May 21
• Flow and algorithm PollResize and RunTick integration. article Standard Reviewed Thu May 21
• Verification and traceability Resize channel tests and platform extern anchors. 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
  Concurrency package

  Channel and fiber delivery

• Feature
  Console controls

  Relayout on Resize messages

What this feature specifies

How the corelib observes terminal size changes and notifies UI code: Platform.Terminal.QuerySize, PollResize → Channel<ConsoleMessage>, and same-fiber OnResize event hubs. No new runtime builtins—only existing environment, ioctl externs, and fiber/channel primitives.

Contract statement

• Console.ConsoleSize uses character cells (columns, rows as i32).
• QuerySize must try platform Winsize (Linux, macOS, Windows) then fall back to COLUMNS / LINES parsing.
• PollResize must Send ConsoleMessage::Resize(now) only when dimensions change.
• SubscribeOnResize must invoke the handler synchronously once with the current size after subscription.
• Resize delivery must not use a separate OS-thread callback API in v1.

Implementation anchors

• compiler/corelib/packages/console/src/Platform/Terminal.bd
• compiler/corelib/packages/console/src/Console.bd
• compiler/corelib/packages/console/src/Console/ConsoleMessage.bd
• Tests: ConsoleMessageChannelTests.bd

Decisions

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

Articles

• Channel vs OnResize deliveryCross-fiber resize uses Channel; same-fiber uses OnResize hub.
• Contracts and edge casesResize polling and delivery requirements.
• Design modelConsoleMessage variants and resize notification surfaces.
• ExamplesSubscribing to resize via channel or event hub.
• Flow and algorithmPollResize and RunTick integration.
• Verification and traceabilityResize channel tests and platform extern anchors.