@carlonicora/nextjs-jsonapi 1.108.0 → 1.109.0

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

@@ -1,3 +1,4 @@
+import { v4 as uuidv4 } from "uuid";
 import { AbstractApiData, ApiDataInterface, JsonApiHydratedDataInterface, Modules } from "../../../core";
 import { AssistantMessageInput, AssistantMessageInterface, AssistantMessageRole } from "./AssistantMessageInterface";
 import { resolveReferenceableModules } from "../../assistant/utils/resolveReferenceableModules";
@@ -12,6 +13,7 @@ export class AssistantMessage extends AbstractApiData implements AssistantMessag
   private _outputTokens?: number;
   private _references?: ApiDataInterface[];
   private _citations?: (ChunkInterface & ChunkRelationshipMeta)[];
+  private _isOptimistic = false;
 
   get role(): AssistantMessageRole {
     return this._role ?? "assistant";
@@ -45,6 +47,10 @@ export class AssistantMessage extends AbstractApiData implements AssistantMessag
     return this._citations ?? [];
   }
 
+  get isOptimistic(): boolean {
+    return this._isOptimistic;
+  }
+
   rehydrate(data: JsonApiHydratedDataInterface): this {
     super.rehydrate(data);
     const attrs = data.jsonApi.attributes ?? {};
@@ -93,10 +99,29 @@ export class AssistantMessage extends AbstractApiData implements AssistantMessag
     };
   }
 
+  /**
+   * JSON:API envelope for POST /assistants/:id/assistant-messages.
+   * Different from `createJsonApi` (which expects a full message with role/position/assistant ref);
+   * the append-to-thread endpoint derives those server-side, so we only send `content` and
+   * the optional retrieval-mode flags.
+   */
+  createAppendMessageJsonApi(params: { content: string; howToMode?: boolean; limitToHowToId?: string }) {
+    return {
+      data: {
+        type: Modules.AssistantMessage.name,
+        attributes: {
+          content: params.content,
+          ...(params.howToMode !== undefined ? { howToMode: params.howToMode } : {}),
+          ...(params.limitToHowToId !== undefined ? { limitToHowToId: params.limitToHowToId } : {}),
+        },
+      },
+    };
+  }
+
   static buildOptimistic(params: { content: string; position: number; assistantId?: string }): AssistantMessage {
     const msg = new AssistantMessage();
     const jsonApi: Record<string, unknown> = {
-      id: `tmp-${crypto.randomUUID()}`,
+      id: uuidv4(),
       type: Modules.AssistantMessage.name,
       attributes: {
         role: "user",
@@ -110,6 +135,7 @@ export class AssistantMessage extends AbstractApiData implements AssistantMessag
       };
     }
     msg.rehydrate({ jsonApi: jsonApi as any, included: [] });
+    msg._isOptimistic = true;
     return msg;
   }
 }

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

@@ -20,4 +20,5 @@ export interface AssistantMessageInterface extends ApiDataInterface {
   get outputTokens(): number | undefined;
   get references(): ApiDataInterface[];
   get citations(): (ChunkInterface & ChunkRelationshipMeta)[];
+  get isOptimistic(): boolean;
 }

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

