@cosmicdrift/kumiko-renderer-web 0.146.4 → 0.147.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer-web",
-  "version": "0.146.4",
+  "version": "0.147.0",
   "description": "Web-platform bindings for @cosmicdrift/kumiko-renderer. HTML default-primitives, browser history-based navigation, EventSource-backed live events, and a one-call createKumikoApp that mounts the whole stack via react-dom.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -16,9 +16,9 @@
     "./styles.css": "./src/styles.css"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.146.4",
-    "@cosmicdrift/kumiko-headless": "0.146.4",
-    "@cosmicdrift/kumiko-renderer": "0.146.4",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.147.0",
+    "@cosmicdrift/kumiko-headless": "0.147.0",
+    "@cosmicdrift/kumiko-renderer": "0.147.0",
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
     "@radix-ui/react-label": "^2.1.8",

package/src/__tests__/dashboard-screen.test.tsx

@@ -326,6 +326,10 @@ describe("KumikoScreen dashboard — neue Panel-Kinds", () => {
     );
     await waitFor(() => expect(screen.getByText("92.753 €")).toBeTruthy());
     expect(screen.queryByTestId("kpi-icon")).toBeNull();
+    // #931: unregistriertes Icon darf auch keinen leeren, akzentgefärbten
+    // Chip-Wrapper rendern (StatCard gated den Span auf icon !== undefined).
+    const card = screen.getByTestId("dashboard-panel-kpi");
+    expect(card.querySelector('[style*="123456"]')).toBeNull();
   });
 
   test("stat-Panel: fehlende deltaDirection unterdrückt den Chip (kein Crash)", async () => {

package/src/__tests__/form-action-bar.test.tsx

@@ -120,6 +120,15 @@ describe("DefaultSection Card-Standard (subtitle + actions-Footer)", () => {
     expect(actions.textContent).toContain("Übernehmen");
   });
 
+  test('standalone: variant="destructive" adds a destructive border, default variant does not', () => {
+    render(
+      <Section testId="danger" title="Danger zone" variant="destructive">
+        <div>x</div>
+      </Section>,
+    );
+    expect(screen.getByTestId("danger").className).toContain("border-destructive/40");
+  });
+
   test("title-only standalone (Bestands-Consumer) hat keinen Divider mehr", () => {
     render(
       <Section testId="legacy" title="Stammdaten">

package/src/__tests__/projection-list-actions.test.tsx

@@ -86,4 +86,46 @@ describe("projectionList writeHandler-Actions", () => {
     expect(write.mock.calls[0]?.[0]).toBe("status:write:maintenance:sync");
     expect(write.mock.calls[0]?.[1]).toEqual({ source: "manual" });
   });
+
+  // Prod-Bug 2026-06-07 (siehe useRowActionTrigger): ein verschluckter
+  // Write-Fehler sah für den User wie "nichts passiert" aus. Row- UND
+  // Toolbar-Action auf projectionList müssen denselben Surfacing-Pfad wie
+  // entityList nehmen (Toast statt stiller no-op).
+  test("Row-Action-Fehler wird als Toast surfaced, nicht verschluckt", async () => {
+    const write = mock(async (_type: string, _payload: unknown) => ({
+      isSuccess: false,
+      error: { code: "internal_error", httpStatus: 500, message: "maintenance start failed" },
+    }));
+    const { ToastProvider } = await import("../primitives/toast");
+    render(
+      <ToastProvider>
+        <DispatcherProvider dispatcher={makeDispatcher(write as unknown as Dispatcher["write"])}>
+          <KumikoScreen schema={schema} qn="status:screen:maintenance-list" />
+        </DispatcherProvider>
+      </ToastProvider>,
+    );
+    await waitFor(() => expect(screen.getByText("DB-Upgrade")).toBeTruthy());
+
+    fireEvent.click(screen.getByRole("button", { name: "status:action:start" }));
+    expect(await screen.findByText("maintenance start failed")).toBeTruthy();
+  });
+
+  test("Toolbar-Action-Fehler wird als Toast surfaced, nicht verschluckt", async () => {
+    const write = mock(async (_type: string, _payload: unknown) => ({
+      isSuccess: false,
+      error: { code: "internal_error", httpStatus: 500, message: "maintenance sync failed" },
+    }));
+    const { ToastProvider } = await import("../primitives/toast");
+    render(
+      <ToastProvider>
+        <DispatcherProvider dispatcher={makeDispatcher(write as unknown as Dispatcher["write"])}>
+          <KumikoScreen schema={schema} qn="status:screen:maintenance-list" />
+        </DispatcherProvider>
+      </ToastProvider>,
+    );
+    await waitFor(() => expect(screen.getByText("DB-Upgrade")).toBeTruthy());
+
+    fireEvent.click(screen.getByRole("button", { name: "status:action:sync" }));
+    expect(await screen.findByText("maintenance sync failed")).toBeTruthy();
+  });
 });

package/src/__tests__/use-mutation.test.tsx

@@ -0,0 +1,86 @@
+import { describe, expect, mock, test } from "bun:test";
+import type { Dispatcher } from "@cosmicdrift/kumiko-headless";
+import { DispatcherProvider, useMutation } from "@cosmicdrift/kumiko-renderer";
+import type { ReactNode } from "react";
+import { act, createMockDispatcher, renderHook, waitFor } from "./test-utils";
+
+function wrap(dispatcher: Dispatcher) {
+  return ({ children }: { children: ReactNode }) => (
+    <DispatcherProvider dispatcher={dispatcher}>{children}</DispatcherProvider>
+  );
+}
+
+describe("useMutation", () => {
+  // #902/2: two overlapping calls on one instance (list-row actions sharing
+  // it) must not let the earlier-STARTED, later-RESOLVING call clobber the
+  // state set by the later-started, earlier-resolving one.
+  test("out-of-order resolution: state reflects the most recently started call, not the most recently resolved one", async () => {
+    let resolveFirst: (() => void) | undefined;
+    const write = mock(async (_type: string, payload: unknown) => {
+      if ((payload as { id: string }).id === "row-1") {
+        await new Promise<void>((resolve) => {
+          resolveFirst = resolve;
+        });
+        return { isSuccess: true, data: { id: "row-1" } };
+      }
+      return { isSuccess: true, data: { id: "row-2" } };
+    });
+    const dispatcher = createMockDispatcher({ write: write as unknown as Dispatcher["write"] });
+    const { result } = renderHook(() => useMutation("row:update"), {
+      wrapper: wrap(dispatcher),
+    });
+
+    let firstCallDone: Promise<unknown>;
+    let secondCallDone: Promise<unknown>;
+    act(() => {
+      firstCallDone = result.current.mutate({ id: "row-1" });
+    });
+    await act(async () => {
+      secondCallDone = result.current.mutate({ id: "row-2" });
+      // let the second (no-delay) call resolve before the first
+      await Promise.resolve();
+    });
+
+    await waitFor(() => expect(result.current.data).toEqual({ id: "row-2" }));
+    expect(result.current.pending).toBe(false); // row-2 (the latest call) already settled
+
+    await act(async () => {
+      resolveFirst?.();
+      await firstCallDone;
+      await secondCallDone;
+    });
+
+    // The first call resolving late must not overwrite row-2's state.
+    expect(result.current.data).toEqual({ id: "row-2" });
+    expect(result.current.pending).toBe(false);
+  });
+
+  test("reset() invalidates a still-pending call's late state update", async () => {
+    let resolveWrite: (() => void) | undefined;
+    const write = mock(async () => {
+      await new Promise<void>((resolve) => {
+        resolveWrite = resolve;
+      });
+      return { isSuccess: true, data: { id: "late" } };
+    });
+    const dispatcher = createMockDispatcher({ write: write as unknown as Dispatcher["write"] });
+    const { result } = renderHook(() => useMutation("row:update"), {
+      wrapper: wrap(dispatcher),
+    });
+
+    let mutateDone: Promise<unknown>;
+    act(() => {
+      mutateDone = result.current.mutate({ id: "x" });
+    });
+    act(() => {
+      result.current.reset();
+    });
+    await act(async () => {
+      resolveWrite?.();
+      await mutateDone;
+    });
+
+    expect(result.current.data).toBeNull();
+    expect(result.current.pending).toBe(false);
+  });
+});

package/src/app/dashboard-body.tsx

@@ -9,7 +9,7 @@
 //                   anzeigefertige Werte (der Query-Handler formatiert).
 //                   deltaField/deltaDirectionField(+deltaToneField) sind
 //                   optional — nur wenn BEIDE Felder gesetzt sind UND geliefert
-//                   werden, zeigt die Kachel einen Delta-Chip ("↓ 23 %").
+//                   werden, zeigt die Kachel einen Delta-Chip ("↓23 %").
 //                   icon/accentColor sind statisch am Panel (keine Query-
 //                   Felder) — icon über extensionSectionComponents wie bei
 //                   custom-Panels, accentColor ein roher CSS-Farbwert.
@@ -61,43 +61,34 @@ const STAT_TONES: ReadonlySet<string> = new Set(["default", "positive", "warn"])
 const WIDE_PANEL = "sm:col-span-2 lg:col-span-4";
 const HALF_PANEL = "sm:col-span-2 lg:col-span-2";
 
-function StatPanelIcon({
+function StatPanelBody({
   panel,
+  label,
   screenId,
   filterParams,
 }: {
   readonly panel: DashboardStatPanel;
+  readonly label: string;
   readonly screenId: string;
   readonly filterParams: Readonly<Record<string, unknown>>;
 }): ReactNode {
-  const name = panel.icon !== undefined ? extensionSectionName(panel.icon) : undefined;
-  const Icon = useExtensionSectionComponent(name);
+  // Resolved HERE (not in a separate always-rendered child) so `icon` on
+  // <StatCard> is `undefined` — not a React element that renders empty —
+  // when the icon name isn't registered. StatCard gates its accent chip on
+  // `icon !== undefined`, so a resolved-but-hidden element used to leave a
+  // stray accent-colored chip next to the label.
+  const iconName = panel.icon !== undefined ? extensionSectionName(panel.icon) : undefined;
+  const Icon = useExtensionSectionComponent(iconName);
   useEffect(() => {
-    if (panel.icon !== undefined && name !== undefined && Icon === undefined) {
+    if (panel.icon !== undefined && iconName !== undefined && Icon === undefined) {
       // biome-ignore lint/suspicious/noConsole: dev-warning für Setup-Fehler
       console.warn(
         `[kumiko] Dashboard stat-panel "${panel.id}" on screen "${screenId}" references icon ` +
-          `"${name}", which is not registered in clientFeatures.extensionSectionComponents.`,
+          `"${iconName}", which is not registered in clientFeatures.extensionSectionComponents.`,
       );
     }
-  }, [panel.icon, panel.id, name, Icon, screenId]);
-  if (Icon === undefined) return null;
-  return (
-    <Icon entityName={screenId} entityId={null} screenId={screenId} filterParams={filterParams} />
-  );
-}
+  }, [panel.icon, panel.id, iconName, Icon, screenId]);
 
-function StatPanelBody({
-  panel,
-  label,
-  screenId,
-  filterParams,
-}: {
-  readonly panel: DashboardStatPanel;
-  readonly label: string;
-  readonly screenId: string;
-  readonly filterParams: Readonly<Record<string, unknown>>;
-}): ReactNode {
   const { data, error, loading, refetch } = useQuery<Readonly<Record<string, unknown>>>(
     panel.query,
     filterParams,
@@ -114,14 +105,19 @@ function StatPanelBody({
   return (
     <StatCard
       icon={
-        panel.icon !== undefined ? (
-          <StatPanelIcon panel={panel} screenId={screenId} filterParams={filterParams} />
+        Icon !== undefined ? (
+          <Icon
+            entityName={screenId}
+            entityId={null}
+            screenId={screenId}
+            filterParams={filterParams}
+          />
         ) : undefined
       }
       label={label}
       value={String(record[panel.valueField] ?? "—")}
       tone={tone}
-      accentColor={panel.accentColor}
+      {...(Icon !== undefined && { accentColor: panel.accentColor })}
       {...(sub !== undefined && sub !== null && { sub: String(sub) })}
       {...(delta !== undefined && { delta })}
       testId={`dashboard-panel-${panel.id}`}

package/src/index.ts

@@ -155,6 +155,8 @@ export {
 } from "./tokens";
 export { SidebarMenu, SidebarMenuButton, SidebarMenuItem, SidebarProvider } from "./ui/sidebar";
 export type {
+  AiTextAreaProps,
+  AiTextFieldProps,
   BooleanFieldProps,
   ComparisonMetric,
   DateFieldProps,
@@ -176,6 +178,8 @@ export type {
   TimeseriesPoint,
 } from "./widgets";
 export {
+  AiTextArea,
+  AiTextField,
   BooleanField,
   CollapsibleSection,
   ComparisonTable,

package/src/layout/nav-tree.tsx

@@ -619,11 +619,11 @@ function NavMenuNode({ node, collapsed, onToggle }: NavSubProps): ReactNode {
 
   const chevron = s.expandable ? (
     <SidebarMenuAction
-      aria-label={t(s.isCollapsed ? "kumiko.nav.expand" : "kumiko.nav.collapse")}
-      aria-expanded={!s.isCollapsed}
+      aria-label={t(s.isExpanded ? "kumiko.nav.collapse" : "kumiko.nav.expand")}
+      aria-expanded={s.isExpanded}
       onClick={() => onToggle(node.qualifiedName)}
     >
-      {s.isCollapsed ? <ChevronRight /> : <ChevronDown />}
+      {s.isExpanded ? <ChevronDown /> : <ChevronRight />}
     </SidebarMenuAction>
   ) : null;
 
@@ -675,15 +675,15 @@ function NavMenuNode({ node, collapsed, onToggle }: NavSubProps): ReactNode {
         onClick={() => {
           if (s.expandable) onToggle(node.qualifiedName);
         }}
-        {...(s.expandable && { "aria-expanded": !s.isCollapsed })}
+        {...(s.expandable && { "aria-expanded": s.isExpanded })}
       >
         <NavLeadingIcon node={node} active={false} expanded={s.isExpanded} />
         <span className="truncate">{s.displayLabel}</span>
         {s.expandable &&
-          (s.isCollapsed ? (
-            <ChevronRight className="ml-auto" />
-          ) : (
+          (s.isExpanded ? (
             <ChevronDown className="ml-auto" />
+          ) : (
+            <ChevronRight className="ml-auto" />
           ))}
       </SidebarMenuButton>
       <NodeActions node={node} />
@@ -724,15 +724,15 @@ function NavSubNode({ node, collapsed, onToggle }: NavSubProps): ReactNode {
   const chevron = s.expandable ? (
     <button
       type="button"
-      aria-label={t(s.isCollapsed ? "kumiko.nav.expand" : "kumiko.nav.collapse")}
-      aria-expanded={!s.isCollapsed}
+      aria-label={t(s.isExpanded ? "kumiko.nav.collapse" : "kumiko.nav.expand")}
+      aria-expanded={s.isExpanded}
       onClick={(e) => {
         e.stopPropagation();
         onToggle(node.qualifiedName);
       }}
       className="absolute top-1 right-1 flex size-5 items-center justify-center rounded-md text-sidebar-foreground/70 hover:bg-sidebar-accent hover:text-sidebar-accent-foreground"
     >
-      {s.isCollapsed ? <ChevronRight className="size-3.5" /> : <ChevronDown className="size-3.5" />}
+      {s.isExpanded ? <ChevronDown className="size-3.5" /> : <ChevronRight className="size-3.5" />}
     </button>
   ) : null;
 

package/src/primitives/index.tsx

@@ -144,7 +144,7 @@ function DefaultButton({
       data-loading={loading === true ? "true" : undefined}
       variant={BUTTON_VARIANT[variant]}
       size={BUTTON_SIZE[size]}
-      {...(ariaLabel !== undefined && { "aria-label": ariaLabel })}
+      aria-label={ariaLabel}
       className={className}
     >
       {loading === true ? <Loader2 className="size-4 animate-spin" aria-hidden="true" /> : children}
@@ -1509,7 +1509,14 @@ export function FormScreenShell({
   );
 }
 
-function DefaultSection({ title, subtitle, children, actions, testId }: SectionProps): ReactNode {
+function DefaultSection({
+  title,
+  subtitle,
+  children,
+  actions,
+  variant = "default",
+  testId,
+}: SectionProps): ReactNode {
   const insideForm = useContext(InsideFormContext);
 
   // h3 statt CardTitle (= div): erhält die Heading-Semantik für
@@ -1542,7 +1549,13 @@ function DefaultSection({ title, subtitle, children, actions, testId }: SectionP
   // actions hier = rechtsbündige Reihe (das Form trägt den eigenen Footer).
   if (insideForm) {
     return (
-      <section data-testid={testId} className="flex flex-col gap-4 px-6 py-6">
+      <section
+        data-testid={testId}
+        className={cn(
+          "flex flex-col gap-4 px-6 py-6",
+          variant === "destructive" && "border-l-2 border-destructive/40",
+        )}
+      >
         {header}
         {children}
         {actions !== undefined && (
@@ -1565,7 +1578,14 @@ function DefaultSection({ title, subtitle, children, actions, testId }: SectionP
   // `children`) WOULD get silently clipped — verify this against any new
   // standalone-section content that renders its own non-portaled overlay.
   return (
-    <div data-testid={testId} className={cn(cardSurface(), "overflow-hidden")}>
+    <div
+      data-testid={testId}
+      className={cn(
+        cardSurface(),
+        "overflow-hidden",
+        variant === "destructive" && "border-destructive/40",
+      )}
+    >
       <div className="flex flex-col gap-4 px-6 py-6">
         {header}
         {children}

package/src/widgets/__tests__/ai-text-field.test.tsx

@@ -0,0 +1,267 @@
+import { describe, expect, mock, test } from "bun:test";
+import { DispatcherProvider } from "@cosmicdrift/kumiko-renderer";
+import { type ReactElement, useState } from "react";
+import {
+  createMockDispatcher,
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+} from "../../__tests__/test-utils";
+import { AiTextArea, AiTextField, type AiTextFieldProps } from "../ai-text-field";
+
+function renderWithDispatcher(
+  ui: ReactElement,
+  query: NonNullable<Parameters<typeof createMockDispatcher>[0]>["query"],
+) {
+  const dispatcher = createMockDispatcher({ query });
+  return render(<DispatcherProvider dispatcher={dispatcher}>{ui}</DispatcherProvider>);
+}
+
+// Real controlled-component loop: onChange feeds back into `value` so
+// Tab-accept sees the actually-typed text, not a stale prop. Plain
+// `mock()`-only setups (no state) can't exercise this — that's a test
+// bug we hit and fixed once already (see git history), keep it this way.
+function ControlledAiTextField(
+  props: Omit<AiTextFieldProps, "value" | "onChange"> & {
+    readonly initialValue: string;
+    readonly onChangeSpy?: (v: string) => void;
+  },
+) {
+  const { initialValue, onChangeSpy, ...rest } = props;
+  const [value, setValue] = useState(initialValue);
+  return (
+    <AiTextField
+      {...rest}
+      value={value}
+      onChange={(v) => {
+        setValue(v);
+        onChangeSpy?.(v);
+      }}
+    />
+  );
+}
+
+describe("AiTextField", () => {
+  test("plain typing calls onChange like a normal text field", () => {
+    const onChangeSpy = mock((_v: string) => {});
+    renderWithDispatcher(
+      <ControlledAiTextField
+        label="Title"
+        id="title"
+        name="title"
+        initialValue=""
+        onChangeSpy={onChangeSpy}
+        actions={[]}
+        completion={false}
+        testId="title"
+      />,
+      (async () => ({
+        isSuccess: true,
+        data: { type: "text", text: "", usage: { inputTokens: 0, outputTokens: 0 } },
+      })) as never,
+    );
+    fireEvent.change(screen.getByTestId("title-input"), { target: { value: "hi" } });
+    expect(onChangeSpy).toHaveBeenCalledWith("hi");
+  });
+
+  test("ghost-text: shows suggestion, Tab accepts it appended to the typed text", async () => {
+    const onChangeSpy = mock((_v: string) => {});
+    renderWithDispatcher(
+      <ControlledAiTextField
+        label="Title"
+        id="title"
+        name="title"
+        initialValue=""
+        onChangeSpy={onChangeSpy}
+        actions={[]}
+        completionDebounceMs={5}
+        testId="title"
+      />,
+      (async () => ({
+        isSuccess: true,
+        data: { type: "text", text: "fox", usage: { inputTokens: 1, outputTokens: 1 } },
+      })) as never,
+    );
+
+    const input = screen.getByTestId("title-input");
+    fireEvent.change(input, { target: { value: "the quick brown " } });
+
+    await waitFor(() => expect(screen.queryByText("fox")).toBeTruthy(), { timeout: 1000 });
+
+    fireEvent.keyDown(input, { key: "Tab" });
+    expect(onChangeSpy).toHaveBeenLastCalledWith("the quick brown fox");
+  });
+
+  test("ghost-text: Esc discards the suggestion without calling onChange", async () => {
+    const onChangeSpy = mock((_v: string) => {});
+    renderWithDispatcher(
+      <ControlledAiTextField
+        label="Title"
+        id="title"
+        name="title"
+        initialValue=""
+        onChangeSpy={onChangeSpy}
+        actions={[]}
+        completionDebounceMs={5}
+        testId="title"
+      />,
+      (async () => ({
+        isSuccess: true,
+        data: { type: "text", text: "there", usage: { inputTokens: 1, outputTokens: 1 } },
+      })) as never,
+    );
+
+    const input = screen.getByTestId("title-input");
+    fireEvent.change(input, { target: { value: "hi " } });
+    await waitFor(() => expect(screen.queryByText("there")).toBeTruthy(), { timeout: 1000 });
+
+    onChangeSpy.mockClear();
+    fireEvent.keyDown(input, { key: "Escape" });
+    expect(screen.queryByText("there")).toBeNull();
+    expect(onChangeSpy).not.toHaveBeenCalled();
+  });
+
+  test("feature_disabled → toolbar hides, field stays usable (graceful degradation)", async () => {
+    const onChangeSpy = mock((_v: string) => {});
+    renderWithDispatcher(
+      <ControlledAiTextField
+        label="Title"
+        id="title"
+        name="title"
+        initialValue=""
+        onChangeSpy={onChangeSpy}
+        completionDebounceMs={5}
+        testId="title"
+      />,
+      (async () => ({
+        isSuccess: false,
+        error: { code: "feature_disabled", message: "off", i18nKey: "errors.feature.disabled" },
+      })) as never,
+    );
+
+    fireEvent.change(screen.getByTestId("title-input"), { target: { value: "hi " } });
+    await waitFor(() => expect(screen.queryByRole("button")).toBeNull(), { timeout: 1000 });
+    expect(screen.getByTestId("title-input")).toBeTruthy();
+  });
+
+  test("correct action: opens dialog, runs immediately, apply calls onChange with the result", async () => {
+    const onChangeSpy = mock((_v: string) => {});
+    renderWithDispatcher(
+      <ControlledAiTextField
+        label="Title"
+        id="title"
+        name="title"
+        initialValue="teh cat sat"
+        onChangeSpy={onChangeSpy}
+        completion={false}
+        actions={["correct"]}
+        testId="title"
+      />,
+      (async (_type: string, payload: unknown) => {
+        const mode = (payload as { mode: string }).mode;
+        if (mode !== "correct") throw new Error(`unexpected mode ${mode}`);
+        return {
+          isSuccess: true,
+          data: { type: "text", text: "the cat sat", usage: { inputTokens: 3, outputTokens: 3 } },
+        };
+      }) as never,
+    );
+
+    fireEvent.click(screen.getByRole("button", { name: "Correct" }));
+    await waitFor(() => expect(screen.queryByText("the cat sat")).toBeTruthy());
+
+    fireEvent.click(screen.getByRole("button", { name: "Confirm" }));
+    expect(onChangeSpy).toHaveBeenCalledWith("the cat sat");
+  });
+});
+
+describe("AiTextField ghost-text overlay — scroll sync", () => {
+  test("Tab/Escape aside: overlay mirrors the input's scrollLeft on an interactive scroll", async () => {
+    renderWithDispatcher(
+      <ControlledAiTextField
+        label="Title"
+        id="title"
+        name="title"
+        initialValue=""
+        actions={[]}
+        completionDebounceMs={5}
+        testId="title"
+      />,
+      (async () => ({
+        isSuccess: true,
+        data: { type: "text", text: "fox", usage: { inputTokens: 1, outputTokens: 1 } },
+      })) as never,
+    );
+
+    const input = screen.getByTestId("title-input") as HTMLInputElement;
+    fireEvent.change(input, { target: { value: "the quick brown " } });
+    await waitFor(() => expect(screen.queryByText("fox")).toBeTruthy(), { timeout: 1000 });
+
+    const overlay = input.parentElement?.querySelector('[aria-hidden="true"]') as HTMLDivElement;
+    expect(overlay).toBeTruthy();
+
+    // Interactive scroll (e.g. arrow-key caret move) — caught by the
+    // onScroll handler.
+    Object.defineProperty(input, "scrollLeft", { value: 50, writable: true });
+    fireEvent.scroll(input);
+    expect(overlay.scrollLeft).toBe(50);
+  });
+
+  test("overlay resyncs on typing even without a `scroll` event (Chrome doesn't fire one for caret-follow auto-scroll)", async () => {
+    renderWithDispatcher(
+      <ControlledAiTextField
+        label="Title"
+        id="title"
+        name="title"
+        initialValue=""
+        actions={[]}
+        completionDebounceMs={5}
+        testId="title"
+      />,
+      (async () => ({
+        isSuccess: true,
+        data: { type: "text", text: "fox", usage: { inputTokens: 1, outputTokens: 1 } },
+      })) as never,
+    );
+
+    const input = screen.getByTestId("title-input") as HTMLInputElement;
+    fireEvent.change(input, { target: { value: "the quick brown " } });
+    await waitFor(() => expect(screen.queryByText("fox")).toBeTruthy(), { timeout: 1000 });
+
+    const overlay = input.parentElement?.querySelector('[aria-hidden="true"]') as HTMLDivElement;
+
+    // Simulate the browser having auto-scrolled the input to reveal the
+    // caret WITHOUT firing a `scroll` event — the real Chrome behavior this
+    // bug hinged on. Only the value/suggestion-keyed layout effect (not
+    // onScroll) can catch this.
+    Object.defineProperty(input, "scrollLeft", { value: 120, writable: true });
+    fireEvent.change(input, { target: { value: "the quick brown f" } });
+    await waitFor(() => expect(screen.queryByText("fox")).toBeTruthy(), { timeout: 1000 });
+
+    expect(overlay.scrollLeft).toBe(120);
+  });
+});
+
+describe("AiTextArea", () => {
+  test("renders a textarea with the given rows", () => {
+    const onChange = mock((_v: string) => {});
+    renderWithDispatcher(
+      <AiTextArea
+        label="Body"
+        id="body"
+        name="body"
+        value=""
+        onChange={onChange}
+        rows={6}
+        actions={[]}
+        completion={false}
+        testId="body"
+      />,
+      (async () => ({ isSuccess: true, data: {} })) as never,
+    );
+    const el = screen.getByTestId("body-input") as HTMLTextAreaElement;
+    expect(el.tagName).toBe("TEXTAREA");
+    expect(el.getAttribute("rows")).toBe("6");
+  });
+});