@cueloop/client 0.1.0-alpha.65 → 0.1.0-alpha.66

package/src/components/stories-app.tsx

@@ -1,109 +1,169 @@
 /**
- * The interactive stories catalog (`bun run stories`): a left list of
- * component modules (j/k), h/l cycling through the module's stories, and the
+ * The interactive stories catalog (`bun run stories`): a nested tree of
+ * component modules on the left (j/k to move, h/l to fold or open) and the
  * selected story rendered live in the preview pane. The same story objects
  * back the snapshot harness - what this TUI shows is what the tests assert.
  */
 
-import React, { useMemo, useState } from "react";
-import { createCliRenderer } from "@opentui/core";
+import React, { useEffect, useMemo, useRef, useState } from "react";
+import { createCliRenderer, type ScrollBoxRenderable } from "@opentui/core";
 import { createRoot, useKeyboard } from "@opentui/react";
 import { DARK } from "../theme";
 import { ThemeProvider } from "./theme-context";
-import { loadStories, type LoadedStory } from "./story";
-import { FRAME_BORDER_STYLE } from "./primitives/frame";
+import { buildStoryTree, loadStories, type LoadedStory } from "./story";
+import { AppShell } from "./AppShell";
+import { ShellHeader } from "./ShellHeader";
+import { Tree } from "./primitives/Tree";
+import { NERD } from "./primitives/icons";
+import { allFolderIds, flattenTree } from "./primitives/tree-model";
 
