@gaia-ai/addon-gaia-ui 0.6.4 → 0.7.0

package/README.md

@@ -1,5 +1,5 @@
 # @gaia-ai/addon-gaia-ui
 
-GAIA TUI: interactive terminal UI (project dashboard, ticket list, ticket detail) as a dropsh `tui` renderer plugin.
+GAIA TUI: interactive terminal UI (dashboard, projects, tickets) as a dropsh `tui` renderer plugin.
 
 Part of the GAIA CLI. Install the meta package `@gaia-ai/gaia` to get the `gaia` CLI with all addons. Source: https://git.key-tec.de/keytec/gaia (gaia-cli/).

package/dist/src/Agent/Component/agent-list/index.d.ts

@@ -0,0 +1,6 @@
+import type { HostedAgent } from '../../../types.js';
+/** A fixed-column flat table for the Ticket-Agents screen: header + one line per
+ *  live agent (its label · the project/group it runs for). One physical row per
+ *  entry, so the Kernel's `1 + index` selection math holds. The agents are the
+ *  host's live set (from `list(group)`); a finished agent drops out on refresh. */
+export declare function agentListRows(agents: HostedAgent[]): string[];

package/dist/src/Agent/Component/agent-list/index.js

@@ -0,0 +1,14 @@
+import { pad } from '../../../lib/format.js';
+/** A fixed-column flat table for the Ticket-Agents screen: header + one line per
+ *  live agent (its label · the project/group it runs for). One physical row per
+ *  entry, so the Kernel's `1 + index` selection math holds. The agents are the
+ *  host's live set (from `list(group)`); a finished agent drops out on refresh. */
+export function agentListRows(agents) {
+    const header = `${pad('AGENT', 32)} PROJECT`;
+    if (agents.length === 0)
+        return [header, 'No ticket agents.'];
+    return [
+        header,
+        ...agents.map((a) => `${pad(a.label || a.id, 32)} ${a.group}`),
+    ];
+}

package/dist/src/Agent/launch.d.ts

@@ -0,0 +1,25 @@
+import type { CreateFormPayload } from '../Entity/ticket/Form/create.js';
+import type { TuiAgentService } from '../types.js';
+/** The launch intent passed to {@link TuiAgentService.launch}. */
+export type CreateLaunch = Parameters<TuiAgentService['launch']>[0];
+/**
+ * Build the `ticket:create` launch intent for a project. The prompt is a pure
+ * pointer to WORKFLOW.md (the pre-filled form is passed via
+ * `$GAIA_NEW_TICKET_INPUT`); `GAIA_ID` is never inherited (a create must not be
+ * bound to a claimed ticket).
+ */
+export declare function buildCreateLaunch(opts: {
+    project: string;
+    cwd: string;
+    specPath?: string | undefined;
+    workflow?: string | undefined;
+    createPrompt?: string | undefined;
+    label?: string | undefined;
+}): CreateLaunch;
+/**
+ * A short human label for the agent list: the description's first line (capped to 40
+ * incl. the ellipsis), else "New <workflow>". GAIA-236 AC-8: it builds the `label`
+ * `buildCreateLaunch` takes, so it belongs to the module that builds the launch
+ * intent — moved from `Service/create-form.ts` unchanged.
+ */
+export declare function shortName(payload: CreateFormPayload): string;

package/dist/src/Agent/launch.js

