@elabs-ai/components-ui 4.1.0 → 5.0.0

package/src/components/state-panel/state-panel.test.tsx

@@ -122,7 +122,7 @@ describe("StatePanel", () => {
     expect(wrapper?.className ?? "").not.toContain("size-10");
   });
 
-  it("illustration path renders the title at the subtitle role, distinct from the icon path's text-sm (#47)", () => {
+  it("illustration path renders the title at the subtitle role, distinct from the icon path's text-body (#47)", () => {
     // A 112px+ illustration needs a heavier title to group with — bumping the
     // title to `text-subtitle` (styling-and-tokens.md's typography-scale
     // roles) only on the illustration path, so the plain `icon` path (a
@@ -132,13 +132,13 @@ describe("StatePanel", () => {
     );
     const titleWithIllustration = withIllustration.querySelector("h3");
     expect(titleWithIllustration?.className ?? "").toContain("text-subtitle");
-    expect(titleWithIllustration?.className ?? "").not.toMatch(/\btext-sm\b/);
+    expect(titleWithIllustration?.className ?? "").not.toMatch(/\btext-body\b/);
 
     const { container: withIcon } = render(
       <StatePanel kind="empty" title="No items" icon={<span data-testid="i" />} />,
     );
     const titleWithIcon = withIcon.querySelector("h3");
-    expect(titleWithIcon?.className ?? "").toMatch(/\btext-sm\b/);
+    expect(titleWithIcon?.className ?? "").toMatch(/\btext-body\b/);
     expect(titleWithIcon?.className ?? "").not.toContain("text-subtitle");
   });
 

package/src/components/state-panel/state-panel.tsx

@@ -1,8 +1,11 @@
+"use client";
+
 import { type CSSProperties, type ReactNode } from "react";
 import { CircleAlert } from "lucide-react";
 import { cva, type VariantProps } from "class-variance-authority";
 import { cn } from "../../lib/cn";
 import { ILLUSTRATION_ACCENT_VAR } from "../../illustrations/illustration-base";
+import { useLocale } from "../locale-provider";
 
 // ─── Variants ────────────────────────────────────────────────────────────────
 
@@ -123,13 +126,15 @@ export function StatePanel({
   icon,
   illustration,
   titleAs: Tag = "h3",
-  loadingLabel = "Loading…",
+  loadingLabel,
   size = "md",
   actions,
   className,
 }: StatePanelProps) {
+  const { t } = useLocale();
   const isLoading = kind === "loading";
   const isError = kind === "error";
+  const resolvedLoadingLabel = loadingLabel ?? t("loading");
 
   // Role: loading → status + live region; error → alert; empty → (none needed).
   const roleProps = isLoading
@@ -139,9 +144,9 @@ export function StatePanel({
       : {};
 
   // Default title / description fallbacks for error state (mirroring old ErrorState).
-  const resolvedTitle = title ?? (isError ? "Something went wrong" : undefined);
+  const resolvedTitle = title ?? (isError ? t("ui.statePanel.errorTitle") : undefined);
   const resolvedDescription =
-    description ?? (isError ? "An unexpected error occurred. Please try again." : undefined);
+    description ?? (isError ? t("ui.statePanel.errorDescription") : undefined);
 
   // Resolve displayed icon.
   let resolvedIcon: ReactNode;
@@ -166,8 +171,8 @@ export function StatePanel({
           KEEPS text-destructive: an icon is a mark, so the fill rung is
           correct there — do not "tidy" it onto -text too. */}
       {isError && (
-        <span className="text-meta font-semibold uppercase tracking-widest text-destructive-text">
-          Error
+        <span className="text-eyebrow uppercase text-destructive-text">
+          {t("ui.statePanel.errorEyebrow")}
         </span>
       )}
 
@@ -223,21 +228,23 @@ export function StatePanel({
             <Tag
               className={cn(
                 "font-semibold text-foreground",
-                illustration ? "text-subtitle" : "text-sm",
+                illustration ? "text-subtitle" : "text-body",
               )}
             >
               {resolvedTitle}
             </Tag>
           )}
           {resolvedDescription && (
-            <p className="mx-auto max-w-sm text-sm text-muted-foreground">{resolvedDescription}</p>
+            <p className="mx-auto max-w-sm text-body text-muted-foreground">
+              {resolvedDescription}
+            </p>
           )}
         </div>
       )}
 
       {/* Loading label (visually shown as supporting text; also the live-region content). */}
-      {isLoading && loadingLabel && (
-        <span className="text-sm text-muted-foreground">{loadingLabel}</span>
+      {isLoading && resolvedLoadingLabel && (
+        <span className="text-body text-muted-foreground">{resolvedLoadingLabel}</span>
       )}
 
       {actions ? <div className="mt-1 flex items-center gap-2">{actions}</div> : null}

package/src/components/status-badge/status-badge.stories.tsx

@@ -1,3 +1,4 @@
+import type { CSSProperties } from "react";
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import { Ban, ShieldAlert } from "lucide-react";
 import { STATUSES, StatusBadge, StatusIcon } from "./status-badge";
@@ -44,6 +45,15 @@ const meta = {
       control: "boolean",
       table: { category: "Appearance" },
     },
+    appearance: {
+      description:
+        "Explicit fill/border/ink treatment override, meaningful only on the colour-bearing " +
+        "statuses (running/complete/awaiting-approval/failed). `solid` is never honoured on " +
+        "a CustomStatus tone — the out-of-vocabulary hatch stays calm-only.",
+      control: { type: "select" },
+      options: [undefined, "tint", "solid", "outline", "neutral"],
+      table: { category: "Appearance" },
+    },
     children: {
       description: "Override the default status label text.",
       control: "text",
@@ -122,6 +132,49 @@ export const CustomVocabulary: Story = {
   ),
 };
 
+/**
+ * The four explicit `appearance` overrides on every colour-bearing status —
+ * each renders a `data-appearance` attribute regardless of the ancestor
+ * `--badge-appearance` token. `pending`/`denied`/`skipped` are already
+ * neutral pills, so `appearance` has no additional effect there.
+ */
+export const Appearances: Story = {
+  render: () => (
+    <div className="flex flex-col gap-3">
+      {(["tint", "solid", "outline", "neutral"] as const).map((appearance) => (
+        <div key={appearance} className="flex flex-wrap items-center gap-2">
+          <span className="w-16 text-caption text-muted-foreground">{appearance}</span>
+          <StatusBadge appearance={appearance} status="running" />
+          <StatusBadge appearance={appearance} status="complete" />
+          <StatusBadge appearance={appearance} status="awaiting-approval" />
+          <StatusBadge appearance={appearance} status="failed" />
+        </div>
+      ))}
+    </div>
+  ),
+};
+
+/**
+ * With no explicit `appearance` prop, an ancestor's `--badge-appearance`
+ * token drives the treatment — including the out-of-vocabulary `tone` hatch,
+ * which never reaches `solid` even here (the calm-only integrity
+ * constraint), so its custom statuses stay on their tint wash.
+ */
+export const TokenDrivenAppearance: Story = {
+  render: () => (
+    <div
+      className="flex flex-wrap gap-2"
+      style={{ "--badge-appearance": "solid" } as CSSProperties}
+    >
+      <StatusBadge status="running" />
+      <StatusBadge status="complete" />
+      <StatusBadge status="awaiting-approval" />
+      <StatusBadge status="failed" />
+      <StatusBadge status={{ label: "Stopped (guardrail)", tone: "warning", icon: ShieldAlert }} />
+    </div>
+  ),
+};
+
 /**
  * The `StatusIcon` atom for tight rows (test results, rail nodes) — the
  * adjacent row text must carry the status name for AT users.

package/src/components/status-badge/status-badge.test.tsx

@@ -65,6 +65,43 @@ describe("StatusBadge", () => {
     expect(icon?.getAttribute("class")).toContain("motion-reduce:animate-none");
   });
 
+  it("renders no data-appearance attribute when appearance is unset", () => {
+    const { container } = render(<StatusBadge status="running" />);
+    expect(container.querySelector('[data-status="running"]')).not.toHaveAttribute(
+      "data-appearance",
+    );
+  });
+
+  it("renders data-appearance when an explicit appearance is passed", () => {
+    const { container } = render(<StatusBadge appearance="outline" status="running" />);
+    expect(container.querySelector('[data-status="running"]')).toHaveAttribute(
+      "data-appearance",
+      "outline",
+    );
+  });
+
+  it("clamps an explicit appearance=solid away on a CustomStatus tone (calm-only hatch)", () => {
+    render(
+      <StatusBadge
+        appearance="solid"
+        status={{ label: "Stopped", tone: "warning", icon: ShieldAlert }}
+      />,
+    );
+    const badge = screen.getByText("Stopped").closest("[data-slot='status-badge']");
+    expect(badge).not.toHaveAttribute("data-appearance");
+  });
+
+  it("honours a non-solid explicit appearance on a CustomStatus tone", () => {
+    render(
+      <StatusBadge
+        appearance="outline"
+        status={{ label: "Stopped", tone: "warning", icon: ShieldAlert }}
+      />,
+    );
+    const badge = screen.getByText("Stopped").closest("[data-slot='status-badge']");
+    expect(badge).toHaveAttribute("data-appearance", "outline");
+  });
+
   it("merges className last and spreads props", () => {
     const { container } = render(
       <StatusBadge className="bg-muted" data-testid="badge" status="pending" />,

package/src/components/status-badge/status-badge.tsx

@@ -47,7 +47,12 @@ import {
   type LucideIcon,
   type LucideProps,
 } from "lucide-react";
-import { badgeVariants } from "../badge/badge";
+import {
+  BADGE_APPEARANCE_RECIPES,
+  BADGE_APPEARANCE_RECIPES_CALM,
+  badgeVariants,
+  type BadgeAppearance,
+} from "../badge/badge";
 import { cn } from "../../lib/cn";
 
 /** The canonical, closed 7-state status enum (research 10 §B.1). */
@@ -220,17 +225,35 @@ export const statusBadgeVariants = cva(
   {
     variants: {
       status: {
-        // calm: neutral fill
+        // calm: neutral fill — structural, not a colour role: `appearance`
+        // has no effect (see badge.tsx's `secondary`/`outline` variants).
         pending: "border-transparent bg-secondary text-secondary-foreground",
         // calm: status alpha-wash (escapes the decoration drawn-not-filled rule)
-        running: "border-info/40 bg-info/10 text-info-text",
-        complete: "border-success/40 bg-success/10 text-success-text",
+        running: cn(
+          "border-info/40 bg-info/10 text-info-text",
+          "[--badge-fill:var(--info)] [--badge-ink:var(--info-text)] [--badge-on:var(--info-foreground)]",
+          BADGE_APPEARANCE_RECIPES,
+        ),
+        complete: cn(
+          "border-success/40 bg-success/10 text-success-text",
+          "[--badge-fill:var(--success)] [--badge-ink:var(--success-text)] [--badge-on:var(--success-foreground)]",
+          BADGE_APPEARANCE_RECIPES,
+        ),
         // ATTENTION: solid fill — must grab the eye
-        "awaiting-approval": "border-transparent bg-warning text-warning-foreground",
-        // calm: de-emphasized neutrals
+        "awaiting-approval": cn(
+          "border-transparent bg-warning text-warning-foreground",
+          "[--badge-fill:var(--warning)] [--badge-ink:var(--warning-text)] [--badge-on:var(--warning-foreground)]",
+          BADGE_APPEARANCE_RECIPES,
+        ),
+        // calm: de-emphasized neutrals — structural, `appearance` has no effect.
         denied: "border-transparent bg-muted text-muted-foreground",
         // ATTENTION: solid fill — must grab the eye
-        failed: "border-transparent bg-destructive text-destructive-foreground",
+        failed: cn(
+          "border-transparent bg-destructive text-destructive-foreground",
+          "[--badge-fill:var(--destructive)] [--badge-ink:var(--destructive-text)] [--badge-on:var(--destructive-foreground)]",
+          BADGE_APPEARANCE_RECIPES,
+        ),
+        // calm: neutral fill — structural, `appearance` has no effect.
         skipped: "border-transparent bg-secondary text-muted-foreground",
       },
       /**
@@ -238,14 +261,36 @@ export const statusBadgeVariants = cva(
        * same alpha-wash/neutral technique as the calm `status` recipes above).
        * There is deliberately no solid/attention recipe here: the loud fill
        * stays exclusive to the canonical `awaiting-approval`/`failed` states
-       * (integrity constraint 2, see the file docblock).
+       * (integrity constraint 2, see the file docblock). For the same reason,
+       * a non-neutral tone only ever wires `BADGE_APPEARANCE_RECIPES_CALM`
+       * (tint/outline/neutral — never solid), so even a theme's global
+       * `--badge-appearance: solid` cannot loudify the hatch; `StatusBadge`
+       * also clamps an explicit `appearance="solid"` prop away below.
        */
       tone: {
+        // Already a neutral pill — `appearance` has no effect (mirrors
+        // Badge's `secondary`).
         neutral: "border-transparent bg-secondary text-secondary-foreground",
-        info: "border-info/40 bg-info/10 text-info-text",
-        success: "border-success/40 bg-success/10 text-success-text",
-        warning: "border-warning/40 bg-warning/10 text-warning-text",
-        destructive: "border-destructive/40 bg-destructive/10 text-destructive-text",
+        info: cn(
+          "border-info/40 bg-info/10 text-info-text",
+          "[--badge-fill:var(--info)] [--badge-ink:var(--info-text)]",
+          BADGE_APPEARANCE_RECIPES_CALM,
+        ),
+        success: cn(
+          "border-success/40 bg-success/10 text-success-text",
+          "[--badge-fill:var(--success)] [--badge-ink:var(--success-text)]",
+          BADGE_APPEARANCE_RECIPES_CALM,
+        ),
+        warning: cn(
+          "border-warning/40 bg-warning/10 text-warning-text",
+          "[--badge-fill:var(--warning)] [--badge-ink:var(--warning-text)]",
+          BADGE_APPEARANCE_RECIPES_CALM,
+        ),
+        destructive: cn(
+          "border-destructive/40 bg-destructive/10 text-destructive-text",
+          "[--badge-fill:var(--destructive)] [--badge-ink:var(--destructive-text)]",
+          BADGE_APPEARANCE_RECIPES_CALM,
+        ),
       },
       /** `md` for inline use; `sm` for rail nodes / dense rows. */
       size: {
@@ -265,20 +310,36 @@ export interface StatusBadgeProps
   status: Status | CustomStatus;
   /** Render label-only (no status icon). */
   hideIcon?: boolean;
+  /**
+   * Explicit per-instance override of the fill/border/ink treatment — see
+   * `Badge`'s own doc. Meaningful only on the colour-bearing statuses
+   * (`running`/`complete`/`awaiting-approval`/`failed`) and tones
+   * (`info`/`success`/`warning`/`destructive`); `pending`/`denied`/`skipped`
+   * and the `neutral` tone are already neutral pills. On a `CustomStatus`
+   * (the out-of-vocabulary hatch), `"solid"` is never honoured — the hatch
+   * is calm-only (integrity constraint 2, file docblock).
+   */
+  appearance?: BadgeAppearance;
 }
 
 export const StatusBadge = forwardRef<HTMLSpanElement, StatusBadgeProps>(function StatusBadge(
-  { status, size, hideIcon = false, className, children, ...props },
+  { status, size, appearance, hideIcon = false, className, children, ...props },
   ref,
 ) {
   if (isCustomStatus(status)) {
     const { label, tone, icon: Icon } = status;
+    // Calm-only hatch: `solid` never reaches a custom tone, even via an
+    // explicit prop (integrity constraint 2) — `statusBadgeVariants`'
+    // `tone` branches also never wire the `solid` recipe, so a theme's
+    // global `--badge-appearance: solid` can't reach it either.
+    const toneAppearance = appearance === "solid" ? undefined : appearance;
     return (
       <span
         ref={ref}
         data-slot="status-badge"
         data-status="custom"
         data-tone={tone}
+        data-appearance={toneAppearance}
         className={cn(statusBadgeVariants({ tone, size }), className)}
         {...props}
       >
@@ -295,6 +356,7 @@ export const StatusBadge = forwardRef<HTMLSpanElement, StatusBadgeProps>(functio
       data-slot="status-badge"
       data-status={status}
       data-tone={STATUS_TONE_MAP[status]}
+      data-appearance={appearance}
       className={cn(statusBadgeVariants({ status, size }), className)}
       {...props}
     >

package/src/components/surface-tour/index.ts

@@ -0,0 +1,11 @@
+export {
+  AffordanceHint,
+  DEFAULT_SURFACE_TOUR_ACTIONS_LABELS,
+  SurfaceTour,
+  SurfaceTourActions,
+  type AffordanceHintProps,
+  type SurfaceTourActionsLabels,
+  type SurfaceTourActionsProps,
+  type SurfaceTourProps,
+  type SurfaceTourTab,
+} from "./surface-tour";

package/src/components/surface-tour/surface-tour.stories.tsx

@@ -0,0 +1,150 @@
+import { lazy, type CSSProperties } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, userEvent, waitFor, within } from "storybook/test";
+import { Skeleton } from "../skeleton";
+import { SurfaceTour, SurfaceTourActions, type SurfaceTourTab } from "./surface-tour";
+
+function Surface({ name }: { name: string }) {
+  return (
+    <div className="flex size-full flex-col gap-3 p-6">
+      <p className="text-title text-foreground">{name}</p>
+      <p className="text-body text-muted-foreground">A full-size surface fills the frame.</p>
+      <button type="button" className="w-fit rounded-md border px-3 py-1 text-body focus-ring">
+        Interact
+      </button>
+    </div>
+  );
+}
+
+// A surface whose code arrives later — stands in for a `next/dynamic` / `React.lazy` chunk.
+const LazyCanvas = lazy(
+  () =>
+    new Promise<{ default: () => React.JSX.Element }>((resolve) =>
+      setTimeout(() => resolve({ default: () => <Surface name="Canvas (lazy)" /> }), 600),
+    ),
+);
+
+const TABS: SurfaceTourTab[] = [
+  {
+    id: "dashboard",
+    label: "Dashboard",
+    useCase: "KPIs, charts and records on one screen.",
+    hint: "Drag a tile",
+    render: () => <Surface name="Dashboard" />,
+    actions: (
+      <SurfaceTourActions
+        storybookHref="?path=/docs/layout-surfacetour--docs"
+        prompt={"Using brand-ui, build a dashboard.\nKPIs, charts and records on one screen."}
+        command="npx -y @elabs-ai/components-cli create my-app --template dashboard"
+      />
+    ),
+  },
+  {
+    id: "canvas",
+    label: "Canvas",
+    useCase: "Nodes and edges on a pannable canvas.",
+    render: () => <LazyCanvas />,
+    fallback: <Skeleton className="size-full min-h-96" />,
+    actions: <SurfaceTourActions prompt={"Using brand-ui, build a node canvas."} />,
+  },
+  {
+    id: "settings",
+    label: "Settings",
+    useCase: "Forms, sections and saved state.",
+    render: () => <Surface name="Settings" />,
+  },
+];
+
+const meta = {
+  title: "Layout/SurfaceTour",
+  component: SurfaceTour,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "A tour of full-size surfaces behind a sticky tab strip: the frame stays put while surfaces crossfade, lazy surfaces show a Skeleton until their code arrives, a one-time corner hint nudges the first interaction, and an actions row sits under the frame. Set `--surface-tour-sticky-top` to your nav height.",
+      },
+    },
+  },
+  args: {
+    tabs: TABS,
+    title: "Seven surfaces, one system",
+    description: "Pick a surface; the frame stays, the content changes.",
+    frameClassName: "h-112",
+  },
+  beforeEach: () => {
+    window.sessionStorage.clear();
+  },
+} satisfies Meta<typeof SurfaceTour>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Three tabs, one lazy: the canvas shows a Skeleton until its code resolves; arrow keys move between tabs. */
+export const Default: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const frame = canvasElement.querySelector<HTMLElement>('[data-slot="surface-tour-frame"]')!;
+    const heightBefore = frame.getBoundingClientRect().height;
+    await userEvent.click(canvas.getByRole("tab", { name: "Canvas" }));
+    await waitFor(() => expect(canvas.getByText("Canvas (lazy)")).toBeInTheDocument(), {
+      timeout: 3000,
+    });
+    expect(frame.getBoundingClientRect().height).toBe(heightBefore);
+    await userEvent.keyboard("{ArrowRight}");
+    await waitFor(() =>
+      expect(canvas.getByRole("tab", { name: "Settings" })).toHaveAttribute(
+        "aria-selected",
+        "true",
+      ),
+    );
+  },
+};
+
+/** The tab strip sticks at `--surface-tour-sticky-top` while the tour scrolls under it. */
+export const StickyTabs: Story = {
+  parameters: { layout: "fullscreen" },
+  decorators: [
+    (Story) => (
+      <div className="p-4" style={{ "--surface-tour-sticky-top": "16px" } as CSSProperties}>
+        <Story />
+        <div className="h-screen" />
+      </div>
+    ),
+  ],
+  args: { frameClassName: "h-screen" },
+  play: async ({ canvasElement }) => {
+    const bar = canvasElement.querySelector<HTMLElement>('[data-slot="surface-tour-tabs"]')!;
+    const win = canvasElement.ownerDocument.defaultView!;
+    win.scrollTo(0, 240);
+    await waitFor(() => expect(Math.round(bar.getBoundingClientRect().top)).toBe(16));
+    win.scrollTo(0, 400);
+    await waitFor(() => expect(Math.round(bar.getBoundingClientRect().top)).toBe(16));
+    win.scrollTo(0, 0);
+  },
+};
+
+/** The corner hint appears after a beat, leaves on the first interaction and stays gone this session. */
+export const AffordanceHintOnce: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const hint = await waitFor(
+      () => {
+        const el = canvasElement.querySelector<HTMLElement>('[data-slot="affordance-hint"]');
+        expect(el).toHaveAttribute("data-visible");
+        return el!;
+      },
+      { timeout: 3000 },
+    );
+    expect(hint).toHaveAttribute("aria-hidden", "true");
+    await userEvent.click(canvas.getByRole("button", { name: "Interact" }));
+    await waitFor(() => expect(hint).not.toHaveAttribute("data-visible"));
+    await userEvent.click(canvas.getByRole("tab", { name: "Settings" }));
+    await userEvent.click(canvas.getByRole("tab", { name: "Dashboard" }));
+    await new Promise((resolve) => setTimeout(resolve, 1200));
+    const again = canvasElement.querySelector('[data-slot="affordance-hint"]');
+    expect(again).not.toHaveAttribute("data-visible");
+  },
+};

package/src/components/surface-tour/surface-tour.test.tsx

@@ -0,0 +1,117 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { act, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import {
+  AffordanceHint,
+  SurfaceTour,
+  SurfaceTourActions,
+  type SurfaceTourTab,
+} from "./surface-tour";
+
+function makeTabs(prefetch = vi.fn()): SurfaceTourTab[] {
+  return [
+    { id: "one", label: "One", useCase: "First surface.", render: () => <p>Surface one</p> },
+    { id: "two", label: "Two", render: () => <p>Surface two</p>, prefetch },
+    { id: "three", label: "Three", render: () => <p>Surface three</p>, hint: "Try me" },
+  ];
+}
+
+describe("SurfaceTour", () => {
+  beforeEach(() => {
+    window.sessionStorage.clear();
+    window.history.replaceState(null, "", "/");
+  });
+
+  it("renders the default tab with data-slots and only mounts the active surface", () => {
+    const { container } = render(<SurfaceTour title="Tour" tabs={makeTabs()} />);
+    expect(container.querySelector('[data-slot="surface-tour"]')).not.toBeNull();
+    expect(container.querySelector('[data-slot="surface-tour-frame"]')).not.toBeNull();
+    expect(screen.getByText("Surface one")).toBeInTheDocument();
+    expect(screen.queryByText("Surface two")).toBeNull();
+    expect(screen.getByText("First surface.")).toBeInTheDocument();
+    expect(screen.getByRole("region", { name: "Tour" })).toBeInTheDocument();
+  });
+
+  it("switches tabs, unmounts the previous surface and writes the hash without a history entry", async () => {
+    const onTabChange = vi.fn();
+    render(<SurfaceTour tabs={makeTabs()} hashKey="tour" onTabChange={onTabChange} />);
+    const before = window.history.length;
+    fireEvent.mouseDown(screen.getByRole("tab", { name: "Two" }), { button: 0, ctrlKey: false });
+    await waitFor(() => expect(screen.getByText("Surface two")).toBeInTheDocument());
+    await waitFor(() => expect(screen.queryByText("Surface one")).toBeNull());
+    expect(onTabChange).toHaveBeenCalledWith("two");
+    expect(window.location.hash).toBe("#tour=two");
+    expect(window.history.length).toBe(before);
+  });
+
+  it("opens the tab named in the hash on mount", async () => {
+    window.history.replaceState(null, "", "/#tour=three");
+    Element.prototype.scrollIntoView = vi.fn();
+    render(<SurfaceTour tabs={makeTabs()} hashKey="tour" />);
+    await waitFor(() => expect(screen.getByText("Surface three")).toBeInTheDocument());
+    expect(screen.getByRole("tab", { name: "Three" })).toHaveAttribute("aria-selected", "true");
+  });
+
+  it("prefetches a tab's code once on hover or focus", () => {
+    const prefetch = vi.fn();
+    render(<SurfaceTour tabs={makeTabs(prefetch)} />);
+    const tab = screen.getByRole("tab", { name: "Two" });
+    fireEvent.pointerEnter(tab);
+    fireEvent.focus(tab);
+    expect(prefetch).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("AffordanceHint", () => {
+  beforeEach(() => window.sessionStorage.clear());
+
+  it("appears after the delay, leaves on the first keydown and never returns this session", () => {
+    vi.useFakeTimers();
+    const view = render(
+      <div data-testid="host">
+        <AffordanceHint storageKey="hint-a">Drag a tile</AffordanceHint>
+      </div>,
+    );
+    const hint = screen.getByText("Drag a tile");
+    expect(hint).toHaveAttribute("aria-hidden", "true");
+    expect(hint).not.toHaveAttribute("data-visible");
+    act(() => vi.advanceTimersByTime(800));
+    expect(hint).toHaveAttribute("data-visible");
+    fireEvent.keyDown(screen.getByTestId("host"), { key: "a" });
+    expect(hint).not.toHaveAttribute("data-visible");
+    view.unmount();
+    render(
+      <div>
+        <AffordanceHint storageKey="hint-a">Again</AffordanceHint>
+      </div>,
+    );
+    act(() => vi.advanceTimersByTime(2000));
+    expect(screen.getByText("Again")).not.toHaveAttribute("data-visible");
+    vi.useRealTimers();
+  });
+});
+
+describe("SurfaceTourActions", () => {
+  it("links to Storybook, copies the multi-line prompt and shows the command", async () => {
+    const writeText = vi.fn(() => Promise.resolve());
+    Object.defineProperty(navigator, "clipboard", {
+      value: { writeText },
+      configurable: true,
+      writable: true,
+    });
+    render(
+      <SurfaceTourActions
+        storybookHref="/storybook/?path=/docs/x--docs"
+        prompt={"line one\nline two"}
+        command="npx create"
+      />,
+    );
+    expect(screen.getByRole("link", { name: "Open in Storybook" })).toHaveAttribute(
+      "href",
+      "/storybook/?path=/docs/x--docs",
+    );
+    expect(screen.getByText("npx create")).toBeInTheDocument();
+    fireEvent.click(screen.getByRole("button", { name: "Copy prompt" }));
+    await waitFor(() => expect(writeText).toHaveBeenCalledWith("line one\nline two"));
+    await waitFor(() => expect(screen.getByText("Prompt copied")).toBeInTheDocument());
+  });
+});