## Purpose

The chatview2 widget renders a channel's message history as a virtualized,
scrollable chat log with typed interactive messages, replacing the current
`bin/app` chatview. This spec defines its observable behavior: scene API,
buffer semantics, scrolling, storage, loading, filtering, resource
management, and feature parity with the current implementation.

## Requirements

### Requirement: Single chat screen with channel retargeting

The chatview SHALL support rebinding to a different channel's message
store at runtime via a `set_channel` method. On exit from a channel it
SHALL release that channel's in-memory buffer; on entry it SHALL reload
the target channel's messages through the background loading pipeline.
Message-type sub-nodes and their signal wirings SHALL remain attached and
functional across channel switches.

#### Scenario: Switching channels clears and reloads

- **WHEN** `set_channel` is called with a channel that has stored history
- **THEN** the previously displayed messages are no longer rendered and
  the target channel's newest messages load in the background

#### Scenario: Signal wirings survive channel switches

- **WHEN** the UI has subscribed to a message-type sub-node signal and the
  channel is switched
- **THEN** the subscription remains active and receives signals from
  messages of the newly bound channel

#### Scenario: Entering a channel with no history

- **WHEN** `set_channel` targets a channel with an empty store
- **THEN** the view renders empty and remains interactive

### Requirement: Scroll position restore on re-entry

The chatview SHALL remember, per channel, where the user left off and
restore that position on re-entry. The remembered state SHALL identify the
message being viewed (anchor id plus pixel offset) so restoration is stable
when messages arrive while the channel is not open. A user who left the
channel at the bottom SHALL return to the bottom.

#### Scenario: Re-entry restores the same content

- **WHEN** the user exits a channel while scrolled into history and new
  messages arrive before re-entry
- **THEN** the restored view shows the same anchor message at the same
  offset within the viewport

#### Scenario: Re-entry at the bottom

- **WHEN** the user exits a channel while at the live bottom
- **THEN** re-entry restores the bottom position and newly arrived
  messages are visible

#### Scenario: Anchor no longer available

- **WHEN** the anchored message cannot be found on re-entry
- **THEN** the scroll position is clamped to a valid position without
  crashing or blocking

### Requirement: Render resources released when out of view

The chatview SHALL release render resources (meshes, glyphs, textures,
layouts) for messages that leave the visible region, using a soft window
plus LRU budget rather than strict window-bound eviction. Scrolling
through a large history SHALL NOT cause unbounded growth of memory or GPU
resource usage. Render-scoped async tasks SHALL be cancelled when their
message is released.

#### Scenario: Long scroll does not accumulate resources

- **WHEN** the user scrolls through many screens of history
- **THEN** resources held for messages far outside the viewport are
  released, and total resource usage stays bounded

### Requirement: Buffer-size independent interaction

Geometry queries (total content height, the set of messages visible at a
scroll position, the position of a given message) and per-frame scrolling
work SHALL NOT scale with the number of buffered messages. UI interaction
responsiveness SHALL NOT degrade as the buffer grows.

#### Scenario: Scrolling a large buffer costs like a small one

- **WHEN** the same viewport is scrolled by the same delta with a small
  and then a very large loaded buffer
- **THEN** per-frame cost and responsiveness are comparable

### Requirement: Scroll semantics in pixels from the bottom

The scroll position SHALL be measured in pixels from the live bottom of
the content (`0` = bottom, increasing = further up in history) and
SHALL be clamped to the valid range. The position SHALL be internal
view state, not a settable scene property: externally, the view SHALL
expose a `scroll_to_bottom` method and an at-bottom indication that
distinguishes "at the live bottom" from "scrolled into history".

#### Scenario: Scroll zero pins to live bottom

- **WHEN** the view is at the bottom and a new message arrives
- **THEN** the view stays at the bottom and the new message is visible

#### Scenario: Clamping

- **WHEN** a gesture or animation requests a scroll position beyond the
  valid range
- **THEN** the resulting position is clamped and no error occurs

#### Scenario: Scroll to bottom

