@cueloop/client 0.1.0-alpha.9 → 0.1.0-alpha.90

package/src/components/stories-app.tsx

@@ -0,0 +1,193 @@
+/**
+ * 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, { 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 { buildStoryTree, loadStories, type LoadedStory } from "./story";
+import { PaneGrid } from "./PaneGrid";
+import { ShellHeader } from "./ShellHeader";
+import { AnsiScreen } from "./AnsiScreen";
+import { Tree } from "./primitives/Tree";
+import { NERD } from "./primitives/icons";
+import { flattenTree } from "./primitives/tree-model";
+
+interface StoriesAppProps {
+  stories: LoadedStory[];
+  onExit: () => void;
+}
+
+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 firstStoryId = `${stories[0]!.moduleTitle}/${stories[0]!.storyName}`;
+
+  const [expandedIds, setExpandedIds] = useState<ReadonlySet<string>>(
+    () => new Set(treeNodes.filter((node) => node.children !== undefined).map((node) => node.id)),
+  );
+  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") 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") {
+      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}>
+      <PaneGrid
+        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.ansi ? (
+                  <AnsiScreen
+                    ansi={opened.story.ansi()}
+                    cols={opened.story.size?.width ?? 80}
+                    rows={opened.story.size?.height ?? 24}
+                  />
+                ) : (
+                  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>
+        }
+      />
+    </ThemeProvider>
+  );
+}
+
+if (import.meta.main) {
+  const stories = await loadStories();
+  const renderer = await createCliRenderer();
+
+  createRoot(renderer).render(
+    <StoriesApp
+      stories={stories}
+      onExit={() => {
+        renderer.destroy();
+        queueMicrotask(() => process.exit(0));
+      }}
+    />,
+  );
+}

package/src/components/stories.test.tsx

@@ -0,0 +1,74 @@
+/**
+ * The catalog IS the regression suite: every exported story renders in
+ * a virtual terminal, its char frame snapshots, and its declared colors must
+ * appear among the styled spans. A component file without a colocated
+ * stories file fails the harness, so the safety net cannot silently thin.
+ */
+
+import React from "react";
+import { describe, expect, test } from "bun:test";
+import { testRender } from "@opentui/react/test-utils";
+import { RGBA } from "@opentui/core";
+import { componentFilesMissingStories, loadStories } from "./story";
+import { AnsiScreen } from "./AnsiScreen";
+import { settle } from "../test-support";
+
+const stories = await loadStories();
+
+/** Hex of a painted color; undefined for unpainted (transparent) spans. */
+function hexOf(color: RGBA | null | undefined): string | undefined {
+  if (!color) return undefined;
+  const [red, green, blue] = color.toInts();
+
+  return "#" + [red, green, blue].map((part) => part!.toString(16).padStart(2, "0")).join("");
+}
+
+describe("stories catalog", () => {
+  test("every component file ships stories", () => {
+    expect(componentFilesMissingStories()).toEqual([]);
+  });
+
+  test("the catalog is not empty", () => {
+    expect(stories.length).toBeGreaterThan(0);
+  });
+
+  for (const { moduleTitle, storyName, story } of stories) {
+    test(`${moduleTitle}/${storyName} renders, snapshots, and carries its colors`, async () => {
+      // Arrange
+      const size = story.size ?? { width: 80, height: 24 };
+      const node = story.ansi ? (
+        <AnsiScreen ansi={story.ansi()} cols={size.width} rows={size.height} />
+      ) : (
+        story.render!()
+      );
+
+      // Act
+      const setup = await testRender(node, size);
+
+      // settle, not just visual-idle: async stories (a file read, a virtualizer's
+      // first measure) commit after React's own scheduler, invisible to idle
+      await settle(setup);
+      const frame = setup.captureCharFrame();
+
+      // Assert
+      expect(frame).toMatchSnapshot(`${moduleTitle}/${storyName}`);
+      if (story.expectedColors?.length) {
+        const seenColors = new Set<string>();
+
+        for (const line of setup.captureSpans().lines) {
+          for (const span of line.spans) {
+            const foregroundHex = hexOf(span.fg);
+            const backgroundHex = hexOf(span.bg);
+
+            if (foregroundHex) seenColors.add(foregroundHex);
+            if (backgroundHex) seenColors.add(backgroundHex);
+          }
+        }
+        for (const expectedColor of story.expectedColors) {
+          expect(seenColors).toContain(expectedColor.toLowerCase());
+        }
+      }
+      setup.renderer.destroy();
+    });
+  }
+});

package/src/components/story-fixtures.ts