@@ -0,0 +1,49 @@
+// Ticket-create launch request (AC-3). Pressing `n` starts an embedded agent
+// that runs the GAIA `ticket:create` workflow. This module is pure: it builds
+// the launch intent (prompt + env) the TUI hands to the injected agent host
+// (`services.agents.launch`); the host (herdr) owns transport + layout. No
+// node-pty / @xterm, no session object.
+const CREATE_PROMPT = 'Read the repository\'s WORKFLOW.md and follow its "Create ticket" section to ' +
+    'create a new GAIA ticket. Do not start work on the new ticket.';
+/**
+ * Build the `ticket:create` launch intent for a project. The prompt is a pure
+ * pointer to WORKFLOW.md (the pre-filled form is passed via
+ * `$GAIA_NEW_TICKET_INPUT`); `GAIA_ID` is never inherited (a create must not be
+ * bound to a claimed ticket).
+ */
+export function buildCreateLaunch(opts) {
+    const env = {
+        ...process.env,
+        TERM: 'xterm-256color',
+        GAIA_PROJECT: opts.project,
+    };
+    delete env.GAIA_ID;
+    if (opts.specPath)
+        env.GAIA_NEW_TICKET_INPUT = opts.specPath;
+    if (opts.workflow)
+        env.GAIA_WORKFLOW = opts.workflow;
+    return {
+        group: opts.project,
+        cwd: opts.cwd,
+        prompt: opts.createPrompt?.trim() || CREATE_PROMPT,
+        env,
+        isNew: true,
+        ...(opts.label !== undefined ? { label: opts.label } : {}),
+    };
+}
+/**
+ * A short human label for the agent list: the description's first line (capped to 40
+ * incl. the ellipsis), else "New <workflow>". GAIA-236 AC-8: it builds the `label`
+ * `buildCreateLaunch` takes, so it belongs to the module that builds the launch
+ * intent — moved from `Service/create-form.ts` unchanged.
+ */
+export function shortName(payload) {
+    const firstLine = payload.description
+        .split('\n')
+        .map((l) => l.trim())
+        .find((l) => l.length > 0);
+    if (firstLine) {
+        return firstLine.length > 40 ? `${firstLine.slice(0, 39)}…` : firstLine;
+    }
+    return `New ${payload.workflow?.label ?? 'ticket'}`;
+}

package/dist/src/Component/section-list/index.d.ts

@@ -7,3 +7,40 @@ export declare function flattenSections(sections: Section[]): {
     lines: string[];
     boldRows: Set<number>;
 };
+/**
+ * One collapsible entry: a caret header row plus the rows shown in each state.
+ *
+ * GAIA-255 D2: the Comments tab's collapse/expand interaction and the Overview
+ * tab's Description are ONE primitive rather than two renderers that happen to
+ * agree — AC-2 asks for "the same expand interaction the Comments tab offers",
+ * and structural sharing is the only form of that claim a test can hold.
+ */
+export interface ExpandableEntry {
+    /** The header row's text, after the caret. */
+    header: string;
+    /** Rows shown while collapsed (indented like the expanded body). */
+    collapsed: string[];
+    /** Rows shown while expanded. */
+    expanded: string[];
+}
+/** The rendered rows of a list of expandable entries. */
+export interface ExpandableView {
+    lines: string[];
+    boldRows: Set<number>;
+    /** `headerRows[i]` is the row index of entry i's header — the selection map. */
+    headerRows: number[];
+    selectable: number;
+}
+/**
+ * Flatten expandable entries: one caret header row per entry (`▸` collapsed,
+ * `▾` expanded) followed by that state's rows. `headerRows[i]` is entry i's
+ * header row, which is both the highlight target and the click map (the rows are
+ * NOT uniformly spaced — an expanded entry appends its body).
+ *
+ * Zero entries render `emptyMessage` and nothing selectable, so an empty list is
+ * an explicit statement rather than a blank screen.
+ */
+export declare function flattenExpandable(entries: ExpandableEntry[], { expanded, emptyMessage, }: {
+    expanded?: ReadonlySet<number>;
+    emptyMessage: string;
+}): ExpandableView;

package/dist/src/Component/section-list/index.js