- **WHEN** `scroll_to_bottom` is invoked (e.g. the down-arrow button)
- **THEN** any in-flight motion stops and the view returns to the live
  bottom; the at-bottom indication reflects the position

### Requirement: Direct-drag scrolling

Touch-drag scrolling, delivered by the app gesture subsystem as a drag
lifecycle (`DragStart`/`DragMove`/`DragEnd`), SHALL move content 1:1
with the pointer in pixels, without animation or smoothing on top. The
slop dead-zone before the drag starts and the move delivery cadence
SHALL come from the gesture session, not the view. Starting a drag —
or touching down over the view — SHALL cancel any in-flight glide or
scroll animation.

#### Scenario: Finger tracking is pixel-exact

- **WHEN** the finger moves up by N pixels during a drag
- **THEN** the content scrolls exactly N pixels, delivered at the
  gesture session's move cadence, with no acceleration or smoothing
  added by the view

#### Scenario: Slop dead-zone precedes scroll

- **WHEN** a touch travels less than the session's touch slop
- **THEN** no scroll occurs and the touch remains eligible for
  tap/long-press recognition

#### Scenario: Grabbing stops motion

- **WHEN** a touch begins while an animated scroll or glide is in progress
- **THEN** the animation/glide stops immediately and the drag takes over

### Requirement: Animated page scrolling for wheel and keys

Mouse wheel ticks and PageUp/PageDown SHALL scroll half a page, animated
with easing. Repeated ticks while an animation is in flight SHALL
retarget/coalesce the animation rather than accumulate velocity.

#### Scenario: Single wheel tick

- **WHEN** the mouse wheel is scrolled one tick
- **THEN** the view animates half a page in the wheel direction

#### Scenario: Repeated ticks coalesce

- **WHEN** several wheel ticks occur in quick succession
- **THEN** the animation target extends by half a page per tick and the
  motion remains smooth, without a velocity runaway

### Requirement: Flick inertia

Releasing a drag with sufficient velocity SHALL produce an inertial glide
that decays over time and stops within the clamped range. Release
velocity SHALL be taken from the gesture session's `DragEnd` velocity
(the view does not sample its own). Touching down over the view during a
glide SHALL stop it, including before the touch travels past the touch
slop.

#### Scenario: Flick decays and stops

- **WHEN** the finger is released with upward velocity
- **THEN** the content glides in the same direction, decaying, and comes
  to rest at or within the valid scroll range

#### Scenario: Touchdown stops a glide

- **WHEN** the user touches the view while an inertial glide is in motion
- **THEN** the glide stops immediately, even if the touch never travels
  past the touch slop

### Requirement: Scroll compensation for height changes

When a message below the viewport bottom changes height, the scroll
position SHALL be adjusted by the height delta so the viewed content stays
stable, unless scroll is `0` (bottom pinned). Height changes inside the
viewport SHALL grow or shrink the content around the current view without
jumping. Total height and the maximum scroll SHALL reflect height changes
immediately.

#### Scenario: Image loads below the reading position

- **WHEN** the user is scrolled into history and a message below the
  viewport grows as its image loads
- **THEN** the viewed content does not move

#### Scenario: Expansion inside the viewport

- **WHEN** the user expands a collapsed message that is on screen
- **THEN** the message expands in place without the surrounding content
  jumping out of view

### Requirement: Message type sub-nodes

Each message type SHALL be represented by exactly one sub-node of the
chatview, exposing type-specific styling properties, signals whose
payloads identify the message (msg id) plus type-specific data, and
methods. Message lifecycle operations defined by each type's own
semantics (e.g. inserting messages of that type, file status updates)
SHALL be methods and signals of the type's sub-node; the chatview node
SHALL expose only view-wide methods and signals (channel switching,
filtering, selection). Sub-nodes SHALL NOT be created or destroyed when
the buffer changes (channel switch, load, eviction). Registering a new
message type SHALL NOT require modifying existing types.

#### Scenario: Nick click emits an identified signal

