feat(cli): implement missing output element types (tree, code, diff, text, separator, action_hint) #903

Closed
opened 2026-03-13 23:48:14 +00:00 by freemo · 2 comments
Owner

Metadata

  • Commit Message: feat(cli): implement missing output element types and handles
  • Branch: feature/m5-output-elements

Background and Context

The specification defines 10 output element types for the rendering framework. The current implementation has only 4: panel, table, status, and progress. Six element types are missing, along with their corresponding handle classes.

Missing element types (6): tree, code, diff, text, separator, action_hint

Missing handle classes (4): TreeHandle, TextHandle, CodeHandle, DiffHandle

Present element types (4): panel (PanelHandle), table (TableHandle), status (StatusHandle), progress (ProgressHandle)

The specification also defines a live materialization strategy (15fps in-place terminal updates) which is missing — the RichMaterializer currently delegates to _BaseBufferStrategy (sequential buffer) instead of implementing true live rendering. Only 2 of 3 materialization strategies exist (sequential_buffer, accumulate).

All 6 renderers exist (plain, color, table, rich, json, yaml).

Related: #884 covers the output envelope structure (field names), not the element type infrastructure.

Spec reference: Output Rendering Framework, ~lines 25629-28215

Acceptance Criteria

  • TreeHandle class exists with create/update/close lifecycle
  • TextHandle class exists with create/update/close lifecycle
  • CodeHandle class exists with create/update/close lifecycle
  • DiffHandle class exists with create/update/close lifecycle
  • All 10 element types can be created via OutputSession
  • Each element type produces correct snapshot data for JSON/YAML serialization
  • separator and action_hint element types work in all 6 renderers
  • live materialization strategy renders at ~15fps with in-place terminal updates
  • RichMaterializer uses the live strategy (not sequential buffer delegation)

Subtasks

  • Implement TreeHandle (tree data model, expand/collapse, recursive rendering)
  • Implement TextHandle (plain text blocks with optional styling)
  • Implement CodeHandle (syntax-highlighted code blocks with language tag)
  • Implement DiffHandle (unified diff rendering with +/- coloring)
  • Implement separator element type (horizontal rule/divider)
  • Implement action_hint element type (suggested next actions)
  • Register all new element types in OutputSession
  • Add snapshot data models for JSON/YAML serialization
  • Implement LiveMaterializationStrategy at ~15fps
  • Wire RichMaterializer to use live strategy
  • Update all 6 renderers to handle new element types
  • Tests (Behave): Each new element type renders in all 6 formats
  • Verify coverage >= 97% via nox -s coverage_report
  • Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

  • All subtasks above are completed and checked off.
  • A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
  • The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
  • The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
## Metadata - **Commit Message**: `feat(cli): implement missing output element types and handles` - **Branch**: `feature/m5-output-elements` ## Background and Context The specification defines 10 output element types for the rendering framework. The current implementation has only 4: `panel`, `table`, `status`, and `progress`. Six element types are missing, along with their corresponding handle classes. **Missing element types (6):** `tree`, `code`, `diff`, `text`, `separator`, `action_hint` **Missing handle classes (4):** `TreeHandle`, `TextHandle`, `CodeHandle`, `DiffHandle` **Present element types (4):** `panel` (PanelHandle), `table` (TableHandle), `status` (StatusHandle), `progress` (ProgressHandle) The specification also defines a `live` materialization strategy (15fps in-place terminal updates) which is missing — the `RichMaterializer` currently delegates to `_BaseBufferStrategy` (sequential buffer) instead of implementing true live rendering. Only 2 of 3 materialization strategies exist (sequential_buffer, accumulate). All 6 renderers exist (plain, color, table, rich, json, yaml). **Related**: #884 covers the output envelope structure (field names), not the element type infrastructure. **Spec reference**: Output Rendering Framework, ~lines 25629-28215 ## Acceptance Criteria - [ ] `TreeHandle` class exists with create/update/close lifecycle - [ ] `TextHandle` class exists with create/update/close lifecycle - [ ] `CodeHandle` class exists with create/update/close lifecycle - [ ] `DiffHandle` class exists with create/update/close lifecycle - [ ] All 10 element types can be created via `OutputSession` - [ ] Each element type produces correct snapshot data for JSON/YAML serialization - [ ] `separator` and `action_hint` element types work in all 6 renderers - [ ] `live` materialization strategy renders at ~15fps with in-place terminal updates - [ ] `RichMaterializer` uses the live strategy (not sequential buffer delegation) ## Subtasks - [ ] Implement `TreeHandle` (tree data model, expand/collapse, recursive rendering) - [ ] Implement `TextHandle` (plain text blocks with optional styling) - [ ] Implement `CodeHandle` (syntax-highlighted code blocks with language tag) - [ ] Implement `DiffHandle` (unified diff rendering with +/- coloring) - [ ] Implement `separator` element type (horizontal rule/divider) - [ ] Implement `action_hint` element type (suggested next actions) - [ ] Register all new element types in `OutputSession` - [ ] Add snapshot data models for JSON/YAML serialization - [ ] Implement `LiveMaterializationStrategy` at ~15fps - [ ] Wire `RichMaterializer` to use live strategy - [ ] Update all 6 renderers to handle new element types - [ ] Tests (Behave): Each new element type renders in all 6 formats - [ ] Verify coverage >= 97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done.
freemo added this to the v3.5.0 milestone 2026-03-13 23:48:40 +00:00
Author
Owner

Dependencies / Related Issues:

  • Related: #884 (output envelope structure — covers field name alignment but not element types/handles)
  • This issue covers the element type infrastructure and live materialization; #884 covers the envelope fields.
**Dependencies / Related Issues:** - Related: #884 (output envelope structure — covers field name alignment but not element types/handles) - This issue covers the element type infrastructure and live materialization; #884 covers the envelope fields.
freemo self-assigned this 2026-03-29 02:30:30 +00:00
Author
Owner

PR #1191 implements the LiveMaterializationStrategy and wires it to RichMaterializer, completing all acceptance criteria for this issue.

What was implemented:

  • LiveMaterializationStrategy — the third materialization strategy type (spec §26456-26492) with ~15 fps frame-rate throttling, dirty-element tracking, and per-frame composition in declaration order
  • RichMaterializer now extends LiveMaterializationStrategy with supports_incremental_updates=True
  • 5 new Behave scenarios covering the live strategy behavior
  • Public export of LiveMaterializationStrategy
  • Updated SD-2 and SD-7 documentation

Note: All 10 element types (panel, table, status, progress, tree, text, code, diff, separator, action_hint), all handle classes, all renderers, and all session factory methods were already fully implemented in prior work. This PR adds the missing live materialization strategy that was the last gap identified in the issue.

PR #1191 implements the `LiveMaterializationStrategy` and wires it to `RichMaterializer`, completing all acceptance criteria for this issue. **What was implemented:** - `LiveMaterializationStrategy` — the third materialization strategy type (spec §26456-26492) with ~15 fps frame-rate throttling, dirty-element tracking, and per-frame composition in declaration order - `RichMaterializer` now extends `LiveMaterializationStrategy` with `supports_incremental_updates=True` - 5 new Behave scenarios covering the live strategy behavior - Public export of `LiveMaterializationStrategy` - Updated SD-2 and SD-7 documentation **Note:** All 10 element types (panel, table, status, progress, tree, text, code, diff, separator, action_hint), all handle classes, all renderers, and all session factory methods were already fully implemented in prior work. This PR adds the missing live materialization strategy that was the last gap identified in the issue.
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
cleveragents/cleveragents-core#903
No description provided.