@carlonicora/nextjs-jsonapi 3.12.0 → 3.13.0

package/src/features/handbook/data/handbookDisplay.ts

@@ -0,0 +1,55 @@
+import { HandbookPageInterface } from "./HandbookPageInterface";
+import { HandbookSectionInterface } from "./HandbookSectionInterface";
+
+/**
+ * The handbook is INDEXED in English and SHOWN translated.
+ *
+ * A page's translation lives on the same node as its English original — matched
+ * by `path` at ingest time — and arrives as ordinary attributes beside it.
+ * There is no second id, no locale in any URL and no second resource, so
+ * nothing about ordering, grouping or section membership changes: `path`,
+ * `order` and `section` stay English and are still what every sort reads. Only
+ * the rendered words are resolved here.
+ *
+ * These five functions are the ONE place that resolution happens. A component
+ * reaching for `page.title` directly renders English to an Italian reader, and
+ * a per-component `??` would be five copies of the same rule to keep in step.
+ *
+ * Each parameter is a `Pick` of the interface rather than the whole of it, so a
+ * caller holding a projection — a row from a sparse fieldset, a spec fixture —
+ * passes it without a cast, while a rename on either interface still breaks
+ * this file rather than drifting from it.
+ */
+
+/** The page title to render: the translation when there is one, else English. */
+export function handbookPageTitle(page: Pick<HandbookPageInterface, "title" | "displayTitle">): string {
+  return page.displayTitle ?? page.title;
+}
+
+/** The page's one-line description, translated when the ingest matched one. */
+export function handbookPageSummary(
+  page: Pick<HandbookPageInterface, "summary" | "displaySummary">,
+): string | undefined {
+  return page.displaySummary ?? page.summary;
+}
+
+/**
+ * The markdown body to render. Detail-only, exactly as `content` is:
+ * `displayContent` is the whole file and is absent from every list payload, so
+ * this is never called on a row that came out of a list read.
+ */
+export function handbookPageContent(page: Pick<HandbookPageInterface, "content" | "displayContent">): string {
+  return page.displayContent ?? page.content;
+}
+
+/** The section heading to render, translated when the ingest matched one. */
+export function handbookSectionTitle(section: Pick<HandbookSectionInterface, "title" | "displayTitle">): string {
+  return section.displayTitle ?? section.title;
+}
+
+/** The section blurb to render, translated when the ingest matched one. */
+export function handbookSectionSummary(
+  section: Pick<HandbookSectionInterface, "summary" | "displaySummary">,
+): string | undefined {
+  return section.displaySummary ?? section.summary;
+}

package/src/features/handbook/data/index.ts

@@ -0,0 +1,16 @@
+export * from "./handbookDisplay";
+export * from "./HandbookPage";
+export * from "./HandbookPageFields";
+export * from "./HandbookPageInput";
+export * from "./HandbookPageInterface";
+export * from "./HandbookPageService";
+export * from "./HandbookSection";
+export * from "./HandbookSectionInput";
+export * from "./HandbookSectionInterface";
+export * from "./HandbookSectionService";
+export * from "./HandbookThread";
+export * from "./HandbookThreadInterface";
+export * from "./HandbookThreadMessage";
+export * from "./HandbookThreadMessageInterface";
+export * from "./HandbookThreadMessageService";
+export * from "./HandbookThreadService";

package/src/features/handbook/hooks/__tests__/useHandbookAsk.spec.ts