- **WHEN** the user clicks a nick inside a privmsg
- **THEN** the privmsg type sub-node emits a signal carrying the msg id
  and nick, which the UI can use (e.g. inserting the nick into the chat
  editor)

#### Scenario: Lifecycle operations go through type nodes

- **WHEN** a privmsg is inserted, confirmed, or a file status changes
- **THEN** the operation is invoked as a method on the corresponding
  type sub-node (privmsg insert/confirm, filemsg status), not on the
  chatview node

#### Scenario: New message type is additive

- **WHEN** a new message type is registered with its sub-node and payload
  decoder
- **THEN** existing types and stored messages continue to work unchanged

### Requirement: Debug introspection and deletion

The chatview SHALL provide methods to support live testing:
enumerating the ids (with timestamps) of currently loaded messages in
display order, and deleting a loaded message by id. Deletion SHALL
remove the message from the buffer (updating ordering, geometry, and
rendered state correctly) and from the channel's storage. These methods
are testing affordances, not user-facing features.

#### Scenario: Enumerate loaded messages

- **WHEN** the id-enumeration method is called
- **THEN** it returns the ids and timestamps of all currently loaded
  messages in display order

#### Scenario: Delete by id updates everything

- **WHEN** a loaded message is deleted by id via the deletion method
- **THEN** it disappears from the view, geometry (total height, scroll
  range) updates correctly, and it is absent after the channel is
  re-entered

### Requirement: Styling inheritance and regen

Styling properties shared across message types (e.g. font size, line
height, timestamp styling, selection color) SHALL be defined once on the
chatview node. A type sub-node SHALL only define properties specific to
it and MAY override an inherited property by defining its own. Message
types SHALL receive live property handles when created; changing a styling
property SHALL cause affected messages' rendered state to be rebuilt
(regen) with re-measured heights.

#### Scenario: Font size change re-renders everything

- **WHEN** the chatview font size property changes
- **THEN** all rendered messages are re-laid-out at the new size, heights
  are re-measured, and the scroll position remains valid (compensated)

#### Scenario: Type-specific override

- **WHEN** a type sub-node defines its own value for an otherwise
  inherited property
- **THEN** messages of that type render using the override while other
  types use the inherited value

### Requirement: Async message content updates

Message types MAY run async tasks that update their own persistent data
(e.g. download progress, decoded image buffers) and then rebuild their
rendered state, including height. Tasks tied to rendering SHALL be
cancelled on release. Tasks that must outlive eviction (e.g. background
downloads) SHALL be hosted on the type sub-node, keyed by msg id or
content address so duplicates are not spawned, and surviving tasks SHALL
keep updating state; re-materializing a message SHALL attach to running
tasks or current state rather than restart from scratch.

#### Scenario: Download continues while evicted

- **WHEN** a file message's download task is running and the message
  scrolls out of view
- **THEN** the download continues, and scrolling back shows current
  progress without a duplicate task

#### Scenario: Content update changes height

- **WHEN** an image finishes loading and replaces a progress placeholder
- **THEN** the message re-renders at its new height and scroll
  compensation keeps the view stable per the height-change rules

### Requirement: Random insertion at any timestamp

Messages SHALL be insertable at any timestamp position (including
backfill of older messages during sync) with the view updating correctly.
Buffer ordering SHALL use the (timestamp, msg_id) composite key.
Inserting a message whose (timestamp, msg_id) already exists SHALL be
ignored (deduplication).

#### Scenario: Backfilled message appears in order

- **WHEN** an older message arrives while the user views history that
  includes its timestamp position
- **THEN** it appears at the correct chronological position without
  duplicating or displacing other messages

#### Scenario: Same-millisecond messages coexist

- **WHEN** two messages share a timestamp but have different msg ids
- **THEN** both are stored, ordered, and rendered

#### Scenario: Duplicate insert is ignored

- **WHEN** the same (timestamp, msg_id) is inserted twice
- **THEN** the second insert has no visible effect

### Requirement: Persisted message storage format

