| 1 | <!-- English translation of adr/0057-chat-surface-pipeline-adoption.md. Canonical Russian: ../../adr/0057-chat-surface-pipeline-adoption.md --> |
| 2 | |
| 3 | # ADR 0057: Chat surface adoption of Skia composition pipeline |
| 4 | |
| 5 | **Status:** Accepted · Implemented |
| 6 | **Date:** 2026-04-17 |
| 7 | |
| 8 | ## Related ADRs |
| 9 | |
| 10 | | ADR | Role | |
| 11 | |-----|------| |
| 12 | | [0031](0031-agent-chat-clarification-batches-and-threading.md) | refinement packages, threading | |
| 13 | | [0044](0044-avalonia-host-skia-agent-chat-surface.md) | early hypothesis host/render split | |
| 14 | | [0055](0055-skia-instrument-composition-pipeline.md) | shared pipeline | |
| 15 | | [0056](0056-semantic-map-pipeline-adoption.md) | first implemented consumer | |
| 16 | | [0072](0072-chat-topic-cards-intent-melody-keyboard-contract.md) | overview/detail layout and keyboard-first intent for themes over pipeline | |
| 17 | |
| 18 | --- |
| 19 | ## Context |
| 20 | |
| 21 | After implementing the pipeline in Semantic Map ([0056](0056-semantic-map-pipeline-adoption.md)), the next planned consumer is the chat surface: |
| 22 | |
| 23 | - threads, |
| 24 | - confirmations, |
| 25 | - prioritization and declutter in high-density event mode. |
| 26 | |
| 27 | The chat in `MfdShellView` remains a product MFD surface, but the canonical surface is now built around the Skia pipeline snapshot, and not around the Avalonia list/tree. |
| 28 | The new Skia layer is not needed for “replacement for the sake of replacement”, but for scenarios where the linear tape does not provide sufficient situational readability and does not show the width of the branches. |
| 29 | |
| 30 | --- |
| 31 | |
| 32 | ## Solution |
| 33 | |
| 34 | <a id="adr0057-p1"></a> |
| 35 | |
| 36 | ### 1) Accept chat surface as the next pipeline-consumer |
| 37 | |
| 38 | The chat is being transferred to the same composition approach from [0055](0055-skia-instrument-composition-pipeline.md): |
| 39 | |
| 40 | 1. **Intent**: building a model of the current state of the dialogue (threads, pending confirmations, active branches). |
| 41 | 2. **Declutter**: message/acknowledgment prioritization and compression of noise elements. |
| 42 | 3. **Layout**: layout of conversation nodes and confirmation cards. |
| 43 | 4. **Render**: Skia-rendering of the scene. |
| 44 | |
| 45 | <a id="adr0057-p2"></a> |
| 46 | |
| 47 | ### 2) Fix single product path via Skia surface |
| 48 | |
| 49 | After the snapshot composer appears: |
| 50 | |
| 51 | - `ChatPanelView` remains a host container and an input form, but not an alternative feed; |
| 52 | - product rendering of the chat goes through a single Skia surface; |
| 53 | - legacy Avalonia list-path is not considered a mandatory fallback. |
| 54 | |
| 55 | Avalonia remains a shell/host layer, and not a parallel product implementation of the chat scene. |
| 56 | |
| 57 | <a id="adr0057-p3"></a> |
| 58 | |
| 59 | ### 3) Select chat intent units as first-class |
| 60 | |
| 61 | Minimum set of domain entities for v1: |
| 62 | |
| 63 | - `ThreadNode`, |
| 64 | - `MessageNode`, |
| 65 | - `ConfirmationNode`, |
| 66 | - `DecisionEdge` (`ask`, `confirm`, `resolve`, `supersede`). |
| 67 | |
| 68 | The layout layer should not evaluate these entities from the UI tree; it gets them from the Intent-stage. |
| 69 | |
| 70 | --- |
| 71 | |
| 72 | ## Consequences |
| 73 | |
| 74 | ### Pros |
| 75 | |
| 76 | - Chat becomes consistent with the general model of Skia tools (0055). |
| 77 | - Threads/confirmations get a clearly controlled composition rather than a "flat tape with crutches". |
| 78 | - Reuse pipeline practices already tested on Semantic Map. |
| 79 | |
| 80 | ### Cons |
| 81 | |
| 82 | - The complexity of the chat subsystem is increasing. |
| 83 | - It is necessary to keep strict snapshot/contract tests because the surface is no longer duplicated by the second UI path. |
| 84 | |
| 85 | --- |
| 86 | |
| 87 | ## Non-targets |
| 88 | |
| 89 | - Do not return the parallel Avalonia list-path as a "safety" baseline without a new ADR. |
| 90 | - Do not record the final visual language here (colors, typography, animations) - these are separate UX iterations. |
| 91 | - Do not change chat MCP contracts in this ADR without a separate contract fixation. |
| 92 | |
| 93 | --- |
| 94 | |
| 95 | ## Implementation plan (minimum) |
| 96 | |
| 97 | 1. Introduce the `ChatSurfaceCompositor` framework and stage contracts (`Intent/Declutter/Layout`) in the 0055 style. |
| 98 | 2. Raise the intent layer: `ThreadNode` / `MessageNode` / `ConfirmationNode` / `DecisionEdge` on top of the canonical dialogue history. |
| 99 | 3. Connect `ClarificationBatch` / `ClarificationResponse` to real chat flow and MCP entrypoints, without string collapse as the only truth. |
| 100 | 4. Add snapshot/contract composition tests and threading/clarification scripts. |