@@ -1,3 +1,25 @@
+/**
+ * Append one body row, applying the MINIMAL MARKDOWN rule: an ATX heading
+ * (`#`…`######`) renders as bold with the markers stripped — the same rule a
+ * section heading follows, styled after fit(). Bullets and code fences stay raw
+ * by design (explicit v1 decision).
+ *
+ * Extracted so `flattenSections` and `flattenExpandable` cannot answer "what does
+ * a `## Context` line render as" differently: the Description block is rendered
+ * by BOTH (flat on the piped render, expandable on the Overview tab), and a rule
+ * living in only one of them would make the same body look different depending on
+ * which renderer reached it.
+ */
+function pushRow(lines, boldRows, line) {
+    const md = /^(#{1,6})\s+(.*)$/.exec(line);
+    if (md) {
+        boldRows.add(lines.length);
+        lines.push(md[2] ?? '');
+    }
+    else {
+        lines.push(line);
+    }
+}
 // Flatten `{heading, lines}` sections into plain rows plus the indices that are
 // bold (section headings + markdown ATX headings). Headings carry NO ANSI here —
 // the draw step applies bold after fit(), so sanitizeDisplay never sees (and
@@ -8,20 +30,45 @@ export function flattenSections(sections) {
     for (const section of sections) {
         boldRows.add(lines.length);
         lines.push(section.heading);
-        for (const line of section.lines) {
-            // Minimal markdown: an ATX heading (`#`…`######`) renders as bold with the
-            // markers stripped — same rule as a section heading, styled after fit().
-            // Bullets and code fences stay raw by design (explicit v1 decision).
-            const md = /^(#{1,6})\s+(.*)$/.exec(line);
-            if (md) {
-                boldRows.add(lines.length);
-                lines.push(md[2] ?? '');
-            }
-            else {
-                lines.push(line);
-            }
-        }
+        for (const line of section.lines)
+            pushRow(lines, boldRows, line);
         lines.push('');
     }
     return { lines, boldRows };
 }
+/**
+ * Flatten expandable entries: one caret header row per entry (`▸` collapsed,
+ * `▾` expanded) followed by that state's rows. `headerRows[i]` is entry i's
+ * header row, which is both the highlight target and the click map (the rows are
+ * NOT uniformly spaced — an expanded entry appends its body).
+ *
+ * Zero entries render `emptyMessage` and nothing selectable, so an empty list is
+ * an explicit statement rather than a blank screen.
+ */
+export function flattenExpandable(entries, { expanded = new Set(), emptyMessage,
+// GAIA-255 AC-11 review: `ReadonlySet` because the render path is handed ONE
+// shared empty set for every not-yet-expanded tab (`expandedFor`) — growing
+// it here would leak one tab's expansion into all the others. The renderer
+// only ever calls `.has()`, so the narrowing costs it nothing.
+ }) {
+    if (!entries.length) {
+        return {
+            lines: [emptyMessage],
+            boldRows: new Set(),
+            headerRows: [],
+            selectable: 0,
+        };
+    }
+    const lines = [];
+    const boldRows = new Set();
+    const headerRows = [];
+    entries.forEach((entry, i) => {
+        headerRows.push(lines.length);
+        boldRows.add(lines.length);
+        lines.push(`${expanded.has(i) ? '▾' : '▸'} ${entry.header}`);
+        for (const line of expanded.has(i) ? entry.expanded : entry.collapsed) {
+            pushRow(lines, boldRows, line);
+        }
+    });
+    return { lines, boldRows, headerRows, selectable: entries.length };
+}

package/dist/src/Component/stats-panel/index.d.ts

@@ -0,0 +1,49 @@
+/** A filled bar cell. U+2588 FULL BLOCK. */
+export declare const BAR_FULL = "\u2588";
+/** An empty bar cell. U+2591 LIGHT SHADE. */
+export declare const BAR_EMPTY = "\u2591";
+/**
+ * The bar's width in display columns.
+ *
+ * `█`/`░` are narrow per `lib/width-table.ts` — neither is in `WIDE_RANGES` — so
+ * the row geometry GAIA-241's hit testing depends on is unaffected. They are NOT
+ * ASCII, though, and both are East-Asian-AMBIGUOUS: a terminal configured
+ * ambiguous-as-wide (common in CJK setups) renders them two columns and shifts
+ * every number column at runtime while every test here stays green, because the
+ * width table deliberately treats Ambiguous as narrow (the frame's box-drawing
+ * characters depend on that). Accepted rather than mitigated — spec R9. If it
+ * ever bites, the fix is an ASCII bar glyph, never a width-table change.
+ */
+export declare const BAR_WIDTH = 20;
+/** One row of a block: a name and its counts, most-significant number last. */
+export interface StatsPanelRow {
+    label: string;
+    /**
+     * The counts to print, in column order. The LAST one is what the bar
+     * measures — for a breakdown row that is the month, so a row whose day count
+     * is zero still shows the activity it actually had.
+     */
+    numbers: number[];
+}
+export interface StatsPanelOptions {
+    /**
+     * Column titles, printed as a header row above the numbers. Omitted for a
+     * single-number block, where the label already says which window it is.
+     *
+     * The mock in spec D11 hangs these titles off the block's HEADING line; they
+     * are their own row here because the heading belongs to `flattenSections`,
+     * which owns the bold-row set. Same information, one row lower, and the two
+     * components keep their boundary.
+     */
+    columns?: readonly string[] | undefined;
+    /** What to render instead of rows when there are none (spec R7). */
+    emptyMessage?: string | undefined;
+}
+/**
+ * One block's body rows: an optional column header, then one row per entry.
+ *
+ * Every column is measured with `displayWidth` (through `pad`/`padNumber`), so a
+ * wide-character label cannot shift the numbers out of alignment — the failure
+ * that makes a table of counts unreadable exactly when the data is interesting.
+ */
+export declare function statsPanelRows(rows: readonly StatsPanelRow[], { columns, emptyMessage }?: StatsPanelOptions): string[];

package/dist/src/Component/stats-panel/index.js

@@ -0,0 +1,114 @@
+import { pad } from '../../lib/format.js';
+import { displayWidth } from '../../lib/width.js';
+// GAIA-256 spec D11 — the Dashboard's `/usage`-style bar rows.
+//
+// A SHARED component (the third in `src/Component/`), and it earns that place by
+// carrying no entity vocabulary at all: it takes `{ label, numbers }` and draws
+// bars. Nothing here knows a ticket from a run from a project — which is exactly
+// what G4 asserts, and why the Dashboard can render four different blocks from
+// one function.
+//
+// It produces the ROWS OF ONE BLOCK. Stacking blocks under bold headings is
+// `flattenSections`' job (`Component/section-list`), unchanged: this component
+// only fills a block's body.
+/** A filled bar cell. U+2588 FULL BLOCK. */
+export const BAR_FULL = '█';
+/** An empty bar cell. U+2591 LIGHT SHADE. */
+export const BAR_EMPTY = '░';
+/**
+ * The bar's width in display columns.
+ *
+ * `█`/`░` are narrow per `lib/width-table.ts` — neither is in `WIDE_RANGES` — so
+ * the row geometry GAIA-241's hit testing depends on is unaffected. They are NOT
+ * ASCII, though, and both are East-Asian-AMBIGUOUS: a terminal configured
+ * ambiguous-as-wide (common in CJK setups) renders them two columns and shifts
+ * every number column at runtime while every test here stays green, because the
+ * width table deliberately treats Ambiguous as narrow (the frame's box-drawing
+ * characters depend on that). Accepted rather than mitigated — spec R9. If it
+ * ever bites, the fix is an ASCII bar glyph, never a width-table change.
+ */
+export const BAR_WIDTH = 20;
+/**
+ * The label column, in display columns: 26 for the text plus {@link LABEL_GAP}.
+ *
+ * The text budget is wide enough for the longest label the Dashboard actually
+ * builds: a breakdown row suffixes its entity type (`gaia · tickets`), the
+ * unattributed bucket's `— unattributed · tickets` is 24 columns and a real
+ * project name reaches 26 (`gaia-e2e-project · tickets`). At 18 that suffix was
+ * cut to `— unattributed · t…`, which silently made the two entity types
+ * indistinguishable in exactly the row where attribution is already unclear.
+ */
+const LABEL_WIDTH = 27;
+/**
+ * Columns of the label field reserved as the gap before the bar.
+ *
+ * Load-bearing, not decoration. `pad` fills a label to exactly `LABEL_WIDTH`, so
+ * a label of precisely that width left NO separator and the row rendered
+ * `gaia-e2e-project · tickets████████` — a real project name, at exactly 26
+ * columns. A truncated label collided the same way, ending in `…` against the
+ * bar. Every fixture in the tests was shorter, which is why the suite was green
+ * while the screen was wrong; the gap is part of the geometry now so the label
+ * length cannot decide whether it exists.
+ *
+ * It is ADDED to the field rather than taken out of it: the 26 columns above are
+ * a content budget with a stated reason, and spending one of them on the gap
+ * would cut `gaia-e2e-project · tickets` to `gaia-e2e-project · ticke…` — losing
+ * exactly the entity-type suffix that tells the two rows of a project apart.
+ */
+const LABEL_GAP = 1;
+/** One number column, in display columns. */
+const NUMBER_WIDTH = 8;
+/** The indent every row of a block carries, matching the other body renderers. */
+const INDENT = '  ';
+/** `value` right-aligned to `width` DISPLAY columns — the number columns' rule. */
+function padNumber(value, width) {
+    const gap = Math.max(0, width - displayWidth(value));
+    return ' '.repeat(gap) + value;
+}
+/**
+ * The bar for `value` within a group whose largest bar value is `max`.
+ *
+ * Scaled RELATIVE TO THE LARGEST VALUE IN ITS OWN GROUP, not to a limit. This is
+ * the one place the `/usage` analogy does not carry: `/usage` measures against a
+ * quota, and there is no quota here — so a full bar means "the biggest of these",
+ * never "100 %". An all-zero group has no maximum to scale by and renders empty
+ * rather than dividing by zero.
+ */
+function bar(value, max) {
+    const filled = max > 0
+        ? Math.max(0, Math.min(BAR_WIDTH, Math.round((value / max) * BAR_WIDTH)))
+        : 0;
+    return BAR_FULL.repeat(filled) + BAR_EMPTY.repeat(BAR_WIDTH - filled);
+}
+/**
+ * One block's body rows: an optional column header, then one row per entry.
+ *
+ * Every column is measured with `displayWidth` (through `pad`/`padNumber`), so a
+ * wide-character label cannot shift the numbers out of alignment — the failure
+ * that makes a table of counts unreadable exactly when the data is interesting.
+ */
+export function statsPanelRows(rows, { columns, emptyMessage } = {}) {
+    if (rows.length === 0) {
+        return emptyMessage === undefined ? [] : [`${INDENT}${emptyMessage}`];
+    }
+    const barValue = (row) => row.numbers.at(-1) ?? 0;
+    const max = Math.max(...rows.map(barValue));
+    const out = [];
+    if (columns && columns.length > 0) {
+        out.push(INDENT +
+            pad('', LABEL_WIDTH) +
+            ' '.repeat(BAR_WIDTH) +
+            columns.map((c) => padNumber(c, NUMBER_WIDTH)).join(''));
+    }
+    for (const row of rows) {
+        out.push(INDENT +
+            // Padded to the field width MINUS the gap, then the gap: the label
+            // column stays `LABEL_WIDTH` wide either way, so the header row above
+            // and every bar below still line up.
+            pad(row.label, LABEL_WIDTH - LABEL_GAP) +
+            ' '.repeat(LABEL_GAP) +
+            bar(barValue(row), max) +
+            row.numbers.map((n) => padNumber(String(n), NUMBER_WIDTH)).join(''));
+    }
+    return out;
+}

package/dist/src/Component/tab-bar/index.d.ts

@@ -7,3 +7,14 @@ export interface DetailTab {
 export declare const DETAIL_TABS: DetailTab[];
 /** The tab bar as a single row; the active tab is bracketed. */
 export declare function tabBar(activeIndex: number): string;
+/** Where one detail tab sits inside the bar: `[start, end)` in display columns
+ *  from the bar's own first column. */
+export interface DetailTabSpan {
+    index: number;
+    start: number;
+    end: number;
+}
+/** The bar's own hit map, built from the SAME `segment`/`SEPARATOR` the rendered
+ *  bar is joined from — see `Component/top-tabs/index.ts`'s `topTabSpans` for the
+ *  full argument. */
+export declare function detailTabSpans(activeIndex: number): DetailTabSpan[];

package/dist/src/Component/tab-bar/index.js

@@ -1,3 +1,4 @@
+import { displayWidth } from '../../lib/width.js';
 // The ticket-detail screen is split into tabs so only one tab's content draws at
 // a time (keeps the fixed-height window small) — Sub-tickets + Referenced share a
 // Related tab, Comments is its own tab with collapsible entries (owned by the
@@ -16,7 +17,26 @@ export const DETAIL_TABS = [
     },
     { id: 'runs', label: 'Runs', headings: ['Runs'] },
 ];
+/** What joins two tabs in the rendered bar — part of neither tab's span. */
+const SEPARATOR = ' ';
+/** One tab's rendered segment: bracketed when active, space-padded otherwise. */
+const segment = (tab, index, activeIndex) => index === activeIndex ? `[${tab.label}]` : ` ${tab.label} `;
 /** The tab bar as a single row; the active tab is bracketed. */
 export function tabBar(activeIndex) {
-    return DETAIL_TABS.map((t, i) => i === activeIndex ? `[${t.label}]` : ` ${t.label} `).join(' ');
+    return DETAIL_TABS.map((t, i) => segment(t, i, activeIndex)).join(SEPARATOR);
+}
+/** The bar's own hit map, built from the SAME `segment`/`SEPARATOR` the rendered
+ *  bar is joined from — see `Component/top-tabs/index.ts`'s `topTabSpans` for the
+ *  full argument. */
+export function detailTabSpans(activeIndex) {
+    const spans = [];
+    let start = 0;
+    DETAIL_TABS.forEach((tab, index) => {
+        if (index > 0)
+            start += displayWidth(SEPARATOR);
+        const width = displayWidth(segment(tab, index, activeIndex));
+        spans.push({ index, start, end: start + width });
+        start += width;
+    });
+    return spans;
 }

package/dist/src/Component/ticket-detail/index.d.ts

@@ -1,6 +1,14 @@
 import type { TicketDetailDocument } from '../../types.js';
 import type { CommentItem } from '../comment-item/index.js';
 import type { Section } from '../section-list/index.js';
+/**
+ * The `expandedComments` set a freshly opened ticket detail starts with: the
+ * newest comment expanded, every older one collapsed.
+ *
+ * It lives beside the sort on purpose — "index 0 is the newest" is one module's
+ * invariant, so the kernel never needs to know which index that is.
+ */
+export declare function initialExpandedComments(document: TicketDetailDocument): Set<number>;
 /**
  * The ticket detail sections, each with an explicit empty state:
  * Description, Comments, Sub-tickets, Runs, Referenced tickets, Links,

package/dist/src/Component/ticket-detail/index.js

@@ -19,8 +19,71 @@ function refCount(document, name) {
     const data = document.data?.relationships?.[name]?.data;
     return Array.isArray(data) ? data.length : data ? 1 : 0;
 }
+/**
+ * Newest-first — the exact reversal of the server's total order
+ * (`CommentsItemList`: `created ASC, id ASC`), three keys applied in turn:
+ * `created` DESC, then `drupal_internal__id` DESC (the server's own monotonic
+ * key, so two comments written in the same second keep the server's relative
+ * order, reversed), then the resource `id` DESC.
+ *
+ * The third key exists to make the comparator TOTAL rather than leaning on
+ * `Array.prototype.sort` being stable in modern V8: the order must be
+ * *deterministic* — identical for the same comments in any input order, and
+ * defined even for a fixture or partial include that carries no
+ * `drupal_internal__id`. Stability would only preserve whatever order the
+ * include happened to arrive in.
+ *
+ * A missing or unparseable `created` sorts LAST (treated as the oldest), so a
+ * malformed row can never take the top slot and steal the default expansion.
+ */
+function compareCommentsNewestFirst(a, b) {
+    const at = Date.parse(asString(a.attributes?.created) ?? '');
+    const bt = Date.parse(asString(b.attributes?.created) ?? '');
+    const aUnknown = Number.isNaN(at);
+    const bUnknown = Number.isNaN(bt);
+    if (aUnknown !== bUnknown)
+        return aUnknown ? 1 : -1;
+    if (!aUnknown && at !== bt)
+        return bt - at;
+    const ai = Number(a.attributes?.drupal_internal__id);
+    const bi = Number(b.attributes?.drupal_internal__id);
+    if (!Number.isNaN(ai) && !Number.isNaN(bi) && ai !== bi)
+        return bi - ai;
+    // Code-unit comparison, not localeCompare: a locale-sensitive collation would
+    // put the "deterministic" back in the hands of the runtime's locale data.
+    const aid = a.id ?? '';
+    const bid = b.id ?? '';
+    return aid === bid ? 0 : aid < bid ? 1 : -1;
+}
+/**
+ * The document's `gaia_comment` includes, NEWEST FIRST.
+ *
+ * This is the single function both renderings read — `detailSections`' Comments
+ * section (→ `detailLines`, the non-TTY render) and `commentItems` (→ the
+ * interactive Comments tab) — so newest-first is one line of code and the two
+ * orders structurally cannot drift.
+ *
+ * It sorts the copy `filter` already allocated and NEVER `document.included`
+ * itself: that array is mixed (comments *plus* sub-tickets, runs and referenced
+ * tickets) and shared with those consumers, so an in-place sort would be an
+ * invisible side effect on someone else's input.
+ */
 function commentResources(document) {
-    return (document.included ?? []).filter((r) => r.type === 'gaia_comment--gaia_comment');
+    return (document.included ?? [])
+        .filter((r) => r.type === 'gaia_comment--gaia_comment')
+        .sort(compareCommentsNewestFirst);
+}
+/**
+ * The `expandedComments` set a freshly opened ticket detail starts with: the
+ * newest comment expanded, every older one collapsed.
+ *
+ * It lives beside the sort on purpose — "index 0 is the newest" is one module's
+ * invariant, so the kernel never needs to know which index that is.
+ */
+export function initialExpandedComments(document) {
+    return commentResources(document).length
+        ? new Set([0])
+        : new Set();
 }
 /**
  * The ticket detail sections, each with an explicit empty state:
@@ -108,9 +171,10 @@ export function commentItems(document) {
         return { type, author, created, bodyLines, preview: bodyLines[0] ?? '' };
     });
 }
-// The whole ticket-detail document flattened (all sections). Reserved helper —
-// currently unused by the interactive screen (which renders one tab at a time
-// via tabViewLines); kept as a tested convenience for a full-document render.
+// The whole ticket-detail document flattened (all sections) — the NON-TTY ticket
+// render, printed verbatim by the kernel when stdout is not a terminal
+// (`Kernel/tui-kernel.ts:147`), i.e. what `gaia ui GAIA-nnn | cat` shows. The
+// interactive screen renders one tab at a time via tabViewLines instead.
 export function detailLines(detail) {
     return flattenSections(detailSections(detail ?? {}));
 }