Messages SHALL be persisted in the per-channel kvdb tree with key
`(timestamp big-endian, msg_id)` and value `[type_id][type-owned
bytes]`; the type decides how to interpret its bytes. Unconfirmed
messages SHALL be persisted with a confirmed flag (type-owned payload
state), and their later confirmation SHALL update the existing entry in
place rather than create a duplicate. The format is a clean break from
the previous chatview: values it cannot decode are corrupt data and
SHALL fail explicitly (panic) rather than be skipped or misread.

#### Scenario: Unconfirmed then confirmed

- **WHEN** a message is sent unconfirmed and later confirmed via the
  privmsg type node's confirm method
- **THEN** exactly one stored entry exists, rendered with confirmed
  styling, and it survives app restart

#### Scenario: Corrupt entry fails explicitly

- **WHEN** a stored value carries an unknown type id or undecodable
  payload
- **THEN** loading fails loudly with an explicit error identifying the
  entry, never a silent skip

### Requirement: Background loading pipeline

All message loading — channel entry, live receive, scrolling toward
history, and filter changes — SHALL happen in an async background pipeline
that never blocks UI interaction. The loader SHALL maintain coverage of
the visible region plus a preload margin, waking on demand.

#### Scenario: Entering a large channel is non-blocking

- **WHEN** `set_channel` targets a channel with a large history
- **THEN** the UI is immediately interactive while messages stream in

### Requirement: Runtime message filter

A filter callback SHALL be settable and replaceable at runtime. The filter
SHALL decide which stored messages enter the buffer during loading;
filtered-out messages SHALL still be persisted. Changing the filter SHALL
rebuild the visible set through the background pipeline.

#### Scenario: Filter narrows the view

- **WHEN** a filter that excludes some messages is set and the buffer
  reloads
- **THEN** excluded messages are not rendered but remain in storage

#### Scenario: Filter replaced at runtime

- **WHEN** the filter callback is swapped
- **THEN** the view rebuilds in the background using the new filter

### Requirement: Privmsg rendering parity

Privmsgs SHALL render with the current chatview's feature set: nick
coloring (stable per nick), CTCP ACTION rendering, NOTICE styling with
reduced font size, unconfirmed gray styling, timestamps, URL detection
with colored/backgrounded spans, URL click/tap opening, and URL
right-click or long-press copying with the "copied link" toast overlay.

#### Scenario: URL interaction parity

- **WHEN** a message containing a URL is clicked, or long-pressed on
  touch
- **THEN** the URL opens (click) or is copied with the toast overlay
  (long-press/right-click), matching current behavior

### Requirement: Selection across message types

Any displayed message, regardless of type, SHALL be selectable (mouse
click toggle, `Tap` toggle, drag sweep, long-press entering selection
mode with subsequent drag extending the selection, tap toggling in
selection mode). `copy_select`
SHALL copy the selected messages' text in display order joined by
newlines, where each selected message contributes copy text defined by
its type; a type MAY contribute nothing. `unselect` SHALL clear all
selection. `select_changed` SHALL fire on transitions between having
and not having any selection.

#### Scenario: Mixed-type selection copies per-type text

- **WHEN** a privmsg, a file message, and a date separator are all
  selected and `copy_select` is invoked
- **THEN** the clipboard contains each message's type-defined copy
  text (privmsg its rendered line, file message its file URL, date
  separator its date label) joined by newlines in display order, and
  selection is cleared

#### Scenario: Every type toggles

- **WHEN** a date separator line is clicked
- **THEN** it becomes selected and shows the selection highlight,
  unlike the current chatview where separators are unselectable

#### Scenario: Long-press selects and drag extends

- **WHEN** a long-press lands on a message line and the finger then
  drags without lifting
- **THEN** the pressed line becomes selected, selection mode is entered,
  and the drag extends the selection instead of scrolling

#### Scenario: Selection transitions signal

- **WHEN** the first line becomes selected, or the last selection is
  cleared
- **THEN** `select_changed` fires with true and false respectively

### Requirement: Expandable message height

