@yadsh/dsh-qa-surface 0.13.0 → 0.14.0

package/lib/types/client/QaSessionController.d.ts

@@ -1,7 +1,13 @@
 import type { ConnectionGenerationState } from "@deepseek-ai/dsh-client-connection/client";
-import type { QaAttachmentDraft, QaSessionState, ResolvedQaSurfaceConfig } from "../types.js";
-import type { QaApprovalApi, QaConversation, QaCreateSession, QaFileUpload, QaSecureSession, QaSessions, QaSessionsApi, QaQuestionApi, QaSlashApi, QaSourceApi, StorageLike } from "./types.js";
+import type { QaAttachmentDraft, QaQueueOperation, QaSessionState, ResolvedQaSurfaceConfig } from "../types.js";
+import type { QaApprovalApi, QaConversation, QaCreateSession, QaFileUpload, QaQueueStatusRemote, QaSecureSession, QaSessions, QaSessionsApi, QaQuestionApi, QaSlashApi, QaSourceApi, StorageLike } from "./types.js";
 import type { QaApprovalDecision, QaQuestionAnswerItem } from "../types.js";
+declare module "@deepseek-ai/dsh-api-session-controller/client" {
+    interface SessionReferenceSourceMap {
+        /** The QA surface holds the Session of the chat it is showing. */
+        qaSurface: unknown;
+    }
+}
 export interface QaAccountsFacade {
     /** The account bearer token, or null while anonymous. */
     readonly token: () => string | null;
@@ -44,6 +50,14 @@ export interface QaSessionControllerOptions {
      * working, which is exactly the pre-feature behaviour.
      */
     readonly slashApi?: QaSlashApi;
+    /**
+     * The Host's live read of the request ceiling. Absent on a Host build that
+     * predates it — and unanswered, or answered by a deployment that sets no
+     * ceiling — the surface sends the way it always did: the ceiling is an
+     * arrangement between browsers about how much this stand can take, never a
+     * reason a question cannot be asked.
+     */
+    readonly queueStatus?: QaQueueStatusRemote;
     readonly storage?: StorageLike;
     /**
      * Browser file-upload service, resolved lazily: the page may not serve the
@@ -91,8 +105,11 @@ export declare class QaSessionController {
     private readonly streamPublisher;
     private state;
     private session;
+    /** The reference that keeps {@link session} alive; released with the binding. */
+    private sessionReference;
     private conversationBinding;
     private unsubscribeSession;
+    private unsubscribeInbox;
     private unsubscribeChat;
     private readonly unsubscribeConnection;
     private ensuring;
@@ -101,6 +118,18 @@ export declare class QaSessionController {
     private admissionPending;
     private pendingSubmission;
     private pendingSequence;
+    /**
+     * Request ids this binding has seen the Host name — in the Inbox queue or as a
+     * durable transcript row. The mask that keeps an echo the session library
+     * failed to retire from coming back as a question still crossing the
+     * transport: the retirement is `@deepseek-ai/dsh-api-session-controller`'s own
+     * contract, deferred to an animation frame that a surface with no frame clock
+     * never runs, and `projectQueue` in project-session-state.ts carries the
+     * citation, what the substitute costs and does not cost, and the point where
+     * this set is dead code. Kept for the whole binding: a request id is minted per
+     * submission, so an id the Host has named can never belong to a later send.
+     */
+    private readonly admittedSubmissions;
     private policyReady;
     /** Historical transcript retained after the Host classifies policy drift. */
     private compatibilityReadOnly;
@@ -111,6 +140,31 @@ export declare class QaSessionController {
     private connectedOnce;
     private disposed;
     private generation;
+    /**
+     * The session the current chat identity names, or null while the chat it
+     * names has no session yet. This is what makes the identity a chat identity
+     * rather than a counter: {@link bind} compares the session it is about to
+     * adopt against it, so any path that ends up in another session takes another
+     * identity — and a draft adopting its first session keeps the one it holds.
+     * It only ever names a session this controller holds: {@link bind} hands it
+     * out once the adoption has cleared every wait that caller asked it to take —
+     * a chat is opened and attested, a subagent transcript is only opened — and
+     * both a failed adoption and {@link unbind} take it back. The converse does
+     * not hold: a held session may name nothing, which is the transcript of an
+     * attestation this chat could not pass and whose caller still reads it. So a
+     * chat whose first send fell short keeps its identity while naming no session,
+     * and the retry — which brings a fresh id — stays in the composer the question
+     * was typed into instead of reading as a move to another chat.
+     */
+    private namedSession;
+    /**
+     * Chat identity handed to the surface (`QaSessionState.chatKey`). Taken from
+     * the page-wide sequence on every move to another chat, and never when the
+     * bound draft merely creates its session: a component that keeps per-chat
+     * state in React therefore survives the first prompt of a new chat, while two
+     * chats never read the same identity.
+     */
+    private chatKey;
     private chatsRevision;
     private selectedSubrole;
     private adminPreview;
@@ -120,6 +174,9 @@ export declare class QaSessionController {
     private readonly hostApprovals;
     /** Host-side question requests of the bound chat waiting for the operator. */
     private readonly hostQuestions;
+    private readonly queueRemote;
+    /** Last send the stand had no room for; drives the request-ceiling dialog. */
+    private requestQueueNotice;
     /** Set while a running turn is polled for parked requests. */
     private pendingTimer;
     /**
@@ -165,6 +222,21 @@ export declare class QaSessionController {
      * runtime and never becomes a model message.
      */
     send(text: string, attachments?: readonly QaAttachmentDraft[], pick?: string | null): Promise<boolean>;
+    /**
+     * What the stand answers about its load, or null when it does not answer.
+     *
+     * Every failure here sends the question anyway. The ceiling exists to keep a
+     * weak model from drowning, not to be a door a browser cannot open: an
+     * unreadable count says nothing about the load, and refusing a visitor on
+     * that would be a worse answer than the one they would have got.
+     */
+    private readQueueStatus;
+    /**
+     * Close the request-ceiling dialog. Nothing is retried and nothing is
+     * dropped: the held-back question is still the composer's own text, so asking
+     * it again is the visitor's keystroke, taken once the stand has a place free.
+     */
+    dismissRequestQueueNotice(): void;
     /**
      * Run one admitted human command. The Host answers it and writes the
      * lifecycle into the session log; this method only decides what the composer
@@ -193,6 +265,13 @@ export declare class QaSessionController {
     private slashCatalogReady;
     /** The slash view of the current state; assembled where the state is. */
     private slashView;
+    /**
+     * Turns the loaded Chat window has recorded as durably finished. The Host
+     * writes one per `turn/end`, so the count only moves on a fact the
+     * transcript itself carries — unlike the session's running bit, which the
+     * list relay can also deliver stale.
+     */
+    private durableTurnEndCount;
     /** Publish a browser-only copy before any network or Host admission awaits. */
     private beginSubmission;
     /**
@@ -204,11 +283,28 @@ export declare class QaSessionController {
      */
     regenerate(): Promise<boolean>;
     stop(): Promise<void>;
+    /**
+     * Edit, send now, or drop one message that still waits for its turn. Every
+     * operation addresses the occurrence id the Host's queue frame carried, so a
+     * row the agent claimed a moment ago is refused by the Host rather than
+     * quietly dropped here.
+     *
+     * The answer is the refusal text rather than a flag, and the strip beside the
+     * composer keeps showing it: a session frame follows a refusal within
+     * milliseconds, and the shared error line is cleared by exactly that frame.
+     */
+    queueAction(id: string, action: QaQueueOperation, text?: string): Promise<string | null>;
     /**
      * Enter the "new chat" draft: show an empty composer without creating any
      * session. Nothing appears in the chat list and no Host session is spent
      * until the first prompt is actually sent, which materializes the session
      * lazily ({@link materializeDraft}). Fixed-policy deployments cannot draft.
+     *
+     * A draft is a chat of its own, so entering one takes the screen the way
+     * {@link switchTo} does; see the note where the generation moves. Stopping the
+     * turn that was running first takes a round-trip, and a chat opened through it
+     * keeps the screen: the draft is what the visitor asked for before that click,
+     * so this call gives up rather than taking the chat back from under them.
      */
     startDraft(policyChange?: boolean): Promise<void>;
     /**
@@ -278,13 +374,104 @@ export declare class QaSessionController {
      * attested session id, or null when nothing was attested.
      */
     private recoverForSend;
+    /**
+     * Begin a chat of its own: take a fresh identity from the page-wide sequence,
+     * leave it naming no session, and retire the send the ending chat had in
+     * flight. Called on every move between chats — reset, switch, subagent view —
+     * by {@link bind} when it ends up in a session the identity does not name, and
+     * by the bootstrap whose restored chat was refused, for the replacement it is
+     * about to open.
+     */
+    private openChat;
+    /**
+     * Adopt one Host session as the chat on screen: take its binding, wait for it
+     * to open, attest the policy, and only then hand the chat identity to the
+     * session, so {@link namedSession} never names one this controller does not
+     * hold. A caller that asks for no attestation — the subagent view, whose
+     * transcript is read rather than written into — is named once its session is
+     * open.
+     *
+     * Answers whether the adoption happened. `true` is a finished one: this call
+     * holds the session and the chat identity names it, so the caller may publish
+     * what it kept for that chat — the draft it retired, the id it persisted.
+     * `false` is a step back: the chat on screen moved on while this call waited,
+     * it undoes nothing of the chat that replaced it and leaves the screen holding
+     * nothing of this one ({@link stepBack}), and the caller must keep its own
+     * state as unclaimed — a draft that was never materialized stays a draft, and a
+     * chat that was never adopted is not persisted as the open one.
+     *
+     * Any of those waits can outlive the operation it belongs to — the user moves
+     * to another chat while a first send is still looking for its session. Two
+     * questions decide that at each wait: is this still the generation the caller
+     * owns, and is this still the session this call took? The first is the page's
+     * own — every path that takes the screen raises the generation. The second is
+     * kept beside it because a generation only records who was asked to start, not
+     * what the controller holds by the time an adoption resumes: a binding
+     * somebody else retired in between is no more this one's to finish.
+     */
     private bind;
+    /**
+     * Give up on an adoption the chat on screen has outgrown, and answer whether
+     * that is what happened (`true` — the caller has nothing left to publish).
+     *
+     * Past the binding this call installed a session of its own: the retained
+     * reference, the three subscriptions beside it, and whatever those
+     * subscriptions write on every frame. The path that took the screen usually
+     * retired all of that with its own {@link unbind} — but the bootstrap raises the
+     * generation while keeping the transcript readable until its own session
+     * exists, and an adoption left behind by it would otherwise go on holding a
+     * Host session nobody is in and publishing that chat's frames into the surface:
+     * each frame clears the error the bootstrap published and answers for a binding
+     * the page has given up on. Undoing the install is therefore this call's own
+     * hand — and only its own: the chat that already replaced this one holds the
+     * name, the subscriptions and the policy proof, and emptying its screen is the
+     * failure this method exists to prevent.
+     */
+    private stepBack;
+    /**
+     * Is this adoption still the one on screen? The generation says whether the
+     * operation that asked for it still owns the page — every path that takes the
+     * screen raises it, {@link startDraft} among them — and the session says
+     * whether the binding this call took is still the one held, which a generation
+     * alone cannot answer: a newer chat raises it before it has taken any name, and
+     * a caller can retire the binding it holds inside its own generation.
+     */
+    private ownsAdoption;
     private unbind;
     private waitForConnection;
     /** Project one session notification; the running-turn spacing policy
      * (first frame at once, further frames absorbed) lives in the publisher. */
     private publishSessionUpdate;
     private publish;
+    /**
+     * The messages the Host has accepted for the agent's next turn. They arrive
+     * through the session's Inbox projection rather than the snapshot the queue
+     * strip used to read: `rc.2` moved pending input onto the projection surface,
+     * and a key the Host never published reads as no queued work.
+     */
+    private queuedMessages;
+    /**
+     * Record the submissions this binding has seen the Host name — the queue rows
+     * it holds and the durable input rows it has written. Naming the message is the
+     * server's own receipt for it, so from that notification on the row belongs to
+     * the chat, not to the transport: an echo the claim leaves behind must not read
+     * again as a question still crossing. The scan is only paid for while some
+     * queued echo still waits for its name.
+     *
+     * Both lists are read because neither is reliable alone, and the transcript is
+     * the durable one: a send admitted and claimed between two notifications never
+     * appears in a queue frame this browser is handed, but its row stays in the
+     * transcript, so the next frame names it. And the receipt is never dropped
+     * while the binding lives — an id the server has named belongs to the submission
+     * that minted it (`beginSubmission` returns a fresh `randomUUID`), so no later
+     * send can need the row this hides, whereas forgetting the receipt re-draws the
+     * ghost the moment the snapshot registers the echo again.
+     *
+     * Read from the notification, not from the projected frame: the projection of a
+     * running turn is spaced, and an absorbed frame is dropped rather than
+     * replayed, so spacing must not decide whether this browser ever saw the name.
+     */
+    private trackAdmittedSubmissions;
     /**
      * The directory the transcript's source paths are anchored on: the chat's
      * own cwd, never the configured pin while the chat is known.
@@ -319,12 +506,18 @@ export declare class QaSessionController {
      * deployment without accounts, where the list is the browser's own.
      */
     private visibleChatIds;
+    /**
+     * Tell the user that a submission they pressed did not go. The composer keeps
+     * its text through a refused send, so silence here would read as success.
+     */
+    private refuseSend;
     private fail;
     /**
-     * Attest the currently bound session. `ok` carries the session id the proof
-     * was issued for; `stale` means the binding changed while the request was
-     * in flight, so nothing was written — the newer binding manages its own
-     * attestation; `refused` is a genuine admission refusal of this binding.
+     * Attest `session`, which defaults to the one currently bound. `ok` carries
+     * the session id the proof was issued for; `stale` means the binding changed
+     * while the request was in flight, so nothing was written — the newer binding
+     * manages its own attestation; `refused` is a genuine admission refusal of
+     * this binding.
      */
     private attestPolicy;
     private emit;

package/lib/types/client/QaSurface.d.ts

@@ -3,7 +3,7 @@ import type { InjectFace, PropsRenderSlots, PropsRuntime } from "@deepseek-ai/ds
 import type { QaConfigController } from "./QaConfigController.js";
 import type { QaRouteController } from "./QaRouteController.js";
 import type { QaAccountsController } from "./QaAccountsController.js";
-import type { QaApprovalApi, QaAccessApi, QaAdminApi, QaConversation, QaCreateSession, QaFileUpload, QaSecureSession, QaSessions, QaSessionsApi, QaQuestionApi, QaSkillApi, QaSlashApi, QaSourceApi } from "./types.js";
+import type { QaApprovalApi, QaAccessApi, QaAdminApi, QaConversation, QaCreateSession, QaFileUpload, QaQueueStatusRemote, QaSecureSession, QaSessions, QaSessionsApi, QaQuestionApi, QaSkillApi, QaSlashApi, QaSourceApi } from "./types.js";
 import type { QaSurfacePanelRegistry } from "./panels/registry.js";
 import type { QaUserSettingsSections } from "./settings-extensions/index.js";
 import type { QaAuditController } from "./audit/controller.js";
@@ -41,6 +41,11 @@ export interface QaSurfaceFace {
      * untouched.
      */
     readonly slashApi?: QaSlashApi;
+    /**
+     * The Host's live read of the request ceiling. Absent on a Host build that
+     * predates it: a deployment with no ceiling never asks, so nothing changes.
+     */
+    readonly queueStatus?: QaQueueStatusRemote;
     /**
      * Browser file-upload service, when the page serves the upload plugin.
      * Resolved per send so a page that loads it later still gets file support.

package/lib/types/client/admin/pages/ExpertMemory.d.ts

@@ -0,0 +1,19 @@
+import type { QaAdminApi } from "../../types.js";
+/**
+ * What the domain experts remembered.
+ *
+ * An expert writes its own notes, and a note that turned out to be wrong keeps
+ * being injected into every later answer of that domain until someone deletes
+ * it. This page is for that someone. The edit is deliberately narrow — the text
+ * and its tags, never the key, which is what the audit trail and the expert's
+ * own `forget` calls point at.
+ *
+ * A reviewer opens the same list read-only: seeing what an expert believes is
+ * the half of the job that produces the report "this is wrong".
+ */
+export declare function AdminExpertMemory(props: {
+    readonly api: QaAdminApi;
+    readonly token: string;
+    readonly canManage: boolean;
+}): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=ExpertMemory.d.ts.map

package/lib/types/client/admin/routes.d.ts

@@ -34,6 +34,8 @@ export type QaAdminRoute = {
     readonly page: "feedback";
 } | {
     readonly page: "quality";
+} | {
+    readonly page: "memory";
 } | {
     readonly page: "audit";
 };
@@ -58,5 +60,5 @@ export declare function parseAdminRoute(pathname: string, routePath: string): Qa
 /** The pathname for one console route; the inverse of {@link parseAdminRoute}. */
 export declare function adminPath(routePath: string, route: QaAdminRoute, search?: string): string;
 /** Which navigation entry is current for one route. */
-export declare function adminSectionOf(route: QaAdminRoute): "overview" | "users" | "access" | "conversations" | "review" | "feedback" | "quality" | "audit";
+export declare function adminSectionOf(route: QaAdminRoute): "overview" | "users" | "access" | "conversations" | "review" | "feedback" | "quality" | "memory" | "audit";
 //# sourceMappingURL=routes.d.ts.map

package/lib/types/client/admin/shared.d.ts

@@ -38,9 +38,11 @@ export declare function useAdminResource<T>(load: (signal: AbortSignal) => Promi
 /** A status chip; the modifier class carries the semantic colour. */
 export declare function Badge(props: {
     readonly tone?: "neutral" | "positive" | "negative" | "warning";
+    readonly testId?: string;
     readonly children: React.ReactNode;
 }): import("react/jsx-runtime").JSX.Element;
 export declare function Empty(props: {
+    readonly testId?: string;
     readonly children: React.ReactNode;
 }): import("react/jsx-runtime").JSX.Element;
 /** A relative timestamp with the exact one available on hover. */
@@ -49,6 +51,7 @@ export declare function Stamp(props: {
 }): import("react/jsx-runtime").JSX.Element;
 export declare function ErrorLine(props: {
     readonly message: string | undefined;
+    readonly testId?: string;
 }): import("react/jsx-runtime").JSX.Element | null;
 /**
  * Cursor paging controls. The cursor is opaque to the browser by design: only
@@ -65,6 +68,7 @@ export declare function Pager(props: {
 /** One labeled filter control in a table toolbar. */
 export declare function FilterField(props: {
     readonly label: string;
+    readonly testId: string;
     readonly children: React.ReactNode;
 }): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=shared.d.ts.map

package/lib/types/client/components/Markdown.d.ts

@@ -7,11 +7,18 @@ export type { MarkdownSourceContext } from "../markdown/source-chip.js";
  * or inline-code token that names a source the owning message knows about
  * renders as a source chip instead of plain text.
  *
+ * `streaming` says the text is a frame of a live answer, so the block the
+ * answer stopped inside is held rather than rendered as settled: an open `$$`
+ * fence shows the TeX being written instead of its dollars, and a table leaves
+ * a half-typed row out until the row is whole.
+ *
  * Memoized on the text value: stream updates re-render only the message whose
  * text actually changed, so committed history is never re-parsed.
  */
-export declare const Markdown: import("react").MemoExoticComponent<({ text, sourceRefs, onSourceOpen, }: {
+export declare const Markdown: import("react").MemoExoticComponent<({ text, streaming, sourceRefs, onSourceOpen, }: {
     readonly text: string;
+    /** Whether the text is still growing; a settled answer renders in full. */
+    readonly streaming?: boolean;
     readonly sourceRefs?: QaSourceRefs;
     readonly onSourceOpen?: (source: QaSource) => void;
 }) => import("react/jsx-runtime").JSX.Element>;

package/lib/types/client/components/QaHeader.d.ts

@@ -21,6 +21,8 @@ export interface QaHeaderProps {
     readonly viewingSubagent: boolean;
     readonly onCloseSubagent: () => void;
     readonly roleSelector?: ReactNode;
+    /** The palette choice, next to the role it belongs to on screen. */
+    readonly themeSwitcher?: ReactNode;
     readonly administration?: {
         readonly onOpen: () => void;
     };
@@ -59,5 +61,5 @@ export interface QaHeaderProps {
     readonly resetDisabled: boolean;
     readonly onReset: () => void;
 }
-export declare function QaHeader({ logoUrl, title, viewingSubagent, onCloseSubagent, roleSelector, administration, agentCount, agentsOpen, onToggleAgents, sourcesVisible, sourcesCount, sourcesComplete, sourcesOpen, onOpenSources, fileCount, filesEnabled, filesOpen, onOpenFiles, settings, panelLauncher, showReset, resetDisabled, onReset, }: QaHeaderProps): import("react/jsx-runtime").JSX.Element;
+export declare function QaHeader({ logoUrl, title, viewingSubagent, onCloseSubagent, roleSelector, themeSwitcher, administration, agentCount, agentsOpen, onToggleAgents, sourcesVisible, sourcesCount, sourcesComplete, sourcesOpen, onOpenSources, fileCount, filesEnabled, filesOpen, onOpenFiles, settings, panelLauncher, showReset, resetDisabled, onReset, }: QaHeaderProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=QaHeader.d.ts.map

package/lib/types/client/components/QaModal.d.ts

@@ -1,4 +1,11 @@
 import { type ReactNode } from "react";
+/**
+ * Whether a dialog of this shell is on screen. The keyboard belongs to it: the
+ * page under it, and anything painted beside it — the notice stack is such a
+ * neighbour — have to stop steering Tab while it holds, or a reader working in
+ * the dialog is turned back into a page under the scrim.
+ */
+export declare function isQaModalOpen(): boolean;
 export interface QaModalProps {
     readonly open: boolean;
     /** Dialog title; also the dialog's accessible name. */

package/lib/types/client/components/QaQueueDock.d.ts

@@ -0,0 +1,27 @@
+import type { QaQueueRow } from "../../types.js";
+export interface QaQueueDockProps {
+    /** Messages waiting for the agent's next turn, oldest first. */
+    readonly rows: readonly QaQueueRow[];
+    /** Only a running turn can be interrupted, so only then is "send now" live. */
+    readonly running: boolean;
+    readonly canEdit: boolean;
+    /**
+     * Each operation answers with its refusal text, or null when the Host took
+     * it; the strip is the only place that answer stays readable.
+     */
+    readonly onEdit: (id: string, text: string) => Promise<string | null>;
+    readonly onSendNow: (id: string) => Promise<string | null>;
+    readonly onRemove: (id: string) => Promise<string | null>;
+}
+/**
+ * The queue strip beside the composer. What the user typed while the agent was
+ * answering is not in the transcript yet — the Host keeps it until the next
+ * turn claims it — so without this strip those messages simply are not on the
+ * screen: they cannot be read back, corrected, sent ahead, or dropped.
+ *
+ * One row shows directly; several fold behind a count so a long queue does not
+ * push the composer off the screen. Editing or an operation in flight forces
+ * the list open, because either way the user is looking at the rows.
+ */
+export declare const QaQueueDock: import("react").MemoExoticComponent<(props: QaQueueDockProps) => import("react/jsx-runtime").JSX.Element | null>;
+//# sourceMappingURL=QaQueueDock.d.ts.map

package/lib/types/client/components/QaRequestQueue.d.ts

@@ -0,0 +1,20 @@
+import type { QaQueueStatus } from "../../types.js";
+/**
+ * The dialog a question gets when the stand has no place left for it.
+ *
+ * Saying where the question is beats saying that the visitor was refused: the
+ * send stopped before anything reached the Host, so nothing was created,
+ * nothing was answered, and the text is still in the composer. A visitor who
+ * cannot tell that asks twice, and a second question is exactly the load the
+ * ceiling exists to keep off a model that is already busy.
+ *
+ * The count names occupied places, not people ahead of the visitor: `active`
+ * includes this visitor's own turns, and a stand that cannot tell whose place
+ * is whose has no business numbering a queue behind which it claims to wait.
+ * @param props - the load read that held the question back, and how to close.
+ */
+export declare function QaRequestQueue(props: {
+    readonly status: QaQueueStatus | null;
+    readonly onClose: () => void;
+}): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=QaRequestQueue.d.ts.map

package/lib/types/client/components/QaThemeSwitcher.d.ts

@@ -0,0 +1,14 @@
+import { type QaThemePreference } from "../theme-preference.js";
+/**
+ * The palette choice of the QA surface. Three cubes, like the Host's own
+ * Appearance row: the selection is the preference, never the resolved scheme,
+ * so «Системная тема» stays pressed while the OS decides which palette that
+ * is. Icons only — the row is the header's, and the labels travel as the
+ * accessible name and the tooltip instead of eating 200px of it.
+ */
+export interface QaThemeSwitcherProps {
+    readonly preference: QaThemePreference;
+    readonly onSelect: (preference: QaThemePreference) => void;
+}
+export declare function QaThemeSwitcher({ preference, onSelect, }: QaThemeSwitcherProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=QaThemeSwitcher.d.ts.map

package/lib/types/client/components/QaTurnNotice.d.ts

@@ -0,0 +1,55 @@
+import type { KeyboardEventHandler, RefObject } from "react";
+import type { QaTurnNoticeItem } from "../notifications/notification-dispatcher.js";
+export interface QaTurnNoticeProps {
+    /** Newest first; the stack keeps a handful and drops what it cannot show. */
+    readonly items: readonly QaTurnNoticeItem[];
+    /** Open the chat a notice is about. */
+    readonly onOpen: (sessionId: string) => void;
+    /** Take one line out of the stack. */
+    readonly onDismiss: (key: string) => void;
+    /**
+     * Offer the desktop channel. Omitted when it is unavailable, refused, or
+     * already answered: the offer is a single question per browser, never a
+     * fixture of the stack.
+     */
+    readonly onEnableDesktop?: () => void;
+    /**
+     * The stack is painted in `document.body`, so the surface that owns it keeps
+     * its Tab ring reachable: `rootRef` is the element the ring counts these
+     * buttons from, and `onKeyDown` traps the key here, where no ancestor
+     * `<main>` can hear it. Both are optional — a stand that reads the stack on
+     * its own needs neither.
+     */
+    readonly rootRef?: RefObject<HTMLDivElement>;
+    readonly onKeyDown?: KeyboardEventHandler<HTMLDivElement>;
+}
+export declare const QA_TURN_NOTICE_COPY: Readonly<{
+    region: "Уведомления о завершённых ходах";
+    finished: "Ход завершён";
+    dismiss: "Скрыть уведомление";
+    offer: "Системные уведомления приходят, даже когда эта вкладка свёрнута.";
+    offerAction: "Включить системные уведомления";
+}>;
+/**
+ * The line of the stack, named once so the markup and whatever walks the lines
+ * cannot drift apart: the surface hands the keyboard back to a neighbouring line
+ * when the one the reader stood on goes away, and it finds its lines by this
+ * class.
+ */
+export declare const QA_TURN_NOTICE_LINE_CLASS = "dsh-qa-turn-notice__item";
+export declare const QA_TURN_NOTICE_LINE_SELECTOR = ".dsh-qa-turn-notice__item";
+/**
+ * The offer block, named the same way. It shares the stack with the lines and is
+ * none of them: the surface reads the desktop opt-in by this class, rather than
+ * by whatever else the stack happens to hold.
+ */
+export declare const QA_TURN_NOTICE_OFFER_CLASS = "dsh-qa-turn-notice__offer";
+export declare const QA_TURN_NOTICE_OFFER_SELECTOR = ".dsh-qa-turn-notice__offer";
+/**
+ * The in-app half of a turn-completion notice: one line per chat that settled
+ * while the reader was elsewhere, carried by the page until they open the chat
+ * or wave it off. It names the chat and the fact — never the answer, which is
+ * what the transcript is for.
+ */
+export declare function QaTurnNotice(props: QaTurnNoticeProps): import("react").ReactPortal | null;
+//# sourceMappingURL=QaTurnNotice.d.ts.map

package/lib/types/client/focus-ring.d.ts

@@ -0,0 +1,65 @@
+import type { KeyboardEvent } from "react";
+/**
+ * Whether a modal gate has taken this element away from the keyboard: the
+ * element itself or an ancestor of it is marked inert.
+ *
+ * `inert` is read as a property, not looked up as an attribute. The gate marks
+ * the page inert from script (`QaWelcomeNotice`), a browser reflects that into
+ * the attribute, and jsdom stores nothing but the property on the element it
+ * was given — so the property is the one thing the two agree on, and the walk
+ * up the parent chain is what stands in for the browser's own inheritance.
+ * That a browser additionally refuses focus to everything found here is the
+ * browser's doing: what a live stand has to settle is that the ring's edge and
+ * the gate's own trap hold the keyboard between them without help from this
+ * file.
+ */
+export declare function isInert(element: HTMLElement): boolean;
+/**
+ * Every control of `root` the keyboard can still reach, in DOM order: what the
+ * page has not hidden, in its markup or in its layout, what still carries a
+ * place in the tab order, what no `inert` ancestor has handed to a dialog, and
+ * what no closed fold keeps out of sight.
+ */
+export declare function focusable(root: HTMLElement): HTMLElement[];
+/**
+ * Hand the keyboard to the first candidate that takes it.
+ *
+ * `focusable` reads the layout as well as the markup, so the candidates are
+ * already the controls the width leaves in the path. This is the post-condition
+ * for a refusal that no read predicts: a page can keep a control from taking
+ * focus in ways its own styles do not say, and a test environment applies no CSS
+ * at all, so each candidate is checked at the moment it is asked — a control that
+ * leaves `document.activeElement` where it was is passed over, instead of leaving
+ * the reader on the same control they pressed Tab from.
+ */
+export declare function focusFirst(candidates: readonly (HTMLElement | null | undefined)[]): void;
+/**
+ * The Tab ring over the roots a surface owns, in the order it walks them.
+ *
+ * A root under a modal gate contributes nothing: none of its controls can take
+ * focus, so an edge of the ring that pointed into one would be a key the page
+ * had already swallowed with nowhere to go — a Tab that sticks.
+ */
+export declare function focusRing(roots: readonly (HTMLElement | null)[]): HTMLElement[];
+/**
+ * Keep Tab inside the ring the surface painted, and let the reader out at
+ * neither edge.
+ *
+ * The ring is wider than `<main>`: a notice stack the surface paints in
+ * `document.body` sits after it in the page, so a Tab leaving the composer
+ * walks into the stack, and the edge where the key is caught and turned back is
+ * the stack's last button — not the last control inside `<main>`, which is where
+ * the ring used to stop the reader short of the notice. A key typed inside such
+ * a portal is trapped by the handler mounted on the portal: the `<main>` above
+ * it is not its ancestor and never hears the key.
+ *
+ * A ring with no controls in it answers nothing: there is nothing here to keep
+ * the reader inside, and a key prevented with nowhere to hand the focus is a key
+ * that sticks.
+ *
+ * The two ends the key is caught at are ends of the *walked* path, so a control
+ * the current width has switched off is neither of them: it holds no focus for
+ * the reader to stand on, and an edge drawn at it is an edge no Tab arrives at.
+ */
+export declare function trapKeys(event: KeyboardEvent<HTMLElement>, roots: readonly (HTMLElement | null)[]): void;
+//# sourceMappingURL=focus-ring.d.ts.map

package/lib/types/client/lineage.d.ts

@@ -31,19 +31,9 @@ export interface SubagentNameCandidate {
     /** The Host's own wording for the delegation; empty when it listed none. */
     readonly label: string;
 }
-/** One durable delegation catalog entry, as the Host lists it. */
-export interface SubagentCatalogEntry {
-    readonly kind?: string;
-    readonly id?: string;
-    readonly label?: string;
-}
-/** Direct delegation catalogs keyed by their parent chat. */
-export type SubagentCatalogs = Readonly<Record<string, {
-    readonly entries?: readonly SubagentCatalogEntry[];
-} | undefined>>;
 /**
- * Delegated sessions whose names a page may sign its notices with: the
- * children of the chats it lists, catalog labels first and list titles after.
+ * Delegated sessions whose names a page may sign its notices with: the children
+ * of the chats it lists, named by the row title the Host's session list carries.
  *
  * `chats` is the visible chat set — the account's own chats while accounts are
  * on, and `undefined` for a deployment without accounts, where every chat on
@@ -53,5 +43,5 @@ export type SubagentCatalogs = Readonly<Record<string, {
  * therefore contributes no id and no label — a foreign chat can neither sign
  * a notice nor be named by one.
  */
-export declare function visibleSubagentCandidates(byId: Readonly<Record<string, SessionSummary>>, catalogs: SubagentCatalogs, chats: ReadonlySet<string> | undefined): readonly SubagentNameCandidate[];
+export declare function visibleSubagentCandidates(byId: Readonly<Record<string, SessionSummary>>, chats: ReadonlySet<string> | undefined): readonly SubagentNameCandidate[];
 //# sourceMappingURL=lineage.d.ts.map