@teammates/consolonia 0.6.3 → 0.7.0

package/dist/index.d.ts

@@ -35,13 +35,15 @@ export { Control } from "./layout/control.js";
 export { Row, type RowOptions } from "./layout/row.js";
 export { Stack, type StackOptions } from "./layout/stack.js";
 export { Border, type BorderOptions } from "./widgets/border.js";
-export { ChatView, type ChatViewOptions, type DropdownItem, type FeedActionItem, } from "./widgets/chat-view.js";
+export { ChatView, type ChatViewOptions, type DropdownItem, type FeedActionEntry, type FeedActionItem, type FeedItem, } from "./widgets/chat-view.js";
+export { FeedStore } from "./widgets/feed-store.js";
 export { Interview, type InterviewOptions, type InterviewQuestion, } from "./widgets/interview.js";
 export { Panel, type PanelOptions } from "./widgets/panel.js";
 export { ScrollView, type ScrollViewOptions } from "./widgets/scroll-view.js";
 export { type StyledLine, StyledText, type StyledTextOptions, } from "./widgets/styled-text.js";
 export { Text, type TextOptions } from "./widgets/text.js";
 export { type DeleteSizer, type InputColorizer, TextInput, type TextInputOptions, } from "./widgets/text-input.js";
+export { VirtualList, type VirtualListItem, type VirtualListOptions, } from "./widgets/virtual-list.js";
 export { type MarkdownOptions, type MarkdownTheme, renderMarkdown, } from "./widgets/markdown.js";
 export { DEFAULT_SYNTAX_THEME, getHighlighter, highlightLine, registerHighlighter, type SyntaxHighlighter, type SyntaxTheme, type SyntaxToken, type SyntaxTokenType, } from "./widgets/syntax.js";
 export { concat, isStyledSpan, pen, type StyledSegment, type StyledSpan, spanLength, spanText, } from "./styled.js";

package/dist/index.js

@@ -47,12 +47,14 @@ export { Stack } from "./layout/stack.js";
 // ── Widgets ─────────────────────────────────────────────────────────
 export { Border } from "./widgets/border.js";
 export { ChatView, } from "./widgets/chat-view.js";
+export { FeedStore } from "./widgets/feed-store.js";
 export { Interview, } from "./widgets/interview.js";
 export { Panel } from "./widgets/panel.js";
 export { ScrollView } from "./widgets/scroll-view.js";
 export { StyledText, } from "./widgets/styled-text.js";
 export { Text } from "./widgets/text.js";
 export { TextInput, } from "./widgets/text-input.js";
+export { VirtualList, } from "./widgets/virtual-list.js";
 // ── Markdown ─────────────────────────────────────────────────────────
 export { renderMarkdown, } from "./widgets/markdown.js";
 // ── Syntax highlighting ──────────────────────────────────────────────

package/dist/widgets/chat-view.d.ts

@@ -34,6 +34,7 @@ import type { InputEvent } from "../input/events.js";
 import { Control } from "../layout/control.js";
 import type { Constraint, Rect, Size } from "../layout/types.js";
 import type { StyledSpan } from "../styled.js";
