@elabs-ai/components-ai 4.1.0 → 5.0.0

package/src/asset-preview.tsx

@@ -30,6 +30,7 @@ import {
   TableHead,
   TableHeader,
   TableRow,
+  useLocale,
 } from "@elabs-ai/components-ui";
 import { cn } from "@elabs-ai/components-ui/lib/cn";
 import type { HTMLAttributes, ReactNode } from "react";
@@ -72,18 +73,87 @@ interface ParsedCsv {
   rows: string[][];
 }
 
-/** Minimal preview-grade CSV split (no quoted-comma handling — it's a glance, not a grid). */
+/**
+ * A small RFC 4180-ish CSV tokenizer: handles quoted fields (commas and
+ * newlines inside quotes don't end the field/row) and the `""` escaped-quote
+ * convention. Single pass over the raw string — no line pre-split, so a
+ * quoted field spanning multiple lines survives intact. Still preview-grade
+ * (unquoted cells are trimmed for the glance table), not a full CSV grammar.
+ */
+function parseCsvRows(content: string): string[][] {
+  const rows: string[][] = [];
+  let row: string[] = [];
+  let field = "";
+  let wasQuoted = false;
+  let inQuotes = false;
+
+  const endField = () => {
+    row.push(wasQuoted ? field : field.trim());
+    field = "";
+    wasQuoted = false;
+  };
+  const endRow = () => {
+    endField();
+    rows.push(row);
+    row = [];
+  };
+
+  for (let i = 0; i < content.length; i++) {
+    const ch = content[i];
+
+    if (inQuotes) {
+      if (ch === '"') {
+        if (content[i + 1] === '"') {
+          field += '"';
+          i += 1;
+        } else {
+          inQuotes = false;
+        }
+      } else {
+        field += ch;
+      }
+      continue;
+    }
+
+    if (ch === '"' && field === "") {
+      inQuotes = true;
+      wasQuoted = true;
+      continue;
+    }
+
+    if (ch === ",") {
+      endField();
+      continue;
+    }
+
+    if (ch === "\r") {
+      continue;
+    }
+
+    if (ch === "\n") {
+      endRow();
+      continue;
+    }
+
+    field += ch;
+  }
+
+  // A trailing field/row with no terminating newline.
+  if (field !== "" || row.length > 0) {
+    endRow();
+  }
+
+  return rows;
+}
+
 function parseCsv(content: string): ParsedCsv {
-  const lines = content
-    .trim()
-    .split(/\r?\n/)
-    .filter((line) => line.length > 0);
-  const [head = "", ...rest] = lines;
-  const split = (line: string) => line.split(",").map((cell) => cell.trim());
-  return { header: split(head), rows: rest.map(split) };
+  const rows = parseCsvRows(content.trim()).filter((r) => !(r.length === 1 && r[0] === ""));
+  const [header = [], ...rest] = rows;
+  return { header, rows: rest };
 }
 
 const CsvPreview = ({ content }: { content: string }) => {
+  const { t } = useLocale();
   const { header, rows } = useMemo(() => parseCsv(content), [content]);
   return (
     <div className="flex flex-col gap-2">
@@ -109,7 +179,7 @@ const CsvPreview = ({ content }: { content: string }) => {
         </TableBody>
       </Table>
       <p className="text-meta text-muted-foreground">
-        {rows.length} {rows.length === 1 ? "row" : "rows"}
+        {t("ai.assetPreview.rowCount", { count: rows.length })}
       </p>
     </div>
   );
@@ -135,6 +205,7 @@ export const AssetPreview = ({
   className,
   ...props
 }: AssetPreviewProps) => {
+  const { t } = useLocale();
   const [mode, setMode] = useState<AssetPreviewMode>(defaultMode);
   const injectedRenderer = useAssetPreviewRenderer();
   const content = asset.content ?? "";
@@ -150,7 +221,7 @@ export const AssetPreview = ({
   if (injected !== null) {
     body = injected;
   } else if (asset.type !== "image" && content.length === 0) {
-    body = <p className="text-body text-muted-foreground">No preview available…</p>;
+    body = <p className="text-body text-muted-foreground">{t("ai.assetPreview.noPreview")}</p>;
   } else if (showRaw) {
     body = <CodeBlock code={content} language={assetLanguage(asset)} wrap />;
   } else {
@@ -197,7 +268,7 @@ export const AssetPreview = ({
               className={cn(!showRaw && "bg-accent text-accent-foreground")}
               onClick={() => setMode("preview")}
             >
-              Preview
+              {t("ai.assetPreview.preview")}
             </Button>
             <Button
               type="button"
@@ -207,7 +278,7 @@ export const AssetPreview = ({
               className={cn(showRaw && "bg-accent text-accent-foreground")}
               onClick={() => setMode("raw")}
             >
-              Raw
+              {t("ai.assetPreview.raw")}
             </Button>
           </ArtifactActions>
         ) : null}

package/src/attachments.tsx

@@ -192,8 +192,8 @@ export const Attachment = ({ data, onRemove, className, children, ...props }: At
           variant === "inline" && [
             "flex h-8 cursor-pointer select-none items-center gap-1.5",
             "rounded-md border border-border px-1.5",
-            "font-medium text-sm transition-colors duration-fast ease-standard motion-reduce:transition-none",
-            "hover:bg-accent hover:text-accent-foreground dark:hover:bg-accent/50",
+            "font-medium text-body transition-colors duration-fast ease-standard motion-reduce:transition-none",
+            "hover:bg-accent/50 hover:text-accent-foreground",
           ],
           variant === "list" && [
             "flex w-full items-center gap-3 rounded-lg border p-3",
@@ -283,7 +283,7 @@ export const AttachmentInfo = ({
     <div className={cn("min-w-0 flex-1", className)} {...props}>
       <span className="block truncate">{label}</span>
       {showMediaType && data.mediaType && (
-        <span className="block truncate text-muted-foreground text-xs">{data.mediaType}</span>
+        <span className="block truncate text-muted-foreground text-meta">{data.mediaType}</span>
       )}
     </div>
   );
@@ -385,7 +385,10 @@ export type AttachmentEmptyProps = HTMLAttributes<HTMLDivElement>;
 
 export const AttachmentEmpty = ({ className, children, ...props }: AttachmentEmptyProps) => (
   <div
-    className={cn("flex items-center justify-center p-4 text-muted-foreground text-sm", className)}
+    className={cn(
+      "flex items-center justify-center p-4 text-muted-foreground text-body",
+      className,
+    )}
     {...props}
   >
     {children ?? "No attachments"}

package/src/chat-shell.test.tsx

@@ -58,8 +58,8 @@ describe("ChatShell — slots", () => {
 
   it("omits the header row entirely when no header is supplied", () => {
     const { container } = render(<ChatShell>t</ChatShell>);
-    // An empty header would still occupy its fixed h-12 row.
-    expect(container.querySelector(".h-12")).toBeNull();
+    // An empty header would still occupy its fixed h-header row.
+    expect(container.querySelector(".h-header")).toBeNull();
   });
 
   it("omits the aside rail entirely when no aside is supplied", () => {
@@ -91,16 +91,46 @@ describe("ChatShell — variants", () => {
     expect(container.querySelector(".border-t")).toBeNull();
   });
 
-  it("makes the bare variant's edge scrims inert (aria-hidden AND pointer-events-none)", () => {
-    const { container } = render(<ChatShell variant="bare">t</ChatShell>);
-    const scrims = container.querySelectorAll("[aria-hidden='true']");
-    expect(scrims).toHaveLength(2);
-    for (const scrim of scrims) expect(scrim).toHaveClass("pointer-events-none");
+  it("makes the edge scrims inert (aria-hidden AND pointer-events-none) in both variants", () => {
+    for (const variant of ["card", "bare"] as const) {
+      const { container, unmount } = render(<ChatShell variant={variant}>t</ChatShell>);
+      const scrims = container.querySelectorAll("[aria-hidden='true']");
+      expect(scrims).toHaveLength(2);
+      for (const scrim of scrims) expect(scrim).toHaveClass("pointer-events-none");
+      unmount();
+    }
   });
+});
 
-  it("renders no scrims in the card variant (there is a real divider instead)", () => {
-    const { container } = render(<ChatShell>t</ChatShell>);
-    expect(container.querySelectorAll("[aria-hidden='true']")).toHaveLength(0);
+describe("ChatShell — floating composer", () => {
+  it("floats the composer over the transcript instead of stacking a footer bar", () => {
+    const { container } = render(
+      <ChatShell composer={<textarea aria-label="Message" />}>
+        <p>transcript</p>
+      </ChatShell>,
+    );
+    const layer = container.querySelector("[data-slot='chat-shell-composer']");
+    expect(layer).toHaveClass("absolute", "bottom-0", "pb-4");
+    // The layer passes pointer events through to the transcript; only the
+    // composer column takes input.
+    expect(layer).toHaveClass("pointer-events-none");
+    expect(screen.getByRole("textbox", { name: "Message" }).parentElement).toHaveClass(
+      "pointer-events-auto",
+      "max-w-(--chat-composer-column)",
+    );
+    expect(container.querySelector(".border-t")).toBeNull();
+  });
+
+  it("publishes the composer height so the transcript can scroll clear of it", () => {
+    const { container, rerender } = render(
+      <ChatShell composer={<textarea aria-label="Message" />}>t</ChatShell>,
+    );
+    const root = container.firstChild as HTMLElement;
+    // jsdom has no layout, so the measured height is 0 — the contract is that
+    // the variable is written at all.
+    expect(root.style.getPropertyValue("--chat-composer-inset")).toBe("0px");
+    rerender(<ChatShell>t</ChatShell>);
+    expect(root.style.getPropertyValue("--chat-composer-inset")).toBe("");
   });
 });
 

package/src/chat-shell.tsx

@@ -1,25 +1,31 @@
 "use client";
 
 import type { ReactNode } from "react";
+import { useLayoutEffect, useRef } from "react";
 import { cn } from "@elabs-ai/components-ui/lib/cn";
 
 export interface ChatShellProps {
   /** Scrollable transcript — typically a <Conversation>. */
   children: ReactNode;
-  /** Sticky composer — typically a <Composer> (the standard chat input). */
+  /**
+   * Floating composer — typically a <Composer> (the standard chat input). It
+   * floats, padded, over the bottom of the transcript, centred at
+   * `--chat-composer-column` (default `--container-3xl`) under a transcript
+   * column of `--chat-column` (default `--container-4xl`, read by
+   * `ConversationContent`); turns scroll up behind it and fade out.
+   */
   composer?: ReactNode;
   /** Optional header row (title, model picker, actions). */
   header?: ReactNode;
   /** Optional right-side context rail (sources, files, memory). */
   aside?: ReactNode;
   /**
-   * Layout treatment:
-   * - `"card"` (default) — a self-contained rounded, bordered chat card. Use
-   *   when the shell sits on a page among other content and needs its own frame.
-   * - `"bare"` — an immersive pane that fills its container with NO frame: the
-   *   transcript fades under the header and above the composer (a token-driven
-   *   top/bottom scrim) and the composer floats on the pane background instead
-   *   of a hard bordered bar. Use when the shell already lives inside a bounded
+   * Frame treatment (the transcript/composer layout is the same in both):
+   * - `"card"` (default) — a self-contained rounded, bordered chat card with a
+   *   divider under the header. Use when the shell sits on a page among other
+   *   content and needs its own frame.
+   * - `"bare"` — an immersive pane that fills its container with NO frame and
+   *   no header divider. Use when the shell already lives inside a bounded
    *   region (an AppShell `SidebarInset`, a full-page workspace) so it doesn't
    *   draw a redundant second frame.
    */
@@ -28,14 +34,15 @@ export interface ChatShellProps {
 }
 
 /**
- * Layout shell for an AI chat built from the AI Elements: a header, a scrollable
- * transcript (give it a <Conversation>, which is `flex-1`), a sticky composer
- * (a <Composer>, the standard chat input), and an optional context rail. Fills
+ * Layout shell for an AI chat built from the AI Elements: a header, a
+ * full-height scrollable transcript (give it a <Conversation>, which is
+ * `flex-1`), a composer floating over the transcript's bottom edge (a
+ * <Composer>, the standard chat input), and an optional context rail. Fills
  * its parent's height.
  *
- * Two layout modes (`variant`): a framed `"card"` for in-page use, and a
- * frameless `"bare"` immersive pane for when the shell already sits inside a
- * bounded region and a second frame would just read as boxy.
+ * Two frames (`variant`): a framed `"card"` for in-page use, and a frameless
+ * `"bare"` immersive pane for when the shell already sits inside a bounded
+ * region and a second frame would just read as boxy.
  */
 export function ChatShell({
   children,
@@ -46,50 +53,89 @@ export function ChatShell({
   className,
 }: ChatShellProps) {
   const bare = variant === "bare";
+  const rootRef = useRef<HTMLDivElement>(null);
+  const composerRef = useRef<HTMLDivElement>(null);
+  const hasComposer = composer != null;
+
+  // The composer floats OVER the transcript, so the transcript has to
+  // know how tall it is — `ConversationContent` pads its bottom by
+  // `--chat-composer-inset` (so the last turn scrolls clear of the composer)
+  // and `ConversationScrollButton` sits just above it. Written straight onto
+  // the root's style: no React state, no re-render per resize.
+  useLayoutEffect(() => {
+    const root = rootRef.current;
+    const node = composerRef.current;
+    if (!root) return;
+    if (!node) {
+      root.style.removeProperty("--chat-composer-inset");
+      return;
+    }
+    const sync = () =>
+      root.style.setProperty("--chat-composer-inset", `${node.getBoundingClientRect().height}px`);
+    sync();
+    if (typeof ResizeObserver === "undefined") return;
+    const observer = new ResizeObserver(sync);
+    observer.observe(node);
+    return () => observer.disconnect();
+  }, [hasComposer]);
+
   return (
     <div
+      ref={rootRef}
+      data-slot="chat-shell"
+      data-variant={variant}
       className={cn(
-        "flex h-full min-h-0 w-full overflow-hidden bg-background",
+        // Reading columns: the transcript (`ConversationContent`) reads a
+        // little wider than the composer beneath it. Override per app, e.g.
+        // `className="[--chat-column:var(--container-5xl)]"`.
+        "flex h-full min-h-0 w-full overflow-hidden bg-background [--chat-column:var(--container-4xl)] [--chat-composer-column:var(--container-3xl)]",
         bare ? null : "rounded-xl border",
         className,
       )}
     >
       <div className="flex min-h-0 min-w-0 flex-1 flex-col">
         {header ? (
-          <div className={cn("flex h-12 shrink-0 items-center px-4", bare ? null : "border-b")}>
+          <div className={cn("flex h-header shrink-0 items-center px-4", bare ? null : "border-b")}>
             {header}
           </div>
         ) : null}
 
-        {bare ? (
-          // Immersive transcript: the scroll area fades at both edges so content
-          // dissolves under the header and above the composer instead of hitting
-          // a hard bordered bar. The overlays are token-driven (`from-background`)
-          // so they fade to the shell's own ground in every theme, and inert
-          // (`pointer-events-none` + `aria-hidden`) so they never block scroll,
-          // steal a tap, or get announced.
-          <div className="relative flex min-h-0 flex-1 flex-col">
-            {children}
-            <div
-              aria-hidden
-              className="pointer-events-none absolute inset-x-0 top-0 z-10 h-8 bg-gradient-to-b from-background to-transparent"
-            />
+        {/* The transcript runs the FULL height of the pane and the composer
+            floats over its bottom edge, so turns scroll up behind the composer
+            and dissolve under the top edge instead of stopping at a hard bar.
+            The scrims are token-driven (`from-background`) so they fade to the
+            shell's own ground in every theme, and inert (`pointer-events-none`
+            + `aria-hidden`) so they never block scroll, steal a tap, or get
+            announced. */}
+        <div className="relative flex min-h-0 flex-1 flex-col">
+          {children}
+          <div
+            aria-hidden
+            className="pointer-events-none absolute inset-x-0 top-0 z-10 h-8 bg-gradient-to-b from-background to-transparent"
+          />
+          <div
+            aria-hidden
+            data-slot="chat-shell-scrim"
+            // Solid under the composer, fading out a little above it.
+            className="pointer-events-none absolute inset-x-0 bottom-0 z-10 bg-gradient-to-t from-background from-50% to-transparent"
+            style={{ height: "calc(var(--chat-composer-inset, 0px) + 3rem)" }}
+          />
+          {composer ? (
+            // The float layer passes pointer events through, so the
+            // transcript's scrollbar and the gutters beside the composer stay
+            // live; only the composer itself takes input. DOM order still puts
+            // it after the transcript (tab order follows reading order).
             <div
-              aria-hidden
-              className="pointer-events-none absolute inset-x-0 bottom-0 z-10 h-12 bg-gradient-to-t from-background to-transparent"
-            />
-          </div>
-        ) : (
-          <div className="flex min-h-0 flex-1 flex-col">{children}</div>
-        )}
-
-        {composer ? (
-          // Bare: the composer floats on the pane ground (transparent, no
-          // divider) above the fade; card: the classic bordered footer.
-          <div className={cn("shrink-0", bare ? "relative z-20 px-4 pb-4" : "border-t p-3")}>
-            {composer}
-          </div>
-        ) : null}
+              ref={composerRef}
+              data-slot="chat-shell-composer"
+              className="pointer-events-none absolute inset-x-0 bottom-0 z-20 px-4 pb-4"
+            >
+              <div className="pointer-events-auto mx-auto w-full max-w-(--chat-composer-column)">
+                {composer}
+              </div>
+            </div>
+          ) : null}
+        </div>
       </div>
       {aside ? <div className="hidden w-80 shrink-0 border-s lg:block">{aside}</div> : null}
     </div>

package/src/chat.stories.tsx

@@ -1,5 +1,6 @@
 import { useState } from "react";
 import type { Meta, StoryObj } from "@storybook/react";
+import { ChatShell } from "./chat-shell";
 import { Conversation, ConversationContent, ConversationScrollButton } from "./conversation";
 import { Message, MessageContent, MessageResponse } from "./message";
 import { Composer } from "./composer";
@@ -45,45 +46,49 @@ function ChatExample() {
   };
 
   return (
-    <div className="mx-auto flex h-[640px] max-w-2xl flex-col overflow-hidden rounded-xl border">
-      <Conversation className="flex-1">
-        <ConversationContent>
-          {messages.map((m) => (
-            <Message from={m.role} key={m.id}>
-              <MessageContent>
-                {m.reasoning ? (
-                  <Reasoning>
-                    <ReasoningTrigger />
-                    <ReasoningContent>{m.reasoning}</ReasoningContent>
-                  </Reasoning>
-                ) : null}
-                <MessageResponse>{m.text}</MessageResponse>
-                {m.role === "assistant" ? (
-                  <Sources>
-                    <SourcesTrigger count={2} />
-                    <SourcesContent>
-                      <Source href="https://example.com" title="Deploy log — wk 23" />
-                      <Source href="https://example.com" title="Billing runbook" />
-                    </SourcesContent>
-                  </Sources>
-                ) : null}
-              </MessageContent>
-            </Message>
-          ))}
-        </ConversationContent>
-        <ConversationScrollButton />
-      </Conversation>
-
-      <Composer
-        className="m-3 mt-0"
-        placeholder="Ask about deploys…"
-        status={status === "submitted" ? "Generating…" : "Awaiting your input"}
-        sendStatus={status}
-        onSubmit={(message) => {
-          const text = message.text?.trim();
-          if (text) send(text);
-        }}
-      />
+    <div className="mx-auto h-[640px] max-w-4xl overflow-hidden rounded-xl border bg-background">
+      <ChatShell
+        variant="bare"
+        composer={
+          <Composer
+            placeholder="Ask about deploys…"
+            status={status === "submitted" ? "Generating…" : "Awaiting your input"}
+            sendStatus={status}
+            onSubmit={(message) => {
+              const text = message.text?.trim();
+              if (text) send(text);
+            }}
+          />
+        }
+      >
+        <Conversation className="flex-1">
+          <ConversationContent>
+            {messages.map((m) => (
+              <Message from={m.role} key={m.id}>
+                <MessageContent>
+                  {m.reasoning ? (
+                    <Reasoning>
+                      <ReasoningTrigger />
+                      <ReasoningContent>{m.reasoning}</ReasoningContent>
+                    </Reasoning>
+                  ) : null}
+                  <MessageResponse>{m.text}</MessageResponse>
+                  {m.role === "assistant" ? (
+                    <Sources>
+                      <SourcesTrigger count={2} />
+                      <SourcesContent>
+                        <Source href="https://example.com" title="Deploy log — wk 23" />
+                        <Source href="https://example.com" title="Billing runbook" />
+                      </SourcesContent>
+                    </Sources>
+                  ) : null}
+                </MessageContent>
+              </Message>
+            ))}
+          </ConversationContent>
+          <ConversationScrollButton />
+        </Conversation>
+      </ChatShell>
     </div>
   );
 }
@@ -100,9 +105,9 @@ const meta = {
           "composed from the @elabs-ai/components-ai grammar: a scrolling " +
           "[Conversation](?path=/story/ai-conversation--default) of " +
           "[Messages](?path=/story/ai-message--presets) with reasoning and sources, plus a " +
-          "[Composer](?path=/story/ai-composer--default). Reach for " +
-          "[ChatShell](?path=/story/ai-chatshell--default) when you want that header + " +
-          "transcript + composer layout as one component instead of assembling it yourself.",
+          "[Composer](?path=/story/ai-composer--default), laid out by " +
+          "[ChatShell](?path=/story/ai-chatshell--default): the transcript scrolls behind the " +
+          "floating composer and both sit in centred reading columns.",
       },
     },
   },

package/src/code-block.test.tsx

@@ -4,7 +4,7 @@ import { fileURLToPath } from "node:url";
 import type { CSSProperties } from "react";
 import { afterEach, describe, expect, it } from "vitest";
 import { render, waitFor } from "@testing-library/react";
-import { CodeBlock } from "./code-block";
+import { CodeBlock, CodeBlockCopyButton, highlightCode } from "./code-block";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -189,3 +189,102 @@ describe("CodeBlock isStreaming (#269, loading-states.md)", () => {
     expect(container.querySelector('[role="status"]')).toBeNull();
   });
 });
+
+describe("CodeBlockCopyButton accessible name (a11y review)", () => {
+  it("has an aria-label so the icon-only button has an accessible name", () => {
+    const { container } = render(
+      <CodeBlock code="const a = 1;" language="tsx">
+        <CodeBlockCopyButton />
+      </CodeBlock>,
+    );
+    expect(container.querySelector("button")).toHaveAccessibleName("Copy");
+  });
+
+  it("lets a consumer override the label", () => {
+    const { container } = render(
+      <CodeBlock code="const a = 1;" language="tsx">
+        <CodeBlockCopyButton aria-label="Copy snippet" />
+      </CodeBlock>,
+    );
+    expect(container.querySelector("button")).toHaveAccessibleName("Copy snippet");
+  });
+});
+
+// ─── `highlightCode` awaited helper for the perf-fix regression locks below ──
+
+function highlightAsync(
+  code: string,
+  language: Parameters<typeof highlightCode>[1],
+  el?: Element | null,
+  skipCache = false,
+): Promise<NonNullable<ReturnType<typeof highlightCode>>> {
+  return new Promise((resolve) => {
+    const cached = highlightCode(code, language, (result) => resolve(result), el, skipCache);
+    if (cached) resolve(cached);
+  });
+}
+
+const flattenTokenContent = (result: NonNullable<ReturnType<typeof highlightCode>>): string =>
+  result.tokens.map((line) => line.map((token) => token.content).join("")).join("\n");
+
+describe("highlightCode cache key — no hash collision (perf review 1.4b/1.4c)", () => {
+  it("does not collide two >200-char strings sharing a length, prefix and suffix but differing in the middle", async () => {
+    const prefix = "a".repeat(150);
+    const suffix = "b".repeat(150);
+    // Same length, same first/last 100 chars — the OLD `length:first100:last100`
+    // cache key collided on exactly this shape (a mid-string edit), showing
+    // whichever of the two resolved second on top of BOTH code blocks.
+    const codeA = `${prefix}1${suffix}`;
+    const codeB = `${prefix}2${suffix}`;
+
+    await highlightAsync(codeA, "tsx");
+    await highlightAsync(codeB, "tsx");
+
+    // Re-requesting codeA must still return a SYNCHRONOUS cache hit for its
+    // OWN content — never codeB's.
+    const againA = highlightCode(codeA, "tsx");
+    expect(againA).not.toBeNull();
+    expect(flattenTokenContent(againA!)).toBe(codeA);
+    expect(flattenTokenContent(againA!)).not.toBe(codeB);
+  });
+});
+
+describe("highlightCode tokensCache is bounded (perf review 1.4a — LRU ~200 entries)", () => {
+  it("evicts the least-recently-used entry once the cache exceeds its cap", async () => {
+    const codes = Array.from({ length: 205 }, (_, i) => `const lruEvictionProbe_${i} = ${i};`);
+
+    for (const code of codes) {
+      // Sequential on purpose: each must actually populate the cache (and
+      // become the most-recently-used entry) before the next one runs.
+
+      await highlightAsync(code, "tsx");
+    }
+
+    // The very first entry inserted is the least-recently-used once 205 > the
+    // 200-entry cap — it must have been evicted, so re-requesting it is a
+    // cache MISS (highlightCode returns null synchronously and kicks off a
+    // fresh async highlight instead).
+    expect(highlightCode(codes[0] as string, "tsx")).toBeNull();
+
+    // The most recently inserted entry is still a synchronous cache hit.
+    expect(highlightCode(codes[204] as string, "tsx")).not.toBeNull();
+  });
+});
+
+describe("highlightCode skipCache (perf review 1.4a — never permanently cache mid-stream)", () => {
+  it("does not persist a highlight into the shared cache when skipCache is set", async () => {
+    const code = "const streamingSkipCacheProbe = 'a';";
+    await highlightAsync(code, "tsx", undefined, true);
+
+    // A later, non-streaming request for the EXACT same code is a cache
+    // MISS — the streaming pass never wrote it in.
+    expect(highlightCode(code, "tsx")).toBeNull();
+  });
+
+  it("still persists an ordinary (non-streaming) highlight", async () => {
+    const code = "const nonStreamingCacheProbe = 'b';";
+    await highlightAsync(code, "tsx");
+
+    expect(highlightCode(code, "tsx")).not.toBeNull();
+  });
+});