@carlonicora/nextjs-jsonapi 3.12.0 → 3.13.0

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

@@ -0,0 +1,26 @@
+import { AbstractService, EndpointCreator, HttpMethod, Modules } from "../../../core";
+import { HandbookSectionInterface } from "./HandbookSectionInterface";
+
+export class HandbookSectionService extends AbstractService {
+  /**
+   * Every section in one read, always.
+   *
+   * There are as many sections as an application has documentation directories
+   * — ten or so — so this takes no `fetchAll` argument and no cursor: unlike
+   * the page list, nothing here is ever a second page, and a caller that could
+   * ask for one page of sections would only be able to get it wrong.
+   */
+  static async findMany(): Promise<HandbookSectionInterface[]> {
+    const endpoint = new EndpointCreator({ endpoint: Modules.HandbookSection });
+
+    endpoint.addAdditionalParam("fetchAll", "true");
+    if (Modules.HandbookSection.inclusions?.lists?.fields)
+      endpoint.limitToFields(Modules.HandbookSection.inclusions.lists.fields);
+
+    return this.callApi({
+      type: Modules.HandbookSection,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+    });
+  }
+}

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

@@ -0,0 +1,114 @@
+import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { HandbookThreadInput, HandbookThreadInterface } from "./HandbookThreadInterface";
+import { HandbookThreadMessageInterface } from "./HandbookThreadMessageInterface";
+
+export class HandbookThread extends AbstractApiData implements HandbookThreadInterface {
+  private _title?: string;
+  private _messageCount?: number;
+  private _messages?: HandbookThreadMessageInterface[];
+
+  get title(): string {
+    return this._title ?? "";
+  }
+
+  get messageCount(): number {
+    return this._messageCount ?? 0;
+  }
+
+  /**
+   * The handbook runs one agent and has no engine choice, so nothing routes on
+   * this. It exists because `AssistantInterface` declares it, which is what
+   * lets the shared chat chrome take a handbook thread unchanged.
+   */
+  get engine(): string | undefined {
+    return undefined;
+  }
+
+  /** A handbook thread is never bound to a product resource. */
+  get boundContentType(): string | undefined {
+    return undefined;
+  }
+
+  get boundContentId(): string | undefined {
+    return undefined;
+  }
+
+  get messages(): HandbookThreadMessageInterface[] {
+    return this._messages ?? [];
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    const attributes = data.jsonApi.attributes ?? {};
+    this._title = attributes.title;
+
+    const fromMeta = data.jsonApi.meta?.messageCount;
+    this._messageCount =
+      typeof fromMeta === "number"
+        ? fromMeta
+        : typeof attributes.messageCount === "number"
+          ? attributes.messageCount
+          : 0;
+
+    const messages = this._readIncluded<HandbookThreadMessageInterface>(
+      data,
+      "messages",
+      Modules.HandbookThreadMessage,
+    );
+    this._messages = Array.isArray(messages) ? messages : messages ? [messages] : [];
+
+    // `groupThreadsByBucket` buckets the sidebar on `updatedAt` as a Date, and
+    // `AbstractApiData` only reads it from `meta`. A thread that carries the
+    // timestamp as an attribute instead would otherwise fall back to "now" and
+    // land every thread in "Today".
+    if (this._updatedAt === undefined && attributes.updatedAt !== undefined)
+      this._updatedAt = new Date(attributes.updatedAt);
+    if (this._createdAt === undefined && attributes.createdAt !== undefined)
+      this._createdAt = new Date(attributes.createdAt);
+
+    return this;
+  }
+
+  /**
+   * The envelope `POST /handbookthreads` accepts: the opening question. The
+   * server derives the title from it, so no title is sent and no client id —
+   * the thread's identity is the server's to mint.
+   *
+   * `handbookPageId` rides the same way `question` does, through this method
+   * and never through `overridesJsonApiCreation`. It is written only when the
+   * caller supplied it: the DTO takes it as optional, and sending an explicit
+   * `null` would fail validation rather than mean "the whole manual".
+   */
+  createJsonApi(data: HandbookThreadInput) {
+    return {
+      data: {
+        type: Modules.HandbookThread.name,
+        attributes: {
+          question: data.question,
+          ...(data.handbookPageId !== undefined ? { handbookPageId: data.handbookPageId } : {}),
+        },
+      },
+      included: [],
+    };
+  }
+
+  /**
+   * The envelope `PATCH /handbookthreads/:id` accepts. A dedicated method
+   * rather than a branch inside `createJsonApi`: the rename sends the title and
+   * nothing else, while a create sends the question and nothing else, and the
+   * service must never hand-build either.
+   */
+  createRenameJsonApi(params: { id: string; title: string }) {
+    return {
+      data: {
+        type: Modules.HandbookThread.name,
+        id: params.id,
+        attributes: {
+          title: params.title,
+        },
+      },
+      included: [],
+    };
+  }
+}

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