+import { type FeedActionItem } from "./feed-store.js";
 import { type StyledLine } from "./styled-text.js";
 import { type DeleteSizer, type InputColorizer, TextInput } from "./text-input.js";
 export interface DropdownItem {
@@ -44,12 +45,7 @@ export interface DropdownItem {
     /** Full text to insert on accept. */
     completion: string;
 }
-/** A single action item within an action line. */
-export interface FeedActionItem {
-    id: string;
-    normalStyle: StyledLine;
-    hoverStyle: StyledLine;
-}
+export type { FeedActionEntry, FeedActionItem, FeedItem, } from "./feed-store.js";
 export interface ChatViewOptions {
     /** Banner text shown at the top of the chat area. */
     banner?: string;
@@ -105,15 +101,14 @@ export interface ChatViewOptions {
 export declare class ChatView extends Control {
     private _banner;
     private _topSeparator;
-    private _feedLines;
-    /** Maps feed line index → action(s) for clickable lines. */
-    private _feedActions;
-    /** Feed line index currently hovered (-1 if none). */
-    private _hoveredAction;
-    /** Maps screen Y → feed line index (rebuilt each render). */
-    private _screenToFeedLine;
-    /** Maps screen Y → row offset within the feed line (for multi-row wrapped lines). */
-    private _screenToFeedRow;
+    /** Identity-based feed item store — replaces _feedLines + _feedActions + _hiddenFeedLines. */
+    private _store;
+    /** ID of the feed item currently hovered (null if none). */
+    private _hoveredItemId;
+    /** Scrollable list widget — owns scroll state, height cache, screen mapping, scrollbar. */
+    private _feed;
+    /** Number of non-feed items (banner + separator) prepended to VirtualList items. */
+    private _feedItemOffset;
     private _bottomSeparator;
     private _progressText;
     private _input;
@@ -130,25 +125,6 @@ export declare class ChatView extends Control {
     private _dropdownStyle;
     private _footerStyle;
     private _maxInputH;
-    private _feedScrollOffset;
-    private _feedX;
-    private _contentWidth;
-    /** Cached measured height per feed line index. Invalidated on width change. */
-    private _feedHeightCache;
-    /** The content width used for the last height cache pass. */
-    private _feedHeightCacheWidth;
-    /** Cached from last render for hit-testing. */
-    private _scrollbarX;
-    private _feedY;
-    private _feedH;
-    private _thumbPos;
-    private _thumbSize;
-    private _maxScroll;
-    private _scrollbarVisible;
-    /** True while the user is dragging the scrollbar thumb. */
-    private _dragging;
-    /** The Y offset within the thumb where the drag started. */
-    private _dragOffsetY;
     private _selAnchor;
     private _selEnd;
     private _selecting;
@@ -195,6 +171,20 @@ export declare class ChatView extends Control {
     get feedLineCount(): number;
     /** Update the content of an existing feed line by index. Also removes its action if any. */
     updateFeedLine(index: number, content: StyledLine): void;
+    /** Update the action items on an existing action line by index. */
+    updateActionList(index: number, actions: FeedActionItem[]): void;
+    /** Insert a plain text line at a specific feed index. */
+    insertToFeed(atIndex: number, text: string, style?: TextStyle): void;
+    /** Insert a styled line at a specific feed index. */
+    insertStyledToFeed(atIndex: number, styledLine: StyledSpan): void;
+    /** Insert an action list at a specific feed index. */
+    insertActionList(atIndex: number, actions: FeedActionItem[]): void;
+    /** Hide or show a single feed line. Hidden lines take zero height. */
+    setFeedLineHidden(index: number, hidden: boolean): void;
+    /** Hide or show a range of feed lines. */
+    setFeedLinesHidden(startIndex: number, count: number, hidden: boolean): void;
+    /** Check if a feed line is hidden. */
+    isFeedLineHidden(index: number): boolean;
     /** Scroll the feed to the bottom. */
     scrollToBottom(): void;
     /** Scroll the feed by a delta (positive = down, negative = up). */
@@ -238,6 +228,8 @@ export declare class ChatView extends Control {
     /** Get the current input override widget, or null. */
     get inputOverride(): Control | null;
     handleInput(event: InputEvent): boolean;
+    /** Map screen Y → feed line index (accounting for banner/separator prefix items). */
+    private _feedLineAtScreen;
     /** Extract the plain text content of a feed line. */
     private _extractFeedLineText;
     /** Resolve which action item the mouse x-position falls on. */
@@ -249,7 +241,8 @@ export declare class ChatView extends Control {
     measure(constraint: Constraint): Size;
     arrange(rect: Rect): void;
     render(ctx: DrawingContext): void;
-    private _renderFeed;
+    /** Build the VirtualList items array from banner + separator + feed store items. */
+    private _buildVirtualListItems;
     private _renderDropdown;
     /** Whether a non-zero text selection is active. */
     private _hasSelection;

package/dist/widgets/chat-view.js

@@ -30,9 +30,11 @@
  *   "tab"     ()                     — user pressed Tab (for autocomplete)
  */
 import { Control } from "../layout/control.js";
+import { FeedStore, } from "./feed-store.js";
 import { StyledText } from "./styled-text.js";
 import { Text } from "./text.js";
 import { TextInput, } from "./text-input.js";
+import { VirtualList } from "./virtual-list.js";
 // ── URL / file path detection ───────────────────────────────────────
 const URL_REGEX = /https?:\/\/[^\s)>\]]+/g;
 const FILE_PATH_REGEX = /(?:[A-Za-z]:[/\\]|\/)[^\s:*?"<>|)>\]]*[^\s:*?"<>|)>\].,:;!]/g;
@@ -43,15 +45,14 @@ export class ChatView extends Control {
     // ── Child controls ─────────────────────────────────────────────
     _banner;
     _topSeparator;
-    _feedLines = [];
-    /** Maps feed line index → action(s) for clickable lines. */
-    _feedActions = new Map();
-    /** Feed line index currently hovered (-1 if none). */
-    _hoveredAction = -1;
-    /** Maps screen Y → feed line index (rebuilt each render). */
-    _screenToFeedLine = new Map();
-    /** Maps screen Y → row offset within the feed line (for multi-row wrapped lines). */
-    _screenToFeedRow = new Map();
+    /** Identity-based feed item store — replaces _feedLines + _feedActions + _hiddenFeedLines. */
+    _store = new FeedStore();
+    /** ID of the feed item currently hovered (null if none). */
+    _hoveredItemId = null;
+    /** Scrollable list widget — owns scroll state, height cache, screen mapping, scrollbar. */
+    _feed;
+    /** Number of non-feed items (banner + separator) prepended to VirtualList items. */
+    _feedItemOffset = 0;
     _bottomSeparator;
     _progressText;
     _input;
@@ -69,28 +70,6 @@ export class ChatView extends Control {
     _dropdownStyle;
     _footerStyle;
     _maxInputH;
-    _feedScrollOffset = 0;
-    // ── Feed geometry (cached from last render for hit-testing) ──
-    _feedX = 0;
-    _contentWidth = 0;
-    // ── Feed line height cache ───────────────────────────────────
-    /** Cached measured height per feed line index. Invalidated on width change. */
-    _feedHeightCache = [];
-    /** The content width used for the last height cache pass. */
-    _feedHeightCacheWidth = -1;
-    // ── Scrollbar state ───────────────────────────────────────────
-    /** Cached from last render for hit-testing. */
-    _scrollbarX = -1;
-    _feedY = 0;
-    _feedH = 0;
-    _thumbPos = 0;
-    _thumbSize = 0;
-    _maxScroll = 0;
-    _scrollbarVisible = false;
-    /** True while the user is dragging the scrollbar thumb. */
-    _dragging = false;
-    /** The Y offset within the thumb where the drag started. */
-    _dragOffsetY = 0;
     // ── Selection state ──────────────────────────────────────────
     _selAnchor = null;
     _selEnd = null;
@@ -130,6 +109,17 @@ export class ChatView extends Control {
         // Top separator (between banner and feed)
         this._topSeparator = new _Separator(this._separatorChar, this._separatorStyle);
         this.addChild(this._topSeparator);
+        // Virtual list (scrollable feed area — owns scroll, height cache, scrollbar)
+        this._feed = new VirtualList({
+            trackStyle: this._separatorStyle,
+            thumbStyle: this._feedStyle,
+        });
+        this._feed.onRenderOverlay = (ctx, x, y, w, h) => {
+            if (this._selAnchor && this._selEnd) {
+                this._renderSelection(ctx, x, y, w, h);
+            }
+        };
+        this.addChild(this._feed);
         // Bottom separator (between feed and input area)
         this._bottomSeparator = new _Separator(this._separatorChar, this._separatorStyle);
         this.addChild(this._bottomSeparator);
@@ -247,36 +237,34 @@ export class ChatView extends Control {
     // ── Public API: Feed ───────────────────────────────────────────
     /** Append a line of plain text to the feed. Auto-scrolls to bottom. */
     appendToFeed(text, style) {
-        const line = new StyledText({
+        const content = new StyledText({
             lines: [text],
             defaultStyle: style ?? this._feedStyle,
             wrap: true,
         });
-        this._feedLines.push(line);
+        this._store.push(content);
         this._autoScrollToBottom();
         this.invalidate();
     }
     /** Append a styled line (StyledSpan) to the feed. */
     appendStyledToFeed(styledLine) {
-        const line = new StyledText({
+        const content = new StyledText({
             lines: [styledLine],
             defaultStyle: this._feedStyle,
             wrap: true,
         });
-        this._feedLines.push(line);
+        this._store.push(content);
         this._autoScrollToBottom();
         this.invalidate();
     }
     /** Append a clickable action line to the feed. Emits "action" on click. */
     appendAction(id, normalContent, hoverContent) {
-        const line = new StyledText({
+        const content = new StyledText({
             lines: [normalContent],
             defaultStyle: this._feedStyle,
             wrap: false,
         });
-        const idx = this._feedLines.length;
-        this._feedLines.push(line);
-        this._feedActions.set(idx, {
+        this._store.push(content, {
             items: [{ id, normalStyle: normalContent, hoverStyle: hoverContent }],
             normalStyle: normalContent,
         });
@@ -288,14 +276,12 @@ export class ChatView extends Control {
         if (actions.length === 0)
             return;
         const combined = this._concatSpans(actions.map((a) => a.normalStyle));
-        const line = new StyledText({
+        const content = new StyledText({
             lines: [combined],
             defaultStyle: this._feedStyle,
             wrap: false,
         });
-        const idx = this._feedLines.length;
-        this._feedLines.push(line);
-        this._feedActions.set(idx, { items: actions, normalStyle: combined });
+        this._store.push(content, { items: actions, normalStyle: combined });
         this._autoScrollToBottom();
         this.invalidate();
     }
@@ -313,49 +299,124 @@ export class ChatView extends Control {
     /** Append multiple plain lines to the feed. */
     appendLines(lines, style) {
         for (const text of lines) {
-            const line = new StyledText({
+            const content = new StyledText({
                 lines: [text],
                 defaultStyle: style ?? this._feedStyle,
                 wrap: true,
             });
-            this._feedLines.push(line);
+            this._store.push(content);
         }
         this._autoScrollToBottom();
         this.invalidate();
     }
     /** Clear everything between the banner and the input box. */
     clear() {
-        this._feedLines = [];
-        this._feedHeightCache = [];
-        this._feedActions.clear();
-        this._hoveredAction = -1;
-        this._feedScrollOffset = 0;
+        this._store.clear();
+        this._hoveredItemId = null;
+        this._feed.reset();
         this.invalidate();
     }
     /** Total number of feed lines. */
     get feedLineCount() {
-        return this._feedLines.length;
+        return this._store.length;
     }
     /** Update the content of an existing feed line by index. Also removes its action if any. */
     updateFeedLine(index, content) {
-        if (index < 0 || index >= this._feedLines.length)
+        const item = this._store.at(index);
+        if (!item)
+            return;
+        item.content.lines = [content];
+        this._feed.invalidateItem(item.id);
+        item.actions = undefined;
+        if (this._hoveredItemId === item.id)
+            this._hoveredItemId = null;
+        this.invalidate();
+    }
+    /** Update the action items on an existing action line by index. */
+    updateActionList(index, actions) {
+        const item = this._store.at(index);
+        if (!item)
+            return;
+        if (actions.length === 0)
+            return;
+        const combined = this._concatSpans(actions.map((a) => a.normalStyle));
+        item.content.lines = [combined];
+        this._feed.invalidateItem(item.id);
+        item.actions = { items: actions, normalStyle: combined };
+        if (this._hoveredItemId === item.id)
+            this._hoveredItemId = null;
+        this.invalidate();
+    }
+    // ── Insert API ──────────────────────────────────────────────────
+    // No _shiftFeedIndices needed — FeedStore handles the single array splice.
+    /** Insert a plain text line at a specific feed index. */
+    insertToFeed(atIndex, text, style) {
+        const content = new StyledText({
+            lines: [text],
+            defaultStyle: style ?? this._feedStyle,
+            wrap: true,
+        });
+        this._store.insert(atIndex, content);
+        this._autoScrollToBottom();
+        this.invalidate();
+    }
+    /** Insert a styled line at a specific feed index. */
+    insertStyledToFeed(atIndex, styledLine) {
+        const content = new StyledText({
+            lines: [styledLine],
+            defaultStyle: this._feedStyle,
+            wrap: true,
+        });
+        this._store.insert(atIndex, content);
+        this._autoScrollToBottom();
+        this.invalidate();
+    }
+    /** Insert an action list at a specific feed index. */
+    insertActionList(atIndex, actions) {
+        if (actions.length === 0)
             return;
-        this._feedLines[index].lines = [content];
-        // Invalidate cached height — content changed, may wrap differently
-        delete this._feedHeightCache[index];
-        this._feedActions.delete(index);
-        if (this._hoveredAction === index)
-            this._hoveredAction = -1;
+        const combined = this._concatSpans(actions.map((a) => a.normalStyle));
+        const content = new StyledText({
+            lines: [combined],
+            defaultStyle: this._feedStyle,
+            wrap: false,
+        });
+        this._store.insert(atIndex, content, {
+            items: actions,
+            normalStyle: combined,
+        });
+        this._autoScrollToBottom();
+        this.invalidate();
+    }
+    // ── Visibility API ────────────────────────────────────────────────
+    /** Hide or show a single feed line. Hidden lines take zero height. */
+    setFeedLineHidden(index, hidden) {
+        const item = this._store.at(index);
+        if (item)
+            item.hidden = hidden;
         this.invalidate();
     }
+    /** Hide or show a range of feed lines. */
+    setFeedLinesHidden(startIndex, count, hidden) {
+        for (let i = startIndex; i < startIndex + count; i++) {
+            const item = this._store.at(i);
+            if (item)
+                item.hidden = hidden;
+        }
+        this.invalidate();
+    }
+    /** Check if a feed line is hidden. */
+    isFeedLineHidden(index) {
+        return this._store.at(index)?.hidden === true;
+    }
     /** Scroll the feed to the bottom. */
     scrollToBottom() {
-        this._autoScrollToBottom();
+        this._feed.scrollToBottom();
         this.invalidate();
     }
     /** Scroll the feed by a delta (positive = down, negative = up). */
     scrollFeed(delta) {
-        this._feedScrollOffset = Math.max(0, this._feedScrollOffset + delta);
+        this._feed.scroll(delta);
         // Clear selection when scrolling (unless actively drag-selecting)
         if (!this._selecting && this._hasSelection()) {
             this.clearSelection();
@@ -548,6 +609,7 @@ export class ChatView extends Control {
         // Mouse events: wheel scrolling, scrollbar drag, selection, actions
         if (event.type === "mouse") {
             const me = event.event;
+            const fb = this._feed.bounds;
             if (me.type === "wheelup") {
                 this.scrollFeed(-3);
                 return true;
@@ -557,49 +619,35 @@ export class ChatView extends Control {
                 return true;
             }
             // Precompute scrollbar hit for reuse
-            const onScrollbar = this._scrollbarVisible &&
-                me.x === this._scrollbarX &&
-                me.y >= this._feedY &&
-                me.y < this._feedY + this._feedH;
-            // Scrollbar drag
-            if (this._scrollbarVisible) {
+            const onScrollbar = fb != null &&
+                this._feed.scrollbarVisible &&
+                me.x === this._feed.scrollbarX &&
+                me.y >= fb.y &&
+                me.y < fb.y + fb.height;
+            // Scrollbar drag — delegate to VirtualList
+            if (this._feed.scrollbarVisible) {
                 if (me.type === "press" && me.button === "left" && onScrollbar) {
-                    const relY = me.y - this._feedY;
-                    if (relY >= this._thumbPos &&
-                        relY < this._thumbPos + this._thumbSize) {
-                        this._dragging = true;
-                        this._dragOffsetY = relY - this._thumbPos;
-                    }
-                    else {
-                        const ratio = relY / this._feedH;
-                        this._feedScrollOffset = Math.round(ratio * this._maxScroll);
-                        this._feedScrollOffset = Math.max(0, Math.min(this._feedScrollOffset, this._maxScroll));
-                        if (this._hasSelection())
-                            this.clearSelection();
-                        this.invalidate();
-                    }
+                    this._feed.handleScrollbarPress(me.y);
+                    if (this._hasSelection())
+                        this.clearSelection();
+                    this.invalidate();
                     return true;
                 }
-                if (me.type === "move" && this._dragging) {
-                    const relY = me.y - this._feedY;
-                    const newThumbPos = relY - this._dragOffsetY;
-                    const maxThumbPos = this._feedH - this._thumbSize;
-                    const clampedPos = Math.max(0, Math.min(newThumbPos, maxThumbPos));
-                    const ratio = maxThumbPos > 0 ? clampedPos / maxThumbPos : 0;
-                    this._feedScrollOffset = Math.round(ratio * this._maxScroll);
+                if (me.type === "move" && this._feed.isDragging) {
+                    this._feed.handleScrollbarDrag(me.y);
                     if (this._hasSelection())
                         this.clearSelection();
                     this.invalidate();
                     return true;
                 }
-                if (me.type === "release" && this._dragging) {
-                    this._dragging = false;
+                if (me.type === "release" && this._feed.isDragging) {
+                    this._feed.handleScrollbarRelease();
                     return true;
                 }
             }
             // Ctrl+click to open URLs or file paths
             if (me.type === "press" && me.button === "left" && me.ctrl) {
-                const feedLineIdx = this._screenToFeedLine.get(me.y) ?? -1;
+                const feedLineIdx = this._feedLineAtScreen(me.y);
                 if (feedLineIdx >= 0) {
                     const text = this._extractFeedLineText(feedLineIdx);
                     // Collect all clickable targets: URLs and absolute file paths
@@ -624,9 +672,9 @@ export class ChatView extends Control {
                         return true;
                     }
                     if (allTargets.length > 1) {
-                        const row = this._screenToFeedRow.get(me.y) ?? 0;
-                        const col = me.x - this._feedX;
-                        const charOffset = row * this._contentWidth + col;
+                        const row = this._feed.rowAtScreen(me.y);
+                        const col = me.x - (fb?.x ?? 0);
+                        const charOffset = row * this._feed.contentWidth + col;
                         const hit = allTargets.find((t) => charOffset >= t.index && charOffset < t.index + t.text.length);
                         const target = hit ?? allTargets[0];
                         this.emit(target.type, target.text);
@@ -639,8 +687,8 @@ export class ChatView extends Control {
                 me.button === "left" &&
                 !me.ctrl &&
                 !onScrollbar) {
-                const feedLineIdx = this._screenToFeedLine.get(me.y) ?? -1;
-                const isAction = feedLineIdx >= 0 && this._feedActions.has(feedLineIdx);
+                const feedLineIdx = this._feedLineAtScreen(me.y);
+                const isAction = feedLineIdx >= 0 && !!this._store.at(feedLineIdx)?.actions;
                 if (!isAction) {
                     this._selAnchor = { x: me.x, y: me.y };
                     this._selEnd = { x: me.x, y: me.y };
@@ -652,8 +700,8 @@ export class ChatView extends Control {
             // Text selection: extend on move (with auto-scroll at edges)
             if (me.type === "move" && this._selecting) {
                 this._selEnd = { x: me.x, y: me.y };
-                const feedTop = this._feedY;
-                const feedBot = this._feedY + this._feedH;
+                const feedTop = fb?.y ?? 0;
+                const feedBot = feedTop + (fb?.height ?? 0);
                 if (me.y < feedTop) {
                     this._startSelScroll(-1);
                 }
@@ -683,27 +731,30 @@ export class ChatView extends Control {
                 return true;
             }
             // Action hover/click in feed area
-            if (this._feedActions.size > 0) {
-                const feedLineIdx = this._screenToFeedLine.get(me.y) ?? -1;
-                const entry = feedLineIdx >= 0 ? this._feedActions.get(feedLineIdx) : undefined;
+            if (this._store.hasActions) {
+                const feedLineIdx = this._feedLineAtScreen(me.y);
+                const feedItem = feedLineIdx >= 0 ? this._store.at(feedLineIdx) : undefined;
+                const entry = feedItem?.actions;
                 if (me.type === "move") {
-                    const newHover = entry ? feedLineIdx : -1;
-                    if (newHover !== this._hoveredAction ||
+                    const newHoverId = entry ? feedItem.id : null;
+                    if (newHoverId !== this._hoveredItemId ||
                         (entry && entry.items.length > 1)) {
-                        if (this._hoveredAction >= 0) {
-                            const prev = this._feedActions.get(this._hoveredAction);
-                            if (prev) {
-                                this._feedLines[this._hoveredAction].lines = [prev.normalStyle];
-                                delete this._feedHeightCache[this._hoveredAction];
+                        // Restore previous hover item to normal style
+                        if (this._hoveredItemId) {
+                            const prevItem = this._store.get(this._hoveredItemId);
+                            if (prevItem?.actions) {
+                                prevItem.content.lines = [prevItem.actions.normalStyle];
+                                this._feed.invalidateItem(prevItem.id);
                             }
                         }
-                        if (entry && newHover >= 0) {
+                        // Apply hover style to new item
+                        if (entry && feedItem) {
                             const hitItem = this._resolveActionItem(entry, me.x);
                             const hoverLine = this._buildHoverLine(entry, hitItem);
-                            this._feedLines[newHover].lines = [hoverLine];
-                            delete this._feedHeightCache[newHover];
+                            feedItem.content.lines = [hoverLine];
+                            this._feed.invalidateItem(feedItem.id);
                         }
-                        this._hoveredAction = newHover;
+                        this._hoveredItemId = newHoverId;
                         this.invalidate();
                     }
                 }
@@ -721,9 +772,16 @@ export class ChatView extends Control {
         }
         return this._input.handleInput(event);
     }
+    /** Map screen Y → feed line index (accounting for banner/separator prefix items). */
+    _feedLineAtScreen(screenY) {
+        const itemIdx = this._feed.itemIndexAtScreen(screenY);
+        return itemIdx >= this._feedItemOffset
+            ? itemIdx - this._feedItemOffset
+            : -1;
+    }
     /** Extract the plain text content of a feed line. */
     _extractFeedLineText(idx) {
-        const styledText = this._feedLines[idx];
+        const styledText = this._store.at(idx)?.content;
         if (!styledText)
             return "";
         return styledText.lines
@@ -794,6 +852,8 @@ export class ChatView extends Control {
             return;
         const W = b.width;
         const H = b.height;
+        // Build VirtualList items: banner + separator + feed items
+        this._buildVirtualListItems();
         // ── Measure fixed-height sections ────────────────────────
         // Progress text height (always 1 row when visible)
         let progressH = 0;
@@ -815,9 +875,10 @@ export class ChatView extends Control {
             const chromeH = botSepH + progressH + overrideH;
             const feedH = Math.max(0, H - chromeH);
             let y = b.y;
-            // 1. Feed area
+            // 1. Feed area — delegate to VirtualList
             if (feedH > 0) {
-                this._renderFeed(ctx, b.x, y, W, feedH);
+                this._feed.arrange({ x: b.x, y, width: W, height: feedH });
+                this._feed.render(ctx);
                 y += feedH;
             }
             // 2. Progress text
@@ -876,9 +937,10 @@ export class ChatView extends Control {
         const feedH = Math.max(0, H - fixedH);
         // ── Arrange and render each section ──────────────────────
         let y = b.y;
-        // 1. Feed area (banner + separator + feed lines all scroll together)
+        // 1. Feed area — delegate to VirtualList
         if (feedH > 0) {
-            this._renderFeed(ctx, b.x, y, W, feedH);
+            this._feed.arrange({ x: b.x, y, width: W, height: feedH });
+            this._feed.render(ctx);
             y += feedH;
         }
         // 2. Progress text (above separator, fixed — not part of scrollable feed)
@@ -939,138 +1001,20 @@ export class ChatView extends Control {
             }
         }
     }
-    // ── Feed rendering ─────────────────────────────────────────────
-    _renderFeed(ctx, x, y, width, height) {
-        // Build the list of scrollable items: banner + separator + feed lines
-        // Each item is { control, height } measured against content width.
-        const contentWidth = width - 1; // reserve 1 col for scrollbar
-        this._feedX = x;
-        this._contentWidth = contentWidth;
+    /** Build the VirtualList items array from banner + separator + feed store items. */
+    _buildVirtualListItems() {
         const items = [];
-        // Banner (if visible)
         if (this._banner.visible) {
-            const bannerSize = this._banner.measure({
-                minWidth: 0,
-                maxWidth: contentWidth,
-                minHeight: 0,
-                maxHeight: Infinity,
-            });
-            const bh = Math.max(1, bannerSize.height);
-            items.push({
-                height: bh,
-                feedLineIdx: -1,
-                render: (cx, cy, cw, ch) => {
-                    this._banner.arrange({ x: cx, y: cy, width: cw, height: ch });
-                    this._banner.render(ctx);
-                },
-            });
-            // Top separator after banner
-            items.push({
-                height: 1,
-                feedLineIdx: -1,
-                render: (cx, cy, cw, _ch) => {
-                    this._topSeparator.arrange({ x: cx, y: cy, width: cw, height: 1 });
-                    this._topSeparator.render(ctx);
-                },
-            });
+            // Banner height changes during animation — always re-measure
+            this._feed.invalidateItem("__banner__");
+            items.push({ id: "__banner__", content: this._banner });
+            items.push({ id: "__topsep__", content: this._topSeparator });
         }
-        // Feed lines — use cached heights to avoid re-measuring every line each frame.
-        // Cache is invalidated when content width changes (e.g. terminal resize).
-        if (contentWidth !== this._feedHeightCacheWidth) {
-            this._feedHeightCache = [];
-            this._feedHeightCacheWidth = contentWidth;
+        this._feedItemOffset = items.length;
+        for (const fi of this._store.items) {
+            items.push(fi);
         }
-        for (let fi = 0; fi < this._feedLines.length; fi++) {
-            const line = this._feedLines[fi];
-            let h = this._feedHeightCache[fi];
-            if (h === undefined) {
-                const lineSize = line.measure({
-                    minWidth: 0,
-                    maxWidth: contentWidth,
-                    minHeight: 0,
-                    maxHeight: Infinity,
-                });
-                h = Math.max(1, lineSize.height);
-                this._feedHeightCache[fi] = h;
-            }
-            items.push({
-                height: h,
-                feedLineIdx: fi,
-                render: (cx, cy, cw, ch) => {
-                    line.arrange({ x: cx, y: cy, width: cw, height: ch });
-                    line.render(ctx);
-                },
-            });
-        }
-        // Calculate total content height
-        let totalContentH = 0;
-        for (const item of items) {
-            totalContentH += item.height;
-        }
-        // Clamp scroll offset
-        const maxScroll = Math.max(0, totalContentH - height);
-        this._feedScrollOffset = Math.max(0, Math.min(this._feedScrollOffset, maxScroll));
-        // Clip feed area
-        ctx.pushClip({ x, y, width, height });
-        // Find the first visible item
-        let skippedRows = 0;
-        let startIdx = 0;
-        for (let i = 0; i < items.length; i++) {
-            if (skippedRows + items[i].height > this._feedScrollOffset)
-                break;
-            skippedRows += items[i].height;
-            startIdx = i + 1;
-        }
-        // Render visible items and build screen→feedLine map
-        this._screenToFeedLine.clear();
-        this._screenToFeedRow.clear();
-        let cy = y - (this._feedScrollOffset - skippedRows);
-        for (let i = startIdx; i < items.length && cy < y + height; i++) {
-            const item = items[i];
-            item.render(x, cy, contentWidth, item.height);
-            // Map screen rows to feed line index + row offset for hit-testing
-            if (item.feedLineIdx >= 0) {
-                for (let row = 0; row < item.height; row++) {
-                    const screenY = cy + row;
-                    if (screenY >= y && screenY < y + height) {
-                        this._screenToFeedLine.set(screenY, item.feedLineIdx);
-                        this._screenToFeedRow.set(screenY, row);
-                    }
-                }
-            }
-            cy += item.height;
-        }
-        // Always cache feed geometry for selection edge-detection
-        this._feedY = y;
-        this._feedH = height;
-        // Render scrollbar and cache geometry for hit-testing
-        if (height > 0 && totalContentH > height) {
-            const scrollX = x + width - 1;
-            const thumbSize = Math.max(1, Math.round((height / totalContentH) * height));
-            const thumbPos = maxScroll > 0
-                ? Math.round((this._feedScrollOffset / maxScroll) * (height - thumbSize))
-                : 0;
-            const trackStyle = this._separatorStyle;
-            const thumbStyle = this._feedStyle;
-            // Cache for mouse interaction
-            this._scrollbarX = scrollX;
-            this._thumbPos = thumbPos;
-            this._thumbSize = thumbSize;
-            this._maxScroll = maxScroll;
-            this._scrollbarVisible = true;
-            for (let row = 0; row < height; row++) {
-                const inThumb = row >= thumbPos && row < thumbPos + thumbSize;
-                ctx.drawChar(scrollX, y + row, inThumb ? "┃" : "│", inThumb ? thumbStyle : trackStyle);
-            }
-        }
-        else {
-            this._scrollbarVisible = false;
-        }
-        // Render selection highlight overlay
-        if (this._selAnchor && this._selEnd) {
-            this._renderSelection(ctx, x, y, width, height);
-        }
-        ctx.popClip();
+        this._feed.items = items;
     }
     // ── Dropdown rendering ─────────────────────────────────────────
     _renderDropdown(ctx, x, y, width, height) {
@@ -1115,10 +1059,13 @@ export class ChatView extends Control {
             [startY, endY] = [endY, startY];
             [startX, endX] = [endX, startX];
         }
+        const fb = this._feed.bounds;
+        const feedX = fb?.x ?? 0;
+        const contentW = this._feed.contentWidth;
         const lines = [];
         for (let row = startY; row <= endY; row++) {
-            const colStart = row === startY ? startX : this._feedX;
-            const colEnd = row === endY ? endX : this._feedX + this._contentWidth - 1;
+            const colStart = row === startY ? startX : feedX;
+            const colEnd = row === endY ? endX : feedX + contentW - 1;
             let line = "";
             for (let col = colStart; col <= colEnd; col++) {
                 const ch = this._ctx.readCharAbsolute(col, row);
@@ -1170,11 +1117,12 @@ export class ChatView extends Control {
             this.scrollFeed(this._selScrollDir * 3);
             // Move selEnd to keep extending the selection while scrolling
             if (this._selEnd) {
+                const fb = this._feed.bounds;
+                const feedY = fb?.y ?? 0;
+                const feedH = fb?.height ?? 0;
                 this._selEnd = {
                     x: this._selEnd.x,
-                    y: this._selScrollDir < 0
-                        ? this._feedY
-                        : this._feedY + this._feedH - 1,
+                    y: this._selScrollDir < 0 ? feedY : feedY + feedH - 1,
                 };
             }
         }, 80);
@@ -1188,8 +1136,7 @@ export class ChatView extends Control {
         this._selScrollDir = 0;
     }
     _autoScrollToBottom() {
-        // Set scroll to a very large value; it will be clamped during render
-        this._feedScrollOffset = Number.MAX_SAFE_INTEGER;
+        this._feed.autoScrollToBottom();
     }
 }
 // ── Internal: Separator line control ─────────────────────────────

package/dist/widgets/feed-store.d.ts

@@ -0,0 +1,58 @@
+/**
+ * FeedStore — Identity-based feed item collection for ChatView.
+ *
+ * Replaces the parallel index-keyed data structures (_feedLines, _feedActions,
+ * _hiddenFeedLines) with a single array of FeedItem objects. Each item has a
+ * stable unique ID so external code can reference items without worrying about
+ * index shifts on insert/remove.
+ */
+import type { StyledLine, StyledText } from "./styled-text.js";
+/** A single clickable action within an action line. */
+export interface FeedActionItem {
+    id: string;
+    normalStyle: StyledLine;
+    hoverStyle: StyledLine;
+}
+/** Entry attached to a feed item — single action or multiple side-by-side. */
+export interface FeedActionEntry {
+    /** All action items on this line. */
+    items: FeedActionItem[];
+    /** Combined normal style for the full line. */
+    normalStyle: StyledLine;
+}
+/** A single item in the feed. */
+export interface FeedItem {
+    /** Stable unique ID. Never changes after creation. */
+    readonly id: string;
+    /** The renderable content. */
+    content: StyledText;
+    /** Optional clickable actions attached to this item. */
+    actions?: FeedActionEntry;
+    /** Whether this item is currently hidden/collapsed. */
+    hidden?: boolean;
+}
+export declare class FeedStore {
+    private _items;
+    private _byId;
+    private _nextId;
+    /** Generate a stable unique ID. */
+    createId(): string;
+    /** Append an item to the end. */
+    push(content: StyledText, actions?: FeedActionEntry): FeedItem;
+    /** Insert an item at position. Existing items shift — no external bookkeeping needed. */
+    insert(index: number, content: StyledText, actions?: FeedActionEntry): FeedItem;
+    /** Get item by ID (O(1)). */
+    get(id: string): FeedItem | undefined;
+    /** Get item by position index (for rendering). */
+    at(index: number): FeedItem | undefined;
+    /** Find the current index of an item by ID. Returns -1 if not found. */
+    indexOf(id: string): number;
+    /** Number of items. */
+    get length(): number;
+    /** Read-only access to the items array (for iteration in render loops). */
+    get items(): readonly FeedItem[];
+    /** Remove all items. */
+    clear(): void;
+    /** Check if any item has actions. */
+    get hasActions(): boolean;
+}

package/dist/widgets/feed-store.js

@@ -0,0 +1,69 @@
+/**
+ * FeedStore — Identity-based feed item collection for ChatView.
+ *
+ * Replaces the parallel index-keyed data structures (_feedLines, _feedActions,
+ * _hiddenFeedLines) with a single array of FeedItem objects. Each item has a
+ * stable unique ID so external code can reference items without worrying about
+ * index shifts on insert/remove.
+ */
+// ── FeedStore ──────────────────────────────────────────────────────
+export class FeedStore {
+    _items = [];
+    _byId = new Map();
+    _nextId = 0;
+    /** Generate a stable unique ID. */
+    createId() {
+        return `f${this._nextId++}`;
+    }
+    /** Append an item to the end. */
+    push(content, actions) {
+        const item = { id: this.createId(), content, actions };
+        this._items.push(item);
+        this._byId.set(item.id, item);
+        return item;
+    }
+    /** Insert an item at position. Existing items shift — no external bookkeeping needed. */
+    insert(index, content, actions) {
+        const clamped = Math.max(0, Math.min(index, this._items.length));
+        const item = { id: this.createId(), content, actions };
+        this._items.splice(clamped, 0, item);
+        this._byId.set(item.id, item);
+        return item;
+    }
+    /** Get item by ID (O(1)). */
+    get(id) {
+        return this._byId.get(id);
+    }
+    /** Get item by position index (for rendering). */
+    at(index) {
+        return this._items[index];
+    }
+    /** Find the current index of an item by ID. Returns -1 if not found. */
+    indexOf(id) {
+        const item = this._byId.get(id);
+        if (!item)
+            return -1;
+        return this._items.indexOf(item);
+    }
+    /** Number of items. */
+    get length() {
+        return this._items.length;
+    }
+    /** Read-only access to the items array (for iteration in render loops). */
+    get items() {
+        return this._items;
+    }
+    /** Remove all items. */
+    clear() {
+        this._items = [];
+        this._byId.clear();
+    }
+    /** Check if any item has actions. */
+    get hasActions() {
+        for (const item of this._items) {
+            if (item.actions)
+                return true;
+        }
+        return false;
+    }
+}

package/dist/widgets/virtual-list.d.ts

@@ -0,0 +1,85 @@
+/**
+ * VirtualList — Reusable scrollable widget for terminal UIs.
+ *
+ * Handles virtual scrolling, height caching (by item ID), screen-to-item
+ * mapping for hit-testing, and scrollbar rendering. Extracted from ChatView
+ * as part of the widget model redesign (Phase 2).
+ */
+import type { DrawingContext, TextStyle } from "../drawing/context.js";
+import { Control } from "../layout/control.js";
+import type { Constraint, Rect, Size } from "../layout/types.js";
+/** An item renderable by VirtualList. */
+export interface VirtualListItem {
+    /** Stable unique ID (used for height cache keying). */
+    readonly id: string;
+    /** The renderable content — must support measure/arrange/render. */
+    readonly content: {
+        measure(constraint: Constraint): Size;
+        arrange(rect: Rect): void;
+        render(ctx: DrawingContext): void;
+    };
+    /** Whether this item is currently hidden (takes zero height). */
+    hidden?: boolean;
+}
+export interface VirtualListOptions {
+    /** Style for the scrollbar track. */
+    trackStyle?: TextStyle;
+    /** Style for the scrollbar thumb. */
+    thumbStyle?: TextStyle;
+}
+export declare class VirtualList extends Control {
+    private _items;
+    private _scrollOffset;
+    private _userScrolledAway;
+    private _maxScroll;
+    private _heightCache;
+    private _cacheWidth;
+    private _screenToItemIdx;
+    private _screenToRow;
+    private _scrollbarX;
+    private _scrollbarVisible;
+    private _thumbPos;
+    private _thumbSize;
+    private _dragging;
+    private _dragOffsetY;
+    private _trackStyle;
+    private _thumbStyle;
+    private _contentWidth;
+    /** Called after items render but before clip pops. For selection overlay etc. */
+    onRenderOverlay?: (ctx: DrawingContext, x: number, y: number, width: number, height: number) => void;
+    constructor(options?: VirtualListOptions);
+    set items(items: VirtualListItem[]);
+    get items(): VirtualListItem[];
+    /** Scroll by delta rows (positive = down, negative = up). */
+    scroll(delta: number): void;
+    /** Scroll to the very bottom. Resets the "scrolled away" flag. */
+    scrollToBottom(): void;
+    /** Auto-scroll to bottom if the user hasn't scrolled away. */
+    autoScrollToBottom(): void;
+    /** Whether the user has scrolled away from the bottom. */
+    get isScrolledAway(): boolean;
+    /** Invalidate cached height for a single item (e.g. after content change). */
+    invalidateItem(id: string): void;
+    /** Invalidate all cached heights. */
+    invalidateAllHeights(): void;
+    /** Reset all state (scroll, cache, maps). Used when feed is cleared. */
+    reset(): void;
+    /** Get the item index (in the items array) at a screen Y coordinate. Returns -1 if none. */
+    itemIndexAtScreen(screenY: number): number;
+    /** Get the row offset within the item at a screen Y coordinate. */
+    rowAtScreen(screenY: number): number;
+    get scrollbarVisible(): boolean;
+    get scrollbarX(): number;
+    get maxScroll(): number;
+    get contentWidth(): number;
+    get isDragging(): boolean;
+    /** Handle a mouse press on the scrollbar. */
+    handleScrollbarPress(screenY: number): void;
+    /** Handle a mouse drag on the scrollbar. */
+    handleScrollbarDrag(screenY: number): void;
+    /** Handle mouse release (end scrollbar drag). */
+    handleScrollbarRelease(): void;
+    measure(constraint: Constraint): Size;
+    arrange(rect: Rect): void;
+    render(ctx: DrawingContext): void;
+}

package/dist/widgets/virtual-list.js

@@ -0,0 +1,262 @@
+/**
+ * VirtualList — Reusable scrollable widget for terminal UIs.
+ *
+ * Handles virtual scrolling, height caching (by item ID), screen-to-item
+ * mapping for hit-testing, and scrollbar rendering. Extracted from ChatView
+ * as part of the widget model redesign (Phase 2).
+ */
+import { Control } from "../layout/control.js";
+// ── VirtualList ────────────────────────────────────────────────────
+export class VirtualList extends Control {
+    _items = [];
+    // ── Scroll state ──────────────────────────────────────────────
+    _scrollOffset = 0;
+    _userScrolledAway = false;
+    _maxScroll = 0;
+    // ── Height cache (keyed by item ID, cleared on width change) ──
+    _heightCache = new Map();
+    _cacheWidth = -1;
+    // ── Screen mapping (rebuilt each render) ──────────────────────
+    _screenToItemIdx = new Map();
+    _screenToRow = new Map();
+    // ── Scrollbar state ───────────────────────────────────────────
+    _scrollbarX = -1;
+    _scrollbarVisible = false;
+    _thumbPos = 0;
+    _thumbSize = 0;
+    _dragging = false;
+    _dragOffsetY = 0;
+    // ── Styles ────────────────────────────────────────────────────
+    _trackStyle;
+    _thumbStyle;
+    // ── Content geometry (set during render, used by callers) ─────
+    _contentWidth = 0;
+    /** Called after items render but before clip pops. For selection overlay etc. */
+    onRenderOverlay;
+    constructor(options = {}) {
+        super();
+        this._trackStyle = options.trackStyle ?? {};
+        this._thumbStyle = options.thumbStyle ?? {};
+    }
+    // ── Public: Items ─────────────────────────────────────────────
+    set items(items) {
+        this._items = items;
+    }
+    get items() {
+        return this._items;
+    }
+    // ── Public: Scroll ────────────────────────────────────────────
+    /** Scroll by delta rows (positive = down, negative = up). */
+    scroll(delta) {
+        this._scrollOffset = Math.max(0, this._scrollOffset + delta);
+        this._userScrolledAway = this._scrollOffset < this._maxScroll;
+    }
+    /** Scroll to the very bottom. Resets the "scrolled away" flag. */
+    scrollToBottom() {
+        this._userScrolledAway = false;
+        this._scrollOffset = Number.MAX_SAFE_INTEGER;
+    }
+    /** Auto-scroll to bottom if the user hasn't scrolled away. */
+    autoScrollToBottom() {
+        if (this._userScrolledAway)
+            return;
+        this._scrollOffset = Number.MAX_SAFE_INTEGER;
+    }
+    /** Whether the user has scrolled away from the bottom. */
+    get isScrolledAway() {
+        return this._userScrolledAway;
+    }
+    // ── Public: Height cache ──────────────────────────────────────
+    /** Invalidate cached height for a single item (e.g. after content change). */
+    invalidateItem(id) {
+        this._heightCache.delete(id);
+    }
+    /** Invalidate all cached heights. */
+    invalidateAllHeights() {
+        this._heightCache.clear();
+        this._cacheWidth = -1;
+    }
+    /** Reset all state (scroll, cache, maps). Used when feed is cleared. */
+    reset() {
+        this._scrollOffset = 0;
+        this._userScrolledAway = false;
+        this._maxScroll = 0;
+        this._heightCache.clear();
+        this._cacheWidth = -1;
+        this._screenToItemIdx.clear();
+        this._screenToRow.clear();
+        this._scrollbarVisible = false;
+    }
+    // ── Public: Hit-testing ───────────────────────────────────────
+    /** Get the item index (in the items array) at a screen Y coordinate. Returns -1 if none. */
+    itemIndexAtScreen(screenY) {
+        return this._screenToItemIdx.get(screenY) ?? -1;
+    }
+    /** Get the row offset within the item at a screen Y coordinate. */
+    rowAtScreen(screenY) {
+        return this._screenToRow.get(screenY) ?? 0;
+    }
+    // ── Public: Scrollbar geometry ────────────────────────────────
+    get scrollbarVisible() {
+        return this._scrollbarVisible;
+    }
+    get scrollbarX() {
+        return this._scrollbarX;
+    }
+    get maxScroll() {
+        return this._maxScroll;
+    }
+    get contentWidth() {
+        return this._contentWidth;
+    }
+    get isDragging() {
+        return this._dragging;
+    }
+    // ── Public: Scrollbar interaction ─────────────────────────────
+    /** Handle a mouse press on the scrollbar. */
+    handleScrollbarPress(screenY) {
+        const b = this.bounds;
+        if (!b)
+            return;
+        const relY = screenY - b.y;
+        if (relY >= this._thumbPos && relY < this._thumbPos + this._thumbSize) {
+            this._dragging = true;
+            this._dragOffsetY = relY - this._thumbPos;
+        }
+        else {
+            // Click-to-position
+            const ratio = relY / b.height;
+            this._scrollOffset = Math.round(ratio * this._maxScroll);
+            this._scrollOffset = Math.max(0, Math.min(this._scrollOffset, this._maxScroll));
+            this._userScrolledAway = this._scrollOffset < this._maxScroll;
+        }
+    }
+    /** Handle a mouse drag on the scrollbar. */
+    handleScrollbarDrag(screenY) {
+        const b = this.bounds;
+        if (!b || !this._dragging)
+            return;
+        const relY = screenY - b.y;
+        const newThumbPos = relY - this._dragOffsetY;
+        const maxThumbPos = b.height - this._thumbSize;
+        const clampedPos = Math.max(0, Math.min(newThumbPos, maxThumbPos));
+        const ratio = maxThumbPos > 0 ? clampedPos / maxThumbPos : 0;
+        this._scrollOffset = Math.round(ratio * this._maxScroll);
+        this._userScrolledAway = this._scrollOffset < this._maxScroll;
+    }
+    /** Handle mouse release (end scrollbar drag). */
+    handleScrollbarRelease() {
+        this._dragging = false;
+    }
+    // ── Control overrides ─────────────────────────────────────────
+    measure(constraint) {
+        const size = {
+            width: constraint.maxWidth,
+            height: constraint.maxHeight,
+        };
+        this.desiredSize = size;
+        return size;
+    }
+    arrange(rect) {
+        this.bounds = rect;
+    }
+    render(ctx) {
+        const b = this.bounds;
+        if (!b || b.width < 1 || b.height < 1)
+            return;
+        const width = b.width;
+        const height = b.height;
+        const contentWidth = width - 1; // reserve 1 col for scrollbar
+        this._contentWidth = contentWidth;
+        // Invalidate height cache on width change
+        if (contentWidth !== this._cacheWidth) {
+            this._heightCache.clear();
+            this._cacheWidth = contentWidth;
+        }
+        // Build measured visible items
+        const indices = [];
+        const heights = [];
+        for (let i = 0; i < this._items.length; i++) {
+            const item = this._items[i];
+            if (item.hidden)
+                continue;
+            let h = this._heightCache.get(item.id);
+            if (h === undefined) {
+                const size = item.content.measure({
+                    minWidth: 0,
+                    maxWidth: contentWidth,
+                    minHeight: 0,
+                    maxHeight: Infinity,
+                });
+                h = Math.max(1, size.height);
+                this._heightCache.set(item.id, h);
+            }
+            indices.push(i);
+            heights.push(h);
+        }
+        // Total content height
+        let totalContentH = 0;
+        for (const h of heights) {
+            totalContentH += h;
+        }
+        // Clamp scroll offset
+        const maxScroll = Math.max(0, totalContentH - height);
+        this._scrollOffset = Math.max(0, Math.min(this._scrollOffset, maxScroll));
+        this._maxScroll = maxScroll;
+        // Clip to our bounds
+        ctx.pushClip({ x: b.x, y: b.y, width, height });
+        // Find first visible item
+        let skippedRows = 0;
+        let startIdx = 0;
+        for (let i = 0; i < indices.length; i++) {
+            if (skippedRows + heights[i] > this._scrollOffset)
+                break;
+            skippedRows += heights[i];
+            startIdx = i + 1;
+        }
+        // Render visible items and build screen→item maps
+        this._screenToItemIdx.clear();
+        this._screenToRow.clear();
+        let cy = b.y - (this._scrollOffset - skippedRows);
+        for (let i = startIdx; i < indices.length && cy < b.y + height; i++) {
+            const itemIdx = indices[i];
+            const item = this._items[itemIdx];
+            const h = heights[i];
+            item.content.arrange({ x: b.x, y: cy, width: contentWidth, height: h });
+            item.content.render(ctx);
+            // Map screen rows to item index + row offset
+            for (let row = 0; row < h; row++) {
+                const screenY = cy + row;
+                if (screenY >= b.y && screenY < b.y + height) {
+                    this._screenToItemIdx.set(screenY, itemIdx);
+                    this._screenToRow.set(screenY, row);
+                }
+            }
+            cy += h;
+        }
+        // Render scrollbar
+        if (height > 0 && totalContentH > height) {
+            const scrollX = b.x + width - 1;
+            const thumbSize = Math.max(1, Math.round((height / totalContentH) * height));
+            const thumbPos = maxScroll > 0
+                ? Math.round((this._scrollOffset / maxScroll) * (height - thumbSize))
+                : 0;
+            this._scrollbarX = scrollX;
+            this._thumbPos = thumbPos;
+            this._thumbSize = thumbSize;
+            this._scrollbarVisible = true;
+            for (let row = 0; row < height; row++) {
+                const inThumb = row >= thumbPos && row < thumbPos + thumbSize;
+                ctx.drawChar(scrollX, b.y + row, inThumb ? "┃" : "│", inThumb ? this._thumbStyle : this._trackStyle);
+            }
+        }
+        else {
+            this._scrollbarVisible = false;
+        }
+        // Overlay callback (selection, etc.)
+        if (this.onRenderOverlay) {
+            this.onRenderOverlay(ctx, b.x, b.y, width, height);
+        }
+        ctx.popClip();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teammates/consolonia",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "description": "Terminal UI rendering engine inspired by Consolonia. Pixel-level compositing with ANSI output.",
   "type": "module",
   "main": "dist/index.js",