@@ -136,14 +136,17 @@ describe("AssistantMessage.rehydrate", () => {
 });
 
 describe("AssistantMessage.buildOptimistic", () => {
-  it("creates a user message with a tmp-prefixed id and the given content + position", () => {
+  const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+  it("creates a user message with a plain UUID id and the given content + position", () => {
     const msg = AssistantMessage.buildOptimistic({
       content: "hello",
       assistantId: "a-1",
       position: 3,
     });
 
-    expect(msg.id.startsWith("tmp-")).toBe(true);
+    expect(msg.id).toMatch(UUID_RE);
+    expect(msg.isOptimistic).toBe(true);
     expect(msg.role).toBe("user");
     expect(msg.content).toBe("hello");
     expect(msg.position).toBe(3);
@@ -152,7 +155,8 @@ describe("AssistantMessage.buildOptimistic", () => {
   it("allows an omitted assistantId (first-message case)", () => {
     const msg = AssistantMessage.buildOptimistic({ content: "first", position: 1 });
 
-    expect(msg.id.startsWith("tmp-")).toBe(true);
+    expect(msg.id).toMatch(UUID_RE);
+    expect(msg.isOptimistic).toBe(true);
     expect(msg.role).toBe("user");
     expect(msg.content).toBe("first");
     expect(msg.position).toBe(1);

package/src/features/help/components/HelpArticleBody.tsx

@@ -0,0 +1,54 @@
+"use client";
+import { ReactNode } from "react";
+import Link from "next/link";
+import { useFormatter, useTranslations } from "next-intl";
+import type { HelpArticle } from "../types/help-article.types";
+import { usePageUrlGenerator } from "../../../client";
+import { useHelp } from "../contexts/HelpContext";
+import { articleUrl } from "../utils/articleUrl";
+import { prevNextWithinMode } from "../utils/helpNavigation";
+
+export function HelpArticleBody({ article, children }: { article: HelpArticle; children: ReactNode }) {
+  const t = useTranslations();
+  const format = useFormatter();
+  const generateUrl = usePageUrlGenerator();
+  const { manifest } = useHelp();
+  const { prev, next } = prevNextWithinMode(manifest, article);
+
+  return (
+    <article className="prose dark:prose-invert max-w-none">
+      <nav className="text-muted-foreground mb-2 text-xs">
+        <Link href={generateUrl({ page: "/help" })}>Help</Link>
+        {" · "}
+        <Link href={generateUrl({ page: `/help/${article.mode}` })}>{t(`help.modes.${article.mode}`)}</Link>
+      </nav>
+      <h1>{article.title}</h1>
+      <p className="text-muted-foreground !mt-0 text-base">{article.summary}</p>
+      {children}
+      <hr className="my-6" />
+      <div className="text-muted-foreground text-xs">
+        <span>
+          {t("help.article.lastUpdated", {
+            date: format.dateTime(new Date(article.lastUpdated), { dateStyle: "short" }),
+          })}
+        </span>
+      </div>
+      <div className="mt-4 flex justify-between text-sm">
+        {prev ? (
+          <Link href={articleUrl(generateUrl, prev)} className="hover:underline">
+            ← {t("help.article.previous")}: {prev.title}
+          </Link>
+        ) : (
+          <span />
+        )}
+        {next ? (
+          <Link href={articleUrl(generateUrl, next)} className="hover:underline">
+            {t("help.article.next")}: {next.title} →
+          </Link>
+        ) : (
+          <span />
+        )}
+      </div>
+    </article>
+  );
+}

package/src/features/help/components/HelpAskAi.tsx

@@ -0,0 +1,36 @@
+"use client";
+import { useState } from "react";
+import { SparklesIcon } from "lucide-react";
+import { useTranslations } from "next-intl";
+import { useCurrentUserContext } from "../../user/contexts/CurrentUserContext";
+import { Button, Tooltip, TooltipTrigger, TooltipContent } from "../../../shadcnui";
+import { HelpAssistantSheet } from "./HelpAssistantSheet";
+
+export function HelpAskAi() {
+  const t = useTranslations();
+  const { currentUser } = useCurrentUserContext();
+  const [open, setOpen] = useState(false);
+  const disabled = !currentUser;
+
+  if (disabled) {
+    return (
+      <Tooltip>
+        <TooltipTrigger render={<Button variant="outline" size="sm" disabled />}>
+          <SparklesIcon className="h-4 w-4" />
+          {t("help.askAi.button")}
+        </TooltipTrigger>
+        <TooltipContent>{t("help.askAi.loginTooltip")}</TooltipContent>
+      </Tooltip>
+    );
+  }
+
+  return (
+    <>
+      <Button variant="outline" size="sm" onClick={() => setOpen(true)}>
+        <SparklesIcon className="h-4 w-4" />
+        {t("help.askAi.button")}
+      </Button>
+      <HelpAssistantSheet open={open} onOpenChange={setOpen} />
+    </>
+  );
+}

package/src/features/help/components/HelpAssistantSheet.tsx

@@ -0,0 +1,53 @@
+"use client";
+import { useTranslations } from "next-intl";
+import { Sheet, SheetContent, SheetHeader, SheetTitle, SheetDescription } from "../../../shadcnui";
+import { AssistantProvider, useAssistantContext } from "../../assistant/contexts/AssistantContext";
+import { AssistantThread } from "../../assistant/components/parts/AssistantThread";
+import { AssistantComposer } from "../../assistant/components/parts/AssistantComposer";
+import { AssistantEmptyState } from "../../assistant/components/parts/AssistantEmptyState";
+
+export function HelpAssistantSheet({ open, onOpenChange }: { open: boolean; onOpenChange: (o: boolean) => void }) {
+  return (
+    <Sheet open={open} onOpenChange={onOpenChange}>
+      <SheetContent
+        side="right"
+        className="flex w-full flex-col data-[side=right]:sm:max-w-2xl data-[side=right]:lg:max-w-3xl"
+      >
+        <AssistantProvider manageUrl={false}>
+          <HelpAssistantSheetBody />
+        </AssistantProvider>
+      </SheetContent>
+    </Sheet>
+  );
+}
+
+function HelpAssistantSheetBody() {
+  const t = useTranslations();
+  const ctx = useAssistantContext();
+  const showThread = !!ctx.assistant || ctx.sending || ctx.messages.length > 0;
+  const send = (content: string) => ctx.sendMessage(content, { howToMode: true });
+
+  return (
+    <>
+      <SheetHeader>
+        <SheetTitle>{t("help.askAi.sheet.title")}</SheetTitle>
+        <SheetDescription>{t("help.askAi.sheet.subtitle")}</SheetDescription>
+      </SheetHeader>
+      {!showThread ? (
+        <AssistantEmptyState onSend={send} />
+      ) : (
+        <>
+          <AssistantThread
+            messages={ctx.messages}
+            sending={ctx.sending}
+            status={ctx.status}
+            onSelectFollowUp={send}
+            failedMessageIds={ctx.failedMessageIds}
+            onRetry={ctx.retrySend}
+          />
+          <AssistantComposer onSend={send} disabled={ctx.sending} />
+        </>
+      )}
+    </>
+  );
+}

package/src/features/help/components/HelpHeader.tsx

@@ -0,0 +1,40 @@
+"use client";
+import Link from "next/link";
+import Image from "next/image";
+import { useTranslations } from "next-intl";
+import { useCurrentUserContext } from "../../user/contexts/CurrentUserContext";
+import { Button } from "../../../shadcnui";
+import { useHelp } from "../contexts/HelpContext";
+import { HelpAskAi } from "./HelpAskAi";
+
+export function HelpHeader() {
+  const t = useTranslations();
+  const { currentUser } = useCurrentUserContext();
+  const { brand } = useHelp();
+  const logo = brand?.logo;
+  const label = brand?.label ?? "Help";
+  const appHref = brand?.appHref ?? "/";
+
+  return (
+    <header className="border-border bg-background flex items-center justify-between border-b px-4 py-3">
+      <Link href="/help" className="flex items-center gap-2">
+        {logo ? <Image src={logo} alt={label} width={28} height={28} /> : null}
+        <span className="text-base font-semibold">
+          {label} · {t("help.footerLink")}
+        </span>
+      </Link>
+      <div className="flex items-center gap-2">
+        <HelpAskAi />
+        {currentUser ? (
+          <Button render={<Link href={appHref} />} nativeButton={false} variant="outline" size="sm">
+            {t("help.header.openApp")}
+          </Button>
+        ) : (
+          <Button render={<Link href="/login" />} nativeButton={false} variant="outline" size="sm">
+            {t("help.header.login")}
+          </Button>
+        )}
+      </div>
+    </header>
+  );
+}

package/src/features/help/components/HelpHint.tsx

@@ -0,0 +1,77 @@
+"use client";
+import { useMemo, useState } from "react";
+import { useTranslations } from "next-intl";
+import Link from "next/link";
+import { HelpCircleIcon } from "lucide-react";
+import {
+  Button,
+  Sheet,
+  SheetContent,
+  SheetTrigger,
+  SheetHeader,
+  SheetTitle,
+  SheetDescription,
+} from "../../../shadcnui";
+import { usePageUrlGenerator } from "../../../client";
+import { useHelp } from "../contexts/HelpContext";
+import { articleUrl } from "../utils/articleUrl";
+import type { HelpArticle } from "../types/help-article.types";
+
+export function HelpHint({ contextKey }: { contextKey: string }) {
+  const t = useTranslations();
+  const generateUrl = usePageUrlGenerator();
+  const { manifest } = useHelp();
+  const [open, setOpen] = useState(false);
+  const [picked, setPicked] = useState<HelpArticle | null>(null);
+
+  const matches = useMemo(
+    () => manifest.filter((a) => a.contextualKeys.includes(contextKey) && !a.draft),
+    [manifest, contextKey],
+  );
+
+  if (matches.length === 0) return null;
+  const active = picked ?? (matches.length === 1 ? matches[0] : null);
+
+  return (
+    <Sheet
+      open={open}
+      onOpenChange={(o) => {
+        setOpen(o);
+        if (!o) setPicked(null);
+      }}
+    >
+      <SheetTrigger render={<Button variant="ghost" size="icon-sm" aria-label={t("help.hint.trigger")} />}>
+        <HelpCircleIcon className="h-4 w-4" />
+      </SheetTrigger>
+      <SheetContent side="right" className="w-full max-w-md sm:max-w-lg">
+        <SheetHeader>
+          <SheetTitle>{active ? active.title : t("help.hint.pickArticle")}</SheetTitle>
+          <SheetDescription>{active?.summary ?? ""}</SheetDescription>
+        </SheetHeader>
+        {active ? (
+          <div className="mt-4 space-y-3">
+            <p className="text-muted-foreground text-sm">{active.summary}</p>
+            <Link href={articleUrl(generateUrl, active)} className="text-sm">
+              {t("help.hint.viewArticle")}
+            </Link>
+          </div>
+        ) : (
+          <ul className="mt-4 space-y-1">
+            {matches.map((a) => (
+              <li key={a.id}>
+                <button
+                  type="button"
+                  onClick={() => setPicked(a)}
+                  className="hover:bg-muted block w-full rounded px-2 py-1 text-left text-sm"
+                >
+                  <div className="font-medium">{a.title}</div>
+                  <div className="text-muted-foreground text-xs">{a.summary}</div>
+                </button>
+              </li>
+            ))}
+          </ul>
+        )}
+      </SheetContent>
+    </Sheet>
+  );
+}

package/src/features/help/components/HelpSearchResultRow.tsx

@@ -0,0 +1,51 @@
+"use client";
+import Link from "next/link";
+import { useTranslations } from "next-intl";
+import { LifeBuoyIcon, ArrowUpRightIcon } from "lucide-react";
+import { CommandItem } from "../../../shadcnui";
+import { usePageUrlGenerator } from "../../../client";
+import { useHelp } from "../contexts/HelpContext";
+
+export interface HelpSearchResultRowProps {
+  result: { id: string; name: string; entityType: string };
+  onSelect?: () => void;
+}
+
+export function HelpSearchResultRow({ result, onSelect }: HelpSearchResultRowProps) {
+  const t = useTranslations();
+  const generateUrl = usePageUrlGenerator();
+  const { manifest } = useHelp();
+  const article = manifest.find((a) => a.id === result.id);
+
+  if (!article) {
+    return (
+      <CommandItem
+        value={result.id}
+        disabled
+        className="text-muted-foreground cursor-not-allowed px-3 py-1.5 text-sm italic"
+      >
+        {t("help.search.removed")}
+      </CommandItem>
+    );
+  }
+
+  return (
+    <CommandItem value={result.id} onSelect={onSelect} className="cursor-pointer p-0">
+      <Link
+        href={generateUrl({ page: `/help/${article.mode}/${article.slug}` })}
+        className="hover:bg-muted flex w-full items-center gap-3 rounded px-3 py-2"
+      >
+        <div className="bg-muted text-muted-foreground flex h-10 w-10 shrink-0 items-center justify-center rounded-full">
+          <LifeBuoyIcon className="h-5 w-5" />
+        </div>
+        <div className="flex min-w-0 flex-1 flex-col">
+          <span className="text-foreground truncate text-sm font-semibold">{article.title}</span>
+          <span className="text-muted-foreground truncate text-xs">
+            {t(`help.modes.${article.mode}`)} · {article.summary}
+          </span>
+        </div>
+        <ArrowUpRightIcon className="text-muted-foreground h-5 w-5 shrink-0" />
+      </Link>
+    </CommandItem>
+  );
+}

package/src/features/help/components/HelpSideNav.tsx

@@ -0,0 +1,84 @@
+"use client";
+import { useTranslations } from "next-intl";
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+import { HELP_MODES } from "../types/help-article.types";
+import { usePageUrlGenerator } from "../../../client";
+import { useHelp } from "../contexts/HelpContext";
+import { useHelpFilter } from "../hooks/useHelpFilter";
+import { buildHelpNav } from "../utils/helpNavigation";
+import { articleUrl, modeUrl } from "../utils/articleUrl";
+
+export function HelpSideNav() {
+  const t = useTranslations();
+  const generateUrl = usePageUrlGenerator();
+  const pathname = usePathname();
+  const { manifest } = useHelp();
+  const groups = buildHelpNav(manifest);
+  const allArticles = groups.flatMap((g) => g.articles);
+  const { query, setQuery, filtered } = useHelpFilter(allArticles);
+  const filtering = query.trim().length > 0;
+
+  return (
+    <nav aria-label="Help navigation" className="flex h-full flex-col gap-3 overflow-y-auto p-4">
+      <input
+        type="search"
+        value={query}
+        onChange={(e) => setQuery(e.target.value)}
+        placeholder={t("help.sideNav.filterPlaceholder")}
+        className="border-input bg-background w-full rounded-md border px-3 py-2 text-sm"
+      />
+      {filtering ? (
+        filtered.length === 0 ? (
+          <p className="text-muted-foreground text-sm">{t("help.sideNav.noMatches")}</p>
+        ) : (
+          <ul className="space-y-1">
+            {filtered.map((a) => (
+              <li key={a.id}>
+                <Link
+                  href={articleUrl(generateUrl, a)}
+                  className={
+                    "hover:bg-muted block rounded px-2 py-1 text-sm " +
+                    (pathname.endsWith(`/help/${a.mode}/${a.slug}`) ? "bg-muted font-medium" : "")
+                  }
+                >
+                  {a.title}
+                </Link>
+              </li>
+            ))}
+          </ul>
+        )
+      ) : (
+        HELP_MODES.map((mode) => {
+          const group = groups.find((g) => g.mode === mode)!;
+          if (group.articles.length === 0) return null;
+          return (
+            <div key={mode}>
+              <Link
+                href={modeUrl(generateUrl, mode)}
+                className="text-muted-foreground hover:text-foreground mb-1 block text-xs font-semibold tracking-wider uppercase"
+              >
+                {t(`help.modes.${mode}`)}
+              </Link>
+              <ul className="space-y-0.5">
+                {group.articles.map((a) => (
+                  <li key={a.id}>
+                    <Link
+                      href={articleUrl(generateUrl, a)}
+                      className={
+                        "hover:bg-muted block rounded px-2 py-1 text-sm " +
+                        (pathname.endsWith(`/help/${a.mode}/${a.slug}`) ? "bg-muted font-medium" : "")
+                      }
+                    >
+                      {a.title}
+                    </Link>
+                  </li>
+                ))}
+              </ul>
+            </div>
+          );
+        })
+      )}
+    </nav>
+  );
+}

package/src/features/help/components/HelpTOC.tsx

@@ -0,0 +1,49 @@
+"use client";
+import { useEffect, useState } from "react";
+import { useTranslations } from "next-intl";
+import type { HelpHeading } from "../types/help-article.types";
+
+export function HelpTOC({ headings }: { headings: readonly HelpHeading[] }) {
+  const t = useTranslations();
+  const [active, setActive] = useState<string | null>(null);
+
+  useEffect(() => {
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const e of entries) {
+          if (e.isIntersecting) setActive(e.target.id);
+        }
+      },
+      { rootMargin: "0px 0px -70% 0px", threshold: 0 },
+    );
+    headings.forEach((h) => {
+      const el = document.getElementById(h.slug);
+      if (el) observer.observe(el);
+    });
+    return () => observer.disconnect();
+  }, [headings]);
+
+  if (headings.length === 0) return null;
+  return (
+    <nav aria-label={t("help.toc.title")} className="hidden lg:block">
+      <div className="text-muted-foreground mb-2 text-xs font-semibold tracking-wider uppercase">
+        {t("help.toc.title")}
+      </div>
+      <ul className="space-y-1 text-sm">
+        {headings.map((h) => (
+          <li key={h.slug} style={{ paddingLeft: `${(h.depth - 2) * 0.75}rem` }}>
+            <a
+              href={`#${h.slug}`}
+              className={
+                "block truncate hover:text-foreground " +
+                (active === h.slug ? "text-foreground font-medium" : "text-muted-foreground")
+              }
+            >
+              {h.text}
+            </a>
+          </li>
+        ))}
+      </ul>
+    </nav>
+  );
+}

package/src/features/help/components/__tests__/HelpAskAi.spec.tsx

@@ -0,0 +1,68 @@
+import { describe, it, expect, vi } from "vitest";
+import { render, screen, fireEvent } from "@testing-library/react";
+import { configureJsonApi } from "../../../../client/config";
+import { HelpProvider } from "../../contexts/HelpContext";
+import { HelpAskAi } from "../HelpAskAi";
+
+vi.mock("../../../user/contexts/CurrentUserContext", () => ({
+  useCurrentUserContext: () => ({ currentUser: (globalThis as any).__mockUser ?? null }),
+}));
+
+// HelpAssistantSheet is intentionally rendered ONLY when logged-in to keep the
+// disabled-state DOM minimal. We mock it to a marker so the test asserts presence.
+vi.mock("../HelpAssistantSheet", () => ({
+  HelpAssistantSheet: ({ open }: { open: boolean }) => (open ? <div data-testid="sheet" /> : null),
+}));
+
+function setupConfig() {
+  configureJsonApi({
+    apiUrl: "http://localhost",
+    helpContent: { manifest: [], namespaceUuid: "00000000-0000-5000-8000-000000000000" },
+  });
+}
+
+describe("HelpAskAi", () => {
+  it("renders a disabled button + tooltip for anonymous users", () => {
+    (globalThis as any).__mockUser = null;
+    setupConfig();
+
+    render(
+      <HelpProvider>
+        <HelpAskAi />
+      </HelpProvider>,
+    );
+
+    const button = screen.getByRole("button");
+    expect(button).toHaveAttribute("disabled");
+    // vitest.setup.ts stubs next-intl's useTranslations to return the key as-is.
+    // The TooltipTrigger renders as a <span>, so the disabled <button> is the
+    // only <button> in the DOM (no nested-button hydration risk).
+    expect(screen.queryByTestId("sheet")).toBeNull();
+  });
+
+  it("clicking the disabled button does not open the sheet", () => {
+    (globalThis as any).__mockUser = null;
+    setupConfig();
+    render(
+      <HelpProvider>
+        <HelpAskAi />
+      </HelpProvider>,
+    );
+    fireEvent.click(screen.getByRole("button"));
+    expect(screen.queryByTestId("sheet")).toBeNull();
+  });
+
+  it("renders an enabled button for logged-in users; clicking opens the sheet", () => {
+    (globalThis as any).__mockUser = { id: "u-1" };
+    setupConfig();
+    render(
+      <HelpProvider>
+        <HelpAskAi />
+      </HelpProvider>,
+    );
+    const button = screen.getByRole("button");
+    expect(button).not.toHaveAttribute("disabled");
+    fireEvent.click(button);
+    expect(screen.getByTestId("sheet")).toBeInTheDocument();
+  });
+});

package/src/features/help/components/__tests__/HelpAssistantSheet.spec.tsx

@@ -0,0 +1,36 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen, fireEvent } from "@testing-library/react";
+import { HelpAssistantSheet } from "../HelpAssistantSheet";
+
+const sendMessage = vi.fn().mockResolvedValue(undefined);
+
+vi.mock("../../../assistant/contexts/AssistantContext", () => ({
+  AssistantProvider: ({ children }: { children: React.ReactNode }) => <>{children}</>,
+  useAssistantContext: () => ({
+    assistant: undefined,
+    messages: [],
+    sending: false,
+    status: undefined,
+    failedMessageIds: new Set(),
+    sendMessage,
+    retrySend: vi.fn(),
+  }),
+}));
+
+describe("HelpAssistantSheet", () => {
+  beforeEach(() => sendMessage.mockClear());
+
+  it("submitting the composer calls sendMessage with howToMode: true", async () => {
+    render(<HelpAssistantSheet open={true} onOpenChange={() => {}} />);
+
+    // AssistantEmptyState renders the composer (a textarea + send button).
+    const textarea = screen.getByPlaceholderText("features.assistant.composer_placeholder");
+    fireEvent.change(textarea, { target: { value: "how do scenes work?" } });
+
+    // The empty-state composer's send button is found by its visible text.
+    const sendButton = screen.getByRole("button", { name: /save|send/i });
+    fireEvent.click(sendButton);
+
+    expect(sendMessage).toHaveBeenCalledWith("how do scenes work?", { howToMode: true });
+  });
+});