@@ -0,0 +1,31 @@
+import { AssistantInterface } from "../../assistant/data/AssistantInterface";
+import { HandbookThreadMessageInterface } from "./HandbookThreadMessageInterface";
+
+/**
+ * A persisted handbook conversation.
+ *
+ * It extends `AssistantInterface` so the shared chat chrome —
+ * `AssistantSidebar`, `AssistantThreadHeader`, `groupThreadsByBucket` — accepts
+ * it verbatim. It is NOT an Assistant: an Assistant is company scoped and a
+ * platform administrator has no company, so the handbook owns its own threads
+ * and answers `engine` / `boundContentType` / `boundContentId` with `undefined`.
+ */
+export interface HandbookThreadInterface extends AssistantInterface {
+  /** Side-loaded by `GET /handbookthreads/:id`; empty on the list endpoint. */
+  get messages(): HandbookThreadMessageInterface[];
+}
+
+/**
+ * The payload that opens a thread: the first question. The server derives the
+ * title from it, so nothing else is sent.
+ */
+export type HandbookThreadInput = {
+  id: string;
+  question: string;
+  /**
+   * Scopes retrieval to one handbook page. Set only by the reader's ask sheet,
+   * when the reader turns the "this page only" chip on; absent everywhere else,
+   * and the agent then searches the whole manual.
+   */
+  handbookPageId?: string;
+};

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

