@cueloop/client 0.1.0-alpha.10 → 0.1.0-alpha.100

package/src/prototype/prototype-browser.ts

@@ -0,0 +1,321 @@
+/// <reference lib="dom" />
+/**
+ * Headless-Chromium backing for prototype review: render an HTML file to a PNG
+ * and resolve a click coordinate to a DOM element. puppeteer-core is imported
+ * lazily so plan/diff review and the test suite never load it.
+ */
+
+export interface PrototypeElement {
+  selector: string;
+  quote: string;
+  box: ElementBox;
+}
+
+export interface ElementBox {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface PrototypeViewport {
+  width: number;
+  height: number;
+}
+
+export interface PrototypeRenderer {
+  readonly viewport: PrototypeViewport;
+  screenshot(): Promise<Uint8Array>;
+  elementAt(cssX: number, cssY: number): Promise<PrototypeElement | null>;
+  scrollBy(deltaY: number): Promise<boolean>;
+  close(): Promise<void>;
+}
+
+export interface LaunchOptions {
+  filePath: string;
+  viewport: PrototypeViewport;
+  deviceScaleFactor?: number;
+  executablePath?: string;
+  colorScheme?: "dark" | "light";
+}
+
+/** Cell click -> CSS pixel inside the letterboxed image, or null when outside it. */
+export function imageCellToCss(
+  event: { x: number; y: number },
+  image: { x: number; y: number; width: number; height: number },
+  viewport: PrototypeViewport,
+): { x: number; y: number } | null {
+  const columnInImage = event.x - image.x;
+  const rowInImage = event.y - image.y;
+
+  if (
+    columnInImage < 0 ||
+    rowInImage < 0 ||
+    columnInImage >= image.width ||
+    rowInImage >= image.height
+  ) {
+    return null;
+  }
+
+  return {
+    x: ((columnInImage + 0.5) / image.width) * viewport.width,
+    y: ((rowInImage + 0.5) / image.height) * viewport.height,
+  };
+}
+
+/** CSS pixel rect -> the image cell it maps to, for anchoring overlays. */
+export function cssBoxToCell(
+  box: ElementBox,
+  image: { x: number; y: number; width: number; height: number },
+  viewport: PrototypeViewport,
+) {
+  const scaleColumn = image.width / viewport.width;
+  const scaleRow = image.height / viewport.height;
+
+  return {
+    column: image.x + Math.floor(box.x * scaleColumn),
+    row: image.y + Math.floor(box.y * scaleRow),
+    columns: Math.max(1, Math.round(box.width * scaleColumn)),
+    rows: Math.max(1, Math.round(box.height * scaleRow)),
+  };
+}
+
+export type PrototypeRendererFactory = (options: LaunchOptions) => Promise<PrototypeRenderer>;
+
+let rendererFactory: PrototypeRendererFactory | null = null;
+
+/** Override the renderer factory so tests can inject a browserless fake. */
+export function setPrototypeRendererFactory(factory: PrototypeRendererFactory | null): void {
+  rendererFactory = factory;
+}
+
+/** The active factory - the injected fake in tests, else real headless Chromium. */
+export function prototypeRendererFactory(): PrototypeRendererFactory {
+  return rendererFactory ?? launchPrototypeRenderer;
+}
+
+type PuppeteerBrowser = Awaited<ReturnType<typeof import("puppeteer-core").default.launch>>;
+
+// One Chromium per process, kept warm and reused across prototype opens: the
+// launch is the dominant load cost, so each open only spawns a fresh page.
+let sharedBrowser: Promise<PuppeteerBrowser> | null = null;
+
+/** Install only the browser lifecycle used by unit tests, without launching Chrome. */
+export function setPrototypeBrowserForTest(browser: Pick<PuppeteerBrowser, "close"> | null): void {
+  // SAFETY: tests call only closePrototypeBrowser before resetting this seam, so close is the sole
+  // browser member the shared slot can read while the double is installed.
+  sharedBrowser = browser ? Promise.resolve(browser as PuppeteerBrowser) : null;
+}
+
+async function warmBrowser(executablePath: string | undefined): Promise<PuppeteerBrowser> {
+  // reuse the warm browser only while it is still connected; a crashed or
+  // disconnected Chromium is dropped so the next open relaunches instead of
+  // calling newPage on a dead process forever
+  const cached = sharedBrowser ? await sharedBrowser.catch(() => null) : null;
+
+  if (cached && cached.connected) return cached;
+  const puppeteer = (await import("puppeteer-core")).default;
+  const launched = puppeteer.launch({
+    executablePath: executablePath ?? chromeExecutable(),
+    headless: true,
+    args: ["--no-sandbox", "--hide-scrollbars", "--force-color-profile=srgb"],
+  });
+
+  sharedBrowser = launched;
+  const browser = await launched.catch((error) => {
+    if (sharedBrowser === launched) sharedBrowser = null;
+    throw error;
+  });
+
+  browser.once("disconnected", () => {
+    if (sharedBrowser === launched) sharedBrowser = null;
+  });
+
+  return browser;
+}
+
+/**
+ * Close the warm Chromium so it never orphans when cueloop exits. Called from
+ * the shutdown path (the normal quit is not a signal, so puppeteer's own signal
+ * handlers do not fire). Idempotent.
+ */
+export async function closePrototypeBrowser(): Promise<void> {
+  const pending = sharedBrowser;
+
+  sharedBrowser = null;
+  if (!pending) return;
+  const browser = await pending.catch(() => null);
+
+  await browser?.close().catch(() => undefined);
+}
+
+export async function launchPrototypeRenderer(options: LaunchOptions): Promise<PrototypeRenderer> {
+  const { pathToFileURL } = await import("node:url");
+  const browser = await warmBrowser(options.executablePath);
+  // close only the page on teardown, never the shared browser, so the next open
+  // reuses the warm Chromium
+  const page = await browser.newPage();
+
+  try {
+    await page.setViewport({
+      width: options.viewport.width,
+      height: options.viewport.height,
+      deviceScaleFactor: options.deviceScaleFactor ?? 2,
+    });
+    // match the terminal's scheme so a theme-aware mockup renders its dark or
+    // light variant to sit correctly on the surface it emerges into
+    await page.emulateMediaFeatures([
+      { name: "prefers-color-scheme", value: options.colorScheme ?? "light" },
+    ]);
+    // `load` waits for images and styles but skips networkidle0's fixed 500ms
+    // idle window, which a static local file would otherwise always pay
+    await page.goto(pathToFileURL(options.filePath).href, { waitUntil: "load" });
+    // Render the mockup on the terminal's own surface rather than on an opaque
+    // page: strip the root background so it never paints a square box, and the
+    // capture (taken with alpha, below) lets the active terminal theme show
+    // through around the mockup's own components - the prototype emerges into
+    // whatever theme is running instead of sitting in a grey card.
+    await page.evaluate(() => {
+      for (const element of [document.documentElement, document.body]) {
+        element?.style.setProperty("background", "transparent", "important");
+      }
+    });
+  } catch (error) {
+    await page.close().catch(() => undefined);
+    throw error;
+  }
+
+  return {
+    viewport: options.viewport,
+    async screenshot() {
+      // omitBackground keeps the alpha from the stripped page background, so the
+      // terminal composites the mockup over its own theme surface.
+      const buffer = await page.screenshot({
+        type: "png",
+        encoding: "binary",
+        omitBackground: true,
+      });
+
+      return new Uint8Array(buffer);
+    },
+    async elementAt(cssX, cssY) {
+      return page.evaluate(elementAtScript, cssX, cssY);
+    },
+    async scrollBy(deltaY) {
+      return page.evaluate(scrollByScript, deltaY);
+    },
+    async close() {
+      await page.close().catch(() => undefined);
+    },
+  };
+}
+
+/** Serialized into the page (self-contained for puppeteer): resolve the click to a component element. */
+function elementAtScript(x: number, y: number) {
+  const SEMANTIC = new Set([
+    "SECTION",
+    "ARTICLE",
+    "LI",
+    "NAV",
+    "HEADER",
+    "FOOTER",
+    "ASIDE",
+    "FORM",
+  ]);
+  const isNamed = (element: Element): boolean =>
+    element.classList.length > 0 || SEMANTIC.has(element.tagName);
+  // a card wraps several children: climb to the nearest named container holding
+  // more than one child, else the nearest named ancestor, else the clicked leaf
+  const componentRoot = (start: Element): Element => {
+    let namedFallback: Element | null = null;
+    let current: Element | null = start;
+
+    while (current && current !== document.body) {
+      if (isNamed(current)) {
+        if (current.childElementCount > 1) return current;
+        namedFallback = namedFallback ?? current;
+      }
+      current = current.parentElement;
+    }
+
+    return namedFallback ?? start;
+  };
+  const selectorFor = (start: Element): string => {
+    const parts: string[] = [];
+    let current: Element | null = start;
+
+    while (current && current.nodeType === 1 && current !== document.documentElement) {
+      let part = current.tagName.toLowerCase();
+
+      if (current.id) {
+        parts.unshift(part + "#" + CSS.escape(current.id));
+        break;
+      }
+      const parent: Element | null = current.parentElement;
+
+      if (parent) {
+        const currentTagName = current.tagName;
+        const twins = [...parent.children].filter((child) => child.tagName === currentTagName);
+
+        if (twins.length > 1) part += ":nth-of-type(" + (twins.indexOf(current) + 1) + ")";
+      }
+      parts.unshift(part);
+      current = current.parentElement;
+    }
+
+    return parts.join(" > ");
+  };
+  // Prefer the nearest focusable target before falling back to its component container.
+  const focusableTarget = (start: Element | null): Element | null => {
+    for (
+      let element: Element | null = start;
+      element && element !== document.body;
+      element = element.parentElement
+    ) {
+      if (element instanceof HTMLElement && element.tabIndex >= 0) {
+        return element;
+      }
+    }
+
+    return null;
+  };
+  const hit = document.elementFromPoint(x, y);
+
+  if (!(hit instanceof Element)) return null;
+  const node = focusableTarget(hit) ?? componentRoot(hit);
+  const selector = selectorFor(node);
+
+  if (!selector) return null;
+  const text = (node.textContent || "").replace(/\s+/g, " ").trim();
+  const tag = node.tagName.toLowerCase();
+  const quote = text
+    ? text.slice(0, 80)
+    : node.id
+      ? tag + "#" + node.id
+      : node.classList.length
+        ? tag + "." + node.classList[0]
+        : tag;
+  const rect = node.getBoundingClientRect();
+
+  return { selector, quote, box: { x: rect.x, y: rect.y, width: rect.width, height: rect.height } };
+}
+
+function scrollByScript(deltaY: number): boolean {
+  const before = window.scrollY;
+
+  window.scrollBy(0, deltaY);
+
+  return window.scrollY !== before;
+}
+
+/** Standard Chrome install locations by platform; puppeteer-core ships no browser. */
+function chromeExecutable(): string {
+  if (process.platform === "darwin") {
+    return "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome";
+  }
+  if (process.platform === "win32") {
+    return "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe";
+  }
+
+  return "/usr/bin/google-chrome";
+}

package/src/prototype/prototype-pixels.tsx

@@ -0,0 +1,35 @@
+/**
+ * Lazy boundary for the opt-in kitty pixel prototype. The pixel path pulls in the
+ * kitty image writer, the headless-browser renderer, and (on first paint) puppeteer;
+ * none of that belongs in the runtime unless the `[experimental] prototype_pixels`
+ * flag is on. Importing only the TYPE here is erased at build time, so the real
+ * module - and its dependencies - loads only when this component actually mounts,
+ * which App does exclusively for a pixel prototype. This lives outside components/
+ * on purpose: it is an app boundary, not a visual component the story catalog covers.
+ */
+
+import React, { useEffect, useState } from "react";
+import type { PrototypeContentViewProps } from "./components/PrototypeContentView";
+
+type PixelPrototypeView =
+  (typeof import("./components/PrototypeContentView"))["PrototypeContentView"];
+
+export function PrototypePixels(props: PrototypeContentViewProps): React.ReactNode {
+  const [View, setView] = useState<PixelPrototypeView | null>(null);
+
+  useEffect(() => {
+    let alive = true;
+
+    void import("./components/PrototypeContentView").then((module) => {
+      if (alive) setView(() => module.PrototypeContentView);
+    });
+
+    return () => {
+      alive = false;
+    };
+  }, []);
+
+  if (!View) return null;
+
+  return <View {...props} />;
+}

package/src/settings/components/SettingsDialog.stories.tsx

@@ -0,0 +1,117 @@
+import React from "react";
+import { DARK } from "../../appearance/theme";
+import { THEME_PRESETS } from "../../appearance/theme-presets";
+import type { Story, StoryMeta } from "../../stories/story";
+import { SettingsDialog, type SettingsCategory } from "./SettingsDialog";
+
+export const meta: StoryMeta = { title: "Overlays/SettingsDialog" };
+
+const CATEGORIES: SettingsCategory[] = [
+  {
+    id: "general",
+    name: "General",
+    rows: [
+      { key: "displayName", label: "Display name", kind: "text" },
+      {
+        key: "autoClose",
+        label: "Auto-close on submit",
+        kind: "cycle",
+        options: ["off", "3s", "on"],
+      },
+    ],
+  },
+  {
+    id: "display",
+    name: "Display",
+    rows: [
+      {
+        key: "planWidth",
+        label: "Plan width",
+        kind: "cycle",
+        options: ["default", "wide", "full"],
+      },
+      { key: "showLineNumbers", label: "Line numbers", kind: "toggle" },
+    ],
+  },
+  {
+    id: "appearance",
+    name: "Appearance",
+    rows: [
+      {
+        key: "theme",
+        label: "Theme",
+        kind: "cycle",
+        options: ["cueloop", "Rosé Pine Moon", "Nord"],
+      },
+    ],
+  },
+];
+
+const VALUES = {
+  displayName: "amber-heron",
+  autoClose: "3s",
+  planWidth: "default",
+  showLineNumbers: true,
+  theme: "Rosé Pine Moon",
+};
+
+export const NavZone: Story = {
+  render: () => (
+    <SettingsDialog
+      isOpen
+      version="0.1.0-alpha.32"
+      keybindsSections={[]}
+      categories={CATEGORIES}
+      values={VALUES}
+      activeCategoryId="general"
+      activeRowIndex={0}
+      activeZone="nav"
+      onCategorySelect={() => {}}
+      onRowActivate={() => {}}
+      onClose={() => {}}
+    />
+  ),
+  expectedColors: [DARK.accent],
+  size: { width: 100, height: 30 },
+};
+
+export const BodyZone: Story = {
+  render: () => (
+    <SettingsDialog
+      isOpen
+      version="0.1.0-alpha.32"
+      keybindsSections={[]}
+      categories={CATEGORIES}
+      values={VALUES}
+      activeCategoryId="display"
+      activeRowIndex={1}
+      activeZone="body"
+      onCategorySelect={() => {}}
+      onRowActivate={() => {}}
+      onClose={() => {}}
+    />
+  ),
+  expectedColors: [DARK.green],
+  size: { width: 100, height: 30 },
+};
+
+export const AppearanceThemed: Story = {
+  render: () => (
+    <SettingsDialog
+      isOpen
+      version="0.1.0-alpha.32"
+      keybindsSections={[]}
+      categories={CATEGORIES}
+      values={VALUES}
+      activeCategoryId="appearance"
+      activeRowIndex={0}
+      activeZone="body"
+      onCategorySelect={() => {}}
+      onRowActivate={() => {}}
+      onClose={() => {}}
+      theme={THEME_PRESETS["rose-pine-moon"]}
+    />
+  ),
+  expectedColors: [THEME_PRESETS["rose-pine-moon"].accent],
+  size: { width: 100, height: 30 },
+};

package/src/settings/components/SettingsDialog.tsx

@@ -0,0 +1,183 @@
+/**
+ * The settings overlay: a centered Dialog whose left nav lists the categories as
+ * first-level leaves (General, Appearance, Actions, Keybinds), and whose right
+ * body shows the active category's typed rows or the keybinds cheatsheet. The
+ * component is controlled: the caller owns the open flag, the active
+ * category/row/zone, and value changes, so the app's keyboard grammar (and the
+ * stories catalog) drive it without a second key handler inside.
+ */
+
+import { ScrollArea } from "../../ui/components/ScrollArea";
+import React from "react";
+import { useTerminalDimensions } from "@opentui/react";
+import type { Theme } from "../../appearance/theme";
+import type { CheatsheetSection } from "../../keyboard/key-bindings";
+import { useComponentTheme } from "../../appearance/components/theme-context";
+import { Dialog } from "../../ui/components/primitives/Dialog";
+import { Tree } from "../../ui/components/primitives/Tree";
+import type { TreeNode } from "../../ui/components/primitives/tree-model";
+import { CycleRow, TextRow, ToggleRow, type SettingsRowDescriptor } from "./SettingsRows";
+
+export interface SettingsCategory {
+  id: string;
+  name: string;
+  rows: SettingsRowDescriptor[];
+  customBody?: React.ReactNode;
+}
+
+export type SettingsValues = Record<string, string | boolean>;
+
+/** The category id whose right pane shows the keybinds cheatsheet rather than rows. */
+const KEYBINDS_CATEGORY_ID = "keybinds";
+
+export interface SettingsDialogProps {
+  isOpen: boolean;
+  version: string;
+  categories: SettingsCategory[];
+  values: SettingsValues;
+  keybindsSections: CheatsheetSection[];
+  activeCategoryId: string;
+  activeRowIndex: number;
+  activeZone: "nav" | "body";
+  onCategorySelect: (categoryId: string) => void;
+  onRowActivate: (row: SettingsRowDescriptor) => void;
+  onClose: () => void;
+  theme?: Theme;
+}
+
+function navTree(categories: SettingsCategory[]): TreeNode[] {
+  return categories.map((category) => ({ id: category.id, label: category.name }));
+}
+
+function KeybindsBody({
+  sections,
+  tokens,
+}: {
+  sections: CheatsheetSection[];
+  tokens: Theme;
+}): React.ReactNode {
+  return (
+    <ScrollArea>
+      {sections.map((section) => (
+        <box key={section.title} style={{ flexDirection: "column" }}>
+          <text fg={tokens.accent}>{section.title}</text>
+          {section.entries.map((entry, index) => (
+            <text key={`${section.title}-${index}`}>
+              <span fg={tokens.text}>{entry.keys.padEnd(12)}</span>
+              <span fg={tokens.textMuted}>{entry.label}</span>
+            </text>
+          ))}
+          <text> </text>
+        </box>
+      ))}
+    </ScrollArea>
+  );
+}
+
+export function SettingsDialog({
+  isOpen,
+  version,
+  categories,
+  values,
+  keybindsSections,
+  activeCategoryId,
+  activeRowIndex,
+  activeZone,
+  onCategorySelect,
+  onRowActivate,
+  onClose,
+  theme,
+}: SettingsDialogProps): React.ReactNode {
+  const tokens = useComponentTheme(theme);
+  const { width: terminalWidth, height: terminalHeight } = useTerminalDimensions();
+
+  if (!isOpen) return null;
+  const category =
+    categories.find((candidate) => candidate.id === activeCategoryId) ?? categories[0];
+
+  if (!category) return null;
+  const onKeybinds = category.id === KEYBINDS_CATEGORY_ID;
+
+  return (
+    <Dialog
+      isOpen
+      title=" Settings "
+      width={Math.min(76, terminalWidth - 6)}
+      height={Math.min(22, terminalHeight - 4)}
+      background={tokens.elevated}
+      onDismiss={onClose}
+      theme={theme}
+    >
+      <box style={{ flexDirection: "row", flexGrow: 1 }}>
+        <box style={{ flexDirection: "column", width: 20, paddingLeft: 1, paddingRight: 1 }}>
+          <Tree
+            nodes={navTree(categories)}
+            expandedIds={new Set<string>()}
+            selectedId={category.id}
+            hideIcons
+            selectedBackground={tokens.border}
+            onSelect={onCategorySelect}
+            onToggle={onCategorySelect}
+            theme={theme}
+          />
+        </box>
+        <box style={{ borderStyle: "single", border: ["left"], borderColor: tokens.border }} />
+        <box style={{ flexDirection: "column", flexGrow: 1, paddingLeft: 2, paddingRight: 1 }}>
+          {onKeybinds ? <KeybindsBody sections={keybindsSections} tokens={tokens} /> : null}
+          {onKeybinds ? null : category.customBody}
+          {onKeybinds
+            ? null
+            : category.rows.map((row, rowIndex) => {
+                const isActive = activeZone === "body" && rowIndex === activeRowIndex;
+                const value = values[row.key];
+
+                if (row.kind === "toggle") {
+                  return (
+                    <ToggleRow
+                      key={row.key}
+                      label={row.label}
+                      value={value === true}
+                      isActive={isActive}
+                      onPress={() => onRowActivate(row)}
+                      theme={theme}
+                    />
+                  );
+                }
+                if (row.kind === "cycle") {
+                  return (
+                    <CycleRow
+                      key={row.key}
+                      label={row.label}
+                      value={String(value ?? "")}
+                      isActive={isActive}
+                      onPress={() => onRowActivate(row)}
+                      theme={theme}
+                    />
+                  );
+                }
+
+                return (
+                  <TextRow
+                    key={row.key}
+                    label={row.label}
+                    value={String(value ?? "")}
+                    isActive={isActive}
+                    onPress={() => onRowActivate(row)}
+                    theme={theme}
+                  />
+                );
+              })}
+        </box>
+      </box>
+      <box style={{ flexDirection: "row", height: 1, paddingLeft: 1, paddingRight: 1 }}>
+        <text fg={tokens.textDim}>
+          {activeZone === "nav"
+            ? "j/k nav · l/tab open · esc close"
+            : "j/k row · l/space change · h back · esc close"}
+        </text>
+        <box style={{ flexGrow: 1 }} />
+        <text fg={tokens.textDim}>{`cueloop v${version}`}</text>
+      </box>
+    </Dialog>
+  );
+}

package/src/settings/components/SettingsRows.stories.tsx

@@ -0,0 +1,18 @@
+import React from "react";
+import { DARK } from "../../appearance/theme";
+import type { Story, StoryMeta } from "../../stories/story";
+import { CycleRow, TextRow, ToggleRow } from "./SettingsRows";
+
+export const meta: StoryMeta = { title: "Chrome/SettingsRows" };
+
+export const AllKinds: Story = {
+  render: () => (
+    <box style={{ flexDirection: "column", width: 50 }}>
+      <ToggleRow label="Line numbers" value={true} isActive={false} onPress={() => {}} />
+      <ToggleRow label="Hide whitespace" value={false} isActive={true} onPress={() => {}} />
+      <CycleRow label="Palette" value="dark" isActive={false} onPress={() => {}} />
+      <TextRow label="Vault path" value="~/vaults/notes" isActive={false} onPress={() => {}} />
+    </box>
+  ),
+  expectedColors: [DARK.green, DARK.accent, DARK.border],
+};