feat(ui-preview): add README showcase scenes with PanelHeader inline meta

Add three new UI preview scenes (readme-desktop-hero, readme-desktop-review,
readme-mobile-progress) and extend PanelHeader with metaPlacement prop to
support inline layout. Update tests and CSS accordingly.

Author: pallyoung

packages/web/src/features/agent-panes/components/session-card.test.tsx

@@ -265,6 +265,30 @@ describe("SessionCard", () => {
     expect(screen.getByText("Running")).toHaveClass("badge", "badge-green", "session-state-badge");
   });
 
+  it("renders the session title and badges inside one header row", () => {
+    const { store } = createSessionStore({
+      terminalId: "term-live",
+      state: "idle",
+      endedAt: undefined,
+    });
+
+    const { container } = render(
+      <Provider store={store}>
+        <SessionCard sessionId="sess_123456" />
+      </Provider>
+    );
+
+    const headerRow = container.querySelector(".panel-header__title-row");
+    const inlineMeta = container.querySelector(".panel-header__meta--inline");
+
+    expect(headerRow).not.toBeNull();
+    expect(headerRow).toContainElement(screen.getByText("SESSION-56"));
+    expect(headerRow).toContainElement(screen.getByText("Codex"));
+    expect(headerRow).toContainElement(screen.getByText("Idle"));
+    expect(inlineMeta).not.toBeNull();
+    expect(headerRow).toContainElement(inlineMeta as HTMLElement);
+  });
+
   it("renders a header accessory on the right side of the session header", () => {
     const { store } = createSessionStore({
       terminalId: "term-live",

packages/web/src/features/shared/components/panel-header.test.tsx

@@ -41,4 +41,26 @@ describe("PanelHeader", () => {
     expect(within(status as HTMLElement).getByText("Modified")).toBeInTheDocument();
     expect(screen.queryByRole("button")).not.toBeInTheDocument();
   });
+
+  it("can render meta inline inside the title row when requested", () => {
+    render(
+      <PanelHeader
+        title="SESSION-20"
+        meta={<span>Codex</span>}
+        status={<span>Online</span>}
+        metaPlacement="inline"
+      />
+    );
+
+    const header = document.querySelector(".panel-header");
+    const titleRow = header?.querySelector(".panel-header__title-row");
+    const inlineMeta = header?.querySelector(".panel-header__meta--inline");
+
+    expect(header).toHaveClass("panel-header", "panel-header--inline-meta");
+    expect(titleRow).not.toBeNull();
+    expect(inlineMeta).not.toBeNull();
+    expect(titleRow).toContainElement(screen.getByText("SESSION-20"));
+    expect(titleRow).toContainElement(screen.getByText("Codex"));
+    expect(titleRow).toContainElement(inlineMeta as HTMLElement);
+  });
 });

packages/web/src/styles/components.css

@@ -7198,6 +7198,10 @@ textarea.input {
   min-width: 0;
 }
 
+.panel-header--inline-meta .panel-header__title-row {
+  flex-wrap: nowrap;
+}
+
 .panel-header__title {
   min-width: 0;
   overflow: hidden;
@@ -7223,6 +7227,10 @@ textarea.input {
   min-width: 0;
 }
 
+.panel-header__meta--inline {
+  flex: 0 0 auto;
+}
+
 .panel-header__actions {
   display: inline-flex;
   align-items: center;
@@ -7428,6 +7436,11 @@ textarea.input {
   border-bottom-color: var(--border-focus);
 }
 
+.session-card.session-card--active > .panel-header {
+  background: color-mix(in srgb, var(--bg-active) 88%, var(--bg-page) 12%);
+  border-bottom-color: var(--border-focus);
+}
+
 .session-header-left {
   gap: 8px;
 }
@@ -7438,19 +7451,23 @@ textarea.input {
 }
 
 .session-title-row {
+  display: inline-flex;
+  align-items: center;
   gap: 8px;
   min-width: 0;
+  flex-wrap: nowrap;
 }
 
-.session-title {
+.session-card > .panel-header .panel-header__title {
+  font-family: var(--type-code-inline-family);
   font-size: var(--type-code-inline-size);
   line-height: var(--type-code-inline-line-height);
   font-weight: var(--type-code-inline-weight);
   color: var(--text-secondary);
   letter-spacing: 0.04em;
 }
 
-.session-card.session-card--active .session-title {
+.session-card.session-card--active > .panel-header .panel-header__title {
   color: var(--text-primary);
 }
 
@@ -7476,6 +7493,10 @@ textarea.input {
   white-space: nowrap;
 }
 
+.session-card > .panel-header.panel-header--inline-meta .panel-header__meta {
+  overflow: hidden;
+}
+
 .session-header-actions {
   gap: 4px;
 }
@@ -9262,11 +9283,13 @@ textarea.input {
 
   .mobile-shell__agent-stage .session-header-accessory {
     min-width: 0;
+    max-width: 100%;
   }
 
   .mobile-shell__agent-stage .session-header-right {
+    flex: 0 1 auto;
     min-width: 0;
-    max-width: min(48%, 220px);
+    max-width: 100%;
   }
 
   .mobile-shell__agent-stage .session-title-row {

packages/web/src/styles/components.theme.test.ts

@@ -1,5 +1,6 @@
 // @vitest-environment node
-import { readFileSync } from "node:fs";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 import { build } from "vite";
 import { describe, expect, it } from "vitest";
 
@@ -130,38 +131,51 @@ function getLastRuleBlock(selector: string) {
 }
 
 async function buildRuntimeStylesheet() {
-  const output = await build({
-    configFile: false,
-    root: process.cwd(),
-    plugins: [],
-    build: {
-      write: false,
-      outDir: "dist-test",
-      cssCodeSplit: true,
-      rollupOptions: {
-        input: `${process.cwd()}/src/main.tsx`,
-      },
-    },
-    resolve: {
-      alias: {
-        "@": `${process.cwd()}/src`,
+  const tempDir = mkdtempSync(join(process.cwd(), ".vite-style-build-"));
+  const entryFile = join(tempDir, "runtime-entry.ts");
+
+  writeFileSync(
+    entryFile,
+    [
+      'import buttonStyles from "../src/components/ui/button/index.module.css";',
+      'import tabsStyles from "../src/components/ui/tabs/index.module.css";',
+      "void [buttonStyles.btn, tabsStyles.tab];",
+    ].join("\n"),
+    "utf8"
+  );
+
+  try {
+    const output = await build({
+      configFile: false,
+      root: process.cwd(),
+      plugins: [],
+      build: {
+        write: false,
+        outDir: join(tempDir, "dist"),
+        cssCodeSplit: true,
+        lib: {
+          entry: entryFile,
+          formats: ["es"],
+        },
       },
-    },
-  });
+    });
 
-  const bundle = Array.isArray(output) ? output[0] : output;
-  const chunks = "output" in bundle ? bundle.output : [];
-  const cssAssets = chunks.filter(
-    (chunk): chunk is { type: "asset"; fileName: string; source: string | Uint8Array } =>
-      chunk.type === "asset" && chunk.fileName.endsWith(".css")
-  );
+    const bundle = Array.isArray(output) ? output[0] : output;
+    const chunks = "output" in bundle ? bundle.output : [];
+    const cssAssets = chunks.filter(
+      (chunk): chunk is { type: "asset"; fileName: string; source: string | Uint8Array } =>
+        chunk.type === "asset" && chunk.fileName.endsWith(".css")
+    );
 
-  expect(cssAssets.length, "expected built CSS asset").toBeGreaterThan(0);
-  return cssAssets
-    .map((asset) =>
-      typeof asset.source === "string" ? asset.source : Buffer.from(asset.source).toString("utf8")
-    )
-    .join("\n");
+    expect(cssAssets.length, "expected built CSS asset").toBeGreaterThan(0);
+    return cssAssets
+      .map((asset) =>
+        typeof asset.source === "string" ? asset.source : Buffer.from(asset.source).toString("utf8")
+      )
+      .join("\n");
+  } finally {
+    rmSync(tempDir, { recursive: true, force: true });
+  }
 }
 
 describe("components.css theme-sensitive surfaces", () => {
@@ -447,10 +461,10 @@ describe("components.css theme-sensitive surfaces", () => {
     const sessionCard = getLastRuleBlock(".session-card");
     const activeSessionCard = getLastRuleBlock(".session-card.session-card--active");
     const activeSessionHeader = getLastRuleBlock(
-      ".session-card.session-card--active .session-header"
+      ".session-card.session-card--active > .panel-header"
     );
     const activeSessionTitle = getLastRuleBlock(
-      ".session-card.session-card--active .session-title"
+      ".session-card.session-card--active > .panel-header .panel-header__title"
     );
     const statusBar = getLastRuleBlock(".workspace-status-bar");
     const agentPanes = getLastRuleBlock(".workspace-main-stage > .agent-panes");
@@ -1725,6 +1739,7 @@ describe("components.css theme-sensitive surfaces", () => {
     const progress = getLastRuleBlock(".mobile-shell__agent-stage .session-progress");
     const header = getLastRuleBlock(".mobile-shell__agent-stage > .session-card > .panel-header");
     const titleRow = getLastRuleBlock(".mobile-shell__agent-stage .session-title-row");
+    const headerRight = getLastRuleBlock(".mobile-shell__agent-stage .session-header-right");
     const badges = getLastGroupedRuleBlock(
       /\.mobile-shell__agent-stage \.session-provider-badge,\s*\.mobile-shell__agent-stage \.session-state-badge\s*\{([^}]*)\}/g
     );
@@ -1745,12 +1760,15 @@ describe("components.css theme-sensitive surfaces", () => {
     expect(header).toContain("border-bottom:");
     expect(header).not.toContain("linear-gradient(");
     expect(titleRow).toContain("gap: 6px");
+    expect(headerRight).toContain("max-width: 100%");
+    expect(headerRight).not.toContain("max-width: min(48%, 220px)");
     expect(hasRuleBlock(".mobile-shell__agent-stage .session-header")).toBe(false);
     expect(hasRuleBlock(".mobile-shell__agent-stage .session-header-left")).toBe(false);
     expect(hasRuleBlock(".mobile-shell__agent-stage .session-title")).toBe(false);
     expect(badges).toContain("height: 15px");
     expect(badges).toContain("border-radius: 3px");
     expect(supervisorBadge).toContain("min-height: 26px");
+    expect(supervisorBadge).not.toContain("width: max-content");
     expect(supervisorBadge).toContain("border-radius: 4px");
     expect(supervisorBadge).not.toContain("border-radius: var(--radius-lg)");
     expect(supervisorLabel).toContain("font-size: var(--type-kicker-size)");

packages/web/src/ui-preview/catalog.test.tsx

@@ -122,6 +122,9 @@ describe("UI preview catalog", () => {
     const ids = UI_PREVIEW_SCENES.map((scene) => scene.id);
     expect(ids).toEqual(
       expect.arrayContaining([
+        "readme-desktop-hero",
+        "readme-desktop-review",
+        "readme-mobile-progress",
         "workspace-launch-modal",
         "command-palette",
         "branch-quick-pick",
@@ -308,6 +311,36 @@ describe("UI preview catalog", () => {
     expect(screen.getByText(/\+\s+background: var\(--bg-elevated\);/)).toBeInTheDocument();
   });
 
+  it("renders the README desktop hero scene with a live session and shell terminal", async () => {
+    renderScene("readme-desktop-hero");
+
+    expect(
+      await screen.findByText("Ship the header polish and verify README visuals")
+    ).toBeInTheDocument();
+    expect(screen.getByText("Supervisor")).toBeInTheDocument();
+    expect(screen.getByText("Preview Runner")).toBeInTheDocument();
+    expect(document.querySelector(".workspace-page--desktop .session-card")).toBeTruthy();
+    expect(document.querySelector(".workspace-page--desktop .bottom-terminal")).toBeTruthy();
+  });
+
+  it("renders the README desktop review scene with git and diff context", async () => {
+    renderScene("readme-desktop-review");
+
+    expect(await screen.findByText("README capture polish")).toBeInTheDocument();
+    expect(screen.getByText(/Refine the desktop topbar hierarchy/)).toBeInTheDocument();
+    expect(document.querySelector(".workspace-page--desktop .git-panel")).toBeTruthy();
+    expect(document.querySelector(".workspace-page--desktop .workspace-git-editor")).toBeTruthy();
+  });
+
+  it("renders the README mobile progress scene with session continuity and supervisor state", async () => {
+    renderScene("readme-mobile-progress", "mobile");
+
+    expect(await screen.findByText("Resume mobile progress review")).toBeInTheDocument();
+    expect(screen.getAllByText("Supervisor").length).toBeGreaterThan(0);
+    expect(document.querySelector(".mobile-shell .session-card")).toBeTruthy();
+    expect(document.querySelector(".mobile-shell .workspace-status-bar")).toBeTruthy();
+  });
+
   it("renders the workspace terminal empty review scene", async () => {
     renderScene("workspace-terminal-empty-review");
 

packages/web/src/ui-preview/preview-store.ts

@@ -88,6 +88,7 @@ export interface UiPreviewCommands {
       createdAt: number;
     }>
   >;
+  supervisorBySessionId?: Record<string, Supervisor>;
 }
 
 export interface UiPreviewSeed {
@@ -370,12 +371,20 @@ function createPreviewDispatcher(seed: UiPreviewSeed): DispatchCommand {
       op === "file.delete" ||
       op === "supervisor.create" ||
       op === "supervisor.update" ||
-      op === "supervisor.delete" ||
-      op === "supervisor.get"
+      op === "supervisor.delete"
     ) {
       return ok({} as unknown as T);
     }
 
+    if (op === "supervisor.get") {
+      const sessionId = (args as { sessionId?: string })?.sessionId ?? "";
+      const supervisor =
+        commands.supervisorBySessionId?.[sessionId] ??
+        seed.supervisorBySessionId?.[sessionId] ??
+        null;
+      return ok({ supervisor } as unknown as T);
+    }
+
     return err(`Missing preview handler for ${op}`);
   };
 }

packages/web/src/ui-preview/scene-metadata.test.ts

@@ -20,6 +20,9 @@ describe("ui preview scene metadata", () => {
   it("registers the desktop review scene ids", () => {
     expect(UI_PREVIEW_SCENE_METADATA.map((scene) => scene.id)).toEqual(
       expect.arrayContaining([
+        "readme-desktop-hero",
+        "readme-desktop-review",
+        "readme-mobile-progress",
         "workspace-topbar-review",
         "workspace-sidebar-files-review",
         "workspace-sidebar-git-review",
@@ -62,4 +65,18 @@ describe("ui preview scene metadata", () => {
 
     expect(scene?.capture?.selector).toBe(".settings-mobile-root");
   });
+
+  it("captures the README scenes from their full workspace shells", () => {
+    const heroScene = UI_PREVIEW_SCENE_METADATA.find((entry) => entry.id === "readme-desktop-hero");
+    const reviewScene = UI_PREVIEW_SCENE_METADATA.find(
+      (entry) => entry.id === "readme-desktop-review"
+    );
+    const mobileScene = UI_PREVIEW_SCENE_METADATA.find(
+      (entry) => entry.id === "readme-mobile-progress"
+    );
+
+    expect(heroScene?.capture?.selector).toBe(".workspace-page");
+    expect(reviewScene?.capture?.selector).toBe(".workspace-page");
+    expect(mobileScene?.capture?.selector).toBe("[data-testid='mobile-shell']");
+  });
 });