@carlonicora/nextjs-jsonapi 3.12.0 → 3.13.0

package/src/core/registry/ModuleRegistry.ts

@@ -16,6 +16,10 @@ export interface FoundationModuleDefinitions {
   Module: ModuleWithPermissions;
   Content: ModuleWithPermissions;
   HowTo: ModuleWithPermissions;
+  HandbookPage: ModuleWithPermissions;
+  HandbookSection: ModuleWithPermissions;
+  HandbookThread: ModuleWithPermissions;
+  HandbookThreadMessage: ModuleWithPermissions;
   Assistant: ModuleWithPermissions;
   AssistantMessage: ModuleWithPermissions;
   AssistantAction: ModuleWithPermissions;

package/src/features/assistant/components/parts/AssistantComposer.tsx

@@ -10,9 +10,28 @@ interface Props {
   disabled?: boolean;
   value?: string;
   onValueChange?: (v: string) => void;
+  /**
+   * Textarea placeholder. Defaults to the assistant's own copy ("ask me about a
+   * matter, a client, a document…"), which is wrong on any surface that is not
+   * the law-firm assistant.
+   */
+  placeholder?: string;
+  /**
+   * Label of the send button. Defaults to `ui.buttons.save`, which reads
+   * "Salva" — correct nowhere in a chat, kept only so existing callers do not
+   * move.
+   */
+  sendLabel?: string;
 }
 
-export function AssistantComposer({ onSend, disabled, value: controlled, onValueChange }: Props) {
+export function AssistantComposer({
+  onSend,
+  disabled,
+  value: controlled,
+  onValueChange,
+  placeholder,
+  sendLabel,
+}: Props) {
   const t = useTranslations();
   const [internal, setInternal] = useState("");
   const value = controlled ?? internal;
@@ -41,13 +60,13 @@ export function AssistantComposer({ onSend, disabled, value: controlled, onValue
           value={value}
           onChange={(e) => setValue(e.target.value)}
           onKeyDown={onKeyDown}
-          placeholder={t("features.assistant.composer_placeholder")}
+          placeholder={placeholder ?? t("features.assistant.composer_placeholder")}
           disabled={disabled}
           rows={2}
           className="min-h-[48px] resize-none border-0 bg-transparent focus-visible:ring-0"
         />
         <Button onClick={submit} disabled={!canSend} size="sm" className="h-8">
-          <ArrowUp className="me-1 h-4 w-4" /> {t("features.assistant.send")}
+          <ArrowUp className="me-1 h-4 w-4" /> {sendLabel ?? t("features.assistant.send")}
         </Button>
       </div>
       <div className="text-muted-foreground text-end text-xs">{t("features.assistant.keyboard_hint")}</div>

package/src/features/assistant/components/parts/AssistantSidebar.tsx

@@ -12,9 +12,17 @@ interface Props {
   activeId?: string;
   onSelect: (id: string) => void;
   onNew: () => void;
+  /**
+   * Label of the "start a new thread" button. Defaults to the assistant's own
+   * copy; a surface that is not the assistant (the handbook chat) passes its
+   * own so the control does not read "New assistant" on a handbook page.
+   */
+  newLabel?: string;
+  /** Shown when there are no threads. Same rationale as `newLabel`. */
+  emptyLabel?: string;
 }
 
-export function AssistantSidebar({ threads, activeId, onSelect, onNew }: Props) {
+export function AssistantSidebar({ threads, activeId, onSelect, onNew, newLabel, emptyLabel }: Props) {
   const t = useTranslations();
   const groups = groupThreadsByBucket(threads);
 
@@ -44,12 +52,14 @@ export function AssistantSidebar({ threads, activeId, onSelect, onNew }: Props)
     <aside className="bg-muted/30 flex w-64 flex-col border-e">
       <div className="border-b p-3">
         <Button onClick={onNew} className="w-full" size="sm">
-          <Plus className="me-1 h-4 w-4" /> {t("features.assistant.new")}
+          <Plus className="me-1 h-4 w-4" /> {newLabel ?? t("features.assistant.new")}
         </Button>
       </div>
       <div className="flex-1 overflow-y-auto p-2">
         {threads.length === 0 ? (
-          <div className="text-muted-foreground mt-6 text-center text-xs">{t("features.assistant.empty_sidebar")}</div>
+          <div className="text-muted-foreground mt-6 text-center text-xs">
+            {emptyLabel ?? t("features.assistant.empty_sidebar")}
+          </div>
         ) : (
           <>
             {renderSection(t("features.assistant.bucket_today"), groups.today)}

package/src/features/assistant/components/parts/AssistantThreadHeader.tsx

@@ -21,9 +21,16 @@ interface Props {
   assistant: AssistantInterface;
   onRename: (title: string) => Promise<void>;
   onDelete: () => Promise<void>;
+  /**
+   * Placeholder of the rename field. Defaults to the assistant's own copy
+   * ("name this assistant"), which misnames the thread on any other surface.
+   */
+  renamePlaceholder?: string;
+  /** Body of the delete confirmation. Same rationale as `renamePlaceholder`. */
+  deleteConfirmLabel?: string;
 }
 
-export function AssistantThreadHeader({ assistant, onRename, onDelete }: Props) {
+export function AssistantThreadHeader({ assistant, onRename, onDelete, renamePlaceholder, deleteConfirmLabel }: Props) {
   const t = useTranslations();
   const [renameValue, setRenameValue] = useState(assistant.title);
   const [renameOpen, setRenameOpen] = useState(false);
@@ -56,7 +63,7 @@ export function AssistantThreadHeader({ assistant, onRename, onDelete }: Props)
             <Input
               value={renameValue}
               onChange={(e) => setRenameValue(e.target.value)}
-              placeholder={t("features.assistant.rename_placeholder")}
+              placeholder={renamePlaceholder ?? t("features.assistant.rename_placeholder")}
             />
             <Button onClick={handleRename} size="sm">
               {t("ui.buttons.save")}
@@ -73,7 +80,7 @@ export function AssistantThreadHeader({ assistant, onRename, onDelete }: Props)
           />
           <DialogContent>
             <DialogHeader>
-              <DialogTitle>{t("features.assistant.delete_confirm")}</DialogTitle>
+              <DialogTitle>{deleteConfirmLabel ?? t("features.assistant.delete_confirm")}</DialogTitle>
             </DialogHeader>
             <DialogFooter>
               <Button variant="outline" onClick={() => setDeleteOpen(false)}>

package/src/features/assistant/contexts/AssistantContext.tsx

@@ -22,7 +22,13 @@ interface AssistantContextValue {
   failedMessageIds: Set<string>;
   sendMessage(
     content: string,
-    opts?: { howToMode?: boolean; limitToHowToId?: string; contentBlocks?: unknown[] },
+    opts?: {
+      howToMode?: boolean;
+      limitToHowToId?: string;
+      handbookMode?: boolean;
+      limitToHandbookPageId?: string;
+      contentBlocks?: unknown[];
+    },
   ): Promise<void>;
   retrySend(tempId: string): Promise<void>;
   selectThread(id: string): Promise<void>;
@@ -55,6 +61,13 @@ interface Props {
    * it, so a scoped surface never shows or creates cross-scope threads.
    */
   scope?: { type: string; id: string };
+  /**
+   * Confines every turn of this provider to one retrieval mode. The handbook
+   * surface sets `{ handbookMode: true }` so the flag does not have to be
+   * threaded through the composer on each send — the same reason `scope`
+   * exists on this provider.
+   */
+  retrievalMode?: { handbookMode?: boolean; limitToHandbookPageId?: string };
   /**
    * Builds the browser URL for a thread. Defaults to `/assistants/{id}` (or
    * `/assistants` when no thread is active), which is only correct for the
@@ -100,6 +113,7 @@ export function AssistantProvider({
   titleOverride,
   breadcrumbsOverride,
   scope,
+  retrievalMode,
   threadUrl,
 }: Props) {
   const t = useTranslations();
@@ -130,7 +144,16 @@ export function AssistantProvider({
   const { socket } = useSocketContext();
 
   const sendMessage = useCallback(
-    async (content: string, opts?: { howToMode?: boolean; limitToHowToId?: string; contentBlocks?: unknown[] }) => {
+    async (
+      content: string,
+      opts?: {
+        howToMode?: boolean;
+        limitToHowToId?: string;
+        handbookMode?: boolean;
+        limitToHandbookPageId?: string;
+        contentBlocks?: unknown[];
+      },
+    ) => {
       const trimmed = content.trim();
       if (!trimmed) return;
 
@@ -155,6 +178,8 @@ export function AssistantProvider({
             firstMessage: trimmed,
             howToMode: opts?.howToMode,
             limitToHowToId: opts?.limitToHowToId,
+            handbookMode: opts?.handbookMode ?? retrievalMode?.handbookMode,
+            limitToHandbookPageId: opts?.limitToHandbookPageId ?? retrievalMode?.limitToHandbookPageId,
             contentBlocks: opts?.contentBlocks,
             boundContent: scope,
           };
@@ -180,6 +205,8 @@ export function AssistantProvider({
                 content: trimmed,
                 howToMode: opts?.howToMode,
                 limitToHowToId: opts?.limitToHowToId,
+                handbookMode: opts?.handbookMode ?? retrievalMode?.handbookMode,
+                limitToHandbookPageId: opts?.limitToHandbookPageId ?? retrievalMode?.limitToHandbookPageId,
                 contentBlocks: opts?.contentBlocks,
               });
           setMessages((prev) => [...stripOptimistic(prev), ...result]);
@@ -196,7 +223,7 @@ export function AssistantProvider({
         setStatus(undefined);
       }
     },
-    [assistant, messages, socket, operatorMode, scope, manageUrl, resolveThreadUrl],
+    [assistant, messages, socket, operatorMode, scope, retrievalMode, manageUrl, resolveThreadUrl],
   );
 
   const appendResolvedMessage = useCallback((message: AssistantMessageInterface) => {

package/src/features/assistant/contexts/__tests__/AssistantContext.spec.tsx

@@ -455,6 +455,38 @@ describe("AssistantContext", () => {
     );
   });
 
+  it("forwards handbookMode passed on the send", async () => {
+    const existing = buildAssistantDehydrated({ id: "a-3", title: "Existing" });
+    AssistantService.appendMessage = vi.fn().mockResolvedValue([]);
+
+    const { result } = renderHook(() => useAssistantContext(), {
+      wrapper: ({ children }) => <AssistantProvider dehydratedAssistant={existing}>{children}</AssistantProvider>,
+    });
+    await act(async () => {
+      await result.current.sendMessage("Come funziona il modulo chunk?", { handbookMode: true });
+    });
+
+    expect(AssistantService.appendMessage).toHaveBeenCalledWith(expect.objectContaining({ handbookMode: true }));
+  });
+
+  it("forwards the provider's retrievalMode when the send passes nothing", async () => {
+    const existing = buildAssistantDehydrated({ id: "a-4", title: "Existing" });
+    AssistantService.appendMessage = vi.fn().mockResolvedValue([]);
+
+    const { result } = renderHook(() => useAssistantContext(), {
+      wrapper: ({ children }) => (
+        <AssistantProvider dehydratedAssistant={existing} retrievalMode={{ handbookMode: true }}>
+          {children}
+        </AssistantProvider>
+      ),
+    });
+    await act(async () => {
+      await result.current.sendMessage("Come funziona il modulo chunk?");
+    });
+
+    expect(AssistantService.appendMessage).toHaveBeenCalledWith(expect.objectContaining({ handbookMode: true }));
+  });
+
   it("calls service without opts when called with content only (regression)", async () => {
     const replaceState = vi.spyOn(window.history, "replaceState").mockImplementation(() => {});
     const created = buildAssistantStub({ id: "a-1" });

package/src/features/assistant/data/Assistant.ts

@@ -58,6 +58,8 @@ export class Assistant extends AbstractApiData implements AssistantInterface {
           ...(data.title !== undefined ? { title: data.title } : {}),
           ...(data.howToMode !== undefined ? { howToMode: data.howToMode } : {}),
           ...(data.limitToHowToId !== undefined ? { limitToHowToId: data.limitToHowToId } : {}),
+          ...(data.handbookMode !== undefined ? { handbookMode: data.handbookMode } : {}),
+          ...(data.limitToHandbookPageId !== undefined ? { limitToHandbookPageId: data.limitToHandbookPageId } : {}),
         },
         ...(data.boundContent !== undefined
           ? {

package/src/features/assistant/data/AssistantInterface.ts

@@ -5,6 +5,8 @@ export type AssistantInput = {
   title?: string;
   howToMode?: boolean;
   limitToHowToId?: string;
+  handbookMode?: boolean;
+  limitToHandbookPageId?: string;
   /**
    * BlockNote document behind `firstMessage`. Sent alongside the flattened
    * text so the server can re-derive the content and read `@`-mentions from

package/src/features/assistant/data/AssistantService.ts

@@ -67,6 +67,8 @@ export class AssistantService extends AbstractService {
     content: string;
     howToMode?: boolean;
     limitToHowToId?: string;
+    handbookMode?: boolean;
+    limitToHandbookPageId?: string;
     /** BlockNote document. Serialised by the model into `content`; never its own attribute. */
     contentBlocks?: unknown[];
   }): Promise<AssistantMessageInterface[]> {
@@ -83,6 +85,8 @@ export class AssistantService extends AbstractService {
         content: params.content,
         howToMode: params.howToMode,
         limitToHowToId: params.limitToHowToId,
+        handbookMode: params.handbookMode,
+        limitToHandbookPageId: params.limitToHandbookPageId,
         contentBlocks: params.contentBlocks,
       }),
       overridesJsonApiCreation: true,

package/src/features/assistant-message/components/parts/MessageSourcesContainer.tsx

@@ -87,7 +87,11 @@ export function MessageSourcesContainer({ message, isLatestAssistant, onSelectFo
 
   useEffect(() => {
     if (groups.size === 0) {
-      setResolved([]);
+      // Functional update, and a no-op when it is already empty. A bare
+      // `setResolved([])` sets a NEW array on every run, so a caller whose
+      // `message.citations` identity changes per render loops here until React
+      // gives up with "Maximum update depth exceeded".
+      setResolved((current) => (current.length === 0 ? current : []));
       return;
     }
     let cancelled = false;

package/src/features/assistant-message/data/AssistantMessage.ts

@@ -129,6 +129,8 @@ export class AssistantMessage extends AbstractApiData implements AssistantMessag
     content: string;
     howToMode?: boolean;
     limitToHowToId?: string;
+    handbookMode?: boolean;
+    limitToHandbookPageId?: string;
     contentBlocks?: unknown[];
   }) {
     return {
@@ -142,18 +144,41 @@ export class AssistantMessage extends AbstractApiData implements AssistantMessag
           content: params.contentBlocks !== undefined ? JSON.stringify(params.contentBlocks) : params.content,
           ...(params.howToMode !== undefined ? { howToMode: params.howToMode } : {}),
           ...(params.limitToHowToId !== undefined ? { limitToHowToId: params.limitToHowToId } : {}),
+          ...(params.handbookMode !== undefined ? { handbookMode: params.handbookMode } : {}),
+          ...(params.limitToHandbookPageId !== undefined
+            ? { limitToHandbookPageId: params.limitToHandbookPageId }
+            : {}),
         },
       },
     };
   }
 
   static buildOptimistic(params: { content: string; position: number; assistantId?: string }): AssistantMessage {
+    return AssistantMessage.buildLocal({ ...params, role: "user", isOptimistic: true });
+  }
+
+  /**
+   * A message that exists only on the client, for a surface that renders the
+   * chat presentation without persisting a thread.
+   *
+   * `buildOptimistic` is the user-turn case and delegates here. The handbook
+   * ask surface is the other caller: it has no Assistant and no stored
+   * messages, but it renders through MessageList/MessageItem like every other
+   * chat in the product, so it needs both roles.
+   */
+  static buildLocal(params: {
+    role: AssistantMessageRole;
+    content: string;
+    position: number;
+    assistantId?: string;
+    isOptimistic?: boolean;
+  }): AssistantMessage {
     const msg = new AssistantMessage();
     const jsonApi: Record<string, unknown> = {
       id: uuidv4(),
       type: Modules.AssistantMessage.name,
       attributes: {
-        role: "user",
+        role: params.role,
         content: params.content,
         position: params.position,
       },
@@ -164,7 +189,7 @@ export class AssistantMessage extends AbstractApiData implements AssistantMessag
       };
     }
     msg.rehydrate({ jsonApi: jsonApi as any, included: [] });
-    msg._isOptimistic = true;
+    msg._isOptimistic = params.isOptimistic ?? false;
     return msg;
   }
 }

package/src/features/content/data/content.interface.ts

@@ -5,7 +5,7 @@ export type ContentInput = {
   id: string;
   name?: string;
 
-  authorId: string;
+  authorId?: string;
   editorIds?: string[];
 };
 

package/src/features/handbook/HandbookPageModule.ts

@@ -0,0 +1,41 @@
+import { BookOpenIcon } from "lucide-react";
+import { createJsonApiInclusion } from "../../core";
+import { ModuleFactory } from "../../permissions";
+import { HandbookPage } from "./data/HandbookPage";
+
+export const HandbookPageModule = (factory: ModuleFactory) =>
+  factory({
+    moduleId: "b1f1c2d6-6a0e-4e93-9b6d-3f5f4a2c81e7",
+    pageUrl: "/administration/handbook",
+    name: "handbookpages",
+    model: HandbookPage,
+    icon: BookOpenIcon,
+    inclusions: {
+      lists: {
+        // `content` is deliberately omitted: the list renders titles and
+        // status, and a thousand pages of markdown do not belong in a list
+        // payload. `section`, `order` and `summary` are the index fields the
+        // contents page groups, orders and describes pages by, so they are the
+        // one part of the payload the list surface cannot do without.
+        //
+        // `displayTitle` and `displaySummary` are the translated halves of the
+        // two strings the contents page prints, and a sparse fieldset that
+        // omitted them would leave every row in English. `displayContent` is
+        // NOT here for the same reason `content` is not: it is the whole
+        // markdown body, and it belongs to the detail read alone.
+        fields: [
+          createJsonApiInclusion("handbookpages", [
+            "path",
+            "title",
+            "displayTitle",
+            "section",
+            "order",
+            "summary",
+            "displaySummary",
+            "wordCount",
+            "aiStatus",
+          ]),
+        ],
+      },
+    },
+  });

package/src/features/handbook/HandbookSectionModule.ts

@@ -0,0 +1,35 @@
+import { LibraryIcon } from "lucide-react";
+import { createJsonApiInclusion } from "../../core";
+import { ModuleFactory } from "../../permissions";
+import { HandbookSection } from "./data/HandbookSection";
+
+/**
+ * One top-level directory of the documentation tree. Like the thread message,
+ * it has no `pageUrl` — a section has no page of its own; it is a heading on
+ * the contents surface and nothing more.
+ */
+export const HandbookSectionModule = (factory: ModuleFactory) =>
+  factory({
+    moduleId: "6b0a2f74-1c53-4a0e-9c1d-2e7b4a9d6f30",
+    name: "handbooksections",
+    model: HandbookSection,
+    icon: LibraryIcon,
+    inclusions: {
+      lists: {
+        // `HandbookSectionService.findMany` is the ONLY read of this resource and
+        // it limits to these fields, so the translated halves have to be here:
+        // without them every section heading on the contents page and in the
+        // reader's navigator would stay English however good the translation is.
+        fields: [
+          createJsonApiInclusion("handbooksections", [
+            "key",
+            "title",
+            "displayTitle",
+            "summary",
+            "displaySummary",
+            "order",
+          ]),
+        ],
+      },
+    },
+  });

package/src/features/handbook/HandbookThreadMessageModule.ts

@@ -0,0 +1,21 @@
+import { MessageCircleQuestionIcon } from "lucide-react";
+import { createJsonApiInclusion } from "../../core";
+import { ModuleFactory } from "../../permissions";
+import { HandbookThreadMessage } from "./data/HandbookThreadMessage";
+
+/**
+ * One turn of a handbook conversation. Like the thread, it has no `pageUrl` —
+ * a message is only ever read as part of its thread.
+ */
+export const HandbookThreadMessageModule = (factory: ModuleFactory) =>
+  factory({
+    moduleId: "bef354f2-70e1-4f4f-9953-10d3d74cad0c",
+    name: "handbookthreadmessages",
+    model: HandbookThreadMessage,
+    icon: MessageCircleQuestionIcon,
+    inclusions: {
+      lists: {
+        fields: [createJsonApiInclusion("handbookthreadmessages", ["role", "content", "position", "sources"])],
+      },
+    },
+  });

package/src/features/handbook/HandbookThreadModule.ts

@@ -0,0 +1,29 @@
+import { MessagesSquareIcon } from "lucide-react";
+import { createJsonApiInclusion } from "../../core";
+import { ModuleFactory } from "../../permissions";
+import { HandbookThread } from "./data/HandbookThread";
+
+/**
+ * A persisted handbook conversation.
+ *
+ * It carries no `pageUrl`: a thread is selected inside the ask surface
+ * (`/administration/handbook/chat`), never routed to on its own, and a
+ * `pageUrl` here would add a phantom entry to the RBAC path map.
+ *
+ * `lists` deliberately narrows to the title — the sidebar renders nothing else,
+ * and side-loading every message of every thread into the list payload is what
+ * the single-resource endpoint is for.
+ */
+export const HandbookThreadModule = (factory: ModuleFactory) =>
+  factory({
+    moduleId: "aea692c4-7163-49bd-9ddc-1052cc06fa14",
+    name: "handbookthreads",
+    model: HandbookThread,
+    icon: MessagesSquareIcon,
+    identifier: ["title"],
+    inclusions: {
+      lists: {
+        fields: [createJsonApiInclusion("handbookthreads", ["title"])],
+      },
+    },
+  });

package/src/features/handbook/components/containers/HandbookAdminContainer.tsx

@@ -0,0 +1,17 @@
+"use client";
+
+import HandbookContents from "../lists/HandbookContents";
+
+/**
+ * The administration route's entry point for the manual.
+ *
+ * `RoundPageContainer` moved down into `HandbookContents`, which is the only
+ * component that can supply it: the container's title bar reads its heading
+ * from `useSharedContext()`, so `HandbookProvider` has to wrap it, and the
+ * provider's `functions` (the ask launcher, Sincronizza and the status line)
+ * are built from the state `HandbookContents` holds. `HandbookAskContainer`
+ * composes its own surface the same way.
+ */
+export default function HandbookAdminContainer() {
+  return <HandbookContents />;
+}

package/src/features/handbook/components/containers/HandbookAskContainer.tsx

@@ -0,0 +1,142 @@
+"use client";
+
+import { MessagesSquareIcon, Sparkles } from "lucide-react";
+import { useTranslations } from "next-intl";
+import { useMemo } from "react";
+
+import { RoundPageContainer } from "../../../../components/containers/RoundPageContainer";
+import { SectionHeader } from "../../../../components/typography";
+import { Modules } from "../../../../core";
+import { AssistantComposer } from "../../../assistant/components/parts/AssistantComposer";
+import { AssistantSidebar } from "../../../assistant/components/parts/AssistantSidebar";
+import { AssistantThread } from "../../../assistant/components/parts/AssistantThread";
+import { HandbookProvider } from "../../contexts/HandbookContext";
+import { useHandbookAsk } from "../../hooks/useHandbookAsk";
+
+/**
+ * The handbook ask surface.
+ *
+ * Composition is copied from `AssistantPageContainer` — the full-page assistant
+ * — top to bottom: the thread list lives in the page's details panel (which
+ * renders it on the trailing side) and the conversation fills the card. The
+ * transcript is rendered by the SAME components as every other chat in the
+ * product (`AssistantSidebar`, `AssistantThread`),
+ * which take their data as plain props and are typed against the structural
+ * `AssistantInterface` / `AssistantMessageInterface` that `HandbookThread` and
+ * `HandbookThreadMessage` implement.
+ *
+ * Two deliberate deviations from that reference, both forced by the data source:
+ *
+ * 1. It cannot MOUNT `AssistantPageContainer`, which reads
+ *    `useAssistantContext()`. That provider is bound to the `Assistant` entity,
+ *    which is company scoped, and a platform administrator has no company — so
+ *    the handbook owns its own threads, and the state that provider would hold
+ *    lives in `useHandbookAsk` — shared with the ask sheet, which is the same
+ *    conversation on a different surface.
+ * 2. The composer is the plain `AssistantComposer`, not the BlockNote one. The
+ *    BlockNote composer exists so a first message can carry `@`-mentions of
+ *    product entities; the handbook agent answers from documentation pages and
+ *    has no entities to mention, so that machinery would be dead weight.
+ *
+ * Every label is passed in from the `handbook.*` namespace. The assistant's own
+ * copy ("New assistant", "no assistants yet", "ask me about a matter, a client,
+ * a document…") is wrong on this surface, so the shared parts take optional
+ * label props that default to their existing text.
+ */
+
+type HandbookAskContainerProps = {
+  /** Thread to open on mount, when the route carries one. */
+  handbookThreadId?: string;
+};
+
+export function HandbookAskContainer({ handbookThreadId }: HandbookAskContainerProps = {}) {
+  const t = useTranslations();
+
+  // The conversation itself lives in `useHandbookAsk`, because the ask sheet
+  // holds the same one. The route keeps the default `syncUrl: true`, so the
+  // address bar still follows the open thread exactly as it did when this
+  // component owned the state.
+  const { threads, thread, messages, sending, ask, selectThread, startNew } = useHandbookAsk({ handbookThreadId });
+
+  const showThread = !!thread || sending || messages.length > 0;
+  // Memoised, and not as a micro-optimisation: it was a fresh object on every
+  // render being fed into RoundPageContainer, which is the shape that produces
+  // React's "Maximum update depth exceeded".
+  const details = useMemo(
+    () => (
+      // The panel supplies its own padding and border; cancel both so the list
+      // reads as the panel body rather than a card inside it.
+      <div className="-m-4 flex h-full min-h-0 [&>aside]:w-full [&>aside]:border-e-0 [&>aside]:bg-transparent">
+        <AssistantSidebar
+          threads={threads}
+          activeId={thread?.id}
+          onSelect={selectThread}
+          onNew={startNew}
+          newLabel={t("handbook.chat.new")}
+          emptyLabel={t("handbook.chat.empty_sidebar")}
+        />
+      </div>
+    ),
+    [selectThread, startNew, t, thread?.id, threads],
+  );
+
+  return (
+    // `RoundPageContainer` reads the page heading from the shared context, and
+    // `forceHeader` is what renders it — without a provider the hook throws.
+    // `HandbookProvider` is that provider for every handbook surface; the ask
+    // is the one that overrides the title, because it is a conversation about
+    // the manual rather than a page of it.
+    <HandbookProvider titleType={t("handbook.chat.title")}>
+      <RoundPageContainer
+        module={Modules.HandbookPage}
+        id={thread?.id}
+        fullWidth
+        forceHeader
+        defaultDetailsOpen
+        detailsTitle={t("handbook.chat.list_title")}
+        detailsIcon={<MessagesSquareIcon />}
+        details={details}
+      >
+        {/* No `rounded-lg border` here. `AssistantPageContainer` has them on
+            this wrapper, but RoundPageContainer already draws the card's border
+            around this child, so copying them doubles it. a360's own chat
+            content — ConversationMessageContainer — is a bare
+            `flex h-full w-full min-h-0 flex-col`, and that is the shape this
+            app's pages are built to. */}
+        <div className="flex h-full min-h-0 w-full flex-col overflow-hidden">
+          {showThread ? (
+            <>
+              {/* No per-thread header. `RoundPageContainer` already renders the
+                  page header above this card, and a second title row inside it
+                  is the double header. `AssistantThreadHeader` also carries
+                  rename/delete, which this surface does not offer —
+                  `ConversationMessageContainer` has no such row either. */}
+              <AssistantThread
+                messages={messages}
+                sending={sending}
+                status={t("handbook.chat.pending")}
+                onSelectFollowUp={ask}
+              />
+            </>
+          ) : (
+            <div className="flex flex-1 items-center justify-center p-10">
+              <div className="flex max-w-2xl flex-col items-center text-center">
+                <span className="mb-3 flex h-10 w-10 items-center justify-center rounded-full bg-gradient-to-br from-blue-400 to-violet-500 text-white">
+                  <Sparkles className="h-5 w-5" />
+                </span>
+                <SectionHeader>{t("handbook.chat.empty_state.title")}</SectionHeader>
+                <p className="text-muted-foreground mt-1 text-sm">{t("handbook.chat.empty_state.subtitle")}</p>
+              </div>
+            </div>
+          )}
+          <AssistantComposer
+            onSend={ask}
+            disabled={sending}
+            placeholder={t("handbook.chat.placeholder")}
+            sendLabel={t("handbook.chat.ask")}
+          />
+        </div>
+      </RoundPageContainer>
+    </HandbookProvider>
+  );
+}