@@ -0,0 +1,144 @@
+import { v4 as uuidv4 } from "uuid";
+import { AbstractApiData, ApiDataInterface, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import type {
+  AssistantMessageRole,
+  AssistantMessageType,
+} from "../../assistant-message/data/AssistantMessageInterface";
+import { ChunkInterface, ChunkRelationshipMeta } from "../../chunk/data/ChunkInterface";
+import { HandbookThreadMessageInput, HandbookThreadMessageInterface } from "./HandbookThreadMessageInterface";
+
+/**
+ * One persisted handbook turn.
+ *
+ * The getters below are the structural contract `AssistantMessageInterface`
+ * asks for, which is what lets `AssistantThread` render handbook messages with
+ * no adapter. The handbook has no token accounting, no entity references, no
+ * chunk citations and no approval actions, so those answer `undefined` / `[]`
+ * rather than being faked.
+ */
+export class HandbookThreadMessage extends AbstractApiData implements HandbookThreadMessageInterface {
+  private _role?: AssistantMessageRole;
+  private _content?: string;
+  private _position?: number;
+  private _sources?: string[];
+  private _isOptimistic = false;
+
+  get role(): AssistantMessageRole {
+    return this._role ?? "assistant";
+  }
+
+  get content(): string {
+    return this._content ?? "";
+  }
+
+  get position(): number {
+    return this._position ?? 0;
+  }
+
+  get sources(): string[] {
+    return this._sources ?? [];
+  }
+
+  /** The handbook agent returns no follow-ups. */
+  get suggestedQuestions(): string[] {
+    return [];
+  }
+
+  /** Token accounting is not billed against a handbook thread. */
+  get inputTokens(): number | undefined {
+    return undefined;
+  }
+
+  get outputTokens(): number | undefined {
+    return undefined;
+  }
+
+  /** The handbook answers from pages, never from product entities. */
+  get references(): ApiDataInterface[] {
+    return [];
+  }
+
+  /** Cited pages travel in `sources`, not as Chunk resources. */
+  get citations(): (ChunkInterface & ChunkRelationshipMeta)[] {
+    return [];
+  }
+
+  /** Set only by `buildLocal`; a rehydrated message is always real. */
+  get isOptimistic(): boolean {
+    return this._isOptimistic;
+  }
+
+  /** There is no operator engine behind the handbook, so never an approval request. */
+  get messageType(): AssistantMessageType {
+    return "text";
+  }
+
+  get actionId(): string | undefined {
+    return undefined;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    const attributes = data.jsonApi.attributes ?? {};
+    this._role = attributes.role as AssistantMessageRole | undefined;
+    this._content = attributes.content;
+    this._position = typeof attributes.position === "number" ? attributes.position : Number(attributes.position ?? 0);
+    this._sources = Array.isArray(attributes.sources) ? attributes.sources : [];
+
+    return this;
+  }
+
+  /**
+   * The envelope `POST /handbookthreads/:id/handbookthreadmessages` accepts:
+   * only the question. Role and position are derived server-side from the
+   * thread, and there is no client-chosen id for the pair of messages the turn
+   * creates.
+   *
+   * `handbookPageId` rides the same way `question` does, through this method
+   * and never through `overridesJsonApiCreation`. It is written only when the
+   * caller supplied it: the DTO takes it as optional, and sending an explicit
+   * `null` would fail validation rather than mean "the whole manual".
+   */
+  createJsonApi(data: HandbookThreadMessageInput) {
+    return {
+      data: {
+        type: Modules.HandbookThreadMessage.name,
+        attributes: {
+          question: data.question,
+          ...(data.handbookPageId !== undefined ? { handbookPageId: data.handbookPageId } : {}),
+        },
+      },
+      included: [],
+    };
+  }
+
+  /**
+   * A message that exists only on the client: the optimistic user turn while
+   * the agent runs, and the failure notice when it does not answer. Mirrors
+   * `AssistantMessage.buildLocal`, which the stateless handbook surface used
+   * before threads existed.
+   */
+  static buildLocal(params: {
+    role: AssistantMessageRole;
+    content: string;
+    position: number;
+    isOptimistic?: boolean;
+  }): HandbookThreadMessage {
+    const message = new HandbookThreadMessage();
+    message.rehydrate({
+      jsonApi: {
+        id: uuidv4(),
+        type: Modules.HandbookThreadMessage.name,
+        attributes: {
+          role: params.role,
+          content: params.content,
+          position: params.position,
+        },
+      } as any,
+      included: [],
+    });
+    message._isOptimistic = params.isOptimistic ?? false;
+    return message;
+  }
+}

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

@@ -0,0 +1,35 @@
+import { AssistantMessageInterface } from "../../assistant-message/data/AssistantMessageInterface";
+
+/**
+ * One turn of a persisted handbook conversation.
+ *
+ * It extends `AssistantMessageInterface` rather than restating it: the shared
+ * chat components (`AssistantThread` → `MessageList` → `MessageItem`) are typed
+ * against that interface and take their data as plain props, so a handbook
+ * message that satisfies the same structural contract renders through them with
+ * no adapter. Everything the handbook has no concept of — token counts,
+ * references, citations, approval actions — is answered with the empty value.
+ *
+ * `sources` is the handbook's own addition: repo-relative page paths, in the
+ * order retrieval returned them.
+ */
+export interface HandbookThreadMessageInterface extends AssistantMessageInterface {
+  get sources(): string[];
+}
+
+/**
+ * The payload of one question appended to an existing thread. `id` is the
+ * client-generated identity every model input in this framework carries; the
+ * append endpoint derives role and position server-side, so the envelope the
+ * model builds sends only `question`.
+ */
+export type HandbookThreadMessageInput = {
+  id: string;
+  question: string;
+  /**
+   * Scopes retrieval to one handbook page. Set only by the reader's ask sheet,
+   * when the reader turns the "this page only" chip on; absent everywhere else,
+   * and the agent then searches the whole manual.
+   */
+  handbookPageId?: string;
+};

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

@@ -0,0 +1,30 @@
+import { AbstractService, EndpointCreator, HttpMethod, Modules } from "../../../core";
+import { HandbookThreadMessageInput } from "./HandbookThreadMessageInterface";
+
+export class HandbookThreadMessageService extends AbstractService {
+  /**
+   * Appends one question to an existing thread and runs the agent turn.
+   *
+   * It returns nothing on purpose: the caller reads the turn back with
+   * `HandbookThreadService.findOne`, which is the one endpoint the contract
+   * guarantees side-loads the full message list. That keeps a single code path
+   * for "load the thread after a mutation" — the same one the sidebar's select
+   * uses — instead of two ways of arriving at the transcript.
+   *
+   * The API answers 400 when the installation has no usable AI configuration
+   * and 403 for a non-administrator; both reach the caller as a thrown error.
+   */
+  static async ask(params: HandbookThreadMessageInput & { threadId: string }): Promise<void> {
+    await this.callApi({
+      type: Modules.HandbookThreadMessage,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({
+        endpoint: Modules.HandbookThread,
+        id: params.threadId,
+        childEndpoint: Modules.HandbookThreadMessage,
+      }).generate(),
+      input: { id: params.id, question: params.question, handbookPageId: params.handbookPageId },
+      suppressGlobalError: true,
+    });
+  }
+}

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

@@ -0,0 +1,86 @@
+import { AbstractService, EndpointCreator, HttpMethod, Modules, NextRef, PreviousRef } from "../../../core";
+import { HandbookThread } from "./HandbookThread";
+import { HandbookThreadInput, HandbookThreadInterface } from "./HandbookThreadInterface";
+
+export class HandbookThreadService extends AbstractService {
+  /**
+   * `next` / `prev` are not optional extras: `useDataListRetriever` drives
+   * pagination by handing the cursor back here, so a findMany that drops them
+   * renders exactly one page and no navigation, however many rows exist.
+   * Mirrors HowToService.findMany.
+   */
+  static async findMany(
+    params: {
+      search?: string;
+      fetchAll?: boolean;
+      next?: NextRef;
+      prev?: PreviousRef;
+    } = {},
+  ): Promise<HandbookThreadInterface[]> {
+    const endpoint = new EndpointCreator({ endpoint: Modules.HandbookThread });
+
+    if (params.fetchAll) endpoint.addAdditionalParam("fetchAll", "true");
+    if (params.search) endpoint.addAdditionalParam("search", params.search);
+    if (Modules.HandbookThread.inclusions?.lists?.fields)
+      endpoint.limitToFields(Modules.HandbookThread.inclusions.lists.fields);
+    if (Modules.HandbookThread.inclusions?.lists?.types)
+      endpoint.limitToType(Modules.HandbookThread.inclusions.lists.types);
+
+    return this.callApi({
+      type: Modules.HandbookThread,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+      next: params.next,
+    });
+  }
+
+  /** Returns the thread with its messages side-loaded — the sidebar's select. */
+  static async findOne(params: { id: string }): Promise<HandbookThreadInterface> {
+    return this.callApi<HandbookThreadInterface>({
+      type: Modules.HandbookThread,
+      method: HttpMethod.GET,
+      endpoint: new EndpointCreator({ endpoint: Modules.HandbookThread, id: params.id }).generate(),
+    });
+  }
+
+  /**
+   * Opens a thread with its first question. The response is the thread (title
+   * included); the messages are read back with `findOne`, because only the
+   * single-resource endpoint side-loads them.
+   *
+   * The API answers 400 when the installation has no usable AI configuration
+   * and 403 for a non-administrator; both reach the caller as a thrown error.
+   *
+   * `HandbookThreadInput.handbookPageId` scopes retrieval to one page. It rides
+   * through the model's `createJsonApi()`, exactly as `question` does — there is
+   * no `overridesJsonApiCreation` on this path.
+   */
+  static async create(params: HandbookThreadInput): Promise<HandbookThreadInterface> {
+    return this.callApi<HandbookThreadInterface>({
+      type: Modules.HandbookThread,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({ endpoint: Modules.HandbookThread }).generate(),
+      input: params,
+      suppressGlobalError: true,
+    });
+  }
+
+  static async rename(params: { id: string; title: string }): Promise<void> {
+    const thread = new HandbookThread();
+    await this.callApi({
+      type: Modules.HandbookThread,
+      method: HttpMethod.PATCH,
+      endpoint: new EndpointCreator({ endpoint: Modules.HandbookThread, id: params.id }).generate(),
+      input: thread.createRenameJsonApi({ id: params.id, title: params.title }),
+      overridesJsonApiCreation: true,
+    });
+  }
+
+  static async delete(params: { id: string }): Promise<void> {
+    await this.callApi({
+      type: Modules.HandbookThread,
+      method: HttpMethod.DELETE,
+      endpoint: new EndpointCreator({ endpoint: Modules.HandbookThread, id: params.id }).generate(),
+    });
+  }
+}

package/src/features/handbook/data/__tests__/HandbookThreadService.spec.ts

@@ -0,0 +1,112 @@
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { AbstractService } from "../../../../core/abstracts/AbstractService";
+import { ApiRequestDataTypeInterface } from "../../../../core/interfaces/ApiRequestDataTypeInterface";
+import { ModuleRegistry } from "../../../../core/registry/ModuleRegistry";
+import { HandbookThread } from "../HandbookThread";
+import { HandbookThreadMessage } from "../HandbookThreadMessage";
+import { HandbookThreadMessageService } from "../HandbookThreadMessageService";
+import { HandbookThreadService } from "../HandbookThreadService";
+
+// ModuleRegistry is backed by a globalThis symbol shared across test files in a
+// worker, hence the register-if-absent guard (same idiom as
+// Assistant.scope.spec.ts).
+const registerIfAbsent = (key: string, module: ApiRequestDataTypeInterface) => {
+  try {
+    ModuleRegistry.get(key as any);
+  } catch {
+    ModuleRegistry.register(key, module);
+  }
+};
+
+beforeAll(() => {
+  registerIfAbsent("HandbookThread", { name: "handbookthreads", model: HandbookThread } as any);
+  registerIfAbsent("HandbookThreadMessage", {
+    name: "handbookthreadmessages",
+    model: HandbookThreadMessage,
+  } as any);
+});
+
+// `callApi` is a protected static on AbstractService; the services inherit it,
+// so spying on the base class intercepts every call without touching the HTTP
+// layer.
+type CallApiParams = {
+  method: string;
+  endpoint: string;
+  input?: unknown;
+  next?: unknown;
+  overridesJsonApiCreation?: boolean;
+};
+const callApi = () => vi.spyOn(AbstractService as any, "callApi");
+const firstCall = (spy: ReturnType<typeof callApi>): CallApiParams => spy.mock.calls[0][0] as CallApiParams;
+
+describe("HandbookThreadService.findMany", () => {
+  beforeEach(() => vi.restoreAllMocks());
+
+  it("forwards the pagination cursor — `useDataListRetriever` pages through it", async () => {
+    const spy = callApi().mockResolvedValue([]);
+
+    await HandbookThreadService.findMany({ next: { next: "handbookthreads?page[cursor]=42" } });
+
+    expect(spy).toHaveBeenCalledWith(expect.objectContaining({ next: { next: "handbookthreads?page[cursor]=42" } }));
+  });
+
+  it("still calls with an undefined cursor on the first page", async () => {
+    const spy = callApi().mockResolvedValue([]);
+
+    await HandbookThreadService.findMany();
+
+    expect(spy).toHaveBeenCalledWith(expect.objectContaining({ next: undefined }));
+  });
+
+  it("passes search and fetchAll through to the endpoint", async () => {
+    const spy = callApi().mockResolvedValue([]);
+
+    await HandbookThreadService.findMany({ search: "cypher", fetchAll: true });
+
+    const endpoint = firstCall(spy).endpoint;
+    expect(endpoint).toContain("handbookthreads");
+    expect(endpoint).toContain("cypher");
+    expect(endpoint).toContain("fetchAll");
+  });
+});
+
+describe("HandbookThreadService mutations", () => {
+  beforeEach(() => vi.restoreAllMocks());
+
+  it("creates a thread from the question alone and lets the model build the envelope", async () => {
+    const spy = callApi().mockResolvedValue({});
+
+    await HandbookThreadService.create({ id: "client-1", question: "  " });
+
+    const call = firstCall(spy);
+    expect(call.method).toBe("POST");
+    expect(call.input).toEqual({ id: "client-1", question: "  " });
+    expect(call.overridesJsonApiCreation).toBeUndefined();
+  });
+
+  it("renames through the model's dedicated envelope, never a hand-built one", async () => {
+    const spy = callApi().mockResolvedValue(undefined);
+
+    await HandbookThreadService.rename({ id: "t1", title: "Filtri di azienda" });
+
+    const call = firstCall(spy);
+    expect(call.method).toBe("PATCH");
+    expect(call.input).toEqual(new HandbookThread().createRenameJsonApi({ id: "t1", title: "Filtri di azienda" }));
+  });
+});
+
+describe("HandbookThreadMessageService.ask", () => {
+  beforeEach(() => vi.restoreAllMocks());
+
+  it("posts the question to the thread's message collection", async () => {
+    const spy = callApi().mockResolvedValue(undefined);
+
+    await HandbookThreadMessageService.ask({ id: "m1", threadId: "t1", question: "Come funziona?" });
+
+    const call = firstCall(spy);
+    expect(call.method).toBe("POST");
+    expect(call.endpoint).toContain("handbookthreads/t1/handbookthreadmessages");
+    expect(call.input).toEqual({ id: "m1", question: "Come funziona?" });
+  });
+});

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

@@ -0,0 +1,92 @@
+import { describe, expect, it } from "vitest";
+import {
+  handbookPageContent,
+  handbookPageSummary,
+  handbookPageTitle,
+  handbookSectionSummary,
+  handbookSectionTitle,
+} from "./handbookDisplay";
+
+/**
+ * The one rule the whole feature depends on: indexed in English, shown
+ * translated, and nothing but the rendered words changes.
+ */
+describe("handbookDisplay", () => {
+  describe("a page with a translation", () => {
+    const page = {
+      title: "Module anatomy",
+      displayTitle: "Anatomia di un modulo",
+      summary: "What a feature module contains.",
+      displaySummary: "Cosa contiene un modulo.",
+      content: "# Module anatomy\n",
+      displayContent: "# Anatomia di un modulo\n",
+    };
+
+    it("renders the translated title", () => {
+      expect(handbookPageTitle(page)).toBe("Anatomia di un modulo");
+    });
+
+    it("renders the translated summary", () => {
+      expect(handbookPageSummary(page)).toBe("Cosa contiene un modulo.");
+    });
+
+    it("renders the translated body", () => {
+      expect(handbookPageContent(page)).toBe("# Anatomia di un modulo\n");
+    });
+  });
+
+  describe("a page without a translation", () => {
+    const page = {
+      title: "Module anatomy",
+      displayTitle: undefined,
+      summary: "What a feature module contains.",
+      displaySummary: undefined,
+      content: "# Module anatomy\n",
+      displayContent: undefined,
+    };
+
+    it("falls back to the English title", () => {
+      expect(handbookPageTitle(page)).toBe("Module anatomy");
+    });
+
+    it("falls back to the English summary", () => {
+      expect(handbookPageSummary(page)).toBe("What a feature module contains.");
+    });
+
+    it("falls back to the English body", () => {
+      expect(handbookPageContent(page)).toBe("# Module anatomy\n");
+    });
+
+    it("leaves a summary that exists in neither language undefined", () => {
+      expect(handbookPageSummary({ summary: undefined, displaySummary: undefined })).toBeUndefined();
+    });
+  });
+
+  describe("sections", () => {
+    it("renders the translated title and summary when there is one", () => {
+      const section = {
+        title: "Backend",
+        displayTitle: "Backend (API)",
+        summary: "The API.",
+        displaySummary: "Le API.",
+      };
+      expect(handbookSectionTitle(section)).toBe("Backend (API)");
+      expect(handbookSectionSummary(section)).toBe("Le API.");
+    });
+
+    it("falls back to English when there is none", () => {
+      const section = { title: "Backend", displayTitle: undefined, summary: "The API.", displaySummary: undefined };
+      expect(handbookSectionTitle(section)).toBe("Backend");
+      expect(handbookSectionSummary(section)).toBe("The API.");
+    });
+  });
+
+  /**
+   * An empty string is a translation the ingest wrote, not a missing one, so
+   * `??` is the correct operator and `||` would be wrong: the fallback must
+   * only fire on `undefined`.
+   */
+  it("treats an empty translation as a translation", () => {
+    expect(handbookPageTitle({ title: "Module anatomy", displayTitle: "" })).toBe("");
+  });
+});