Long messages SHALL be capped to a default height with an affordance to
expand to full height; expansion changes the message height and follows
the height-change scroll rules. In v1 the privmsg body is plain text with
nicks and URLs; the payload format and APIs SHALL accommodate a richer
span/block body (quotes, styling, code, math) added later without
breaking stored messages or the buffer/scroll machinery.

#### Scenario: Long message collapses and expands

- **WHEN** a message taller than the cap is rendered and the user toggles
  expansion
- **THEN** the message renders capped, then expands in place following
  the height-change rules, and collapsing restores the capped height

### Requirement: File message parity

fud file messages SHALL be derived from privmsg text containing fud URLs,
render the file status lifecycle (initializing, idle, downloading with
progress, downloaded, error), request downloads on click/tap via a signal,
update rendering when status changes, and display downloaded images
scaled to fit width and height bounds.

#### Scenario: File download lifecycle

- **WHEN** a file message is tapped while idle and the download progresses
- **THEN** a download request signal fires, status renders with progress,
  and on completion the image (or completed state) is displayed

### Requirement: Reflow on viewport changes

When the viewport width or window scale changes, the chatview SHALL
re-wrap affected messages, re-measure heights, and keep the user's
reading position stable: the anchored content remains in view after
reflow, and a bottom-pinned view stays bottom-pinned. Height-only
viewport changes (e.g. the input editor growing) SHALL NOT trigger
re-wrapping. Reflow SHALL complete without losing messages.

#### Scenario: Width change keeps reading position

- **WHEN** the window is resized while the user is reading history
- **THEN** messages re-wrap at the new width and the message under the
  viewport anchor remains in view at the same offset

#### Scenario: Bottom stays bottom across reflow

- **WHEN** a reflow occurs while the view is pinned at the live bottom
- **THEN** the view remains pinned at the bottom

#### Scenario: Height-only change does not rewrap

- **WHEN** the chat editor grows and only the viewport height changes
- **THEN** no re-wrapping occurs and the scroll position remains valid

### Requirement: Date separators and derived messages

Date separator messages SHALL be derived from the stored messages' dates,
never persisted, and inserted into the display order at day boundaries.

#### Scenario: Day boundary renders a separator

- **WHEN** consecutive messages span midnight
- **THEN** a date separator renders between them showing the new date

### Requirement: i18n support

Message types SHALL accept the i18n translation fish and use it for
translatable user-facing strings (e.g. file status labels).

#### Scenario: File status string is translated

- **WHEN** the active language differs and a file message shows "tap to
  download"
- **THEN** the string is rendered translated

### Requirement: Keyboard scrolling

PageUp/PageDown (and wheel equivalents) SHALL scroll via the animated page
scrolling behavior, and keyboard input SHALL be consumable so it does not
leak to other UI elements while interacting with the chatview.

#### Scenario: PageUp animates half a page

- **WHEN** PageUp is pressed
- **THEN** the view animates half a page up and the key event is consumed

### Requirement: Gesture subsystem integration

The chatview SHALL receive touch input exclusively through the app
gesture subsystem: it SHALL declare its accepted gestures via
`gesture_set` (tap, long-press, vertical drag), pass an exact
`gesture_hit_test` matching its rect, and consume the `GestureAction`
stream via `handle_gesture`. It SHALL NOT implement its own recognition
thresholds, long-press timers, or velocity sampling; touch slop, tap
bounds, long-press firing, move throttling, and release velocity SHALL
come from the session. Interactive layers floating over the chatview
(e.g. the scroll-to-bottom arrow) SHALL carry a higher node priority
than the chatview so the session's priority-ordered target resolution
delivers their gestures to them.

#### Scenario: Overlaying arrow receives its taps

- **WHEN** the scroll-to-bottom arrow is visible over the chatview and
  tapped
- **THEN** the arrow receives the tap (triggering scroll-to-bottom) and
  the chatview does not treat it as selection or content activation

#### Scenario: No local recognition

- **WHEN** a touch stream is delivered to the chatview
- **THEN** slop gating, tap/long-press discrimination, long-press
  timing, and release-velocity sampling are those of the gesture
  session; the chatview applies only scroll physics and content
  dispatch