-function StoriesApp({
-  stories,
-  onExit,
-}: {
+interface StoriesAppProps {
   stories: LoadedStory[];
   onExit: () => void;
-}): React.ReactNode {
-  const moduleTitles = useMemo(
-    () => [...new Set(stories.map((story) => story.moduleTitle))],
+}
+
+function StoriesApp({ stories, onExit }: StoriesAppProps): React.ReactNode {
+  const treeNodes = useMemo(() => buildStoryTree(stories), [stories]);
+  const storiesById = useMemo(
+    () => new Map(stories.map((story) => [`${story.moduleTitle}/${story.storyName}`, story])),
     [stories],
   );
-  const [moduleIndex, setModuleIndex] = useState(0);
-  const [storyIndex, setStoryIndex] = useState(0);
-  const moduleTitle = moduleTitles[moduleIndex]!;
-  const moduleStories = stories.filter((story) => story.moduleTitle === moduleTitle);
-  const current = moduleStories[Math.min(storyIndex, moduleStories.length - 1)]!;
+  const firstStoryId = `${stories[0]!.moduleTitle}/${stories[0]!.storyName}`;
+
+  const [expandedIds, setExpandedIds] = useState<ReadonlySet<string>>(() =>
+    allFolderIds(treeNodes),
+  );
+  const [selectedId, setSelectedId] = useState(firstStoryId);
+  const [openedId, setOpenedId] = useState(firstStoryId);
+  const [treeOpen, setTreeOpen] = useState(true);
+
+  const rows = flattenTree(treeNodes, { expandedIds });
+  const selectedRow = rows.find((row) => row.id === selectedId) ?? rows[0];
+  const opened = storiesById.get(openedId);
+  const sidebarScroll = useRef<ScrollBoxRenderable | null>(null);
+
+  // keep the moving selection inside the scrolled viewport
+  useEffect(() => {
+    try {
+      sidebarScroll.current?.scrollChildIntoView(`tree-row-${selectedId}`);
+    } catch {
+      // reveal is best-effort; the selection state is already correct
+    }
+  }, [selectedId]);
+
+  const openStory = (id: string): void => {
+    if (storiesById.has(id)) setOpenedId(id);
+  };
+
+  const toggleFolder = (id: string): void => {
+    setExpandedIds((current) => {
+      const next = new Set(current);
+      if (next.has(id)) next.delete(id);
+      else next.add(id);
+
+      return next;
+    });
+  };
+
+  const expandFolder = (id: string): void => {
+    setExpandedIds((current) => new Set(current).add(id));
+  };
+
+  const collapseFolder = (id: string): void => {
+    setExpandedIds((current) => {
+      const next = new Set(current);
+      next.delete(id);
+
+      return next;
+    });
+  };
+
+  const moveSelection = (delta: number): void => {
+    const index = rows.findIndex((row) => row.id === selectedId);
+    const nextIndex = Math.max(0, Math.min(rows.length - 1, index + delta));
+    const nextRow = rows[nextIndex];
+    if (nextRow !== undefined) setSelectedId(nextRow.id);
+  };
 
   useKeyboard((key) => {
     if (key.name === "q") onExit();
-    else if (key.name === "j" || key.name === "down") {
-      setModuleIndex((index) => Math.min(moduleTitles.length - 1, index + 1));
-      setStoryIndex(0);
-    } else if (key.name === "k" || key.name === "up") {
-      setModuleIndex((index) => Math.max(0, index - 1));
-      setStoryIndex(0);
-    } else if (key.name === "l" || key.name === "right") {
-      setStoryIndex((index) => (index + 1) % moduleStories.length);
+    else if (key.name === "j" || key.name === "down") moveSelection(1);
+    else if (key.name === "k" || key.name === "up") moveSelection(-1);
+    else if (selectedRow === undefined) return;
+    else if (key.name === "l" || key.name === "right") {
+      if (selectedRow.isFolder) expandFolder(selectedRow.id);
+      else openStory(selectedRow.id);
     } else if (key.name === "h" || key.name === "left") {
-      setStoryIndex((index) => (index - 1 + moduleStories.length) % moduleStories.length);
+      if (selectedRow.isFolder) collapseFolder(selectedRow.id);
+    } else if (key.name === "return" || key.name === "space") {
+      if (selectedRow.isFolder) toggleFolder(selectedRow.id);
+      else openStory(selectedRow.id);
     }
   });
 
   return (
     <ThemeProvider theme={DARK}>
-      <box
-        style={{
-          flexDirection: "column",
-          width: "100%",
-          height: "100%",
-          backgroundColor: DARK.background,
-        }}
-      >
-        <box style={{ height: 1, backgroundColor: DARK.panel, paddingLeft: 1 }}>
-          <text fg={DARK.text}>
-            <span fg={DARK.accent}>cueloop stories</span>
-            <span fg={DARK.textDim}>
-              {" "}
-              · {moduleTitle} / {current.storyName}
-            </span>
-          </text>
-        </box>
-        <box style={{ flexDirection: "row", flexGrow: 1 }}>
-          <box
-            style={{
-              width: 28,
-              backgroundColor: DARK.panel,
-              flexDirection: "column",
-              paddingLeft: 1,
-              paddingTop: 1,
-            }}
-          >
-            {moduleTitles.map((title, index) => (
-              <text key={title} fg={index === moduleIndex ? DARK.accent : DARK.textMuted}>
-                {index === moduleIndex ? "▸ " : "  "}
-                {title}
-              </text>
-            ))}
-          </box>
-          <box
-            style={{
-              flexGrow: 1,
-              flexDirection: "column",
-              border: true,
-              borderStyle: FRAME_BORDER_STYLE,
-              borderColor: DARK.border,
-            }}
-            title={` ${current.storyName} (${moduleStories.indexOf(current) + 1}/${moduleStories.length}) `}
-          >
-            {/* remount per story so component-local state never leaks across */}
-            <box
-              key={`${moduleTitle}/${current.storyName}`}
-              style={{ flexGrow: 1, flexDirection: "column" }}
-            >
-              {current.story.render()}
+      <AppShell
+        theme={DARK}
+        mainHeader={
+          <ShellHeader
+            theme={DARK}
+            leftIcons={[{ glyph: NERD.settings }]}
+            leftLabel="cueloop storybook"
+            inspectorOpen={treeOpen}
+            onToggleInspector={treeOpen ? undefined : () => setTreeOpen(true)}
+          />
+        }
+        inspectorHeader={
+          <ShellHeader
+            theme={DARK}
+            inspectorOpen={treeOpen}
+            onToggleInspector={() => setTreeOpen(false)}
+          />
+        }
+        main={
+          opened !== undefined ? (
+            <scrollbox style={{ flexGrow: 1, paddingLeft: 1, paddingTop: 1 }} focused={false}>
+              {/* remount per story so component-local state never leaks across */}
+              <box key={openedId} style={{ flexDirection: "column" }}>
+                {opened.story.render()}
+              </box>
+            </scrollbox>
+          ) : (
+            <box style={{ flexGrow: 1, paddingLeft: 1, paddingTop: 1 }}>
+              <text fg={DARK.textDim}>Select a story</text>
+            </box>
+          )
+        }
+        inspectorWidth={34}
+        inspector={
+          treeOpen ? (
+            <box style={{ flexDirection: "column", flexGrow: 1, paddingTop: 1 }}>
+              <scrollbox ref={sidebarScroll} style={{ flexGrow: 1 }} focused={false}>
+                <Tree
+                  nodes={treeNodes}
+                  expandedIds={expandedIds}
+                  selectedId={selectedId}
+                  theme={DARK}
+                  onSelect={(id) => {
+                    setSelectedId(id);
+                    openStory(id);
+                  }}
+                  onToggle={(id) => {
+                    setSelectedId(id);
+                    toggleFolder(id);
+                  }}
+                />
+              </scrollbox>
             </box>
+          ) : undefined
+        }
+        footer={
+          <box style={{ height: 1, paddingLeft: 1 }}>
+            <text fg={DARK.textDim}>j/k move · h/l fold or open · enter open · q quit</text>
           </box>
-        </box>
-        <box style={{ height: 1, backgroundColor: DARK.panel, paddingLeft: 1 }}>
-          <text fg={DARK.textDim}>j/k component · h/l story · q quit</text>
-        </box>
-      </box>
+        }
+      />
     </ThemeProvider>
   );
 }

package/src/components/story-tree.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, test } from "bun:test";
+import { buildStoryTree, type LoadedStory } from "./story";
+import type { TreeNode } from "./primitives/tree-model";
+
+/** A story object whose render is never invoked in these structural tests. */
+const STUB = { render: () => null };
+
+function story(moduleTitle: string, storyName: string): LoadedStory {
+  return { moduleTitle, storyName, story: STUB };
+}
+
+function childLabels(node: TreeNode): string[] {
+  return (node.children ?? []).map((child) => child.label);
+}
+
+describe("buildStoryTree", () => {
+  test("splits moduleTitle on / into nested folders keyed by their path", () => {
+    // Arrange
+    const stories = [story("Primitives/Tree", "Default"), story("Layout/AppShell", "Default")];
+
+    // Act
+    const tree = buildStoryTree(stories);
+
+    // Assert
+    expect(tree.map((node) => [node.id, node.label])).toEqual([
+      ["Primitives", "Primitives"],
+      ["Layout", "Layout"],
+    ]);
+    expect(tree[0]!.children!.map((node) => node.id)).toEqual(["Primitives/Tree"]);
+  });
+
+  test("groups sibling components under one shared parent folder", () => {
+    // Arrange
+    const stories = [story("Primitives/Tree", "Default"), story("Primitives/Card", "Default")];
+
+    // Act
+    const tree = buildStoryTree(stories);
+
+    // Assert
+    expect(tree).toHaveLength(1);
+    expect(childLabels(tree[0]!)).toEqual(["Tree", "Card"]);
+  });
+
+  test("nests to the full depth of the moduleTitle path", () => {
+    // Arrange
+    const stories = [story("A/B/C", "Only")];
+
+    // Act
+    const tree = buildStoryTree(stories);
+    const a = tree[0]!;
+    const b = a.children![0]!;
+
+    // Assert
+    expect([a.id, b.id]).toEqual(["A", "A/B"]);
+    expect(b.children![0]!.id).toBe("A/B/C");
+  });
+
+  test("adds each story as a leaf keyed `${moduleTitle}/${storyName}` under its component", () => {
+    // Arrange
+    const stories = [story("Primitives/Tree", "Empty"), story("Primitives/Tree", "Deep")];
+
+    // Act
+    const tree = buildStoryTree(stories);
+    const component = tree[0]!.children![0]!;
+
+    // Assert
+    expect(component.id).toBe("Primitives/Tree");
+    expect(component.children!.map((leaf) => [leaf.id, leaf.label])).toEqual([
+      ["Primitives/Tree/Empty", "Empty"],
+      ["Primitives/Tree/Deep", "Deep"],
+    ]);
+  });
+
+  test("hoists a component with a single story of its own name into one leaf row", () => {
+    // Arrange
+    const stories = [story("Primitives/Card", "Card")];
+
+    // Act
+    const tree = buildStoryTree(stories);
+    const hoisted = tree[0]!.children![0]!;
+
+    // Assert
+    expect(hoisted.children).toBeUndefined();
+    expect(hoisted.id).toBe("Primitives/Card/Card");
+    expect(hoisted.label).toBe("Card");
+  });
+
+  test("keeps the folder when its single story differs from the component name", () => {
+    // Arrange
+    const stories = [story("Primitives/Card", "Default")];
+
+    // Act
+    const tree = buildStoryTree(stories);
+    const component = tree[0]!.children![0]!;
+
+    // Assert
+    expect(component.id).toBe("Primitives/Card");
+    expect(component.children!.map((leaf) => leaf.id)).toEqual(["Primitives/Card/Default"]);
+  });
+});

package/src/components/story.ts

@@ -7,6 +7,7 @@
  */
 
 import type React from "react";
+import type { TreeNode } from "./primitives/tree-model";
 
 export interface StoryMeta {
   /** Catalog path, e.g. "primitives/Card". */
@@ -68,6 +69,60 @@ export async function loadStories(): Promise<LoadedStory[]> {
   return loaded;
 }
 
+/** A folder node keeps its children array live so the builder can append to it. */
+interface StoryTreeFolder extends TreeNode {
+  children: TreeNode[];
+}
+
+// A component folder holding one story of its own name reads as one row, not a folder wrapping a single leaf.
+function hoistSingleStoryFolders(nodes: TreeNode[]): TreeNode[] {
+  return nodes.map((node) => {
+    if (node.children === undefined) return node;
+    const children = hoistSingleStoryFolders(node.children);
+    const onlyChild = children.length === 1 ? children[0] : undefined;
+    if (
+      onlyChild !== undefined &&
+      onlyChild.children === undefined &&
+      onlyChild.label === node.label
+    ) {
+      return onlyChild;
+    }
+
+    return { ...node, children };
+  });
+}
+
+/**
+ * Nest the flat catalog into folder/component groups by splitting each
+ * moduleTitle on "/". Each story becomes a leaf keyed `${moduleTitle}/${storyName}`
+ * under its component node; a component holding a single story of its own name
+ * collapses so its row IS that story leaf.
+ */
+export function buildStoryTree(stories: LoadedStory[]): TreeNode[] {
+  const roots: TreeNode[] = [];
+  const foldersByPath = new Map<string, StoryTreeFolder>();
+
+  for (const { moduleTitle, storyName } of stories) {
+    let siblings = roots;
+    let path = "";
+
+    for (const segment of moduleTitle.split("/")) {
+      path = path === "" ? segment : `${path}/${segment}`;
+      let folder = foldersByPath.get(path);
+      if (folder === undefined) {
+        folder = { id: path, label: segment, children: [] };
+        foldersByPath.set(path, folder);
+        siblings.push(folder);
+      }
+      siblings = folder.children;
+    }
+
+    siblings.push({ id: `${moduleTitle}/${storyName}`, label: storyName });
+  }
+
+  return hoistSingleStoryFolders(roots);
+}
+
 /** Component files that must carry stories: every .tsx that is not a story/test/prototype. */
 export function componentFilesMissingStories(): string[] {
   const componentGlob = new Bun.Glob("**/*.tsx");

package/src/components/theme-context.stories.tsx

@@ -4,7 +4,7 @@ import type { Story, StoryMeta } from "./story";
 import { ThemeProvider } from "./theme-context";
 import { Card } from "./primitives/Card";
 
-export const meta: StoryMeta = { title: "theme-context" };
+export const meta: StoryMeta = { title: "Foundations/Theme" };
 
 /** A high-contrast variant to prove tokens flow through the provider. */
 const HIGH_CONTRAST: Theme = { ...DARK, accent: "#00ffff", elevated: "#000000", border: "#ffffff" };

package/src/session-controller.ts

@@ -371,13 +371,17 @@ class Controller implements ReviewController {
           const session = this.snapshot.session;
 
           if (session && event.sessionId === session.id) void this.refreshSession(session.id);
-          if (!this.options.sessionId) void this.refreshInbox();
+          // the Threads sidebar shows the inbox even on a direct open, so keep it fresh
+          void this.refreshInbox();
         });
         await client.subscribe();
+        // load the inbox in both cases so the sidebar can jump between threads
+        const inbox = await client.sessionList({ status: "pending" });
+
         if (this.options.sessionId) {
-          this.update({ session: await client.sessionGet(this.options.sessionId) });
+          this.update({ session: await client.sessionGet(this.options.sessionId), inbox });
         } else {
-          this.update({ inbox: await client.sessionList({ status: "pending" }) });
+          this.update({ inbox });
         }
       } catch (err) {
         this.update({ error: err instanceof Error ? err.message : String(err) });
@@ -406,7 +410,8 @@ class Controller implements ReviewController {
   }
 
   setStatus(message: string): void {
-    this.update({ status: message });
+    // the persistent status bar is gone; transient feedback surfaces as a toast
+    this.update({ status: message, toast: message ? { body: message } : null });
   }
 
   showToast(body: string, title?: string): void {

package/src/theme.ts

@@ -54,8 +54,8 @@ export const DARK: Theme = {
   text: "#e4e6ec",
   textMuted: "#b1b6c4",
   textDim: "#6b7280",
-  accent: "#f5a3a3",
-  accentInk: "#2a1416",
+  accent: "#cba6f7",
+  accentInk: "#17171a",
   green: "#62d96b",
   red: "#f08080",
   blue: "#a9c8f5",
@@ -80,8 +80,8 @@ export const LIGHT: Theme = {
   text: "#1c1d24",
   textMuted: "#4b5162",
   textDim: "#868c9c",
-  accent: "#b5495b",
-  accentInk: "#ffffff",
+  accent: "#5b3ea6",
+  accentInk: "#fbfbfa",
   green: "#2f8a3e",
   red: "#c0392b",
   blue: "#2f6fb0",

package/src/use-settings-dialog.tsx

@@ -191,6 +191,12 @@ export function useSettingsDialog(params: {
         />
       ),
     },
+    {
+      id: "keybinds",
+      name: "Keybinds",
+      description: "keyboard reference",
+      rows: [],
+    },
   ];
   const settingsValues = {
     autoClose: autoClose === "off" ? "off" : `${autoClose}s`,
@@ -219,6 +225,9 @@ export function useSettingsDialog(params: {
   };
 
   const onCategorySelect = (categoryId: string): void => {
+    // the nav tree carries a synthetic Settings group folder; clicking it must
+    // not become the active category, or the key handler dereferences nothing
+    if (!settingsCategories.some((category) => category.id === categoryId)) return;
     setActionsExpandedIndex(null);
     setSettingsNav({ categoryId, rowIndex: 0, zone: "body" });
   };

package/src/App.review-panel.test.tsx

@@ -1,140 +0,0 @@
-/** The review panel end to end: the b key cycles expanded -> compact -> hidden -> expanded on the live App, and the collapse mode persists to the user config so it survives a restart. Rendering details are locked by the ReviewPanel stories; this suite proves the App wiring and the persistence. */
-
-import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdtempSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import React from "react";
-import { testRender } from "@opentui/react/test-utils";
-import { DaemonServer } from "@cueloop/daemon";
-import type { ReviewSession } from "@cueloop/schema";
-import { App } from "./App";
-import { loadConfig } from "./config";
-import { isolateUserConfig, settle, waitForText, waitForTextGone, pressKey } from "./test-support";
-
-const PLAN = "# Plan\n\nShip the thing.\n";
-
-let home: string;
-let server: DaemonServer;
-let session: ReviewSession;
-let configPath: string;
-let restoreUserConfig: () => void;
-
-beforeEach(() => {
-  home = mkdtempSync(join(tmpdir(), "cueloop-panel-"));
-  configPath = join(home, "config.toml");
-  restoreUserConfig = isolateUserConfig(home, "config.toml");
-  server = new DaemonServer({ home, idleExitMs: 0 });
-  server.start();
-  session = server.core.sessionCreate({
-    workspace: { repoRoot: "/repo", branch: "main" },
-    artifact: { type: "plan", content: PLAN, meta: { title: "Plan" } },
-  });
-});
-afterEach(() => {
-  restoreUserConfig();
-  server.stop();
-  rmSync(home, { recursive: true, force: true });
-});
-
-async function renderApp() {
-  const setup = await testRender(<App home={home} sessionId={session.id} />, {
-    width: 120,
-    height: 30,
-  });
-
-  await waitForText(setup, "Review");
-
-  return setup;
-}
-
-describe("review panel", () => {
-  test("ctrl+r cycles expanded -> compact -> hidden -> expanded", async () => {
-    // Arrange
-    const setup = await renderApp();
-    // each mode has its own signature: expanded draws the tab box and the
-    // submit button, compact keeps only the count strip, hidden draws nothing
-    const railSignature = () => {
-      const frame = setup.captureCharFrame();
-
-      return {
-        tabs: frame.includes("Review  Tree  Agent"),
-        submit: frame.includes("Submit review"),
-        strip: /\s0\s*\n/.test(frame) && frame.includes("<"),
-      };
-    };
-
-    // Assert: expanded
-    expect(railSignature()).toEqual({ tabs: true, submit: true, strip: false });
-
-    // Act
-    await pressKey(setup, "r", { ctrl: true });
-
-    // Assert: compact drops the tabs and the button, keeps the strip
-    await waitForTextGone(setup, "Submit review");
-    expect(railSignature()).toEqual({ tabs: false, submit: false, strip: true });
-
-    // Act
-    await pressKey(setup, "r", { ctrl: true });
-    await settle(setup);
-
-    // Assert: hidden draws no rail at all
-    expect(railSignature()).toEqual({ tabs: false, submit: false, strip: false });
-
-    // Act
-    await pressKey(setup, "r", { ctrl: true });
-
-    // Assert
-    await waitForText(setup, "Submit review"); // back to expanded
-  });
-
-  test("the collapse mode persists to the user config", async () => {
-    // Arrange
-    const setup = await renderApp();
-
-    // Act
-    await pressKey(setup, "r", { ctrl: true }); // -> compact
-
-    // Assert
-    expect(loadConfig({ userConfigPath: configPath }).ui.reviewState).toBe("compact");
-  });
-
-  test("option+w widens the rail and persists the new width", async () => {
-    // Arrange
-    const setup = await renderApp();
-    const startWidth = loadConfig({ userConfigPath: configPath }).ui.reviewWidth;
-
-    // Act
-    await pressKey(setup, "w", { meta: true });
-
-    // Assert
-    const widened = loadConfig({ userConfigPath: configPath }).ui.reviewWidth;
-
-    expect(widened).toBeGreaterThan(startWidth);
-  });
-
-  test("submitting from a hidden panel force-opens the rail so the confirm card is reachable", async () => {
-    // Arrange
-    const setup = await renderApp();
-
-    await pressKey(setup, "r", { ctrl: true }); // -> compact
-    await pressKey(setup, "r", { ctrl: true }); // -> hidden
-
-    // Assert
-    await waitForTextGone(setup, "Submit review"); // rail is gone
-    expect(setup.captureCharFrame()).not.toContain("Submit review");
-
-    // Act
-    await pressKey(setup, "RETURN", { meta: true }); // submit while hidden must not trap in an invisible modal
-
-    // Assert
-    await waitForText(setup, "submit review");
-    const frame = setup.captureCharFrame();
-
-    expect(frame).toContain("submit review"); // the confirm card is visible again
-    expect(frame).toContain("[Approve]");
-
-    // the reveal is live-only: the saved panel preference stays as the user left it
-    expect(loadConfig({ userConfigPath: configPath }).ui.reviewState).toBe("hidden");
-  });
-});