@@ -0,0 +1,198 @@
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { ApiRequestDataTypeInterface } from "../../../../core/interfaces/ApiRequestDataTypeInterface";
+import { DataClassRegistry } from "../../../../core/registry/DataClassRegistry";
+import { ModuleRegistry } from "../../../../core/registry/ModuleRegistry";
+import { HandbookThread } from "../../data/HandbookThread";
+import { HandbookThreadMessage } from "../../data/HandbookThreadMessage";
+import { HandbookThreadMessageService } from "../../data/HandbookThreadMessageService";
+import { HandbookThreadService } from "../../data/HandbookThreadService";
+import { useHandbookAsk } from "../useHandbookAsk";
+
+vi.mock("../../data/HandbookThreadService", () => ({
+  HandbookThreadService: {
+    findMany: vi.fn(),
+    findOne: vi.fn(),
+    create: vi.fn(),
+    rename: vi.fn(),
+    delete: vi.fn(),
+  },
+}));
+
+vi.mock("../../data/HandbookThreadMessageService", () => ({
+  HandbookThreadMessageService: { ask: vi.fn() },
+}));
+
+// The models resolve Modules.HandbookThread / Modules.HandbookThreadMessage
+// lazily through ModuleRegistry, and `_readIncluded` resolves the CONSTRUCTOR
+// through DataClassRegistry. Registering both is the package's spec convention
+// (see HandbookAskContainer.spec.tsx) and is preferred to mocking the core
+// barrel the hook also reads `rehydrate` from.
+const registerIfAbsent = (key: string, module: ApiRequestDataTypeInterface) => {
+  try {
+    ModuleRegistry.get(key as any);
+  } catch {
+    ModuleRegistry.register(key, module);
+  }
+};
+
+beforeAll(() => {
+  registerIfAbsent("HandbookPage", { name: "handbookpages", pageUrl: "/administration/handbook" } as any);
+  const threadModule = { name: "handbookthreads", model: HandbookThread } as any;
+  const messageModule = { name: "handbookthreadmessages", model: HandbookThreadMessage } as any;
+  registerIfAbsent("HandbookThread", threadModule);
+  registerIfAbsent("HandbookThreadMessage", messageModule);
+  DataClassRegistry.registerObjectClass(threadModule, HandbookThread as any);
+  DataClassRegistry.registerObjectClass(messageModule, HandbookThreadMessage as any);
+});
+
+function buildThread(params: {
+  id: string;
+  title: string;
+  messages?: { id: string; role: "user" | "assistant"; content: string; position: number; sources?: string[] }[];
+}): HandbookThread {
+  const messages = params.messages ?? [];
+  return new HandbookThread().rehydrate({
+    jsonApi: {
+      id: params.id,
+      type: "handbookthreads",
+      attributes: { title: params.title },
+      meta: { updatedAt: new Date().toISOString() },
+      relationships: {
+        messages: { data: messages.map((m) => ({ id: m.id, type: "handbookthreadmessages" })) },
+      },
+    },
+    included: messages.map((m) => ({
+      id: m.id,
+      type: "handbookthreadmessages",
+      attributes: { role: m.role, content: m.content, position: m.position, sources: m.sources ?? [] },
+    })),
+  } as any);
+}
+
+const answered = (id: string) =>
+  buildThread({
+    id,
+    title: "Filtri di azienda",
+    messages: [
+      { id: "m1", role: "user", content: "Perché?", position: 0 },
+      { id: "m2", role: "assistant", content: "Inietta il filtro di azienda.", position: 1 },
+    ],
+  });
+
+describe("useHandbookAsk", () => {
+  beforeEach(() => {
+    vi.mocked(HandbookThreadService.findMany).mockReset().mockResolvedValue([]);
+    vi.mocked(HandbookThreadService.findOne).mockReset().mockResolvedValue(answered("t1"));
+    vi.mocked(HandbookThreadService.create)
+      .mockReset()
+      .mockResolvedValue(buildThread({ id: "t1", title: "" }));
+    vi.mocked(HandbookThreadMessageService.ask).mockReset().mockResolvedValue(undefined);
+  });
+
+  it("adds an optimistic user message then replaces the transcript from the read-back", async () => {
+    const { result } = renderHook(() => useHandbookAsk());
+
+    await act(async () => {
+      await result.current.ask("How do migrations run?");
+    });
+
+    await waitFor(() => expect(result.current.messages).toHaveLength(2));
+    expect(HandbookThreadService.findOne).toHaveBeenCalledWith({ id: "t1" });
+    expect(result.current.thread?.id).toBe("t1");
+  });
+
+  it("passes handbookPageId to the create call when one is supplied", async () => {
+    const { result } = renderHook(() => useHandbookAsk({ syncUrl: false }));
+
+    await act(async () => {
+      await result.current.ask("Why?", { handbookPageId: "p2" });
+    });
+
+    expect(HandbookThreadService.create).toHaveBeenCalledWith(expect.objectContaining({ handbookPageId: "p2" }));
+  });
+
+  it("passes handbookPageId to the append call on an open thread", async () => {
+    const { result } = renderHook(() => useHandbookAsk({ syncUrl: false, handbookThreadId: "t1" }));
+    await waitFor(() => expect(result.current.thread?.id).toBe("t1"));
+
+    await act(async () => {
+      await result.current.ask("Why?", { handbookPageId: "p2" });
+    });
+
+    expect(HandbookThreadMessageService.ask).toHaveBeenCalledWith(
+      expect.objectContaining({ threadId: "t1", handbookPageId: "p2" }),
+    );
+    expect(HandbookThreadService.create).not.toHaveBeenCalled();
+  });
+
+  it("keeps the url on the open thread by default", async () => {
+    const replaceState = vi.spyOn(window.history, "replaceState");
+    const { result } = renderHook(() => useHandbookAsk());
+
+    await act(async () => {
+      await result.current.ask("Why?");
+    });
+
+    expect(replaceState).toHaveBeenCalledWith(null, "", "/administration/handbook/chat/t1");
+    replaceState.mockRestore();
+  });
+
+  it("does not touch the URL when syncUrl is false", async () => {
+    const replaceState = vi.spyOn(window.history, "replaceState");
+    const { result } = renderHook(() => useHandbookAsk({ syncUrl: false }));
+
+    await act(async () => {
+      await result.current.ask("Why?");
+    });
+
+    expect(replaceState).not.toHaveBeenCalled();
+    replaceState.mockRestore();
+  });
+
+  it("appends one assistant-side failure message when the API rejects", async () => {
+    vi.mocked(HandbookThreadService.create).mockRejectedValueOnce(new Error("400"));
+    const { result } = renderHook(() => useHandbookAsk());
+
+    await act(async () => {
+      await result.current.ask("Why?");
+    });
+
+    await waitFor(() => expect(result.current.messages).toHaveLength(2));
+    expect(result.current.messages.at(-1)?.role).toBe("assistant");
+    expect(result.current.messages.at(-1)?.content).toBe("handbook.chat.failed");
+    // The asked question stays in the transcript.
+    expect(result.current.messages[0].content).toBe("Why?");
+  });
+
+  it("opens the routed thread on mount without rewriting the url", async () => {
+    const replaceState = vi.spyOn(window.history, "replaceState");
+
+    const { result } = renderHook(() => useHandbookAsk({ handbookThreadId: "t1" }));
+
+    await waitFor(() => expect(result.current.messages).toHaveLength(2));
+    expect(HandbookThreadService.findOne).toHaveBeenCalledWith({ id: "t1" });
+    expect(replaceState).not.toHaveBeenCalled();
+    replaceState.mockRestore();
+  });
+
+  it("loads the thread list and reloads the transcript on select", async () => {
+    vi.mocked(HandbookThreadService.findMany).mockResolvedValue([
+      buildThread({ id: "t1", title: "Filtri di azienda" }),
+    ]);
+    const { result } = renderHook(() => useHandbookAsk());
+
+    await waitFor(() => expect(result.current.threads).toHaveLength(1));
+
+    await act(async () => {
+      await result.current.selectThread("t1");
+    });
+
+    expect(result.current.messages).toHaveLength(2);
+
+    act(() => result.current.startNew());
+    expect(result.current.thread).toBeUndefined();
+    expect(result.current.messages).toHaveLength(0);
+  });
+});

