@gaia-ai/addon-gaia-ui 0.16.1 → 0.16.2

package/dist/src/Entity/ticket/Screen/ticket-filter-bar.js

@@ -105,18 +105,11 @@ export class TicketFilterBar {
             }
             return false;
         }
-        if (!this.disable.has('search') && input === '/') {
-            return true;
-        }
         return false;
     }
     applyTo(row) {
-        const query = this.host.criteria.query.toLocaleLowerCase();
-        return ((!query ||
-            row.identifier.toLocaleLowerCase().includes(query) ||
-            row.title.toLocaleLowerCase().includes(query)) &&
-            (this.host.criteria.state === null ||
-                row.state === this.host.criteria.state) &&
+        return ((this.host.criteria.state === null ||
+            row.state === this.host.criteria.state) &&
             (this.host.criteria.closed === null ||
                 row.closed === this.host.criteria.closed) &&
             (this.host.criteria.parent === null ||

package/dist/src/Entity/ticket/Screen/ticket-search.d.ts

@@ -0,0 +1,44 @@
+import type { ListFilterBadge } from '../../../Screen/full-screen.js';
+import type { ScreenContext } from '../../../Screen/screen.js';
+import type { TicketRow } from '../Data/tickets.js';
+export interface TicketSearchHost {
+    /** The typed line; the host's loader sends it as `filter[search]`. */
+    searchQuery: string;
+    /** The rows on screen, narrowed locally while the server read is in flight.
+     *  Absent on a screen that shows no ticket rows (Team → Work). */
+    readonly rows?: readonly TicketRow[];
+    /** Show these rows until the server answers; `[]` after a refusal. */
+    showRows(rows: readonly TicketRow[]): void;
+    /** Re-read for the current query — `AsyncScreen.reloadInPlace` plus any
+     *  criteria-change bookkeeping (page one, cursor). */
+    reloadSearch(context: ScreenContext): Promise<boolean>;
+}
+/**
+ * The `/` search every terminal ticket list shares (GAIA-544 AC9).
+ *
+ * Composed, not inherited: the lists sit on `ListScreen` and on bare
+ * `AsyncScreen`. The server resolves the line — identifiers and fragments,
+ * origin references (`#19`, `gaia#19`, URLs) — so the screen only narrows
+ * optimistically, debounces the reload, drops stale answers (through
+ * `reloadInPlace`) and states a refusal as the server's sentence over an
+ * emptied list, only while that line is still the query.
+ */
+export declare class TicketSearch {
+    private readonly host;
+    open: boolean;
+    private refusal;
+    private refusedQuery;
+    private base;
+    private cancel;
+    constructor(host: TicketSearchHost);
+    /** The server's refusal of the current line, or ''. */
+    get status(): string;
+    badge(): ListFilterBadge;
+    /** The meta-line hint while the field is open, or ''. */
+    hint(): string;
+    /** Claims `/` to open the field and, while it is open, every key. */
+    handleKey(input: string, context: ScreenContext): boolean;
+    /** Close the field and drop a pending reload — on leave and reset. */
+    close(): void;
+    reset(): void;
+}

package/dist/src/Entity/ticket/Screen/ticket-search.js

@@ -0,0 +1,97 @@
+import { serverMessage } from '../../../lib/jsonapi-error.js';
+import { timerDebounce } from '../../../Widget/option-source.js';
+/**
+ * The `/` search every terminal ticket list shares (GAIA-544 AC9).
+ *
+ * Composed, not inherited: the lists sit on `ListScreen` and on bare
+ * `AsyncScreen`. The server resolves the line — identifiers and fragments,
+ * origin references (`#19`, `gaia#19`, URLs) — so the screen only narrows
+ * optimistically, debounces the reload, drops stale answers (through
+ * `reloadInPlace`) and states a refusal as the server's sentence over an
+ * emptied list, only while that line is still the query.
+ */
+export class TicketSearch {
+    host;
+    open = false;
+    refusal = '';
+    refusedQuery = '';
+    base = [];
+    cancel;
+    constructor(host) {
+        this.host = host;
+    }
+    /** The server's refusal of the current line, or ''. */
+    get status() {
+        return this.host.searchQuery === this.refusedQuery ? this.refusal : '';
+    }
+    badge() {
+        const query = this.host.searchQuery;
+        return query
+            ? { id: 'search', label: '/ search', value: `search: ${query}` }
+            : { id: 'search', label: '/ search' };
+    }
+    /** The meta-line hint while the field is open, or ''. */
+    hint() {
+        return this.open
+            ? 'searching IDENTIFIER + TITLE + ORIGIN · type to filter · Backspace erase · Enter keep · Esc leave'
+            : '';
+    }
+    /** Claims `/` to open the field and, while it is open, every key. */
+    handleKey(input, context) {
+        if (!this.open) {
+            if (input !== '/')
+                return false;
+            this.open = true;
+            this.base = [...(this.host.rows ?? [])];
+            context.requestDraw();
+            return true;
+        }
+        if (input === 'escape' || input === 'enter') {
+            this.open = false;
+            context.requestDraw();
+            return true;
+        }
+        const query = this.host.searchQuery;
+        if (input === 'backspace')
+            this.host.searchQuery = query.slice(0, -1);
+        else if (input.length === 1 && input >= ' ')
+            this.host.searchQuery = query + input;
+        else
+            return true;
+        if (this.host.rows !== undefined) {
+            const needle = this.host.searchQuery.toLocaleLowerCase();
+            this.host.showRows(this.base.filter((row) => row.identifier.toLocaleLowerCase().includes(needle) ||
+                row.title.toLocaleLowerCase().includes(needle)));
+        }
+        this.cancel?.();
+        const debounce = context.options?.debounce ?? timerDebounce;
+        this.cancel = debounce(() => {
+            void this.host.reloadSearch(context).then((current) => {
+                if (!current)
+                    return;
+                this.refusal = '';
+                this.refusedQuery = '';
+                context.requestDraw();
+            }, (caught) => {
+                this.refusal = serverMessage(caught);
+                this.refusedQuery = this.host.searchQuery;
+                this.host.showRows([]);
+                context.requestDraw();
+            });
+        }, 200);
+        context.requestDraw();
+        return true;
+    }
+    /** Close the field and drop a pending reload — on leave and reset. */
+    close() {
+        this.open = false;
+        this.cancel?.();
+        this.cancel = undefined;
+    }
+    reset() {
+        this.close();
+        this.refusal = '';
+        this.refusedQuery = '';
+        this.base = [];
+    }
+}

package/dist/src/Entity/ticket/Screen/tickets.d.ts

@@ -84,10 +84,12 @@ export declare class TicketsScreen extends ListScreen<TicketRow, void> {
     receiveResult(result: unknown, context: ScreenContext): void;
     private openingEdit;
     private status;
-    private searchMode;
-    private cancelSearch;
-    private searchBase;
+    private readonly search;
     leave(): void;
+    get searchQuery(): string;
+    set searchQuery(query: string);
+    /** The search is a criteria change like any other (D5): page one. */
+    reloadSearch(context: ScreenContext): Promise<boolean>;
     row(id: string): TicketRow | undefined;
     selectId(id: string): boolean;
     saveState(): {
@@ -169,10 +171,10 @@ export declare class TicketsScreen extends ListScreen<TicketRow, void> {
      *  for the criteria on screen right now. */
     private hiddenNotice;
     /**
-     * The server is authoritative for filtering. Applying the same predicates to
-     * its bounded page also protects a cached re-entry from clients/test doubles
-     * that ignore query parameters; it cannot add a row the server did not return
-     * or change the page/include contract.
+     * Re-apply the bar's criteria except the search line: the server already
+     * resolved `filter[search]`, including origin references whose identifier
+     * and title omit the typed text. The rest protects a cached re-entry from
+     * clients that ignore the other query parameters.
      */
     protected filterRow(row: TicketRow): boolean;
     /** Every criteria change starts over at page one: a narrowed filter applied on

package/dist/src/Entity/ticket/Screen/tickets.js

@@ -2,13 +2,13 @@ import { actionItem } from '../../../Component/footer-actions/index.js';
 import { copyThrough } from '../../../lib/clipboard.js';
 import { serverMessage } from '../../../lib/jsonapi-error.js';
 import { ListScreen } from '../../../Screen/list-screen.js';
-import { timerDebounce } from '../../../Widget/option-source.js';
 import { resolveWhoCandidate } from '../../user/Data/users.js';
 import { loadTicketDetail } from '../Data/detail.js';
 import { CLOSED_FILTER_VALUES, cycleValue, DEFAULT_TICKET_CRITERIA, STATE_FILTER_VALUES, } from '../Data/query.js';
 import { countTicketsIgnoringClosed, loadFilteredTickets, mapTicketDocument, TICKET_TABLE, } from '../Data/tickets.js';
 import { ticketUrl } from '../Data/url.js';
 import { TicketFilterBar } from './ticket-filter-bar.js';
+import { TicketSearch } from './ticket-search.js';
 export class TicketsScreen extends ListScreen {
     frameId = 'tickets';
     table = TICKET_TABLE;
@@ -105,18 +105,22 @@ export class TicketsScreen extends ListScreen {
     }
     openingEdit = false;
     status = '';
-    searchMode = false;
-    cancelSearch;
-    searchBase = [];
+    search = new TicketSearch(this);
     leave() {
-        const cancelPendingSearch = this.searchMode;
-        this.searchMode = false;
-        if (cancelPendingSearch) {
-            this.cancelSearch?.();
-            this.cancelSearch = undefined;
-        }
+        this.search.close();
         super.leave();
     }
+    get searchQuery() {
+        return this.criteria.query;
+    }
+    set searchQuery(query) {
+        this.criteria = { ...this.criteria, query };
+    }
+    /** The search is a criteria change like any other (D5): page one. */
+    reloadSearch(context) {
+        this.page = 0;
+        return this.reloadInPlace(context);
+    }
     row(id) {
         return this.readyValue?.rows.find((candidate) => candidate.id === id);
     }
@@ -285,10 +289,10 @@ export class TicketsScreen extends ListScreen {
         return `${hidden.count} match${hidden.count === 1 ? '' : 'es'} hidden by closed — press x`;
     }
     /**
-     * The server is authoritative for filtering. Applying the same predicates to
-     * its bounded page also protects a cached re-entry from clients/test doubles
-     * that ignore query parameters; it cannot add a row the server did not return
-     * or change the page/include contract.
+     * Re-apply the bar's criteria except the search line: the server already
+     * resolved `filter[search]`, including origin references whose identifier
+     * and title omit the typed text. The rest protects a cached re-entry from
+     * clients that ignore the other query parameters.
      */
     filterRow(row) {
         return this.filter.applyTo(row);
@@ -387,7 +391,7 @@ export class TicketsScreen extends ListScreen {
             this.criteria.who?.id === this.mine.id;
         const badge = (id, label, value) => (value ? { id, label, value } : { id, label });
         return [
-            badge('search', '/ search', this.criteria.query ? `search: ${this.criteria.query}` : undefined),
+            this.search.badge(),
             badge('state', 's state', this.criteria.state ? `state: ${this.criteria.state}` : undefined),
             // Label, never the uuid (GAIA-299 D3) — including when mine set who.
             badge('who', 'w who', this.criteria.who ? `who: ${this.criteria.who.label}` : undefined),
@@ -416,9 +420,7 @@ export class TicketsScreen extends ListScreen {
             .filter(Boolean)
             .join(' · ');
         const hidden = this.hiddenNotice();
-        const searchOpen = this.searchMode
-            ? 'searching IDENTIFIER + TITLE · type to filter · Backspace erase · Enter keep · Esc leave'
-            : '';
+        const searchOpen = this.search.hint();
         return {
             selectable: this.rows.length,
             selectedIndex: this.selectedIndex,
@@ -435,7 +437,7 @@ export class TicketsScreen extends ListScreen {
         ];
     }
     notice() {
-        return this.status || undefined;
+        return this.search.status || this.status || undefined;
     }
     activate(index, context) {
         const row = this.readyValue?.rows[index];
@@ -456,67 +458,8 @@ export class TicketsScreen extends ListScreen {
             return true;
         if (this.openingEdit)
             return true;
-        if (this.searchMode) {
-            if (input === 'escape' || input === 'enter') {
-                this.searchMode = false;
-                context.requestDraw();
-                return true;
-            }
-            if (input === 'backspace')
-                this.criteria = {
-                    ...this.criteria,
-                    query: this.criteria.query.slice(0, -1),
-                };
-            else if (input.length === 1 && input >= ' ')
-                this.criteria = {
-                    ...this.criteria,
-                    query: this.criteria.query + input,
-                };
-            else
-                return true;
-            const query = this.criteria.query.toLocaleLowerCase();
-            const narrowed = this.searchBase.filter((row) => row.identifier.toLocaleLowerCase().includes(query) ||
-                row.title.toLocaleLowerCase().includes(query));
-            // Optimistic local narrowing until the debounced reload lands; it keeps
-            // the page it is narrowing — the LOADED one, the page these rows came
-            // from — so neither `hasNext` nor the page number can flip on a keystroke.
-            this.replaceReady({
-                hasNext: this.readyValue?.hasNext ?? false,
-                page: this.loadedPage,
-                // The criteria just changed, so the previous collection's total must not
-                // stand beside these narrowed rows (AC 8.3). Nothing has been established
-                // for the new collection yet, so the line states the explicit unknown
-                // (`N of ?`, D6d) until the debounced reload's page answers with its own
-                // `meta.count`.
-                total: null,
-                // Same rule as `ListScreen.load()` (GAIA-312 D4): a narrowing that
-                // dropped rows scatters the survivors through the window, so the window
-                // stops positioning them; one that dropped nothing keeps it.
-                window: narrowed.length === this.searchBase.length
-                    ? (this.readyValue?.window ?? null)
-                    : null,
-                rows: narrowed,
-            });
-            this.cancelSearch?.();
-            const debounce = context.options?.debounce ?? timerDebounce;
-            this.cancelSearch = debounce(() => {
-                // The search is a criteria change like any other (D5).
-                this.page = 0;
-                const guard = this.captureLifecycle(context, true);
-                void this.load(context).then((rows) => {
-                    if (this.replaceReadyIfCurrent(guard, rows, context))
-                        this.requestActiveDraw(context);
-                });
-            }, 200);
-            context.requestDraw();
-            return true;
-        }
-        if (input === '/') {
-            this.searchMode = true;
-            this.searchBase = [...this.rows];
-            context.requestDraw();
+        if (this.search.handleKey(input, context))
             return true;
-        }
         if (input === 'e') {
             const ticketId = this.rows[this.selectedIndex]?.id;
             if (!ticketId || this.openingEdit || !context.services)
@@ -543,7 +486,7 @@ export class TicketsScreen extends ListScreen {
             return true;
         }
         // The paging arrows, dispatched HERE and not by the base (GAIA-294 D3). The
-        // position is the load-bearing part: they are reached only PAST the searchMode
+        // position is the load-bearing part: they are reached only PAST the search
         // branch above, which consumes them, so while the `/` field is open the arrows
         // stay inert — not appended as text (its text branch takes single characters
         // only) and not paging underneath the field. A base that claimed them first
@@ -555,7 +498,7 @@ export class TicketsScreen extends ListScreen {
         if (this.handlePagingInput(input, context))
             return true;
         // GAIA-326 — the copy keys, and their POSITION is the whole reason `y` is
-        // safe: they are reached only past the `searchMode` branch above, which
+        // safe: they are reached only past the search branch above, which
         // consumes every printable character, so `y` typed into the `/` field is a
         // letter and never a copy. Nothing else in `src/` binds `y` or `Y`.
         if (input === 'y' || input === 'Y') {
@@ -632,10 +575,7 @@ export class TicketsScreen extends ListScreen {
         this.mine = undefined;
         this.openingEdit = false;
         this.status = '';
-        this.searchMode = false;
-        this.cancelSearch?.();
-        this.cancelSearch = undefined;
-        this.searchBase = [];
+        this.search.reset();
         this.hiddenByClosed = null;
         super.reset();
     }

package/dist/src/Entity/ticket/Screen/user-tickets.d.ts

@@ -69,16 +69,23 @@ export declare abstract class MemberTicketsScreen extends ListScreen<TicketRow,
         readonly emptyMessage: "No tickets.";
     };
     private criteria;
+    private readonly search;
+    get searchQuery(): string;
+    set searchQuery(query: string);
+    reloadSearch(context: ScreenContext): Promise<boolean>;
     protected tableContext(): void;
     protected abstract loadRows(context: ScreenContext, page: number): Promise<TicketPage>;
     protected ticketCriteria(): TicketCriteria;
     protected filterRow(row: TicketRow): boolean;
     protected renderLoading(): string[];
     protected badges(): readonly ListFilterBadge[];
+    protected notice(): string | undefined;
     protected chrome(context: ScreenContext): FullScreenChrome;
     protected actions(): import("../../../Component/footer-actions/index.js").ActionItem[];
     activate(index: number, context: ScreenContext): boolean;
     handleInput(input: string, context: ScreenContext): boolean;
+    leave(): void;
+    reset(): void;
 }
 export declare class WorkspaceMemberTicketsScreen extends MemberTicketsScreen {
     static readonly route: {

package/dist/src/Entity/ticket/Screen/user-tickets.js

@@ -4,11 +4,24 @@ import { CLOSED_FILTER_VALUES, cycleValue } from '../../cycle.js';
 import { assertActiveMember } from '../../user/Data/member-context.js';
 import { DEFAULT_TICKET_CRITERIA } from '../Data/query.js';
 import { loadUserTickets, TICKET_TABLE, } from '../Data/tickets.js';
+import { TicketSearch } from './ticket-search.js';
 /** Shared member ticket list behavior; subclasses own scope and loading. */
 export class MemberTicketsScreen extends ListScreen {
     frameId = 'user-tickets';
     table = TICKET_TABLE;
     criteria = { ...DEFAULT_TICKET_CRITERIA };
+    search = new TicketSearch(this);
+    get searchQuery() {
+        return this.criteria.query;
+    }
+    set searchQuery(query) {
+        this.criteria = { ...this.criteria, query };
+    }
+    reloadSearch(context) {
+        this.page = 0;
+        this.selectedIndex = 0;
+        return this.reloadInPlace(context);
+    }
     tableContext() { }
     ticketCriteria() {
         return this.criteria;
@@ -21,9 +34,10 @@ export class MemberTicketsScreen extends ListScreen {
     }
     badges() {
         if (this.criteria.closed === null) {
-            return [{ id: 'closed', label: 'x closed' }];
+            return [this.search.badge(), { id: 'closed', label: 'x closed' }];
         }
         return [
+            this.search.badge(),
             {
                 id: 'closed',
                 label: 'x closed',
@@ -31,6 +45,9 @@ export class MemberTicketsScreen extends ListScreen {
             },
         ];
     }
+    notice() {
+        return this.search.status || undefined;
+    }
     chrome(context) {
         const name = context.user?.name ?? context.params?.userName ?? 'user';
         const pagingLine = [this.countLabel(), ...this.pagingSegments()]
@@ -41,7 +58,7 @@ export class MemberTicketsScreen extends ListScreen {
             selectedIndex: this.selectedIndex,
             rowIds: this.rowNodeIds,
             title: `${name} · tickets`,
-            meta: pagingLine,
+            meta: [pagingLine, this.search.hint()].filter(Boolean).join('  ·  '),
         };
     }
     actions() {
@@ -59,6 +76,8 @@ export class MemberTicketsScreen extends ListScreen {
         return true;
     }
     handleInput(input, context) {
+        if (this.search.handleKey(input, context))
+            return true;
         if (input === 'x') {
             this.criteria = {
                 ...this.criteria,
@@ -76,6 +95,15 @@ export class MemberTicketsScreen extends ListScreen {
             return this.activate(this.selectedIndex, context);
         return super.handleInput(input, context);
     }
+    leave() {
+        this.search.close();
+        super.leave();
+    }
+    reset() {
+        this.criteria = { ...this.criteria, query: '' };
+        this.search.reset();
+        super.reset();
+    }
 }
 export class WorkspaceMemberTicketsScreen extends MemberTicketsScreen {
     static route = {

package/dist/src/Screen/async-screen.d.ts

@@ -80,6 +80,13 @@ export declare abstract class AsyncScreen<T> extends BaseScreen {
      */
     protected actionStillCurrent(guard: LifecycleGuard, context: ScreenContext): boolean;
     protected replaceReadyIfCurrent(guard: LifecycleGuard, data: T, context: ScreenContext): boolean;
+    /**
+     * Re-read over the ready surface, superseding any read still in flight.
+     * Resolves `false` when a newer read or a local mutation overtook this one;
+     * rejects only while it is still the current read, so a stale failure
+     * cannot overwrite a newer answer.
+     */
+    protected reloadInPlace(context: ScreenContext): Promise<boolean>;
     protected requestActiveDraw(context: ScreenContext): boolean;
     enter(context: ScreenContext): void;
     retry(context: ScreenContext): Promise<void>;

package/dist/src/Screen/async-screen.js

@@ -1,4 +1,5 @@
 import { filterBadgeStrip, } from '../Component/list-chrome/index.js';
+import { serverMessage } from '../lib/jsonapi-error.js';
 import { columnNode, messageTree } from '../lib/vnode.js';
 import { BaseScreen, presentation, } from './screen.js';
 /**
@@ -103,6 +104,28 @@ export class AsyncScreen extends BaseScreen {
         this.state = 'ready';
         return true;
     }
+    /**
+     * Re-read over the ready surface, superseding any read still in flight.
+     * Resolves `false` when a newer read or a local mutation overtook this one;
+     * rejects only while it is still the current read, so a stale failure
+     * cannot overwrite a newer answer.
+     */
+    async reloadInPlace(context) {
+        const guard = this.captureLifecycle(context, true);
+        let data;
+        try {
+            data = await this.load(context);
+        }
+        catch (caught) {
+            if (!this.lifecycleIsCurrent(guard, context))
+                return false;
+            throw caught;
+        }
+        if (!this.replaceReadyIfCurrent(guard, data, context))
+            return false;
+        this.requestActiveDraw(context);
+        return true;
+    }
     requestActiveDraw(context) {
         if (!context.isActive()) {
             this.staleRedrawCount++;
@@ -167,13 +190,11 @@ export class AsyncScreen extends BaseScreen {
                 return;
             this.refreshing = false;
             if (keepSurface) {
-                this.toast =
-                    caught instanceof Error ? caught.message : String(caught);
+                this.toast = serverMessage(caught);
                 this.requestActiveDraw(context);
                 return;
             }
-            this.failure =
-                caught instanceof Error ? caught : new Error(String(caught));
+            this.failure = new Error(serverMessage(caught));
             this.state = 'error';
             this.requestActiveDraw(context);
         });

package/dist/src/Screen/list-screen.d.ts

@@ -14,7 +14,7 @@ import type { ScreenContext } from './screen.js';
  * enough hooks to be a framework.
  *
  * It does not claim keys from `handleInput` either. The current dispatch ORDER is
- * load-bearing: `←`/`→` sit after the ticket list's `searchMode` branch, where the
+ * load-bearing: `←`/`→` sit after the ticket list's `/` search branch, where the
  * arrows are inert while the `/` field is open. A base that claimed them first
  * would make them page there — a behaviour change, and GAIA-294 is
  * behaviour-neutral. So the dispatch TABLE lives here once and each subclass calls
@@ -93,7 +93,7 @@ export declare abstract class ListScreen<Row extends {
      * `←` forwards too (GAIA-292 R1).
      *
      * WHERE it is called stays the subclass's decision (GAIA-294 D3) — on the ticket
-     * list it must sit after the `searchMode` branch, where the arrows are inert
+     * list it must sit after the `/` search branch, where the arrows are inert
      * while the `/` field is open.
      */
     protected handlePagingInput(input: string, context: ScreenContext): boolean;
@@ -103,6 +103,15 @@ export declare abstract class ListScreen<Row extends {
      * chain continues.
      */
     protected handleCursorInput(input: string, context: ScreenContext): boolean;
+    /**
+     * Show `rows` in place of the loaded page until the next read answers — the
+     * optimistic narrowing of a search. It keeps the LOADED page number so a
+     * keystroke does not flip `page N`; the total becomes the explicit unknown
+     * (`N of ?`); a narrowing that dropped rows stops the window positioning
+     * the survivors (GAIA-312 D4). An emptied list (a refusal) also drops
+     * `hasNext`, so `→` cannot re-send the refused query.
+     */
+    showRows(rows: readonly Row[]): void;
     /** `page N` for the strip above the table (count sits beside it). */
     protected pagingSegments(): string[];
     /**

package/dist/src/Screen/list-screen.js

@@ -24,7 +24,7 @@ import { AsyncScreen } from './async-screen.js';
  * enough hooks to be a framework.
  *
  * It does not claim keys from `handleInput` either. The current dispatch ORDER is
- * load-bearing: `←`/`→` sit after the ticket list's `searchMode` branch, where the
+ * load-bearing: `←`/`→` sit after the ticket list's `/` search branch, where the
  * arrows are inert while the `/` field is open. A base that claimed them first
  * would make them page there — a behaviour change, and GAIA-294 is
  * behaviour-neutral. So the dispatch TABLE lives here once and each subclass calls
@@ -92,7 +92,7 @@ export class ListScreen extends AsyncScreen {
      * `←` forwards too (GAIA-292 R1).
      *
      * WHERE it is called stays the subclass's decision (GAIA-294 D3) — on the ticket
-     * list it must sit after the `searchMode` branch, where the arrows are inert
+     * list it must sit after the `/` search branch, where the arrows are inert
      * while the `/` field is open.
      */
     handlePagingInput(input, context) {
@@ -116,6 +116,24 @@ export class ListScreen extends AsyncScreen {
         context.requestDraw();
         return true;
     }
+    /**
+     * Show `rows` in place of the loaded page until the next read answers — the
+     * optimistic narrowing of a search. It keeps the LOADED page number so a
+     * keystroke does not flip `page N`; the total becomes the explicit unknown
+     * (`N of ?`); a narrowing that dropped rows stops the window positioning
+     * the survivors (GAIA-312 D4). An emptied list (a refusal) also drops
+     * `hasNext`, so `→` cannot re-send the refused query.
+     */
+    showRows(rows) {
+        const current = this.readyValue;
+        this.replaceReady({
+            hasNext: rows.length === 0 ? false : (current?.hasNext ?? false),
+            page: this.loadedPage,
+            total: null,
+            window: current && rows.length === current.rows.length ? current.window : null,
+            rows: [...rows],
+        });
+    }
     /** `page N` for the strip above the table (count sits beside it). */
     pagingSegments() {
         return [`page ${this.loadedPage + 1}`];