savepoint 1.0.3 → 1.0.6

package/agent-skills/ink-tui-design/references/ink-gotchas.md

@@ -1,330 +0,0 @@
-# Ink.js Gotchas & Common Problems
-
-## Table of Contents
-
-1. [Icon / Emoji Width Problems](#1-icon--emoji-width-problems)
-2. [Ctrl+C Handling](#2-ctrlc-handling)
-3. [useInput Conflicts](#3-useinput-conflicts)
-4. [Enter Double-Fire](#4-enter-double-fire)
-5. [CJK / Multi-Width Cursor](#5-cjk--multi-width-cursor)
-6. [Layout Breaks](#6-layout-breaks)
-7. [console.log Interference](#7-consolelog-interference)
-8. [Ink Color Type Errors](#8-ink-color-type-errors)
-
----
-
-## 1. Icon / Emoji Width Problems
-
-### Problem
-
-`string-width` v8+ changed how Variation Selectors (VS15/VS16) are handled,
-causing emoji width calculations to be off. Terminals may render an emoji as
-2 cells wide, but `stringWidth()` sometimes returns 1.
-
-### Solution: WIDTH_OVERRIDES Pattern
-
-```typescript
-import stringWidth from "string-width";
-
-const iconWidthOverrides: Record<string, number> = {
-  "⚡": 1,
-  "✨": 1,
-  "🐛": 1,
-  "🔥": 1,
-  "🚀": 1,
-  "📌": 1,
-  "🟢": 1,
-  "🟠": 1,
-  "👉": 1,
-  "💾": 1,
-  "📤": 1,
-  "🔃": 1,
-  "✅": 1,
-  "⚠️": 1,
-  "🔗": 1,
-  "💻": 1,
-  "☁️": 1,
-};
-
-const getIconWidth = (icon: string): number => {
-  const baseWidth = stringWidth(icon);
-  const override = iconWidthOverrides[icon];
-  return override !== undefined ? Math.max(baseWidth, override) : baseWidth;
-};
-
-// Fixed-width column padding
-const COLUMN_WIDTH = 2;
-const padIcon = (icon: string): string => {
-  const width = getIconWidth(icon);
-  const padding = Math.max(0, COLUMN_WIDTH - width);
-  return icon + " ".repeat(padding);
-};
-```
-
-### Affected Areas
-
-- Status icon columns in board view
-- Progress indicators
-- Any fixed-width layout with inline symbols
-
----
-
-## 2. Ctrl+C Handling
-
-### Problem
-
-Ink handles `Ctrl+C` by default to exit the app. This can fire twice or
-conflict with custom cleanup logic.
-
-### Solution: `exitOnCtrlC: false` + `useInput` + SIGINT
-
-```typescript
-import { render, useApp, useInput } from "ink";
-import process from "node:process";
-
-function App({ onExit }: { onExit: () => void }) {
-  const { exit } = useApp();
-
-  useInput((input, key) => {
-    if (key.ctrl && input === "c") {
-      onExit();
-      exit();
-    }
-  });
-
-  // Also handle SIGINT directly
-  useEffect(() => {
-    const handler = () => {
-      onExit();
-      exit();
-    };
-    process.on("SIGINT", handler);
-    return () => process.off("SIGINT", handler);
-  }, [exit, onExit]);
-
-  return <Box>...</Box>;
-}
-
-// Disable Ink's default Ctrl+C handler
-render(<App onExit={cleanup} />, { exitOnCtrlC: false });
-```
-
----
-
-## 3. useInput Conflicts
-
-### Problem
-
-When multiple `useInput` hooks exist, **all handlers fire** for every keypress.
-A parent and child component may both process the same key.
-
-### Solutions
-
-**Pattern 1: `disabled` prop**
-
-```typescript
-useInput((input, key) => {
-  if (disabled) return; // Ignore input when inactive
-  // Handle key...
-});
-```
-
-**Pattern 2: Mode flag**
-
-```typescript
-const [filterMode, setFilterMode] = useState(false);
-
-useInput((input, key) => {
-  if (filterMode) return; // Global shortcuts disabled while filtering
-  if (input === "c") onCleanupCommand?.();
-});
-```
-
-**Pattern 3: `blockKeys` prop on Input component**
-
-```typescript
-// Inside an Input component
-useInput((input) => {
-  if (blockKeys && blockKeys.includes(input)) {
-    return; // Consume the key; do not propagate to parent
-  }
-});
-
-// Usage
-<Input blockKeys={["c", "r", "f"]} ... />
-```
-
----
-
-## 4. Enter Double-Fire
-
-### Problem
-
-After selecting an item in a Select component, the Enter key event propagates
-to the next screen and triggers an unwanted action there.
-
-### Solution: Ready-state buffering
-
-```typescript
-const [ready, setReady] = useState(false);
-
-useEffect(() => {
-  // Defer input handling until after the first render cycle
-  const timer = setTimeout(() => setReady(true), 50);
-  return () => clearTimeout(timer);
-}, []);
-
-useInput((input, key) => {
-  if (!ready) return; // Drop events during initialization
-  if (key.return) {
-    onSelect(selectedItem);
-  }
-});
-```
-
----
-
-## 5. CJK / Multi-Width Cursor
-
-### Problem
-
-CJK characters and some symbols display as 2 cells wide but count as 1
-character. Calculating cursor position by character count causes drift during
-CJK input.
-
-### Solution: Display-width based position calculation
-
-```typescript
-function getCharWidth(char: string): number {
-  const code = char.codePointAt(0);
-  if (!code) return 1;
-
-  // CJK, Hangul, emoji ranges render as 2 cells wide
-  if (
-    (code >= 0x1100 && code <= 0x115f) || // Hangul Jamo
-    (code >= 0x2e80 && code <= 0x9fff) || // CJK
-    (code >= 0xac00 && code <= 0xd7af) || // Hangul Syllables
-    (code >= 0xf900 && code <= 0xfaff) || // CJK Compatibility
-    (code >= 0xfe10 && code <= 0xfe1f) || // Vertical forms
-    (code >= 0x1f300 && code <= 0x1f9ff) // Emojis
-  ) {
-    return 2;
-  }
-  return 1;
-}
-
-function getDisplayWidth(str: string): number {
-  return [...str].reduce((width, char) => width + getCharWidth(char), 0);
-}
-
-function toDisplayColumn(text: string, charPosition: number): number {
-  return getDisplayWidth(text.slice(0, charPosition));
-}
-```
-
----
-
-## 6. Layout Breaks
-
-### Problem
-
-- Long lines wrap past terminal width
-- Timestamps or labels get pushed to the next line
-- Column positions drift
-
-### Solutions
-
-**Safe margin**
-
-```typescript
-const { stdout } = useStdout();
-const columns = Math.max(20, (stdout?.columns ?? 80) - 1); // 1-cell margin
-
-// Or use 90% width (Gemini CLI pattern)
-const safeColumns = Math.floor(columns * 0.9);
-```
-
-**Fixed-width columns**
-
-```typescript
-const COLUMN_WIDTH = 2;
-const padToWidth = (content: string, width: number): string => {
-  const actualWidth = stringWidth(content);
-  const padding = Math.max(0, width - actualWidth);
-  return content + " ".repeat(padding);
-};
-```
-
-**Truncate to width**
-
-```typescript
-function truncateToWidth(text: string, maxWidth: number): string {
-  let width = 0;
-  let result = "";
-  for (const char of text) {
-    const charWidth = getCharWidth(char);
-    if (width + charWidth > maxWidth) {
-      return result + "…";
-    }
-    width += charWidth;
-    result += char;
-  }
-  return result;
-}
-```
-
----
-
-## 7. console.log Interference
-
-### Problem
-
-`console.log` output competes with Ink's rendering. Ink redraws the screen
-periodically, so log lines get overwritten or corrupt the UI.
-
-### Solutions
-
-**Structured logs to stderr**
-
-```typescript
-import pino from "pino";
-
-const logger = pino({
-  transport: {
-    target: "pino-pretty",
-    options: { destination: 2 }, // stderr
-  },
-});
-```
-
-**Conditional debug logging**
-
-```typescript
-if (process.env.DEBUG) {
-  console.error("Debug:", data); // stderr, not stdout
-}
-```
-
----
-
-## 8. Ink Color Type Errors
-
-### Problem
-
-Using `<Text color="cyan">` in TypeScript can trigger strict type errors
-because Ink's color types are narrow.
-
-### Solutions
-
-```typescript
-// Use a const assertion
-<Text color={"cyan" as const}>...</Text>
-
-// Or define as a variable
-const selectedColor = "cyan" as const;
-<Text color={selectedColor}>...</Text>
-
-// Or use chalk inside the Text node
-import chalk from "chalk";
-<Text>{chalk.cyan("Selected")}</Text>
-```

package/agent-skills/ink-tui-design/references/testing-patterns.md

@@ -1,384 +0,0 @@
-# Testing Patterns & Best Practices
-
-## Table of Contents
-
-1. [Test Environment Setup](#test-environment-setup)
-2. [Component Tests](#component-tests)
-3. [Mock Patterns](#mock-patterns)
-4. [Integration Tests](#integration-tests)
-5. [Edge Cases](#edge-cases)
-6. [Performance Tests](#performance-tests)
-7. [Test Utilities](#test-utilities)
-
----
-
-## Test Environment Setup
-
-### Vitest + happy-dom
-
-```typescript
-/**
- * @vitest-environment happy-dom
- */
-import { describe, it, expect, beforeEach, vi } from "vitest";
-import { render } from "@testing-library/react";
-import { Window } from "happy-dom";
-
-describe("Component", () => {
-  beforeEach(() => {
-    const window = new Window();
-    // @ts-expect-error - happy-dom type mismatch
-    globalThis.window = window;
-    // @ts-expect-error - happy-dom type mismatch
-    globalThis.document = window.document;
-  });
-});
-```
-
-### ink-testing-library
-
-```typescript
-import { render } from "ink-testing-library";
-
-describe("Select", () => {
-  it("should render items", () => {
-    const items = [
-      { label: "Item 1", value: "1" },
-      { label: "Item 2", value: "2" },
-    ];
-
-    const { lastFrame } = render(
-      <Select items={items} onSelect={vi.fn()} />,
-    );
-
-    expect(lastFrame()).toContain("Item 1");
-    expect(lastFrame()).toContain("Item 2");
-  });
-});
-```
-
----
-
-## Component Tests
-
-### Basic Pattern
-
-```typescript
-import { render } from "ink-testing-library";
-import { describe, it, expect, vi } from "vitest";
-
-describe("Header", () => {
-  it("should render title", () => {
-    const { lastFrame } = render(<Header title="Test" />);
-    expect(lastFrame()).toContain("Test");
-  });
-
-  it("should render version when provided", () => {
-    const { lastFrame } = render(
-      <Header title="Test" version="1.0.0" />,
-    );
-    expect(lastFrame()).toContain("1.0.0");
-  });
-});
-```
-
-### Key Input Tests
-
-```typescript
-import { render } from "ink-testing-library";
-
-describe("Select", () => {
-  it("should move selection down on j key", async () => {
-    const items = [
-      { label: "Item 1", value: "1" },
-      { label: "Item 2", value: "2" },
-    ];
-
-    const { stdin, lastFrame } = render(
-      <Select items={items} onSelect={vi.fn()} />,
-    );
-
-    // Initial state
-    expect(lastFrame()).toContain("› Item 1");
-
-    // Press j to move down
-    stdin.write("j");
-
-    // Selection moved
-    expect(lastFrame()).toContain("› Item 2");
-  });
-
-  it("should call onSelect on Enter", () => {
-    const onSelect = vi.fn();
-    const items = [{ label: "Item 1", value: "1" }];
-
-    const { stdin } = render(
-      <Select items={items} onSelect={onSelect} />,
-    );
-
-    stdin.write("\r"); // Enter key
-
-    expect(onSelect).toHaveBeenCalledWith(items[0]);
-  });
-});
-```
-
-### Async Tests
-
-```typescript
-import { render } from "ink-testing-library";
-import { vi } from "vitest";
-
-describe("LoadingIndicator", () => {
-  beforeEach(() => {
-    vi.useFakeTimers();
-  });
-
-  afterEach(() => {
-    vi.useRealTimers();
-  });
-
-  it("should show after delay", async () => {
-    const { lastFrame } = render(
-      <LoadingIndicator isLoading={true} delay={300} />,
-    );
-
-    // Not shown initially
-    expect(lastFrame()).toBe("");
-
-    // Shown after 300ms
-    vi.advanceTimersByTime(300);
-    expect(lastFrame()).toContain("Loading");
-  });
-});
-```
-
----
-
-## Mock Patterns
-
-### External Dependency Mock
-
-```typescript
-vi.mock("../../../fs/project.js", () => ({
-  findProjectRoot: vi.fn().mockResolvedValue("/repo"),
-  readConfig: vi.fn().mockResolvedValue({ defaultRelease: "v1" }),
-  getSavepointPath: vi.fn().mockReturnValue("/repo/.savepoint"),
-}));
-```
-
-### Screen Component Mock
-
-Mock sibling screens to isolate the component under test:
-
-```typescript
-const capturedProps: BoardScreenProps[] = [];
-
-vi.mock("../../components/screens/BoardScreen.js", () => ({
-  BoardScreen: (props: BoardScreenProps) => {
-    capturedProps.push(props);
-    return <div>Mocked BoardScreen</div>;
-  },
-}));
-
-describe("App", () => {
-  beforeEach(() => {
-    capturedProps.length = 0; // Reset
-  });
-
-  it("should pass tasks to BoardScreen", async () => {
-    render(<App />);
-
-    await waitFor(() => {
-      expect(capturedProps.length).toBeGreaterThan(0);
-    });
-
-    expect(capturedProps[0].tasks).toHaveLength(2);
-  });
-});
-```
-
-### Hook Mock
-
-```typescript
-vi.mock("../../hooks/useAsyncData.js", () => ({
-  useAsyncData: () => ({
-    data: [
-      { id: "T001", title: "Setup project" },
-      { id: "T002", title: "Add tests" },
-    ],
-    loading: false,
-    error: null,
-    refresh: vi.fn(),
-  }),
-}));
-```
-
-### Conditional Mock Responses
-
-```typescript
-const mockFetchTasks = vi.fn();
-
-vi.mock("../../../domain/tasks.js", () => ({
-  fetchTasks: mockFetchTasks,
-}));
-
-describe("useAsyncData", () => {
-  it("should handle error", async () => {
-    mockFetchTasks.mockRejectedValueOnce(new Error("Read error"));
-    // Assert error state is set
-  });
-
-  it("should return tasks", async () => {
-    mockFetchTasks.mockResolvedValueOnce([{ id: "T001" }]);
-    // Assert data is returned
-  });
-});
-```
-
----
-
-## Integration Tests
-
-### Navigation Flow
-
-```typescript
-describe("Navigation", () => {
-  it("should navigate from board to detail on Enter", async () => {
-    const { stdin, lastFrame } = render(<App />);
-
-    // Wait for board
-    await waitFor(() => {
-      expect(lastFrame()).toContain("Board");
-    });
-
-    // Press Enter
-    stdin.write("\r");
-
-    // Detail screen appears
-    await waitFor(() => {
-      expect(lastFrame()).toContain("Detail");
-    });
-  });
-
-  it("should go back on Escape", async () => {
-    const { stdin, lastFrame } = render(<App />);
-
-    // Navigate to detail
-    stdin.write("\r");
-    await waitFor(() => {
-      expect(lastFrame()).toContain("Detail");
-    });
-
-    // Press Escape
-    stdin.write("\x1B"); // Escape key
-
-    await waitFor(() => {
-      expect(lastFrame()).toContain("Board");
-    });
-  });
-});
-```
-
----
-
-## Edge Cases
-
-```typescript
-describe("Edge Cases", () => {
-  it("should handle empty list", () => {
-    const { lastFrame } = render(
-      <Select items={[]} onSelect={vi.fn()} />,
-    );
-
-    expect(lastFrame()).not.toContain("undefined");
-  });
-
-  it("should handle very long labels", () => {
-    const items = [{
-      label: "A".repeat(200),
-      value: "1",
-    }];
-
-    const { lastFrame } = render(
-      <Select items={items} onSelect={vi.fn()} />,
-    );
-
-    // Assert output is defined (not crashed)
-    expect(lastFrame()).toBeDefined();
-  });
-});
-```
-
----
-
-## Performance Tests
-
-```typescript
-describe("Performance", () => {
-  it("should handle 1000 items without significant lag", async () => {
-    const items = Array.from({ length: 1000 }, (_, i) => ({
-      label: `Item ${i}`,
-      value: String(i),
-    }));
-
-    const start = performance.now();
-
-    const { stdin } = render(
-      <Select items={items} onSelect={vi.fn()} limit={20} />,
-    );
-
-    // 100 navigation keypresses
-    for (let i = 0; i < 100; i++) {
-      stdin.write("j");
-    }
-
-    const duration = performance.now() - start;
-
-    // Must complete within 1 second
-    expect(duration).toBeLessThan(1000);
-  });
-});
-```
-
----
-
-## Test Utilities
-
-### waitFor Helper
-
-```typescript
-async function waitFor(
-  condition: () => boolean | void,
-  timeout = 1000,
-): Promise<void> {
-  const start = Date.now();
-
-  while (Date.now() - start < timeout) {
-    try {
-      if (condition()) return;
-    } catch {
-      // Condition not yet met
-    }
-    await new Promise((r) => setTimeout(r, 10));
-  }
-
-  throw new Error("waitFor timed out");
-}
-```
-
-### Key Constants
-
-```typescript
-const KEYS = {
-  ENTER: "\r",
-  ESCAPE: "\x1B",
-  UP: "\x1B[A",
-  DOWN: "\x1B[B",
-  LEFT: "\x1B[D",
-  RIGHT: "\x1B[C",
-  TAB: "\t",
-  BACKSPACE: "\x7F",
-  CTRL_C: "\x03",
-};
-```