@@ -0,0 +1,102 @@
+/** Shared fixture data for the stories catalog: one plan session, one diff. */
+
+import type { Annotation, Thread } from "@cueloop/schema";
+import { buildDisplay, marksByDisplay } from "../view-plan";
+import { diffRows } from "../view-diff";
+
+export const FIXTURE_PLAN = `# Migration Plan
+
+## Context
+
+The daemon persists sessions to disk atomically.
+
+## Steps
+
+- move the store
+- add recovery
+
+\`\`\`ts
+export function persist(session: Session): void {
+  // one JSON document per session
+  writeAtomically(pathFor(session.id), serialize(session));
+}
+\`\`\`
+`;
+
+export const FIXTURE_PATCH = `diff --git a/src/store.ts b/src/store.ts
+index 111..222 100644
+--- a/src/store.ts
++++ b/src/store.ts
+@@ -1,4 +1,4 @@
+ export class Store {
+-  private items = [];
++  private items = new Map();
+ }
+`;
+
+export const FIXTURE_ANNOTATIONS: Annotation[] = [
+  {
+    id: "a_story_1",
+    kind: "comment",
+    anchor: { quote: "persists sessions", prefix: "The daemon ", suffix: " to disk" },
+    body: "Which daemon owns this?",
+    createdAt: "2026-01-01T00:00:00Z",
+  },
+  {
+    id: "a_story_2",
+    kind: "comment",
+    anchor: { quote: "move the store", prefix: "", suffix: "" },
+    body: "move the store behind one interface",
+    createdAt: "2026-01-01T00:00:01Z",
+  },
+];
+
+export function fixturePlanSession(overrides: Partial<Thread> = {}): Thread {
+  return {
+    schemaVersion: "1",
+    id: "s_story_plan",
+    workspace: { repoRoot: "/repo", branch: "main" },
+    artifact: {
+      type: "plan",
+      content: FIXTURE_PLAN,
+      meta: { title: "Migration Plan", agent: "agent/worker-3" },
+    },
+    revisions: [{ revision: 1, content: FIXTURE_PLAN, submittedAt: "2026-01-01T00:00:00Z" }],
+    annotations: FIXTURE_ANNOTATIONS,
+    message: null,
+    status: "pending",
+    createdAt: "2026-01-01T00:00:00Z",
+    ...overrides,
+  };
+}
+
+export function fixtureDiffSession(overrides: Partial<Thread> = {}): Thread {
+  return {
+    schemaVersion: "1",
+    id: "s_story_diff",
+    workspace: { repoRoot: "/repo", branch: "main" },
+    artifact: {
+      type: "diff",
+      content: FIXTURE_PATCH,
+      meta: { title: "working tree", agent: "agent/worker-3" },
+    },
+    revisions: [{ revision: 1, content: FIXTURE_PATCH, submittedAt: "2026-01-01T00:00:00Z" }],
+    annotations: [],
+    message: null,
+    status: "pending",
+    createdAt: "2026-01-01T00:00:00Z",
+    ...overrides,
+  };
+}
+
+export function fixtureDisplay() {
+  return buildDisplay(FIXTURE_PLAN);
+}
+
+export function fixtureMarks() {
+  return marksByDisplay(FIXTURE_ANNOTATIONS, fixtureDisplay());
+}
+
+export function fixtureDiffRows() {
+  return diffRows(FIXTURE_PATCH);
+}

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

