"""Output rendering framework for CleverAgents CLI.

This package implements the Output Rendering Framework described in the
specification.  It decouples command output data from visual presentation
through a reactive session/handle/materialiser pipeline.

Spec Deviations
---------------
The following deliberate deviations from the specification (v3_spec.md
§Output Rendering Framework, lines 25417-27276) are documented here.
Each deviation was made for simplicity or because the feature is not
yet needed in the current milestone.

**SD-1 (ElementRenderer / RendererRegistry collapsed)**
  The spec defines separate ``ElementRenderer`` protocol and
  ``RendererRegistry`` class.  This implementation collapses rendering
  into the strategy classes directly, which is simpler and sufficient
  for the six built-in formats.

**SD-2 (RichMaterializer uses LiveMaterializationStrategy)**
  The ``rich`` strategy now uses ``LiveMaterializationStrategy`` for
  in-place terminal updates at ~15 fps (spec §26456).  It delegates
  element rendering to the colour renderer.  Full Rich library widget
  integration (Live, Table, Tree, etc.) is deferred to M8.

**SD-3 (No per-element priority filtering)**
  Element ``priority`` and ``collapse_hint`` fields are stored but not
  used for filtering or collapsing during rendering.  The values are
  preserved in JSON/YAML serialisation for future consumers.

**SD-4 (No real-time streaming in accumulate strategies)**
  The ``json`` and ``yaml`` strategies accumulate all output and
  serialise on session close.  They do not stream partial results.

**SD-5 (No OutputTheme / style customisation)**
  The spec mentions ``OutputTheme`` for user-customisable colours.
  This implementation uses hardcoded ANSI codes.

**SD-6 (No RendererConfig / column width negotiation)**
  Terminal width detection and column width negotiation are not
  implemented.  Plain and colour renderers use a fixed 80-column
  assumption for text wrapping.

**SD-7 (Simplified Rich format)**
  The ``rich`` format uses ``LiveMaterializationStrategy`` with the
  colour renderer instead of Rich library widgets (Live, Table, Tree,
  etc.).  In-place updates are supported; full widget integration is
  deferred to M8.

**SD-8 (No format_output_streaming)**
  The spec defines a streaming variant of format_output.  Only the
  batch ``format_output`` and ``format_output_session`` helpers exist.

**SD-9 (No element handle pooling)**
  The spec mentions handle pooling for high-throughput scenarios.
  Handles are created fresh each time.

**SD-10 (No incremental JSON/YAML)**
  JSON/YAML strategies set ``supports_incremental_updates = False``.
  Incremental update events are only used by future Rich strategy.

**SD-11 (Auto-close for Separator/ActionHint)**
  The spec does not specify auto-close semantics for immutable
  element types.  This implementation auto-closes Separator and
  ActionHint handles immediately after creation for convenience.

**SD-12 (MAX_ELEMENTS_PER_SESSION soft limit)**
  The spec does not define an element count limit.  A soft limit of
  10,000 is enforced as a DoS guard.

**SD-13 (JSON/YAML envelope structure — IMPLEMENTED)**
  The spec's envelope fields (``status``, ``data``, ``messages``,
  ``timing``) are now emitted.  Implemented per M4 fix (#884).

**SD-14 (NO_COLOR env var — IMPLEMENTED)**
  ``NO_COLOR`` (https://no-color.org/) is now respected: when set,
  all visual formats fall back to plain.  Implemented per P1-4.

**SD-15 (CLEVERAGENTS_FORMAT env var not checked)**
  The spec defines ``CLEVERAGENTS_FORMAT`` for overriding the default
  format.  This implementation only accepts ``--format`` CLI flag.

**SD-16 (TerminalCapabilities partial)**
  The spec defines 11 capability fields.  This implementation exposes
  4: ``is_tty``, ``supports_ansi``, ``supports_cursor``, ``term``.

**SD-17 (ElementEvent field differences)**
  ``ElementEvent.element_kind`` is used instead of spec's
  ``element_type``.  Timestamps use ``float`` (monotonic) instead of
  ``datetime``.  ``session_id`` is not included in events.

**SD-18 (SessionEnd missing snapshot field)**
  The spec's ``SessionEnd`` event includes a full session snapshot.
  This implementation only carries ``exit_code``.

**SD-19 (MaterializationStrategy.bind() absent)**
  The spec defines a ``bind()`` method for strategy configuration.
  This implementation configures strategies via constructor arguments.

**SD-20 (on_session_begin missing stream parameter)**
  The spec's ``on_session_begin`` accepts a ``stream: IO`` parameter.
  This implementation passes the ``OutputSession`` reference instead.

**SD-21 (ColumnDef.type renamed to col_type)**
  ``ColumnDef.type`` was renamed to ``col_type`` to avoid shadowing
  the Python builtin ``type()``.

**SD-22 (Sequential IDs instead of ULIDs)**
  Session and handle IDs use sequential counters (``ses-000001``,
  ``hdl-000002``) instead of the spec's ULID format.

**SD-23 (No OutputSession.open() classmethod)**
  The spec defines an ``OutputSession.open()`` class method.  This
  implementation uses ``OutputSession()`` constructor and context
  manager protocol.

**SD-24 (No "closing" session state)**
  The spec defines a ``closing`` intermediate state.  This
  implementation transitions directly from ``open`` to ``closed``.

**SD-25 (created_at is float, not datetime)**
  ``OutputSession.created_at`` uses ``time.time()`` (float epoch)
  instead of the spec's ``datetime`` type.

**SD-26 (TreeHandle.add_child parent_path: str not str|None)**
  The spec allows ``parent_path: str | None`` where ``None`` means
  the root.  This implementation uses empty string for the root.

**SD-27 (ActionHint.description: str="" not str|None)**
  ``ActionHint.description`` defaults to ``""`` instead of ``None``.

**SD-28 (CodeBlock.highlight_lines: list[int]=[] not list[int]|None)**
  ``CodeBlock.highlight_lines`` defaults to an empty list instead of
  ``None``.

**SD-29 (Table format fallback includes color tier)**
  The ``table`` format fallback chain is ``Table → Color → Plain``
  (matching the spec).  Previously documented incorrectly as skipping
  the color tier; corrected per P1-3 (Luis review).

Quick start::

    from cleveragents.cli.output import OutputSession

    with OutputSession(format="plain") as session:
        panel = session.panel("Project Details")
        panel.set_entry("Name", "local/api-service")
        panel.set_entry("Status", "active")
"""

