@elabs-ai/components-ai 4.0.0

package/src/grouped-parts.stories.tsx

@@ -0,0 +1,104 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { GroupedParts } from "./grouped-parts";
+import { groupPartByType, type GroupablePart } from "./part-groups";
+
+const meta = {
+  title: "AI/GroupedParts",
+  component: GroupedParts,
+  tags: ["autodocs"],
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof GroupedParts>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// A representative ordered part list, the shape an AI SDK UIMessage exposes.
+const parts: GroupablePart[] = [
+  {
+    type: "reasoning",
+    state: "done",
+    text: "The user wants Q3 revenue by region. I'll query the warehouse and reconcile.",
+  },
+  {
+    type: "tool-query_warehouse",
+    state: "output-available",
+    input: { sql: "select region, sum(amount) from sales group by region" },
+    output: { rows: 4 },
+  },
+  {
+    type: "tool-reconcile",
+    state: "output-available",
+    input: { source: "ledger" },
+    output: { reconciled: 8 },
+  },
+  { type: "text", text: "Q3 revenue totalled $4.2M across 4 regions — EMEA led at $1.8M." },
+];
+
+/** Default — the reasoning + tool run folds into one collapsible trace; the
+ *  final answer stays a top-level leaf. */
+export const Default: Story = {
+  args: { parts },
+};
+
+/** Streaming — a tool is still running, so the trace rolls up to "running" and
+ *  opens automatically. */
+export const Streaming: Story = {
+  args: {
+    parts: [
+      { type: "reasoning", state: "streaming", text: "Deciding which tables to join…" },
+      { type: "tool-query_warehouse", state: "input-available", input: { sql: "select …" } },
+    ],
+  },
+};
+
+/** Interaction cards never fold — an approval-style part is forced standalone,
+ *  splitting the trace around it. */
+export const StandaloneInteraction: Story = {
+  args: {
+    parts: [
+      { type: "reasoning", state: "done", text: "This will delete 12 records." },
+      { type: "approval-request", state: "approval-requested" },
+      { type: "reasoning", state: "done", text: "Approved — proceeding." },
+      { type: "text", text: "Done — 12 records removed." },
+    ],
+    children: ({ part, isGroup, children }) =>
+      isGroup ? (
+        <>{children}</>
+      ) : part.type === "approval-request" ? (
+        <div className="rounded-md border border-border-strong border-s-4 border-s-border-strong bg-card p-3 text-body">
+          <p className="font-medium text-foreground">Approve deletion of 12 records?</p>
+        </div>
+      ) : part.type === "text" ? (
+        <p className="text-body text-foreground">
+          {String((part as { text?: string }).text ?? "")}
+        </p>
+      ) : undefined,
+  },
+};
+
+/** Custom grouping — group everything into a single trace via a custom groupBy. */
+export const CustomGrouping: Story = {
+  args: {
+    parts,
+    groupBy: groupPartByType<GroupablePart>({
+      groupKey: "group-analysis",
+      inline: [/^reasoning$/, /^tool-/, "text"],
+    }),
+  },
+};
+
+/** Empty — an empty part list renders nothing (no broken UI). */
+export const Empty: Story = {
+  args: { parts: [] },
+};
+
+/** Dark theme — trace disclosure + tool cards in dark. */
+export const DarkTheme: Story = {
+  args: { parts },
+  decorators: [
+    (Story) => (
+      <div data-theme="dark" className="rounded-lg bg-background p-6 text-foreground">
+        <Story />
+      </div>
+    ),
+  ],
+};

package/src/grouped-parts.test.tsx

@@ -0,0 +1,167 @@
+import { describe, expect, it } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { GroupedParts } from "./grouped-parts";
+import {
+  buildPartGroups,
+  groupPartByType,
+  isGroupNode,
+  partsFingerprint,
+  type GroupablePart,
+  type GroupBy,
+} from "./part-groups";
+
+interface P extends GroupablePart {
+  type: string;
+  state?: string;
+  text?: string;
+  id?: string;
+}
+
+describe("part-groups — coalescing", () => {
+  it("coalesces an adjacent reasoning+tool run into one group, leaves text alone", () => {
+    const parts: P[] = [
+      { type: "text", text: "Hi" },
+      { type: "reasoning", state: "done" },
+      { type: "tool-search", state: "output-available" },
+      { type: "text", text: "Done" },
+    ];
+    const tree = buildPartGroups(parts, groupPartByType<P>());
+    expect(tree).toHaveLength(3);
+    expect(tree[0]).toMatchObject({ kind: "leaf", part: { type: "text" } });
+    const group = tree[1];
+    expect(group).toMatchObject({ kind: "group" });
+    if (group?.kind === "group") {
+      expect(group.group.type).toBe("group-work");
+      expect(group.group.indices).toEqual([1, 2]);
+      expect(group.children).toHaveLength(2);
+    }
+    expect(tree[2]).toMatchObject({ kind: "leaf", part: { type: "text" } });
+  });
+
+  it("does NOT merge two groups separated by a standalone part", () => {
+    const parts: P[] = [
+      { type: "reasoning", state: "done" },
+      { type: "approval-request" },
+      { type: "reasoning", state: "done" },
+    ];
+    const tree = buildPartGroups(parts, groupPartByType<P>());
+    expect(tree).toHaveLength(3);
+    expect(tree[1]).toMatchObject({ kind: "leaf", part: { type: "approval-request" } });
+  });
+
+  it("nests multi-element paths", () => {
+    const groupBy: GroupBy<P> = (p) =>
+      p.type === "a" ? ["group-outer", "group-inner"] : p.type === "b" ? ["group-outer"] : [];
+    const parts: P[] = [{ type: "a" }, { type: "a" }, { type: "b" }];
+    const tree = buildPartGroups(parts, groupBy);
+    expect(tree).toHaveLength(1);
+    const outer = tree[0];
+    expect(outer).toMatchObject({ kind: "group", group: { type: "group-outer" } });
+    if (outer?.kind === "group") {
+      expect(outer.children).toHaveLength(2);
+      expect(outer.children[0]).toMatchObject({ kind: "group", group: { type: "group-inner" } });
+      expect(outer.children[1]).toMatchObject({ kind: "leaf", part: { type: "b" } });
+    }
+  });
+});
+
+describe("part-groups — status rollup + identity", () => {
+  it("rolls up to running when any member is running", () => {
+    const parts: P[] = [
+      { type: "reasoning", state: "streaming" },
+      { type: "tool-x", state: "output-available" },
+    ];
+    const tree = buildPartGroups(parts, groupPartByType<P>());
+    expect(tree[0]).toMatchObject({ kind: "group", group: { status: "running" } });
+  });
+
+  it("uses a part id for a stable leaf key across re-renders", () => {
+    const before = buildPartGroups([{ type: "text", id: "abc" }] as P[], groupPartByType<P>());
+    const after = buildPartGroups(
+      [{ type: "text", id: "abc", text: "grown" }] as P[],
+      groupPartByType<P>(),
+    );
+    expect(before[0]!.key).toBe(after[0]!.key);
+  });
+
+  it("fingerprint changes on status change but not on unrelated identity churn", () => {
+    const a = partsFingerprint([{ type: "tool-x", state: "input-available", id: "1" }] as P[]);
+    const b = partsFingerprint([{ type: "tool-x", state: "output-available", id: "1" }] as P[]);
+    expect(a).not.toBe(b);
+  });
+});
+
+describe("groupPartByType — classification", () => {
+  it("honors an explicit inline classifier", () => {
+    const gb = groupPartByType<P>({ classify: (p) => (p.type === "text" ? "inline" : undefined) });
+    const tree = buildPartGroups([{ type: "text" }, { type: "text" }] as P[], gb);
+    expect(tree).toHaveLength(1);
+    expect(tree[0]).toMatchObject({ kind: "group" });
+  });
+
+  it("forces standalone parts out of a group even when classified inline elsewhere", () => {
+    const gb = groupPartByType<P>();
+    expect(gb({ type: "human-input" } as P, { index: 0, parts: [] })).toEqual([]);
+  });
+
+  it("isGroupNode narrows synthetic nodes", () => {
+    expect(isGroupNode({ type: "group-work" })).toBe(true);
+    expect(isGroupNode({ type: "reasoning" })).toBe(false);
+  });
+});
+
+describe("GroupedParts — component", () => {
+  it("renders a default open trace for a running group", () => {
+    render(
+      <GroupedParts
+        parts={[
+          { type: "reasoning", state: "streaming", text: "thinking" },
+          { type: "tool-search", state: "input-available", input: {} },
+        ]}
+      />,
+    );
+    // Running → the trace label + the tool header inside are visible.
+    expect(screen.getByText("Working…")).toBeInTheDocument();
+    expect(screen.getByText("search")).toBeInTheDocument();
+  });
+
+  it("renders the ToolOutput skeleton for an in-flight tool part (#269/#8 — no output area gap)", async () => {
+    const user = userEvent.setup();
+    render(
+      <GroupedParts
+        parts={[{ type: "tool-search", state: "input-streaming", input: {}, id: "call-1" }]}
+      />,
+    );
+    // The outer trace opens by default (running), but the individual Tool's
+    // own disclosure still defaults closed — expand it to reach ToolContent.
+    await user.click(screen.getByText("search"));
+    // Previously the output area was gated behind `output !== undefined ||
+    // errorText`, so an `input-streaming` tool rendered NOTHING here. Now it
+    // shows the settled "Result" heading + a loading live region instead of a
+    // gap.
+    expect(screen.getByText("Result")).toBeInTheDocument();
+    expect(screen.getByRole("status")).toBeInTheDocument();
+  });
+
+  it("passes group nodes (with children) and leaves to the render-prop", () => {
+    render(
+      <GroupedParts parts={[{ type: "reasoning", state: "done" }, { type: "approval-request" }]}>
+        {({ part, isGroup, children }) =>
+          isGroup ? (
+            <div data-testid="group">
+              group:{part.type}
+              {children}
+            </div>
+          ) : (
+            <div data-testid={`leaf-${part.type}`}>leaf:{part.type}</div>
+          )
+        }
+      </GroupedParts>,
+    );
+    expect(screen.getByTestId("group")).toHaveTextContent("group:group-work");
+    // The reasoning leaf renders INSIDE the group; the approval is a standalone leaf.
+    expect(screen.getByTestId("group")).toContainElement(screen.getByTestId("leaf-reasoning"));
+    expect(screen.getByTestId("leaf-approval-request")).toHaveTextContent("leaf:approval-request");
+  });
+});

package/src/grouped-parts.tsx

@@ -0,0 +1,247 @@
+"use client";
+
+/**
+ * GroupedParts — renders an ordered part list, folding adjacent reasoning/tool
+ * parts into collapsible traces (see `part-groups.ts` for the pure engine).
+ *
+ * A render-prop switches on `part.type`. Group nodes arrive as synthetic
+ * `{ type: "group-…", status, indices }` with their rendered `children`; real
+ * parts arrive as leaves. When no render-prop is given, sensible defaults
+ * integrate the existing `Reasoning` / `Tool` components (and a collapsible
+ * trace for groups). It is presentational only — the grouping is a client-side
+ * view transform, never a model output format.
+ *
+ * NOTE: this is a generic function component (not `forwardRef`) because the
+ * render-prop is generic over the part type `T`; `forwardRef` erases generics.
+ */
+
+import { Fragment, useMemo, type ComponentProps, type HTMLAttributes, type ReactNode } from "react";
+import { BrainIcon, ChevronDownIcon } from "lucide-react";
+import {
+  Badge,
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+
+import { Reasoning, ReasoningContent, ReasoningTrigger } from "./reasoning";
+import {
+  Tool,
+  ToolContent,
+  ToolHeader,
+  ToolInput,
+  ToolOutput,
+  statusFromToolState,
+  type ToolPart,
+} from "./tool";
+import {
+  buildPartGroups,
+  defaultPartStatus,
+  groupPartByType,
+  partsFingerprint,
+  type GetPartStatus,
+  type GroupablePart,
+  type GroupBy,
+  type GroupedNode,
+  type GroupStatus,
+  type PartGroupNode,
+} from "./part-groups";
+
+// ─── Render-prop args ─────────────────────────────────────────────────────────
+
+export interface GroupedPartRenderArgs<T extends GroupablePart> {
+  /** The real part (leaf) or the synthetic group node. */
+  part: T | PartGroupNode;
+  /** True when `part` is a synthetic group node. */
+  isGroup: boolean;
+  /** The rendered subtree — group nodes only. */
+  children?: ReactNode;
+  /** Rolled-up status (groups) or the part's status (leaves). */
+  status: GroupStatus;
+  /** Original part indices under this group (groups only). */
+  indices?: number[];
+  /** Original part index (leaves only). */
+  index?: number;
+}
+
+export type GroupedPartRenderer<T extends GroupablePart> = (
+  args: GroupedPartRenderArgs<T>,
+) => ReactNode;
+
+// ─── Default renderers ────────────────────────────────────────────────────────
+
+function DefaultGroup({
+  status,
+  count,
+  children,
+}: {
+  status: GroupStatus;
+  count: number;
+  children: ReactNode;
+}) {
+  const running = status === "running";
+  return (
+    <Collapsible defaultOpen={running} className="not-prose w-full rounded-md border border-border">
+      <CollapsibleTrigger
+        className={cn(
+          "group flex w-full items-center gap-2 p-3 text-body text-muted-foreground",
+          "transition-colors duration-fast ease-standard hover:text-foreground motion-reduce:transition-none",
+          "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset",
+        )}
+      >
+        <BrainIcon aria-hidden="true" className="size-4 shrink-0" />
+        <span className="flex-1 text-start">{running ? "Working…" : "Thought process"}</span>
+        {count > 0 && (
+          <Badge variant="secondary" className="shrink-0">
+            {count}
+          </Badge>
+        )}
+        <ChevronDownIcon
+          aria-hidden="true"
+          className="size-4 shrink-0 transition-transform group-data-[state=open]:rotate-180 motion-reduce:transition-none"
+        />
+      </CollapsibleTrigger>
+      <CollapsibleContent className="space-y-3 p-3 pt-0">{children}</CollapsibleContent>
+    </Collapsible>
+  );
+}
+
+function defaultRenderPart<T extends GroupablePart>(args: GroupedPartRenderArgs<T>): ReactNode {
+  if (args.isGroup) {
+    return (
+      <DefaultGroup status={args.status} count={args.indices?.length ?? 0}>
+        {args.children}
+      </DefaultGroup>
+    );
+  }
+
+  const part = args.part as GroupablePart;
+  const streaming = args.status === "running";
+
+  // Reasoning → the branded Reasoning disclosure.
+  if (part.type === "reasoning" || part.type.startsWith("reasoning")) {
+    const text = typeof part.text === "string" ? part.text : "";
+    return (
+      <Reasoning isStreaming={streaming} defaultOpen={streaming}>
+        <ReasoningTrigger />
+        <ReasoningContent>{text}</ReasoningContent>
+      </Reasoning>
+    );
+  }
+
+  // Tool call → the branded Tool disclosure (defensive: parts are plain objects).
+  if (part.type.startsWith("tool-") || part.type === "dynamic-tool") {
+    const p = part as Record<string, unknown>;
+    const headerProps = {
+      type: p.type,
+      state: p.state ?? "input-available",
+      toolName: p.type === "dynamic-tool" ? p.toolName : undefined,
+    } as ComponentProps<typeof ToolHeader>;
+    // The output area must reflect an in-flight call, not just a settled one
+    // (loading-states.md / #269): a `tool-*` part in `input-streaming` (or
+    // `input-available`, before output/error land) is "pending", so
+    // `ToolOutput` renders its skeleton instead of nothing.
+    const toolStreaming =
+      statusFromToolState((p.state as ToolPart["state"]) ?? "input-available") === "pending";
+    return (
+      <Tool>
+        <ToolHeader {...headerProps} />
+        <ToolContent>
+          {p.input !== undefined && <ToolInput input={p.input} />}
+          {(toolStreaming || p.output !== undefined || Boolean(p.errorText)) && (
+            <ToolOutput
+              output={p.output}
+              errorText={(p.errorText as string) ?? undefined}
+              isStreaming={toolStreaming}
+            />
+          )}
+        </ToolContent>
+      </Tool>
+    );
+  }
+
+  // Text → plain prose (consumers usually override with a markdown renderer).
+  if (part.type === "text") {
+    const text = typeof part.text === "string" ? part.text : "";
+    return <div className="whitespace-pre-wrap text-body text-foreground">{text}</div>;
+  }
+
+  // Unknown leaf types: nothing by default (supply a render-prop for coverage).
+  return null;
+}
+
+// ─── GroupedParts ─────────────────────────────────────────────────────────────
+
+export interface GroupedPartsProps<T extends GroupablePart> extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  "children"
+> {
+  /** The ordered message parts to render. */
+  parts: readonly T[];
+  /** How to group parts. @default `groupPartByType()` */
+  groupBy?: GroupBy<T>;
+  /** Extract a part's status (drives group rollup + streaming affordances). */
+  getStatus?: GetPartStatus<T>;
+  /** Render-prop switching on `part.type`. Omit to use the default renderers. */
+  children?: GroupedPartRenderer<T>;
+}
+
+/**
+ * Renders `parts`, coalescing adjacent grouped parts into collapsible traces.
+ * The tree only rebuilds when the parts' identity/type/status fingerprint
+ * changes, so streaming token updates don't remount rows.
+ */
+export function GroupedParts<T extends GroupablePart>({
+  parts,
+  groupBy = groupPartByType<T>(),
+  getStatus,
+  children,
+  className,
+  ...props
+}: GroupedPartsProps<T>) {
+  const fingerprint = partsFingerprint(parts, getStatus);
+  const tree = useMemo<GroupedNode<T>[]>(
+    () => buildPartGroups(parts, groupBy, getStatus),
+    // Rebuild only on a structural change; `parts`/`groupBy`/`getStatus` identity
+    // may churn per render, but the fingerprint is the real dependency.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [fingerprint, groupBy, getStatus],
+  );
+
+  const renderPart = children ?? defaultRenderPart<T>;
+  const statusOf = (part: T): GroupStatus => getStatus?.(part) ?? defaultPartStatus(part);
+
+  const renderNode = (node: GroupedNode<T>): ReactNode => {
+    if (node.kind === "leaf") {
+      return (
+        <Fragment key={node.key}>
+          {renderPart({
+            part: node.part,
+            isGroup: false,
+            status: statusOf(node.part),
+            index: node.index,
+          })}
+        </Fragment>
+      );
+    }
+    const kids = node.children.map(renderNode);
+    return (
+      <Fragment key={node.key}>
+        {renderPart({
+          part: node.group,
+          isGroup: true,
+          status: node.group.status,
+          indices: node.group.indices,
+          children: <>{kids}</>,
+        })}
+      </Fragment>
+    );
+  };
+
+  return (
+    <div className={cn("flex w-full flex-col gap-3", className)} {...props}>
+      {tree.map(renderNode)}
+    </div>
+  );
+}

package/src/image.stories.tsx

@@ -0,0 +1,67 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Image } from "./image";
+
+// A tiny 1x1 solid-red PNG — enough to exercise decode + skeleton timing
+// without shipping a real asset in the story.
+const RED_DOT =
+  "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC";
+
+const meta = {
+  title: "AI/Image",
+  component: Image,
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof Image>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// `showSkeleton` (default `Boolean(width && height)` — true here, since both
+// are given) covers the box with a `Skeleton` until the `<img>` finishes
+// decoding, reserving the `width`/`height` box so there is no layout shift
+// (loading-states.md, interaction-guidelines.md 'Images'). Without both
+// dimensions there is no box to reserve, so the skeleton defaults off in that
+// case rather than collapsing to nothing (see the `NoSkeleton` story). The
+// Skeleton window is real-decode-timed (there is no consumer `loading` prop
+// like Gallery's — see image.tsx), so it is too fast/racy to freeze reliably
+// in a real-browser Storybook snapshot; it is instead exercised
+// deterministically in image.test.tsx (jsdom never auto-resolves `<img>`
+// loads, so the pending state holds until the test fires `load` itself).
+export const Default: Story = {
+  args: {
+    base64: RED_DOT,
+    mediaType: "image/png",
+    uint8Array: new Uint8Array(),
+    alt: "A generated red square",
+    width: 128,
+    height: 128,
+  },
+};
+
+// BROKEN — a genuinely undecodable payload settles into the `onError`
+// fallback (an `ImageOff` glyph on a muted box, sized to `width`/`height`)
+// instead of leaving the browser's native broken-image glyph bleeding through
+// a perpetually-pulsing Skeleton.
+export const Broken: Story = {
+  args: {
+    base64: "not-a-real-image",
+    mediaType: "image/png",
+    uint8Array: new Uint8Array(),
+    alt: "A generated image",
+    width: 128,
+    height: 128,
+  },
+};
+
+// Disabling `showSkeleton` opts out for a context that already has its own
+// placeholder (e.g. a Gallery tile).
+export const NoSkeleton: Story = {
+  name: "showSkeleton=false",
+  args: {
+    base64: RED_DOT,
+    mediaType: "image/png",
+    uint8Array: new Uint8Array(),
+    alt: "A generated red square",
+    width: 128,
+    height: 128,
+    showSkeleton: false,
+  },
+};

package/src/image.test.tsx

@@ -0,0 +1,105 @@
+import { describe, expect, it, vi } from "vitest";
+import { fireEvent, render } from "@testing-library/react";
+import { createRef } from "react";
+import { Image, type ImageProps } from "./image";
+
+const RED_DOT =
+  "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAIAAACQd1PeAAAADElEQVR4nGP4z8AAAAMBAQDJ/pLvAAAAAElFTkSuQmCC";
+
+const BASE_PROPS: Pick<ImageProps, "base64" | "mediaType" | "uint8Array"> = {
+  base64: RED_DOT,
+  mediaType: "image/png",
+  uint8Array: new Uint8Array(),
+};
+
+describe("Image", () => {
+  it("renders the img with the base64 data URI, alt, width and height", () => {
+    const { container } = render(
+      <Image {...BASE_PROPS} alt="A red square" width={64} height={64} />,
+    );
+    const img = container.querySelector("img");
+    expect(img).not.toBeNull();
+    expect(img?.getAttribute("src")).toBe(`data:image/png;base64,${RED_DOT}`);
+    expect(img?.getAttribute("alt")).toBe("A red square");
+    expect(img?.getAttribute("width")).toBe("64");
+    expect(img?.getAttribute("height")).toBe("64");
+  });
+
+  it("defaults alt to empty (decorative) rather than omitting it", () => {
+    const { container } = render(<Image {...BASE_PROPS} />);
+    expect(container.querySelector("img")?.getAttribute("alt")).toBe("");
+  });
+
+  it("forwards a ref to the underlying <img>", () => {
+    const ref = createRef<HTMLImageElement>();
+    render(<Image ref={ref} {...BASE_PROPS} />);
+    expect(ref.current).toBeInstanceOf(HTMLImageElement);
+  });
+});
+
+describe("Image showSkeleton (#269, loading-states.md)", () => {
+  it("shows a Skeleton (decorative + a live region) until onLoad fires, when width+height are given", () => {
+    const { container } = render(<Image {...BASE_PROPS} alt="" width={64} height={64} />);
+    const skeleton = container.querySelector(".animate-pulse");
+    expect(skeleton).not.toBeNull();
+    expect(skeleton).toHaveAttribute("aria-hidden", "true");
+    // Exactly one live region for the region.
+    expect(container.querySelectorAll('[role="status"]')).toHaveLength(1);
+
+    const img = container.querySelector("img")!;
+    fireEvent.load(img);
+    expect(container.querySelector(".animate-pulse")).toBeNull();
+  });
+
+  it("defaults to no skeleton (and no live region) when width/height are not given — nothing to reserve", () => {
+    const { container } = render(<Image {...BASE_PROPS} alt="" />);
+    expect(container.querySelector(".animate-pulse")).toBeNull();
+    expect(container.querySelector('[role="status"]')).toBeNull();
+  });
+
+  it("skips the skeleton entirely when showSkeleton is explicitly false, even with width+height", () => {
+    const { container } = render(
+      <Image {...BASE_PROPS} alt="" width={64} height={64} showSkeleton={false} />,
+    );
+    expect(container.querySelector(".animate-pulse")).toBeNull();
+    expect(container.querySelector('[role="status"]')).toBeNull();
+  });
+
+  it("shows the skeleton when explicitly enabled even without width/height", () => {
+    const { container } = render(<Image {...BASE_PROPS} alt="" showSkeleton />);
+    expect(container.querySelector(".animate-pulse")).not.toBeNull();
+  });
+
+  it("does not wrap the <img> in a sizing span when no skeleton is shown, so className keeps resolving against the real parent", () => {
+    const { container } = render(<Image {...BASE_PROPS} alt="" className="w-full" />);
+    expect(container.firstElementChild?.tagName).toBe("IMG");
+  });
+
+  it("calls the consumer's onLoad in addition to clearing the skeleton", () => {
+    const onLoad = vi.fn();
+    const { container } = render(
+      <Image {...BASE_PROPS} alt="" width={64} height={64} onLoad={onLoad} />,
+    );
+    fireEvent.load(container.querySelector("img")!);
+    expect(onLoad).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("Image onError fallback (visual regression: broken image bled through the pulsing Skeleton)", () => {
+  it("replaces the img with an ImageOff fallback box instead of leaving the Skeleton pulsing forever", () => {
+    const { container } = render(<Image {...BASE_PROPS} alt="A generated image" />);
+    fireEvent.error(container.querySelector("img")!);
+    // No native <img> (and its browser broken-image glyph) remains in the DOM.
+    expect(container.querySelector("img")).toBeNull();
+    // No skeleton keeps pulsing behind a failed image.
+    expect(container.querySelector(".animate-pulse")).toBeNull();
+    expect(container.querySelector("svg")).not.toBeNull();
+  });
+
+  it("calls the consumer's onError in addition to showing the fallback", () => {
+    const onError = vi.fn();
+    const { container } = render(<Image {...BASE_PROPS} alt="" onError={onError} />);
+    fireEvent.error(container.querySelector("img")!);
+    expect(onError).toHaveBeenCalledTimes(1);
+  });
+});