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

package/dist/src/Component/top-tabs/index.d.ts

@@ -10,6 +10,9 @@ export declare const ROOT_TABS: readonly [{
 }, {
     readonly id: "projects";
     readonly label: "Projects";
+}, {
+    readonly id: "conductors";
+    readonly label: "Conductors";
 }];
 /** The project level: the tabs of an opened project. */
 export declare const PROJECT_TABS: readonly [{
@@ -25,6 +28,40 @@ export declare const PROJECT_TABS: readonly [{
     readonly id: "runs";
     readonly label: "Runs";
 }];
+/**
+ * The ticket level: the sections of ONE OPEN TICKET — GAIA-346.
+ *
+ * The third level this file's GAIA-239 comment has described since it was
+ * written, arriving with the change that needed it. What is new is not the level
+ * but where it is DRAWN: that comment reserved it for "the header box's meta row,
+ * so no top-level bar at all", and the operator's ruling is the opposite — the
+ * sections belong in the bar every other level uses, and the ticket detail keeps
+ * no tab row of its own.
+ *
+ * These entries are NOT destinations. A section is a mode of the one ticket
+ * route: switching one runs no `Router.navigate`, so the screen instance, its
+ * document and its per-section state are untouched (spec D1/F3). The kernel
+ * learns that from the screen, through `Screen.selectTopTab`, and not from a
+ * level name — nothing in this file distinguishes a mode from a destination, and
+ * nothing should.
+ *
+ * `runs` is declared here AND on the project level, which GAIA-256 D2 already
+ * made legal: ids are not globally unique, every function is level-parameterised,
+ * and one bar is on screen at a time.
+ */
+export declare const TICKET_TABS: readonly [{
+    readonly id: "overview";
+    readonly label: "Overview";
+}, {
+    readonly id: "comments";
+    readonly label: "Comments";
+}, {
+    readonly id: "related";
+    readonly label: "Related";
+}, {
+    readonly id: "runs";
+    readonly label: "Runs";
+}];
 /** The tab bars, keyed by level — the one place a level is named. */
 export declare const TAB_LEVELS: {
     readonly root: readonly [{
@@ -33,6 +70,9 @@ export declare const TAB_LEVELS: {
     }, {
         readonly id: "projects";
         readonly label: "Projects";
+    }, {
+        readonly id: "conductors";
+        readonly label: "Conductors";
     }];
     readonly project: readonly [{
         readonly id: "dashboard";
@@ -47,6 +87,19 @@ export declare const TAB_LEVELS: {
         readonly id: "runs";
         readonly label: "Runs";
     }];
+    readonly ticket: readonly [{
+        readonly id: "overview";
+        readonly label: "Overview";
+    }, {
+        readonly id: "comments";
+        readonly label: "Comments";
+    }, {
+        readonly id: "related";
+        readonly label: "Related";
+    }, {
+        readonly id: "runs";
+        readonly label: "Runs";
+    }];
 };
 /** The name of a level that carries a top-level tab bar. */
 export type TabLevel = keyof typeof TAB_LEVELS;
@@ -71,6 +124,29 @@ export type TabLocation = {
         tab: TabIdOf<L>;
     };
 }[TabLevel];
+/**
+ * The bar as the PIECES it is drawn from: one part per tab, carrying that tab's
+ * id, with the joins between them carrying none.
+ *
+ * GAIA-340 Task 11 (spec D6) — this replaces `topTabSpans`, which published the
+ * same layout as `[start, end)` COLUMN ranges for the kernel to resolve a click
+ * against. The bar is a row of renderables now (`Kernel/chrome.ts`), so "which
+ * tab is under the pointer" is answered by the renderer's own hit test — the
+ * part the pointer landed on IS a node, and its id names its tab. A column map
+ * beside that would be a second answer to a question the renderer already
+ * answers, and it needed `displayWidth` to build, which is exactly the string
+ * measurement this ticket exists to delete (R5/D8).
+ *
+ * The argument the spans made survives unchanged, and is why the parts are here
+ * rather than in the chrome: {@link topTabBar} is these parts JOINED, so the
+ * rendered bar and the clickable pieces are two readings of one expression and
+ * cannot drift apart.
+ */
+export interface TabBarPart<Id extends string = TopTabId> {
+    /** The tab this piece is, or absent for the join between two tabs. */
+    readonly tab?: Id;
+    readonly text: string;
+}
 /**
  * One level's tab bar as a single row; the active tab is bracketed.
  *
@@ -78,6 +154,17 @@ export type TabLocation = {
  * at compile time now that there is more than one bar. `topTabBar('root', 'runs')`
  * is a TS2345 naming the root level's valid ids — not a bar that silently
  * brackets nothing.
+ *
+ * NO PRODUCT CALLER SINCE GAIA-340 Task 11, and KEPT — the decision, so it is not
+ * re-litigated. The chrome draws the bar as one node per tab (`tabPartsFor`), so
+ * the only readers of this and of {@link tabBarFor} are four suites that pin the
+ * bar's picture. They are what those pins compare the RENDERED row against, and
+ * the alternative is transcribing the bar into each of them as a literal — a
+ * hand-copied reference cannot notice a label change, where this one is
+ * `renderParts(…).join('')`, i.e. the same expression the chrome's nodes come
+ * from. Two readings of one source cannot drift into two answers; a literal and a
+ * source can. That is the same argument spec D6 makes for moving an independent
+ * reference rather than dropping it, and it costs ten lines and no measurement.
  */
 export declare function topTabBar<L extends TabLevel>(level: L, activeId: TabIdOf<L>): string;
 /**
@@ -87,37 +174,22 @@ export declare function topTabBar<L extends TabLevel>(level: L, activeId: TabIdO
  * not ask the compiler to correlate two independently narrowed properties.
  */
 export declare function tabBarFor(location: TabLocation): string;
-/** Where one tab sits inside the bar: `[start, end)` in display columns from the
- *  bar's own first column. */
-export interface TopTabSpan<Id extends string = TopTabId> {
-    id: Id;
-    start: number;
-    end: number;
-}
 /**
- * One level's own hit map, built from the SAME `segment`/`SEPARATOR` that level's
- * rendered bar is joined from — so the layout and the click mapping are two
- * readings of one expression and cannot drift apart. That is the argument
- * `lib/hit-test.ts` makes for the body rows, applied to a column axis.
- *
- * Offsets are display columns, which is the unit a mouse report carries. For the
- * current ASCII labels that coincides with string offsets, which is what lets
- * the test slice `topTabBar()` with a span and compare.
+ * One level's own bar as its clickable pieces — see {@link TabBarPart}.
  *
  * GAIA-239: the LEVEL is part of the signature, exactly as it is for
  * {@link topTabBar}, and for the same reason twice over. GAIA-241 shipped one
  * `topTabSpans(activeId)` over the single flat bar; read level-blind it would
- * publish the project bar's three spans on the root screen too, so a click at
- * the column where `Ticket-Agents` used to sit would open a tab that screen does
- * not draw — the very defect this ticket removes, arriving through the mouse.
- * A map and a bar of two different levels is now a TS2345, not a silent
- * mis-click.
+ * publish the project bar's pieces on the root screen too, so a click where
+ * `Ticket-Agents` sits on the other level would open a tab that screen does not
+ * draw — the very defect GAIA-239 removed, arriving through the mouse. Pieces
+ * and bar of two different levels is a TS2345, not a silent mis-click.
  */
-export declare function topTabSpans<L extends TabLevel>(level: L, activeId: TabIdOf<L>): TopTabSpan<TabIdOf<L>>[];
+export declare function topTabParts<L extends TabLevel>(level: L, activeId: TabIdOf<L>): TabBarPart<TabIdOf<L>>[];
 /**
- * The same hit map, for a caller holding a whole {@link TabLocation} — the
+ * The same pieces, for a caller holding a whole {@link TabLocation} — the
  * companion of {@link tabBarFor}, and the pairing it needs was already checked
  * when the location was built. Keeping the two in step is what makes "the bar you
  * see is the bar you click" true by construction: both read `location`.
  */
-export declare function tabSpansFor(location: TabLocation): TopTabSpan[];
+export declare function tabPartsFor(location: TabLocation): TabBarPart[];

package/dist/src/Component/top-tabs/index.js

@@ -1,4 +1,3 @@
-import { displayWidth } from '../../lib/width.js';
 // GAIA-239: THE registry — the single place the set, the order and the labels of
 // the top-level tabs are written. Navigation has THREE levels, and every screen
 // shows exactly ONE tab bar: the one of its own level.
@@ -6,9 +5,9 @@ import { displayWidth } from '../../lib/width.js';
 //   root     dashboard, projects, project-picker  → Dashboard · Projects
 //   project  dashboard, project, ticket-agents,   → Dashboard · Tickets ·
 //            project-runs                           Ticket-Agents · Runs
-//   ticket   ticket                               → the DETAIL tabs, drawn as the
-//                                                    header box's meta row, so no
-//                                                    top-level bar at all
+//   ticket   overview, comments, related, runs    → the sections of one open
+//                                                    ticket, in the bar row every
+//                                                    other level uses (GAIA-346)
 //
 // `tickets` is the project/ticket drill-down; `ticket-agents` is the managed
 // create-agent list (GAIA-190); `runs` is the project-scoped run overview
@@ -26,15 +25,23 @@ import { displayWidth } from '../../lib/width.js';
 // `topTabSpans(level, id)`, `tabBarFor(location)`, `TabIdOf<L>`). It was a
 // property of ONE function, the level-blind `locateTab`, which walked the levels
 // in key order and would now resolve the project level's `dashboard` to the ROOT
-// location. `gotoTopTab` was its only caller, and it only ever moves within one
+// location. Top-tab navigation was its only caller, and it only moves within one
 // level — the bar you Tab through or click IS the current level's bar — so it
 // pairs the target with `here.level` directly and `locateTab` is deleted.
 //
-// Only tabs that are actually navigable are listed. A planned screen (`Users` on
-// the root level, `Conductors` on the project level) arrives with its own ticket
-// and adds its entry here then — a tab drawn before its screen exists would
-// advertise navigation the operator cannot take, which is the very defect
-// GAIA-239 removes.
+// Only tabs that are actually navigable are listed. A planned screen (`Users`)
+// arrives with its own ticket and adds its entry here then — a tab drawn before
+// its screen exists would advertise navigation the operator cannot take, which
+// is the very defect GAIA-239 removes.
+//
+// GAIA-232 added `conductors`, and put it on the ROOT level although the note
+// above once reserved it for the project level. A conductor is an operator
+// concern: "is my conductor alive?" has to be answerable without first choosing
+// a project, and one conductor commonly serves work across a checkout rather
+// than sitting inside one project's screen. Which project it serves is a COLUMN
+// of that screen, not a navigation level above it. Being an ordinary entry here
+// is also what keeps it inside the derived id union and gives it GAIA-241's
+// click spans for free.
 //
 // `as const satisfies` is load-bearing on both halves: `satisfies` still
 // shape-checks every entry against `TopTab`, while `as const` keeps the literal
@@ -45,6 +52,7 @@ import { displayWidth } from '../../lib/width.js';
 export const ROOT_TABS = [
     { id: 'dashboard', label: 'Dashboard' },
     { id: 'projects', label: 'Projects' },
+    { id: 'conductors', label: 'Conductors' },
 ];
 /** The project level: the tabs of an opened project. */
 export const PROJECT_TABS = [
@@ -53,16 +61,49 @@ export const PROJECT_TABS = [
     { id: 'ticket-agents', label: 'Ticket-Agents' },
     { id: 'runs', label: 'Runs' },
 ];
+/**
+ * The ticket level: the sections of ONE OPEN TICKET — GAIA-346.
+ *
+ * The third level this file's GAIA-239 comment has described since it was
+ * written, arriving with the change that needed it. What is new is not the level
+ * but where it is DRAWN: that comment reserved it for "the header box's meta row,
+ * so no top-level bar at all", and the operator's ruling is the opposite — the
+ * sections belong in the bar every other level uses, and the ticket detail keeps
+ * no tab row of its own.
+ *
+ * These entries are NOT destinations. A section is a mode of the one ticket
+ * route: switching one runs no `Router.navigate`, so the screen instance, its
+ * document and its per-section state are untouched (spec D1/F3). The kernel
+ * learns that from the screen, through `Screen.selectTopTab`, and not from a
+ * level name — nothing in this file distinguishes a mode from a destination, and
+ * nothing should.
+ *
+ * `runs` is declared here AND on the project level, which GAIA-256 D2 already
+ * made legal: ids are not globally unique, every function is level-parameterised,
+ * and one bar is on screen at a time.
+ */
+export const TICKET_TABS = [
+    { id: 'overview', label: 'Overview' },
+    { id: 'comments', label: 'Comments' },
+    { id: 'related', label: 'Related' },
+    { id: 'runs', label: 'Runs' },
+];
 /** The tab bars, keyed by level — the one place a level is named. */
 export const TAB_LEVELS = {
     root: ROOT_TABS,
     project: PROJECT_TABS,
+    ticket: TICKET_TABS,
 };
 /** 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, activeId) => tab.id === activeId ? `[${tab.label}]` : ` ${tab.label} `;
-const renderBar = (tabs, activeId) => tabs.map((t) => segment(t, activeId)).join(SEPARATOR);
+const renderParts = (tabs, activeId) => tabs.flatMap((tab, index) => index === 0
+    ? [{ tab: tab.id, text: segment(tab, activeId) }]
+    : [{ text: SEPARATOR }, { tab: tab.id, text: segment(tab, activeId) }]);
+const renderBar = (tabs, activeId) => renderParts(tabs, activeId)
+    .map((part) => part.text)
+    .join('');
 /**
  * One level's tab bar as a single row; the active tab is bracketed.
  *
@@ -70,6 +111,17 @@ const renderBar = (tabs, activeId) => tabs.map((t) => segment(t, activeId)).join
  * at compile time now that there is more than one bar. `topTabBar('root', 'runs')`
  * is a TS2345 naming the root level's valid ids — not a bar that silently
  * brackets nothing.
+ *
+ * NO PRODUCT CALLER SINCE GAIA-340 Task 11, and KEPT — the decision, so it is not
+ * re-litigated. The chrome draws the bar as one node per tab (`tabPartsFor`), so
+ * the only readers of this and of {@link tabBarFor} are four suites that pin the
+ * bar's picture. They are what those pins compare the RENDERED row against, and
+ * the alternative is transcribing the bar into each of them as a literal — a
+ * hand-copied reference cannot notice a label change, where this one is
+ * `renderParts(…).join('')`, i.e. the same expression the chrome's nodes come
+ * from. Two readings of one source cannot drift into two answers; a literal and a
+ * source can. That is the same argument spec D6 makes for moving an independent
+ * reference rather than dropping it, and it costs ten lines and no measurement.
  */
 export function topTabBar(level, activeId) {
     return renderBar(TAB_LEVELS[level], activeId);
@@ -83,46 +135,40 @@ export function topTabBar(level, activeId) {
 export function tabBarFor(location) {
     return renderBar(TAB_LEVELS[location.level], location.tab);
 }
-const renderSpans = (tabs, activeId) => {
-    const spans = [];
-    let start = 0;
-    tabs.forEach((tab, index) => {
-        if (index > 0)
-            start += displayWidth(SEPARATOR);
-        const width = displayWidth(segment(tab, activeId));
-        spans.push({ id: tab.id, start, end: start + width });
-        start += width;
-    });
-    return spans;
-};
+// GAIA-256 spec D2 — `locateTab` USED TO LIVE HERE and is deliberately gone.
+//
+// It answered "which level declares this tab id" by walking `TAB_LEVELS` in key
+// order, which made it level-blind and made globally-unique ids a requirement of
+// the whole model. Its single caller was top-tab navigation (no test covered it),
+// and that was always the wrong tool there: navigation moves within ONE level,
+// so the level is already in its hand. There are three levels and TWO shared ids
+// now: `root` and `project` both name a `dashboard`, and since GAIA-346 `project`
+// and `ticket` both name a `runs`. A level-blind walk in key order would resolve
+// the project Dashboard to the ROOT location, and the ticket's Runs SECTION to
+// the project's Runs SCREEN — each drawing the wrong bar for a whole load. The
+// kernel pairs the target with `here.level` instead — sound by construction,
+// because the target came from that level's own registry in both callers — and
+// the requirement disappears with the function.
 /**
- * One level's own hit map, built from the SAME `segment`/`SEPARATOR` that level's
- * rendered bar is joined from — so the layout and the click mapping are two
- * readings of one expression and cannot drift apart. That is the argument
- * `lib/hit-test.ts` makes for the body rows, applied to a column axis.
- *
- * Offsets are display columns, which is the unit a mouse report carries. For the
- * current ASCII labels that coincides with string offsets, which is what lets
- * the test slice `topTabBar()` with a span and compare.
+ * One level's own bar as its clickable pieces — see {@link TabBarPart}.
  *
  * GAIA-239: the LEVEL is part of the signature, exactly as it is for
  * {@link topTabBar}, and for the same reason twice over. GAIA-241 shipped one
  * `topTabSpans(activeId)` over the single flat bar; read level-blind it would
- * publish the project bar's three spans on the root screen too, so a click at
- * the column where `Ticket-Agents` used to sit would open a tab that screen does
- * not draw — the very defect this ticket removes, arriving through the mouse.
- * A map and a bar of two different levels is now a TS2345, not a silent
- * mis-click.
+ * publish the project bar's pieces on the root screen too, so a click where
+ * `Ticket-Agents` sits on the other level would open a tab that screen does not
+ * draw — the very defect GAIA-239 removed, arriving through the mouse. Pieces
+ * and bar of two different levels is a TS2345, not a silent mis-click.
  */
-export function topTabSpans(level, activeId) {
-    return renderSpans(TAB_LEVELS[level], activeId);
+export function topTabParts(level, activeId) {
+    return renderParts(TAB_LEVELS[level], activeId);
 }
 /**
- * The same hit map, for a caller holding a whole {@link TabLocation} — the
+ * The same pieces, for a caller holding a whole {@link TabLocation} — the
  * companion of {@link tabBarFor}, and the pairing it needs was already checked
  * when the location was built. Keeping the two in step is what makes "the bar you
  * see is the bar you click" true by construction: both read `location`.
  */
-export function tabSpansFor(location) {
-    return renderSpans(TAB_LEVELS[location.level], location.tab);
+export function tabPartsFor(location) {
+    return renderParts(TAB_LEVELS[location.level], location.tab);
 }

package/dist/src/Entity/collection.d.ts

@@ -0,0 +1,279 @@
+import type { VNode } from '@opentui/core';
+import type { SectionLine } from '../Component/section-list/index.js';
+import type { DropshClient, JsonApiResource } from '../types.js';
+/** A JSON:API collection document (the raw shape `client.get` returns). */
+export interface JsonApiCollectionDoc {
+    data?: JsonApiResource[];
+    included?: JsonApiResource[];
+    /**
+     * The document-level `meta`. GAIA-305 makes every `gaia_*` collection report its
+     * total here (`GaiaResourceType::includeCount()` -> TRUE, applied by
+     * `GaiaResourceTypeRepository::countsCollections()`); see {@link Page.total}.
+     *
+     * Optional and loosely typed on purpose: a control plane that predates GAIA-305
+     * answers either with no `meta` at all or with a `meta` carrying only `omitted`
+     * — both measured this session — and neither is an error.
+     */
+    meta?: {
+        count?: unknown;
+    };
+    /**
+     * JSON:API's own paging links. `next` is the ONLY valid end-of-list signal, and
+     * it stays so after GAIA-305: a page can simply BE the last one, and `next` is
+     * what says whether it is. `rows.length === limit` cannot answer that — a full
+     * page is exactly as consistent with "more follows" as with "that was all", and
+     * the run collection's last page is short for the ordinary reason that
+     * collections do not divide evenly.
+     *
+     * (GAIA-305 does retire the older reason given here — that access filtering
+     * emptied pages after `page[limit]` had bounded the query, so a SHORT page said
+     * nothing at all. Its query-level access filtering makes pages full again. The
+     * conclusion is unchanged; only the argument for it is.)
+     *
+     * Optional, because the three non-paged readers (the parent picker, the projects
+     * screen, the own-conductor lookup) read one bounded bag and never page.
+     */
+    links?: {
+        next?: unknown;
+    };
+}
+/**
+ * The window a paged read ASKED the server for: the request's own `page[offset]`
+ * and `page[limit]` (GAIA-312 D3).
+ *
+ * A fact about the REQUEST, never an inference about the pages before it. Both
+ * list queries send `page[limit]=size` and `page[offset]=index * size`
+ * (`Entity/*​/Data/query.ts`), and since GAIA-305 the server skips and counts the
+ * same access-filtered collection — which is what lets a screen turn an offset
+ * into a position at all.
+ */
+export interface PageWindow {
+    /** Rows of the collection the request told the server to skip. */
+    offset: number;
+    /** Rows the request told the server to return at most. */
+    limit: number;
+}
+/**
+ * One page of rows plus everything the screen states about it.
+ *
+ * Carried together so a `hasNext`, a page number or a total cannot go stale beside
+ * fresh rows (GAIA-292 D4/D4a).
+ */
+export interface Page<Row> {
+    rows: Row[];
+    hasNext: boolean;
+    /** The page these rows CAME FROM, not the one most recently requested. */
+    page: number;
+    /**
+     * The size of the filtered collection as the SERVER reported it, or null when it
+     * reported none (GAIA-292 D6e).
+     *
+     * It rides the page response's `meta.count`, so it costs no read of its own and
+     * cannot describe a different collection than the rows beside it: the server
+     * applied one query and answered both from it. That is why the earlier background
+     * walk — 28 sequential reads for the open-run collection — is gone rather than
+     * kept as a fallback.
+     *
+     * A number renders as `20 of 107 ticket(s)`; `null` renders as `20 of ?
+     * ticket(s)` (D6d), which is a visible statement that this control plane reports
+     * no total — never a number nobody established.
+     */
+    total: number | null;
+    /**
+     * The window these rows were read with, or `null` when they no longer fill a
+     * window that positions them (GAIA-312 D3/D4).
+     *
+     * Required and explicitly nullable, exactly like {@link Page.total}: "not
+     * established" occupies the field's own place instead of being spelled by an
+     * absent key. `null` means the screen states a row COUNT; a window means it may
+     * state a RANGE, under the test in `ListScreen.countLabel`.
+     */
+    window: PageWindow | null;
+}
+/**
+ * One column of a flat list table (GAIA-294).
+ *
+ * `fields` is the load-bearing member and the reason this type is not just a
+ * `{label, width, get}` triple: it names the JSON:API attributes and
+ * relationships this column's value is built from, so a slice can DERIVE its
+ * sparse fieldset from its column set instead of maintaining a second list beside
+ * it. A column that is not requested cannot exist, because the column IS the
+ * request (GAIA-292 AC 5 made the mismatch a compile error; this makes it
+ * unrepresentable).
+ *
+ * One column may name SEVERAL fields — the run list's STATE reads `state`,
+ * `heartbeat` and `claim_expires_at` through `deriveRunStatus` — and the fieldset
+ * is a superset of the columns' union, because some fields are requested for the
+ * client-side predicates and rendered by nothing.
+ *
+ * GAIA-340 Task 7 — it outlived `lib/table.ts`, whose `renderTable` the tree
+ * replaced, and it lives HERE rather than beside its one renderer in
+ * `Screen/list-screen.ts` (which is where the plan put it) because the two column
+ * SETS are declared in `Entity/*​/Data/`, and `tests/boundary.test.ts` G2 forbids a
+ * data module the `Screen/` directory outright. This file is the placement that
+ * rule leaves — the same one its own header argues for.
+ */
+export interface ListColumn<Row, Ctx = void> {
+    /** Stable identity for the column; not rendered, and the id its cells carry. */
+    readonly key: string;
+    readonly label: string;
+    /** Display columns to lay out; **0** is the trailing column, which takes the
+     *  rest of the row. */
+    readonly width: number;
+    /** The attributes/relationships this column's value is built from. */
+    readonly fields: readonly string[];
+    /**
+     * GAIA-345 D3 — the column's LAYOUT, DECLARED and never measured.
+     *
+     * `width` above is the Yoga basis it has today. `min` is what the column is
+     * never squeezed below, `max` what it never grows past, and `grow` its share of
+     * the row's surplus (0 or absent = never grows). A column that declares none of
+     * the three renders exactly as it did before this ticket, which is what keeps
+     * the current appearance a DECISION rather than an accident of the refactor.
+     *
+     * A BOUND ON THE WRONG SIDE OF `width` IS MEANINGFUL, and since the third pass
+     * of GAIA-345 the code honours it rather than half-honouring it (see the
+     * `declared` derivation in {@link tableRow}). Both readings are of the resolved
+     * width, not of the basis:
+     *
+     *  - `max` BELOW `width` NARROWS the column to `max`, because Yoga's `maxWidth`
+     *    clamps the basis whether or not the cell may shrink. It is the way to say
+     *    "this column is `max` wide" for a column that is also a grower elsewhere,
+     *    and it is what the value is cut against — the ellipsis falls at `max`, not
+     *    at the unreachable `width`.
+     *  - `min` ABOVE `width` WIDENS it to `min`, because `minWidth` wins over both
+     *    the basis and the cap. So `{ width: 5, min: 20 }` is a 20-column column
+     *    that a shrink may take back down to 20 and no further — which is to say
+     *    it is simply 20 wide.
+     *
+     * Neither is a shape any column ships today; both are honoured so that the
+     * first one to declare it gets what it declared. The pair is pinned on the real
+     * renderer in `tests-bun/Screen/list-table-layout.test.ts`.
+     *
+     * A `max` is a DOMAIN constant — `qualification` is the longest member of the
+     * ticket workflow's state_flow, hence STATE's 13 — and never a measurement of
+     * the page. Sizing a column from its content is the property GAIA-340 measured
+     * `TextTableRenderable` for and rejected it over: the columns shift under the
+     * operator every time the page's data changes (spec D4).
+     */
+    readonly min?: number;
+    readonly max?: number;
+    readonly grow?: number;
+    get(row: Row, ctx: Ctx): unknown;
+}
+/**
+ * GAIA-345 D2 — one list, declared once.
+ *
+ * The three members that describe THE LIST move off the per-call options object,
+ * because they are not properties of this frame: `noun` prefixes every node id
+ * the tree declares AND names the count the footer states, `emptyMessage` is what
+ * stands in place of the rows, and `header` says whether this list has one.
+ * `selectedIndex` stays a per-call option — it is the only one that changes
+ * between two frames of the same list.
+ *
+ * That split is the mechanism behind the id rule: {@link listRowIds} and
+ * {@link listTableTree} read ONE `noun`, so a screen can no longer key its rows
+ * `project-picker-candidate-<id>` while publishing `project-picker-row-<id>` as
+ * the node a click lands on — a mismatch whose only symptom is a click that
+ * resolves to nothing.
+ *
+ * `Row extends { id: string }` sits here rather than being restated per screen
+ * for the same reason: every list's row identity is `rowNodeId(noun, row.id)`.
+ */
+export interface ListTable<Row extends {
+    id: string;
+}, Ctx = void> {
+    /** The id prefix every node of this list carries — `ticket`, `run`, `project`. */
+    readonly noun: string;
+    readonly columns: readonly ListColumn<Row, Ctx>[];
+    /** The one row shown in place of the rows when there are none. */
+    readonly emptyMessage: string;
+    /** A bold header row above the data rows. Default true; the project picker is
+     *  the one list that declares it away — it is a question, not a record set. */
+    readonly header?: boolean;
+}
+/** A column-driven list's row ids in selection order — see `lib/vnode.ts`'s
+ *  `rowNodeId`. Beside {@link listTableTree}, which keys the rows under it, and
+ *  reading the SAME `noun` off the same configuration (GAIA-345 D2). */
+export declare const listRowIds: <Row extends {
+    id: string;
+}, Ctx>(table: ListTable<Row, Ctx>, rows: readonly Row[]) => string[];
+/** What {@link listTableTree} needs beyond the configuration and the rows: the
+ *  one member that is per-FRAME rather than per-list (GAIA-345 D2). */
+export interface ListTableOptions {
+    /** The row the cursor stands on, or -1 for none. */
+    readonly selectedIndex: number;
+}
+/**
+ * GAIA-340 D1 — a column-driven list as the renderable tree a screen hands over.
+ *
+ * One node per row, keyed `<noun>-row-<entity id>` (D4/R4) and never by position:
+ * a list re-sorts on every search, page and reload, and a positional key would
+ * move one ticket's cells onto another ticket's node with nothing on screen to
+ * say so. The cells are keyed within their row by the COLUMN's own `key`, which
+ * is what makes the whole set unique by construction.
+ *
+ * MEASURED, so the choice is not re-litigated: `TextTableRenderable` was tried and
+ * rejected. It is ONE renderable whose rows are internal cell views, so no row can
+ * carry a `props.id` — the identity `Kernel/mount.ts` patches by, and the identity
+ * the mouse will need when it moves onto the renderables — and its column widths
+ * are computed from the CONTENT, so the columns would shift every time the page's
+ * data changes.
+ *
+ * THE HIGHLIGHT IS A FULL-WIDTH BAR, and GAIA-345 is where that was decided.
+ * Until then this file argued the opposite — that a bar "needs the row's blank
+ * columns painted, and the only ways to paint them are a padded string or a fixed
+ * colour, and both are worse". The operator overruled it on sight: a highlight
+ * covering only the glyphs came out as one fragment per cell, 58 of 120 columns
+ * in eight pieces, and read as "only the title of the row is active". The two
+ * costs that argument weighed are not the ones that were paid, either. The fill
+ * is a blank run as long as a number the COLUMN DECLARES, so no value is measured
+ * to build it and `lib/width.ts` is not resurrected under a new name (see
+ * {@link tableRow}); and the paint is still the operator's own inverse attribute,
+ * so no colour is frozen and the GAIA-326 regression stays fixed. What the
+ * argument got right is that the row's blank columns have to be painted — it was
+ * wrong that the only ways of doing it were the two bad ones.
+ *
+ * GAIA-340 Task 8 moved it HERE from `Screen/list-screen.ts`, where Task 7 first
+ * wrote it, for the reason {@link ListColumn} gives above it: the run table has a
+ * SECOND consumer in the ticket detail's Runs tab (GAIA-255 AC-6 renders a run
+ * the same way on both screens), that consumer is a `Component/`, and
+ * `tests/boundary.test.ts` G5 forbids anything but an entity-local `Screen/` the
+ * `Screen/` directory. Duplicating the renderer instead would have made "one
+ * renderer, so the two screens cannot disagree" false.
+ */
+export declare function listTableTree<Row extends {
+    id: string;
+}, Ctx>(table: ListTable<Row, Ctx>, rows: readonly Row[], ctx: Ctx, { selectedIndex }: ListTableOptions): VNode;
+/**
+ * GAIA-345 D7 — the SAME list for the surface that has no layout:
+ * `gaia ui GAIA-nnn | cat`.
+ *
+ * GAIA-340 F5 keeps the pipe's own output, and this keeps its BYTES while
+ * retiring the last per-entity column→row mapper (`run-table`'s `runTableRows`):
+ * each cell carries the value and the column's own budget exactly as that emitted
+ * them, and `Component/section-list`'s `lineText` still joins them with ONE
+ * space. A configuration therefore feeds both surfaces, which is what makes "one
+ * component renders every list" true of the run table rather than of its terminal
+ * half only.
+ *
+ * The values are RAW here where {@link listTableTree} runs them through
+ * {@link cellText}. That is not an oversight and not a second rendering rule: the
+ * ellipsis exists because a Yoga budget cuts silently, and a pipe has no budget
+ * to cut against — it prints whatever it is given, at whatever width the reader's
+ * terminal or file happens to be. Cutting here would be a cut nobody asked for.
+ *
+ * The header follows `table.header`, so a headerless list prints headerless and
+ * the two surfaces cannot disagree about whether this list has one.
+ */
+export declare function listTableRows<Row extends {
+    id: string;
+}, Ctx>(table: ListTable<Row, Ctx>, rows: readonly Row[], ctx: Ctx): SectionLine[];
+/**
+ * Read one page of a collection and map it to rows.
+ *
+ * `mapRows` receives `data` AND `included` so each slice keeps its own sideload
+ * indexing — the ticket list indexes every include by id, the run list builds a
+ * ticket-only map — without this function knowing either.
+ */
+export declare function loadPage<Row>(client: DropshClient, path: string, params: unknown, mapRows: (data: JsonApiResource[], included: JsonApiResource[]) => Row[], page: number, window: PageWindow): Promise<Page<Row>>;