@@ -0,0 +1,108 @@
+import { describe, expect, test } from "bun:test";
+import { buildStoryTree, type LoadedStory, type StorySection } 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, section: StorySection = "App"): LoadedStory {
+  return { section, moduleTitle, storyName, story: STUB };
+}
+
+function childLabels(node: TreeNode): string[] {
+  return (node.children ?? []).map((child) => child.label);
+}
+
+describe("buildStoryTree", () => {
+  test("groups the top level by section", () => {
+    const tree = buildStoryTree([
+      story("Primitives/Tree", "Default"),
+      story("Collaborator Join", "JoinSplash", "SSH"),
+    ]);
+
+    expect(tree.map((node) => [node.id, node.label])).toEqual([
+      ["App", "App"],
+      ["SSH", "SSH"],
+    ]);
+  });
+
+  test("splits moduleTitle on / into nested folders under the section", () => {
+    // Arrange
+    const stories = [story("Primitives/Tree", "Default"), story("Layout/AppShell", "Default")];
+
+    // Act
+    const app = buildStoryTree(stories)[0]!;
+
+    // Assert
+    expect(app.children!.map((node) => [node.id, node.label])).toEqual([
+      ["App/Primitives", "Primitives"],
+      ["App/Layout", "Layout"],
+    ]);
+    expect(app.children![0]!.children!.map((node) => node.id)).toEqual(["App/Primitives/Tree"]);
+  });
+
+  test("groups sibling components under one shared parent folder", () => {
+    // Arrange
+    const stories = [story("Primitives/Tree", "Default"), story("Primitives/Card", "Default")];
+
+    // Act
+    const app = buildStoryTree(stories)[0]!;
+
+    // Assert
+    expect(app.children).toHaveLength(1);
+    expect(childLabels(app.children![0]!)).toEqual(["Tree", "Card"]);
+  });
+
+  test("nests to the full depth of the moduleTitle path", () => {
+    // Arrange
+    const stories = [story("A/B/C", "Only")];
+
+    // Act
+    const a = buildStoryTree(stories)[0]!.children![0]!;
+    const b = a.children![0]!;
+
+    // Assert
+    expect([a.id, b.id]).toEqual(["App/A", "App/A/B"]);
+    expect(b.children![0]!.id).toBe("App/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 component = buildStoryTree(stories)[0]!.children![0]!.children![0]!;
+
+    // Assert
+    expect(component.id).toBe("App/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 hoisted = buildStoryTree(stories)[0]!.children![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 component = buildStoryTree(stories)[0]!.children![0]!.children![0]!;
+
+    // Assert
+    expect(component.id).toBe("App/Primitives/Card");
+    expect(component.children!.map((leaf) => leaf.id)).toEqual(["Primitives/Card/Default"]);
+  });
+});

package/src/components/story.ts

@@ -0,0 +1,159 @@
+/**
+ * The story contract. Every component file in components/ ships a
+ * colocated *.stories.tsx that exports `meta` plus named Story objects.
+ * The catalog IS the regression suite: stories.test.tsx walks every story,
+ * snapshots its char frame, and asserts declared colors against the styled
+ * spans; the `bun run stories` TUI renders the same objects interactively.
+ */
+
+import type React from "react";
+import type { TreeNode } from "./primitives/tree-model";
+
+export interface StoryMeta {
+  /** Catalog path, e.g. "primitives/Card". */
+  title: string;
+}
+
+export interface Story {
+  render?: () => React.ReactNode;
+  /** Raw ANSI to paint through AnsiScreen instead of a React tree; exactly one of render or ansi is set. */
+  ansi?: () => string;
+  /**
+   * Colors (hex tokens) that must appear among the rendered frame's styled
+   * spans - the color regression net for color-bearing stories.
+   */
+  expectedColors?: string[];
+  /** Virtual terminal size; defaults to 80x24. */
+  size?: { width: number; height: number };
+}
+
+export type StorySection = "App" | "SSH";
+
+export interface LoadedStory {
+  section: StorySection;
+  moduleTitle: string;
+  storyName: string;
+  story: Story;
+}
+
+export function isStory(value: unknown): value is Story {
+  if (typeof value !== "object" || value === null) return false;
+
+  return (
+    ("render" in value && typeof value.render === "function") ||
+    ("ansi" in value && typeof value.ansi === "function")
+  );
+}
+
+function isStoryMeta(value: unknown): value is StoryMeta {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "title" in value &&
+    typeof value.title === "string"
+  );
+}
+
+const GATEWAY_SRC_DIR = `${import.meta.dir}/../../../gateway/src`;
+
+async function collectStories(
+  dir: string,
+  pattern: string,
+  section: StorySection,
+  loaded: LoadedStory[],
+): Promise<void> {
+  const glob = new Bun.Glob(pattern);
+  const files = [...glob.scanSync({ cwd: dir })].sort();
+
+  for (const file of files) {
+    const moduleExports = await import(`${dir}/${file}`);
+    const meta = moduleExports["meta"];
+    const moduleTitle = isStoryMeta(meta) ? meta.title : file.replace(/\.stories\.tsx?$/, "");
+
+    for (const [exportName, exported] of Object.entries(moduleExports)) {
+      if (exportName === "meta" || !isStory(exported)) continue;
+      loaded.push({ section, moduleTitle, storyName: exportName, story: exported });
+    }
+  }
+}
+
+export async function loadStories(): Promise<LoadedStory[]> {
+  const loaded: LoadedStory[] = [];
+
+  await collectStories(import.meta.dir, "**/*.stories.tsx", "App", loaded);
+  await collectStories(GATEWAY_SRC_DIR, "**/*.stories.ts", "SSH", loaded);
+
+  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 { section, moduleTitle, storyName } of stories) {
+    let siblings = roots;
+    let path = "";
+
+    for (const segment of [section, ...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");
+  const files = [...componentGlob.scanSync({ cwd: import.meta.dir })];
+  const missing: string[] = [];
+
+  for (const file of files) {
+    if (file.endsWith(".stories.tsx") || file.endsWith(".test.tsx")) continue;
+    if (file.endsWith(".prototype.tsx")) continue;
+    if (file === "stories-app.tsx") continue;
+    const storiesSibling = file.replace(/\.tsx$/, ".stories.tsx");
+
+    if (!files.includes(storiesSibling)) missing.push(file);
+  }
+
+  return missing;
+}