from cleveragents.cli.output._renderers import strip_terminal_escapes
from cleveragents.cli.output.handles import (
    MAX_ELEMENTS_PER_SESSION,
    MAX_TABLE_ROWS,
    MAX_TREE_DEPTH,
    ActionHint,
    ActionHintHandle,
    CodeBlock,
    CodeHandle,
    ColumnDef,
    DiffBlock,
    DiffHandle,
    DiffHunk,
    DiffLine,
    ElementClosed,
    ElementClosedError,
    ElementCreated,
    ElementEvent,
    ElementHandle,
    ElementSnapshot,
    ElementUpdated,
    Panel,
    PanelEntry,
    PanelHandle,
    ProgressHandle,
    ProgressIndicator,
    ProgressStep,
    Separator,
    SeparatorHandle,
    SessionEnd,
    StatusHandle,
    StatusMessage,
    Table,
    TableHandle,
    TextBlock,
    TextHandle,
    Tree,
    TreeHandle,
    TreeNode,
)
from cleveragents.cli.output.materializers import (
    ColorMaterializer,
    JsonMaterializer,
    LiveMaterializationStrategy,
    MaterializationStrategy,
    PlainMaterializer,
    RichMaterializer,
    TableMaterializer,
    YamlMaterializer,
)
from cleveragents.cli.output.selection import (
    TerminalCapabilities,
    detect_terminal_capabilities,
    select_materializer,
)
from cleveragents.cli.output.session import OutputSession, StructuredOutput

__all__ = [
    "MAX_ELEMENTS_PER_SESSION",
    "MAX_TABLE_ROWS",
    "MAX_TREE_DEPTH",
    "ActionHint",
    "ActionHintHandle",
    "CodeBlock",
    "CodeHandle",
    "ColorMaterializer",
    "ColumnDef",
    "DiffBlock",
    "DiffHandle",
    "DiffHunk",
    "DiffLine",
    "ElementClosed",
    "ElementClosedError",
    "ElementCreated",
    "ElementEvent",
    "ElementHandle",
    "ElementSnapshot",
    "ElementUpdated",
    "JsonMaterializer",
    "LiveMaterializationStrategy",
    "MaterializationStrategy",
    "OutputSession",
    "Panel",
    "PanelEntry",
    "PanelHandle",
    "PlainMaterializer",
    "ProgressHandle",
    "ProgressIndicator",
    "ProgressStep",
    "RichMaterializer",
    "Separator",
    "SeparatorHandle",
    "SessionEnd",
    "StatusHandle",
    "StatusMessage",
    "StructuredOutput",
    "Table",
    "TableHandle",
    "TableMaterializer",
    "TerminalCapabilities",
    "TextBlock",
    "TextHandle",
    "Tree",
    "TreeHandle",
    "TreeNode",
    "YamlMaterializer",
    "detect_terminal_capabilities",
    "select_materializer",
    "strip_terminal_escapes",
]