package/src/features/handbook/hooks/useHandbookAsk.ts

@@ -0,0 +1,213 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { useCallback, useEffect, useState } from "react";
+import { v4 } from "uuid";
+
+import { Modules, rehydrate } from "../../../core";
+import { usePageUrlGenerator } from "../../../hooks";
+import { HandbookThreadMessage } from "../data/HandbookThreadMessage";
+import type { HandbookThreadInterface } from "../data/HandbookThreadInterface";
+import type { HandbookThreadMessageInterface } from "../data/HandbookThreadMessageInterface";
+import { HandbookThreadMessageService } from "../data/HandbookThreadMessageService";
+import { HandbookThreadService } from "../data/HandbookThreadService";
+
+/**
+ * The state of one handbook conversation, extracted verbatim from
+ * `HandbookAskContainer`.
+ *
+ * Two surfaces now hold a conversation — the full `/chat` route and the side
+ * sheet reachable from contents and reader — and they must behave identically:
+ * same optimistic user message, same read-back through
+ * `HandbookThreadService.findOne`, same error branch. Duplicating that in two
+ * components is how the two drift, so it lives here and both consume it.
+ *
+ * The one difference is the address bar. The route keeps the url on the open
+ * thread; opening a sheet is not a navigation, so the sheet passes
+ * `syncUrl: false` and nothing is written to history.
+ */
+
+/**
+ * Sources ride in the markdown rather than in a bespoke block: the message
+ * renderer already renders markdown, and a list of file paths is exactly that.
+ *
+ * The message is rebuilt through `dehydrate()` + `rehydrate()` rather than a
+ * fresh `buildLocal`, so it keeps its id and React does not remount the bubble
+ * on every render. Mirrors `withPatchedTitle` in `AssistantContext`.
+ */
+function withSources(messages: HandbookThreadMessageInterface[], label: string): HandbookThreadMessageInterface[] {
+  return messages.map((message) => withSourcesInContent(message, label));
+}
+
+function withSourcesInContent(message: HandbookThreadMessageInterface, label: string): HandbookThreadMessageInterface {
+  if (message.role !== "assistant" || message.sources.length === 0) return message;
+
+  const dehydrated = message.dehydrate();
+  const content = `${message.content}\n\n**${label}**\n\n${message.sources.map((source) => `- \`${source}\``).join("\n")}`;
+
+  return rehydrate<HandbookThreadMessageInterface>(Modules.HandbookThreadMessage, {
+    jsonApi: {
+      ...dehydrated.jsonApi,
+      attributes: { ...(dehydrated.jsonApi?.attributes ?? {}), content },
+    },
+    included: dehydrated.included,
+  });
+}
+
+export type UseHandbookAskParams = {
+  /**
+   * Keep the address bar on the open thread. Defaults to `true`, the route's
+   * behaviour; the sheet passes `false`.
+   */
+  syncUrl?: boolean;
+  /** Thread to open on mount, when the route carries one. */
+  handbookThreadId?: string;
+};
+
+export type UseHandbookAskResult = {
+  threads: HandbookThreadInterface[];
+  thread: HandbookThreadInterface | undefined;
+  messages: HandbookThreadMessageInterface[];
+  sending: boolean;
+  ask: (question: string, options?: { handbookPageId?: string }) => Promise<void>;
+  selectThread: (id: string) => Promise<void>;
+  startNew: () => void;
+};
+
+export function useHandbookAsk(params?: UseHandbookAskParams): UseHandbookAskResult {
+  const t = useTranslations();
+  const generateUrl = usePageUrlGenerator();
+
+  const shouldSyncUrl = params?.syncUrl ?? true;
+  const handbookThreadId = params?.handbookThreadId;
+
+  const [threads, setThreads] = useState<HandbookThreadInterface[]>([]);
+  const [thread, setThread] = useState<HandbookThreadInterface | undefined>(undefined);
+  const [messages, setMessages] = useState<HandbookThreadMessageInterface[]>([]);
+  const [sending, setSending] = useState(false);
+
+  const sourcesLabel = t("handbook.chat.sources");
+
+  useEffect(() => {
+    let cancelled = false;
+    (async () => {
+      const loaded = await HandbookThreadService.findMany();
+      if (!cancelled) setThreads(loaded);
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  // A routed thread id opens that thread on mount, so the url survives a reload
+  // or a pasted link. Runs once per id; selecting from the list takes the other
+  // path and only replaces the url.
+  useEffect(() => {
+    if (!handbookThreadId) return;
+    let cancelled = false;
+    (async () => {
+      const selected = await HandbookThreadService.findOne({ id: handbookThreadId });
+      if (cancelled) return;
+      setThread(selected);
+      setMessages(withSources(selected.messages, sourcesLabel));
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [handbookThreadId]);
+
+  /**
+   * Keep the address bar on the open thread, the way ConversationListItem does
+   * (`window.history.replaceState` with the generated url) — selecting a thread
+   * is not a navigation, so this replaces rather than pushes.
+   *
+   * A no-op when the caller asked for no url sync: the sheet floats over a page
+   * that is itself the navigation, and rewriting the url under it would send a
+   * reader who closes the sheet somewhere they never went.
+   */
+  const syncUrl = useCallback(
+    (id?: string) => {
+      if (!shouldSyncUrl) return;
+      const base = `${generateUrl({ page: Modules.HandbookPage })}/chat`;
+      window.history.replaceState(null, "", id ? `${base}/${id}` : base);
+    },
+    [generateUrl, shouldSyncUrl],
+  );
+
+  const selectThread = useCallback(
+    async (id: string) => {
+      const selected = await HandbookThreadService.findOne({ id });
+      setThread(selected);
+      setMessages(withSources(selected.messages, sourcesLabel));
+      syncUrl(id);
+    },
+    [syncUrl],
+  );
+
+  const startNew = useCallback(() => {
+    setThread(undefined);
+    setMessages([]);
+    syncUrl(undefined);
+  }, [syncUrl]);
+
+  const ask = useCallback(
+    async (question: string, options?: { handbookPageId?: string }) => {
+      const trimmed = question.trim();
+      if (!trimmed || sending) return;
+
+      const position = messages.length;
+      setMessages((current) => [
+        ...current,
+        HandbookThreadMessage.buildLocal({ role: "user", content: trimmed, position, isOptimistic: true }),
+      ]);
+      setSending(true);
+
+      try {
+        // Both branches end in the same read: only the single-thread endpoint
+        // side-loads the messages, so the transcript always comes from there.
+        let id = thread?.id;
+        if (id === undefined) {
+          const created = await HandbookThreadService.create({
+            id: v4(),
+            question: trimmed,
+            handbookPageId: options?.handbookPageId,
+          });
+          id = created.id;
+          setThreads((current) => [created, ...current]);
+        } else {
+          await HandbookThreadMessageService.ask({
+            id: v4(),
+            threadId: id,
+            question: trimmed,
+            handbookPageId: options?.handbookPageId,
+          });
+        }
+
+        const loaded = await HandbookThreadService.findOne({ id });
+        setThread(loaded);
+        setMessages(withSources(loaded.messages, sourcesLabel));
+        // The server derives the title from the first question, so the list row
+        // created a moment ago has to pick it up.
+        setThreads((current) => current.map((item) => (item.id === loaded.id ? loaded : item)));
+        syncUrl(loaded.id);
+      } catch {
+        // 400 when the installation has no usable AI configuration, 403 for a
+        // non-administrator. Neither is actionable from here, so both surface
+        // as one assistant-side message rather than a bespoke error pane.
+        setMessages((current) => [
+          ...current,
+          HandbookThreadMessage.buildLocal({
+            role: "assistant",
+            content: t("handbook.chat.failed"),
+            position: position + 1,
+          }),
+        ]);
+      } finally {
+        setSending(false);
+      }
+    },
+    [messages.length, sending, syncUrl, t, thread?.id],
+  );
+
+  return { threads, thread, messages, sending, ask, selectThread, startNew };
+}

package/src/features/handbook/i18n-keys.ts

@@ -0,0 +1,46 @@
+/**
+ * The fixed namespace of i18n keys the handbook feature reads via
+ * useTranslations. Consuming apps must define each entry in their
+ * messages/<locale>.json — this list is the contract between the package and
+ * the app, and the names are frozen: an app that wants different wording
+ * changes its own translation, never the key.
+ *
+ * Mirrors the contract shipped by the administration feature
+ * (features/administration/i18n-keys.ts).
+ */
+export const handbookI18nKeys = [
+  "handbook.title",
+  "handbook.subtitle",
+  "handbook.sync",
+  "handbook.syncing",
+  "handbook.synced",
+  "handbook.syncFailed",
+  "handbook.empty",
+  "handbook.notConfigured",
+  "handbook.chat.title",
+  "handbook.chat.placeholder",
+  "handbook.chat.ask",
+  "handbook.chat.pending",
+  "handbook.chat.failed",
+  "handbook.chat.sources",
+  "handbook.chat.list_title",
+  "handbook.chat.new",
+  "handbook.chat.empty_sidebar",
+  "handbook.chat.rename_placeholder",
+  "handbook.chat.delete_confirm",
+  "handbook.chat.empty_state.title",
+  "handbook.chat.empty_state.subtitle",
+  "handbook.contents.title",
+  "handbook.contents.status",
+  "handbook.contents.failures",
+  "handbook.reader.contents",
+  "handbook.reader.onThisPage",
+  "handbook.reader.previous",
+  "handbook.reader.next",
+  "handbook.ask.open",
+  "handbook.ask.recent",
+  "handbook.ask.all",
+  "handbook.ask.expand",
+  "handbook.ask.thisPageOnly",
+  "handbook.sections.untitled",
+] as const;

package/src/features/handbook/index.ts

@@ -0,0 +1,7 @@
+export * from "./HandbookPageModule";
+export * from "./HandbookSectionModule";
+export * from "./HandbookThreadMessageModule";
+export * from "./HandbookThreadModule";
+export * from "./components";
+export * from "./contexts/HandbookContext";
+export * from "./data";

package/src/features/how-to/components/forms/HowToEditor.tsx

@@ -239,7 +239,6 @@ function HowToEditorInternal({
         const payload: HowToInput = {
           id: values.id,
           name: values.name,
-          authorId: "",
           description: values.description,
           pages: HowTo.serializePagesToString(values.pages),
           howToType: values.howToType,

package/src/features/how-to/components/forms/HowToReindexButton.spec.tsx

@@ -0,0 +1,84 @@
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { showError, showToast } from "../../../../utils/toast";
+import { HowToService } from "../../data/HowToService";
+import HowToReindexButton from "./HowToReindexButton";
+
+vi.mock("../../data/HowToService", () => ({
+  HowToService: { reindex: vi.fn() },
+}));
+
+vi.mock("../../../../utils/toast", () => ({
+  showToast: vi.fn(),
+  showError: vi.fn(),
+}));
+
+vi.mock("next-intl", () => ({
+  useTranslations: () => (key: string) => key,
+}));
+
+describe("HowToReindexButton", () => {
+  beforeEach(() => {
+    vi.mocked(HowToService.reindex).mockReset().mockResolvedValue(undefined);
+    vi.mocked(showToast).mockReset();
+    vi.mocked(showError).mockReset();
+  });
+
+  it("renders the action label", () => {
+    render(<HowToReindexButton refresh={vi.fn().mockResolvedValue(undefined)} />);
+
+    expect(screen.getByRole("button")).toHaveTextContent("howto.reindex.action");
+  });
+
+  it("reindexes, then refreshes the list", async () => {
+    const refresh = vi.fn().mockResolvedValue(undefined);
+    render(<HowToReindexButton refresh={refresh} />);
+
+    await userEvent.click(screen.getByRole("button"));
+
+    await waitFor(() => expect(HowToService.reindex).toHaveBeenCalledTimes(1));
+    await waitFor(() => expect(refresh).toHaveBeenCalledTimes(1));
+  });
+
+  it("shows the running state while the reindex is in flight", async () => {
+    let resolveReindex: () => void = () => {};
+    vi.mocked(HowToService.reindex).mockReturnValue(
+      new Promise<void>((resolve) => {
+        resolveReindex = resolve;
+      }),
+    );
+    render(<HowToReindexButton refresh={vi.fn().mockResolvedValue(undefined)} />);
+
+    await userEvent.click(screen.getByRole("button"));
+
+    await waitFor(() => expect(screen.getByRole("button")).toHaveTextContent("howto.reindex.running"));
+    expect(screen.getByRole("button")).toBeDisabled();
+
+    resolveReindex();
+    await waitFor(() => expect(screen.getByRole("button")).toHaveTextContent("howto.reindex.action"));
+  });
+
+  it("shows the done state once the reindex succeeds", async () => {
+    render(<HowToReindexButton refresh={vi.fn().mockResolvedValue(undefined)} />);
+
+    await userEvent.click(screen.getByRole("button"));
+
+    await waitFor(() => expect(showToast).toHaveBeenCalledWith("howto.reindex.done"));
+    expect(showError).not.toHaveBeenCalled();
+  });
+
+  it("shows the failed state when the reindex rejects, and re-enables itself", async () => {
+    vi.mocked(HowToService.reindex).mockRejectedValue(new Error("boom"));
+    const refresh = vi.fn().mockResolvedValue(undefined);
+    render(<HowToReindexButton refresh={refresh} />);
+
+    await userEvent.click(screen.getByRole("button"));
+
+    await waitFor(() => expect(showError).toHaveBeenCalledWith("howto.reindex.failed"));
+    expect(showToast).not.toHaveBeenCalled();
+    expect(refresh).not.toHaveBeenCalled();
+    await waitFor(() => expect(screen.getByRole("button")).not.toBeDisabled());
+  });
+});

package/src/features/how-to/components/forms/HowToReindexButton.tsx

@@ -0,0 +1,46 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { useState } from "react";
+
+import { Button } from "../../../../shadcnui";
+import { showError, showToast } from "../../../../utils/toast";
+import { HowToService } from "../../data/HowToService";
+
+type HowToReindexButtonProps = {
+  refresh: () => Promise<void>;
+};
+
+/**
+ * Re-queues every guide for chunking.
+ *
+ * Guides are chunked on create and update only, so one written before chunking
+ * existed — or one whose chunks were dropped — is invisible to the help chat
+ * with no way back in. This is the way back in.
+ *
+ * The control is a plain Button, not a trigger: it opens nothing, so the
+ * render-prop composition rule for Base UI triggers does not apply here.
+ */
+export default function HowToReindexButton({ refresh }: HowToReindexButtonProps) {
+  const t = useTranslations();
+  const [isReindexing, setIsReindexing] = useState(false);
+
+  const onReindex = async () => {
+    setIsReindexing(true);
+    try {
+      await HowToService.reindex();
+      await refresh();
+      showToast(t(`howto.reindex.done`));
+    } catch {
+      showError(t(`howto.reindex.failed`));
+    } finally {
+      setIsReindexing(false);
+    }
+  };
+
+  return (
+    <Button variant="outline" onClick={onReindex} disabled={isReindexing}>
+      {isReindexing ? t(`howto.reindex.running`) : t(`howto.reindex.action`)}
+    </Button>
+  );
+}