@gaia-ai/addon-gaia-ui 0.6.5 → 0.8.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/launch.d.ts

@@ -17,9 +17,9 @@ export declare function buildCreateLaunch(opts: {
     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.
+ * A short human label for the agent list: the ticket's title, else the
+ * description's first line (both 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.
  */
 export declare function shortName(payload: CreateFormPayload): string;

package/dist/src/Agent/launch.js

@@ -32,18 +32,25 @@ export function buildCreateLaunch(opts) {
     };
 }
 /**
- * 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.
+ * A short human label for the agent list: the ticket's title, else the
+ * description's first line (both 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.
  */
 export function shortName(payload) {
+    // GAIA-309 D9: the title is what the operator NAMED the ticket, so it is the
+    // better tab label; the description's first line stays the fallback for a
+    // payload that has no title yet. This touches the launch intent's `label`
+    // ONLY — never `prompt`, never `env`, which is what AC-6 pins.
+    const cap = (line) => line.length > 40 ? `${line.slice(0, 39)}…` : line;
+    const title = payload.title.trim();
+    if (title)
+        return cap(title);
     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;
-    }
+    if (firstLine)
+        return cap(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,60 @@
+/** 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;
+    /**
+     * The group's name, printed in the header row's already-empty label field
+     * (GAIA-324 D4). A caller that renders several groups under one heading uses
+     * it to say which group each block of bars is.
+     *
+     * The component stays ENTITY-NEUTRAL: this is a string, and nothing here knows
+     * a ticket from a run. It is padded exactly like a data label, so the title,
+     * the labels beneath it and the column titles keep one geometry.
+     */
+    title?: string | undefined;
+    /** What to render instead of rows when there are none (spec R7). */
+    emptyMessage?: string | undefined;
+}
+/**
+ * One block's body rows: an optional header row (the group's title, the column
+ * titles, or both), 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, title, emptyMessage }?: StatsPanelOptions): string[];

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

@@ -0,0 +1,124 @@
+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 what the field has to hold, and after GAIA-324 that is two
+ * different kinds of text sharing one column: a breakdown row's bare entity name
+ * (a real project name reaches 26 columns on its own — `gaia-e2e-project` plus a
+ * suffix used to; a long one still does), and the group TITLE printed in the
+ * header row's label field above it. Both are padded to the same field, which is
+ * what keeps a title, the labels it captions and the column titles on one
+ * geometry. Kept at 26 rather than narrowed with the `· tickets` suffix GAIA-324
+ * deleted: the budget was never sized for the suffix alone, and a project name
+ * cut to `a-very-long-project-…` is the same unreadable row the width exists to
+ * prevent.
+ */
+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-name██████` — 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 truncate one more column off the longest names — the labels that are
+ * already hardest to tell 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 header row (the group's title, the column
+ * titles, or both), 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, title, 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) || title !== undefined) {
+        out.push(INDENT +
+            // The SAME label geometry as a data row below (padded to the field width
+            // minus the gap, then the gap), so a group title sits exactly over the
+            // labels it captions. With no title this is the blank label field the
+            // header row always had, byte for byte.
+            pad(title ?? '', LABEL_WIDTH - LABEL_GAP) +
+            ' '.repeat(LABEL_GAP) +
+            ' '.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/top-tabs/index.d.ts

@@ -5,11 +5,20 @@ export interface TopTab {
 }
 /** The root level: what there is before a project is chosen. */
 export declare const ROOT_TABS: readonly [{
+    readonly id: "dashboard";
+    readonly label: "Dashboard";
+}, {
     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 [{
+    readonly id: "dashboard";
+    readonly label: "Dashboard";
+}, {
     readonly id: "tickets";
     readonly label: "Tickets";
 }, {
@@ -22,10 +31,19 @@ export declare const PROJECT_TABS: readonly [{
 /** The tab bars, keyed by level — the one place a level is named. */
 export declare const TAB_LEVELS: {
     readonly root: readonly [{
+        readonly id: "dashboard";
+        readonly label: "Dashboard";
+    }, {
         readonly id: "projects";
         readonly label: "Projects";
+    }, {
+        readonly id: "conductors";
+        readonly label: "Conductors";
     }];
     readonly project: readonly [{
+        readonly id: "dashboard";
+        readonly label: "Dashboard";
+    }, {
         readonly id: "tickets";
         readonly label: "Tickets";
     }, {
@@ -75,17 +93,6 @@ 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;
-/**
- * Which level a tab id belongs to, as a whole {@link TabLocation} — or `null`
- * for an id no level declares.
- *
- * The cast is the one place the level→id pairing is asserted rather than
- * checked, and it is sound by construction: the id was just found **in that
- * level's own registry**, which is exactly what `TabLocation` requires.
- * TypeScript cannot see that through the `Object.keys` loop, so it is stated
- * here once, behind a checked lookup, instead of at every call site.
- */
-export declare function locateTab(tab: TopTabId): TabLocation | null;
 /** 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> {

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

@@ -3,8 +3,9 @@ import { displayWidth } from '../../lib/width.js';
 // the top-level tabs are written. Navigation has THREE levels, and every screen
 // shows exactly ONE tab bar: the one of its own level.
 //
-//   root     dashboard, project-picker            → Projects
-//   project  project, ticket-agents, project-runs → Tickets · Ticket-Agents · Runs
+//   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
@@ -14,11 +15,34 @@ import { displayWidth } from '../../lib/width.js';
 // (GAIA-192) — all three project-scoped, which is why they sit on the project
 // level and not on the root one.
 //
-// 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.
+// GAIA-256 spec D2: `dashboard` is declared on BOTH levels, on purpose. There is
+// ONE Dashboard screen — the root one and the project one are the same screen
+// with its project filter unset or set, and its LEVEL follows that same bit, so
+// the bar and the filter can never disagree: they read one value.
+//
+// That is why tab ids are no longer globally unique, and why nothing here
+// requires them to be. The requirement was never a property of the model — every
+// function in this file is already level-parameterised (`topTabBar(level, id)`,
+// `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. 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`)
+// 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
@@ -27,10 +51,13 @@ import { displayWidth } from '../../lib/width.js';
 // `string`, taking the compile-time check with it.
 /** The root level: what there is before a project is chosen. */
 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 = [
+    { id: 'dashboard', label: 'Dashboard' },
     { id: 'tickets', label: 'Tickets' },
     { id: 'ticket-agents', label: 'Ticket-Agents' },
     { id: 'runs', label: 'Runs' },
@@ -65,25 +92,6 @@ export function topTabBar(level, activeId) {
 export function tabBarFor(location) {
     return renderBar(TAB_LEVELS[location.level], location.tab);
 }
-/**
- * Which level a tab id belongs to, as a whole {@link TabLocation} — or `null`
- * for an id no level declares.
- *
- * The cast is the one place the level→id pairing is asserted rather than
- * checked, and it is sound by construction: the id was just found **in that
- * level's own registry**, which is exactly what `TabLocation` requires.
- * TypeScript cannot see that through the `Object.keys` loop, so it is stated
- * here once, behind a checked lookup, instead of at every call site.
- */
-export function locateTab(tab) {
-    for (const level of Object.keys(TAB_LEVELS)) {
-        const tabs = TAB_LEVELS[level];
-        if (tabs.some((t) => t.id === tab)) {
-            return { level, tab };
-        }
-    }
-    return null;
-}
 const renderSpans = (tabs, activeId) => {
     const spans = [];
     let start = 0;

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

@@ -0,0 +1,98 @@
+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;
+}
+/**
+ * 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>>;

package/dist/src/Entity/collection.js

@@ -0,0 +1,46 @@
+// The ONE JSON:API collection-document shape and the ONE page read (GAIA-294).
+//
+// Slice-less on purpose, directly under `Entity/` beside `transport.ts`,
+// `count.ts` and `cycle.ts`. That is the only placement every slice's `Data/` may
+// import: `tests/boundary.test.ts` G2 forbids a data module from reaching another
+// slice, and its `sliceOf` returns undefined for a file sitting here, so these
+// edges are not cross-slice ones.
+//
+// Before this file the document was declared FIVE times — in ticket/Data/tickets,
+// run/Data/runs, ticket/Data/parents, project/Data/projects and
+// conductor/Data/own-conductor — and only the first two carried `links.next`. Same
+// name, different shapes: the drift GAIA-292's "mirroring Task 3 exactly so the
+// two lists cannot drift" was meant to prevent had already happened.
+/**
+ * The collection total a document reports, or null when it reports none.
+ *
+ * Defensive by contract rather than by suspicion: this value is rendered to the
+ * operator as a total, so anything that is not a usable count must become the
+ * explicit unknown instead of a guess (AC 8.5). A count that is absent, not a
+ * number, not finite, or negative is no count.
+ */
+function readTotal(doc) {
+    const count = doc?.meta?.count;
+    if (typeof count !== 'number')
+        return null;
+    if (!Number.isFinite(count) || count < 0)
+        return null;
+    return count;
+}
+/**
+ * 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 async function loadPage(client, path, params, mapRows, page, window) {
+    const doc = (await client.get(path, params));
+    return {
+        rows: mapRows(doc?.data ?? [], doc?.included ?? []),
+        hasNext: Boolean(doc?.links?.next),
+        page,
+        total: readTotal(doc),
+        window,
+    };
+}