Files
kandev/docs/specs/ui/requirements/threads-conversation-deck.md
T

286 lines
16 KiB
Markdown

---
status: active
system: ui
created: 2026-08-28
owners:
- kandev
---
# Threads Conversation Deck Requirements
## Overview
Threads gives a user one horizontally scrollable view of current task
conversations, arranged in full-height columns or a two-row grid. A task can
have several agent sessions, and its tile can switch among those existing
sessions. Only an explicit pending action marks a
question or permission. The deck must show accurate attention states and stay
usable when a workspace has many active tasks.
The UI system owns the responsive interaction and presentation contract. The
platform owns the bounded status and session-stream delivery contract in
[Viewport-bounded Session Delivery](../../platform/requirements/viewport-bounded-session-delivery.md).
## Terminology
- **Task column / tile:** The stable Threads shell for one task. A grid tile
has the same identity and session-selection behavior as a full-height column.
- **Selected session:** The existing agent session whose conversation is shown
in a task column.
- **Attention action:** An explicit pending clarification or permission for a
session.
- **Detail-active column:** A task column that can mount its selected session's
full conversation under the platform delivery budget.
- **Auto-hide composer:** A presentation preference that collapses routine
reply controls until hover or keyboard interaction on pointer-based layouts.
## Requirements
### REQ-UI-THREADS-DECK-001: Existing session switching
**Intent:** Let a user follow every existing agent session in a task without
turning Threads into a session-management surface.
**User story:** As a user with several agents on one task, I want to switch the
conversation in its task column, so that I can follow each agent without
leaving Threads.
#### Acceptance criteria
- **AC-UI-THREADS-DECK-001.1:** When a desktop task column has more than one
session, the system shall show a switch-only session tab list on the right of
the same header row as the task status, workflow, and step metadata.
- **AC-UI-THREADS-DECK-001.2:** The Threads session control shall not create,
delete, rename, close, pin, reorder, or change the primary session, and it
shall not show an add button or a context menu.
- **AC-UI-THREADS-DECK-001.3:** When the user selects a session, only that task
column shall change its conversation. The selection shall not change another
task column or the full task page's active session.
- **AC-UI-THREADS-DECK-001.4:** When a valid session stays selected, another
session status change shall not change the selection.
- **AC-UI-THREADS-DECK-001.5:** When no valid user selection exists, the system
shall select, in order, a session requested by the URL, a session with an
explicit pending action, an active session, the primary session, or the
newest remaining session.
- **AC-UI-THREADS-DECK-001.6:** When the selected session is removed, the system
shall use the same deterministic fallback without changing the task column's
position.
- **AC-UI-THREADS-DECK-001.7:** When a task-detail link opens Threads for a
session that is still a member of the task, the URL shall identify both the
task and session, the deck shall reveal the task column, and that session
shall become selected.
- **AC-UI-THREADS-DECK-001.8:** Each selector item shall show the effective agent
profile name. If profile data is not available, it shall show the custom
session name or the existing fallback label.
- **AC-UI-THREADS-DECK-001.9:** A settled selector item shall show the agent
icon. A `STARTING` or `RUNNING` item shall replace that icon with the grid
spinner.
### REQ-UI-THREADS-DECK-002: Accurate attention state
**Intent:** Show when a person must act without presenting an ordinary
completed turn as an agent question.
#### Acceptance criteria
- **AC-UI-THREADS-DECK-002.1:** When the selected session has a pending
clarification, the task column shall show a question indicator and a
localized question label.
- **AC-UI-THREADS-DECK-002.2:** When the selected session has a pending
permission, the task column shall show a permission indicator and a localized
permission label.
- **AC-UI-THREADS-DECK-002.3:** When a session is `WAITING_FOR_INPUT` without an
explicit pending action, the system shall not show a question or permission
indicator.
- **AC-UI-THREADS-DECK-002.4:** When a task is in its review outcome and no
session needs an explicit action, the task column shall show a completion
indicator with the localized label `Ready for review`.
- **AC-UI-THREADS-DECK-002.5:** When a session is `STARTING` or `RUNNING`, its
selector item shall show the grid spinner without loading its transcript.
- **AC-UI-THREADS-DECK-002.6:** When no valid selection exists and a session
needs attention, the task column shall select that session without loading
another transcript first.
### REQ-UI-THREADS-DECK-003: Responsive bounded deck
**Intent:** Keep Threads responsive with many task columns and preserve native
desktop and mobile navigation.
#### Acceptance criteria
- **AC-UI-THREADS-DECK-003.1:** When Threads contains 30 task columns, the deck
shall preserve stable column order and horizontal scroll geometry while
detail content is activated only for the current viewport under
`REQ-PLATFORM-VIEWPORT-SESSION-DELIVERY-001`.
- **AC-UI-THREADS-DECK-003.2:** Before a task column becomes detail-active, the
system shall show a lightweight shell from task summary data and shall not
show another task's conversation in that shell.
- **AC-UI-THREADS-DECK-003.3:** When a desktop user scrolls a task column into
view, the system shall activate its selected conversation without a page
reload. When the column leaves the detail window, the shell and its local
selection shall remain available.
- **AC-UI-THREADS-DECK-003.4:** On a phone, the system shall keep one snapped
task column detail-active and shall use a compact session picker on the right
of the metadata row instead of a nested horizontal tab strip.
- **AC-UI-THREADS-DECK-003.5:** The phone session picker shall open a bottom
sheet with one row per existing session. Each row shall have a touch target
of at least 44 by 44 CSS pixels. Each row shall show the same agent identity
or grid spinner as the desktop tabs.
- **AC-UI-THREADS-DECK-003.6:** Long task metadata or many session names shall
stay inside the task-column header. Desktop session tabs may scroll inside
their right-side region, and the document shall not gain horizontal
overflow.
- **AC-UI-THREADS-DECK-003.7:** Loading, empty-session, and recoverable
session-list failure states shall remain inside their task column and shall
not block horizontal navigation to other columns.
- **AC-UI-THREADS-DECK-003.8:** On a phone, each snapped conversation shall fill
the available content width. The composer and prose shall remain contained;
wide code and tables may scroll within their own content region.
- **AC-UI-THREADS-DECK-003.9:** On a phone, the task title shall open a bottom
sheet listing admitted threads in stable order with their attention state and
workflow context. Selecting a row shall reveal its conversation and close the
sheet. When several threads are available, the page topbar shall show the
visible task's position and thread count.
- **AC-UI-THREADS-DECK-003.10:** The phone page header shall keep the selected
view and navigation menu directly reachable without horizontal scrolling.
Secondary tools and status shall remain available from that menu.
- **AC-UI-THREADS-DECK-003.11:** Phone task headers shall prioritize the title,
attention state, session picker, and Open task action. Workflow and step
metadata shall remain available in the thread picker. New standalone controls
shall have a minimum 44-pixel touch target.
- **AC-UI-THREADS-DECK-003.12:** The phone page header shall group page identity
and the selected view in one control. Task titles shall have up to two lines.
With multiple threads, position and bounded, noninteractive page indicators
shall sit inline in the existing page topbar, without instruction text or an
additional row. Indicators shall follow the visible thread after swiping or
picker selection. Small decks shall include page dots. Empty decks and a
single thread shall omit the indicator.
- **AC-UI-THREADS-DECK-003.13:** While a phone swipe makes a different thread
nearest the viewport center, the page indicator shall update during the
gesture, without waiting for release, snap completion, session membership,
or transcript loading. Reversing the swipe shall restore the indicator for
the nearest thread. Loading completion alone shall not change its position.
### REQ-UI-THREADS-DECK-004: Conversation layouts
**Intent:** Let users inspect twice as many conversations at a readable width
without changing which tasks or sessions they are following.
#### Acceptance criteria
- **AC-UI-THREADS-DECK-004.1:** Columns shall use the existing full-height,
horizontally scrolling arrangement. Grid shall use two equal-height rows
at the same minimum readable tile width, with horizontal scrolling for
additional tasks and independent vertical transcript scrolling in each tile.
- **AC-UI-THREADS-DECK-004.2:** Grid shall place the stable task sequence from
top to bottom within each visual column, then proceed to the next column.
An odd final task shall occupy the upper tile without duplication. A single
admitted task shall fill the available height in either selected layout.
- **AC-UI-THREADS-DECK-004.3:** Changing layout shall retain the admitted task
set, stable order, selected session per task, and existing reply drafts. It
shall keep the last interacted surviving task visible, falling back to the
current visible task and then the first admitted task when needed.
- **AC-UI-THREADS-DECK-004.4:** A reply or status update shall not move a task
to another tile. Removing a task, changing filters, or following a deep link
shall use the existing deterministic admission and recovery behavior in
either layout; a lower-row task shall be directly reachable.
- **AC-UI-THREADS-DECK-004.5:** Both visible grid rows shall show their selected
live conversations. Offscreen tiles and unselected sibling sessions shall
remain subject to the existing platform delivery budget. Hovering a composer
shall not add a session subscription or mark a conversation read.
- **AC-UI-THREADS-DECK-004.6:** Below the phone breakpoint the system shall
show one full-width, full-height conversation with the existing swipe,
position indicator, and thread picker. A saved Grid preference shall be
retained for wider displays without mounting a hidden desktop grid.
- **AC-UI-THREADS-DECK-004.7:** When the available board content height cannot
fit two 300-CSS-pixel tiles plus their gap, the system shall use Columns and
explain that Grid needs more height. Increasing the available height shall
restore Grid without changing the saved preference or task selection.
- **AC-UI-THREADS-DECK-004.8:** Both layouts shall retain the existing Open
task, task-action, and session-selection controls. Layout selection shall not
add an in-place enlargement mode or change Open task navigation.
### REQ-UI-THREADS-DECK-005: Composer disclosure
**Intent:** Reclaim transcript space while monitoring conversations and keep
normal replying, attention handling, and agent controls reachable.
#### Acceptance criteria
- **AC-UI-THREADS-DECK-005.1:** With auto-hide disabled, each detail-active
conversation shall retain its normal composer. With auto-hide enabled and
no ongoing interaction, draft, or required action, routine composer content
and controls shall collapse, leaving only the existing CI popover trigger
when applicable and increasing the visible transcript height. No Reply,
Stop, plugin, toolbar, or other routine footer controls shall remain visible
in the collapsed state. With no CI status, the footer shall occupy no space.
- **AC-UI-THREADS-DECK-005.2:** On a fine pointer, dwelling over a task tile
shall reveal that tile's composer without taking keyboard focus. A pointer
crossing a tile for less than 150 milliseconds shall not reveal it. After
leaving for 300 milliseconds, it shall collapse only when no keep-open
condition remains.
- **AC-UI-THREADS-DECK-005.3:** Keyboard focus on a task tile shall reveal its
composer, allowing normal navigation to the editor and controls. Explicit
editor-focus actions shall reveal before focusing the editor. Collapsed controls shall not
remain invisible tab stops or appear as active controls to assistive tools.
- **AC-UI-THREADS-DECK-005.4:** While an editor has focus, unsent text or
attachments, a host-owned upload or send in progress, or a focused owned
menu, picker, or dialog, auto-hide shall keep that composer visible.
Hiding shall not unmount the editor or its plugin buttons, cancel a plugin
operation, or revoke its composer capability. Plugin-specific activity is
not required to be observable by the host; plugin controls hide with the
rest of the composer when no host-observable hold remains.
Session changes shall not transfer these states or drafts to another session.
- **AC-UI-THREADS-DECK-005.5:** Pending clarification or permission actions
and actionable session recovery shall remain visible and usable without
hover. Required composer content shall stay expanded until that condition
clears. Agent Stop shall remain available through the revealed composer and
the existing full task page, using the same cancellation-pending feedback.
- **AC-UI-THREADS-DECK-005.6:** Revealing or collapsing a composer shall not
resize neighboring tiles or scroll the board. A transcript following the
latest output shall continue to do so; a user reading history shall retain
the visible message and its offset, subject only to scroll-range clamping.
The editor and final messages shall remain reachable in a short grid tile.
- **AC-UI-THREADS-DECK-005.7:** Phone and coarse-pointer layouts shall retain
the normal visible composer, without overwriting the saved auto-hide
preference. On pointer-based layouts, explicit Collapse shall preserve the
draft and return focus to the task tile without immediately reopening it.
A later tile entry or explicit keyboard reveal shall restore the composer.
Required actions and host-owned sends/uploads shall prevent collapse and
explain why.
- **AC-UI-THREADS-DECK-005.8:** On phones, composing shall remain inside the
single conversation surface. The software keyboard, safe areas, long text,
and composer menus shall not cover the active reply action or create
document-level horizontal overflow. New touch controls shall have hit areas
of at least 44 by 44 CSS pixels.
- **AC-UI-THREADS-DECK-005.9:** Hover, disclosure, and layout changes shall
preserve normal model, mode, attachments, queue/steering, and submission
behavior. They shall neither start an agent nor submit, discard, or clear a
prompt. Full task pages and other chat hosts shall keep their existing
composer behavior.
- **AC-UI-THREADS-DECK-005.10:** Leaving the detail window shall release the
chat even if its composer was expanded. Returning shall restore the existing
session draft without widening the detail window. Transient hover, menu,
and focus state shall not be restored or persisted as view settings.
- **AC-UI-THREADS-DECK-005.11:** Composer reveal and collapse shall smoothly
change the allocated height and fade routine content within 250 milliseconds
after the existing disclosure delay. A reversed interaction shall continue
from the current visual position. CI shall remain visible and interactive
throughout. Reduced-motion users shall receive an immediate change; initial
page rendering and always-visible touch composers shall not animate.
## Out of scope
- Creating, deleting, renaming, reordering, or changing the primary session
from Threads.
- Persisting a Threads-only session selection across browser restarts.
- Copying transcripts or an unbounded session list into a task status summary.
- Replacing the full task workbench or its independent agent-tab behavior.
- Full DOM virtualization of lightweight task-column shells.
- Adjustable row counts, independent tile resizing, masonry, drag reordering,
and a new in-place expansion mode.
- Multiple simultaneous phone transcripts or a hover-only touch workflow.
Task-column scope, filters, sort, limits, and saved presentation persistence are in
[Threads Saved Views](threads-saved-views.md).