<SpecSection title="What this feature specifies" id="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.
</SpecSection>

<SpecSection title="Contract statement" id="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](/platform-spec/core-library/terminal-and-console/console-io-streams/).
</SpecSection>

<SpecSection title="Implementation anchors" id="implementation-anchors">
- `compiler/corelib/packages/console/src/Console/Controls/`
- Tests: `ControlsFrameTests.bd`, `ControlsPanelTests.bd`, `ControlsProgressBarTests.bd`, `ControlsLayoutTests.bd`
</SpecSection>

## Decisions
<!-- spec:generate:adr-index -->
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.
<!-- /spec:generate:adr-index -->
## Articles
<!-- spec:generate:article-index -->
- [Contracts and edge cases](./articles/contracts-and-edge-cases/)
- [Design model](./articles/design-model/)
- [Examples](./articles/examples/)
- [Flow and algorithm](./articles/flow-and-algorithm/)
- [Verification and traceability](./articles/verification-and-traceability/)
<!-- /spec:generate:article-index -->

## 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`.

## 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.

## Purpose

Document **contracts and edge cases** for the **Console Controls** feature: role-specific normative detail beyond the feature hub.

## Canonical references

- Feature hub: [Console Controls](/platform-spec/core-library/terminal-and-console/console-controls/)
- Sibling articles in this bundle (design model, contracts, flow, examples, verification)

## Detailed behavior

### Normative requirements

| ID | Requirement |
| --- | --- |
| **CTL-001** | `Frame.Render` **must** clamp child layout to `columns` × `rows` from `ConsoleSize`. |
| **CTL-002** | Progress ratio **must** be in `0..=1`; out-of-range **should** clamp. |
| **CTL-003** | Full-screen controls **should** emit `Erase.DisplayAll` before draw when ANSI enabled. |
| **CTL-004** | `LiveTick` **must not** block the scheduler indefinitely; one tick == one render pass. |

### Edge cases

- Terminal shrink: controls **should** truncate lines rather than panic.
- Zero-size terminal: render **may** produce empty buffer.
- Resize mid-frame: next tick or `ConsoleMessage::Resize` **should** trigger relayout ([Console terminal events](/platform-spec/core-library/terminal-and-console/console-terminal-events/)).

## Verification

See the verification and traceability article in this bundle and `compiler/corelib/beskid_corelib/tests/corelib_tests/src/console/`.

## Related topics

- Parent [feature hub](/platform-spec/core-library/terminal-and-console/console-controls/) and [Terminal and console area](/platform-spec/core-library/terminal-and-console/)

## Purpose

Document **design model** for the **Console Controls** feature: role-specific normative detail beyond the feature hub.

## Canonical references

- Feature hub: [Console Controls](/platform-spec/core-library/terminal-and-console/console-controls/)
- Sibling articles in this bundle (design model, contracts, flow, examples, verification)

## Detailed behavior

### Control graph

| Type | Role |
| --- | --- |
| `Panel` | Bordered region with title |
| `VerticalStack` / `HorizontalStack` | 1D child arrangement |
| `ProgressBar` | Ratio fill inside width budget |
| `Frame` | Root container tying size + children |
| `LiveTick` | Schedules periodic `Render` invocations |

`RenderContext` carries current column/row cursor, available `ConsoleSize`, and whether ANSI motion is allowed.

### Rendering model

Layout is **greedy character grid**: children receive max width/height from parent minus borders/padding. Output is a single string buffer flushed with cursor save/restore per frame (see [ANSI escape model](/platform-spec/core-library/terminal-and-console/ansi-escape-model/design-model/) DEC sequences).

## Verification

See the verification and traceability article in this bundle and `compiler/corelib/beskid_corelib/tests/corelib_tests/src/console/`.

## Related topics

- Parent [feature hub](/platform-spec/core-library/terminal-and-console/console-controls/) and [Terminal and console area](/platform-spec/core-library/terminal-and-console/)

## Purpose

Document **examples** for the **Console Controls** feature: role-specific normative detail beyond the feature hub.

## Canonical references

- Feature hub: [Console Controls](/platform-spec/core-library/terminal-and-console/console-controls/)
- Sibling articles in this bundle (design model, contracts, flow, examples, verification)

## Detailed behavior

```beskid
ConsoleSize size = Console.QuerySize();
// build Frame + Panel + ProgressBar per Controls API
// frame.Render() → string written with Core.Output.Write
```

Pair with `Console.RunTick` and a `Channel<ConsoleMessage>` for resize-aware dashboards—see [Console terminal events / examples](/platform-spec/core-library/terminal-and-console/console-terminal-events/examples/).

## Verification

See the verification and traceability article in this bundle and `compiler/corelib/beskid_corelib/tests/corelib_tests/src/console/`.

## Related topics

- Parent [feature hub](/platform-spec/core-library/terminal-and-console/console-controls/) and [Terminal and console area](/platform-spec/core-library/terminal-and-console/)

## Purpose

Document **flow and algorithm** for the **Console Controls** feature: role-specific normative detail beyond the feature hub.

## Canonical references

- Feature hub: [Console Controls](/platform-spec/core-library/terminal-and-console/console-controls/)
- Sibling articles in this bundle (design model, contracts, flow, examples, verification)

## Detailed behavior

### Single frame

1. `save ← EmitDec("7")`
2. Optional `Erase.DisplayAll` when clearing screen
3. Walk control tree → append styled/plain segments to buffer
4. `restore ← EmitDec("8")`
5. `Core.Output.Write(buffer)`

### Live tick loop (sketch)

1. Create `Channel<ConsoleMessage>` via `Console.MessagesChannel()`
2. Fiber loop: `Console.RunTick(channel, lastSize)` → may enqueue `Resize`
3. On message: if `Resize`, invalidate layout; call `Frame.Render`
4. Yield or sleep between ticks (host policy)

Cursor/erase sequences: [ANSI escape model](/platform-spec/core-library/terminal-and-console/ansi-escape-model/flow-and-algorithm/).

## Verification

See the verification and traceability article in this bundle and `compiler/corelib/beskid_corelib/tests/corelib_tests/src/console/`.

## Related topics

- Parent [feature hub](/platform-spec/core-library/terminal-and-console/console-controls/) and [Terminal and console area](/platform-spec/core-library/terminal-and-console/)

## Purpose

Document **verification and traceability** for the **Console Controls** feature: role-specific normative detail beyond the feature hub.

## Canonical references

- Feature hub: [Console Controls](/platform-spec/core-library/terminal-and-console/console-controls/)
- Sibling articles in this bundle (design model, contracts, flow, examples, verification)

## Detailed behavior

| Test | Coverage |
| --- | --- |
| `ControlsFrameTests.bd` | Frame save/restore wrapping |
| `ControlsPanelTests.bd` | Panel borders |
| `ControlsProgressBarTests.bd` | Ratio rendering |
| `ControlsLayoutTests.bd` | Stack measurement |

Sources under `compiler/corelib/packages/console/src/Console/Controls/`.

## Verification

See the verification and traceability article in this bundle and `compiler/corelib/beskid_corelib/tests/corelib_tests/src/console/`.

## Related topics

- Parent [feature hub](/platform-spec/core-library/terminal-and-console/console-controls/) and [Terminal and console area](/platform-spec/core-library/terminal-and-console/)