@fnclaude/renderer 0.0.1 → 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Butler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# @fnclaude/renderer
+
+Configurable TUI front-end for Claude Code. Bidirectional stream-json driver, repaint-on-toggle visibility filters (Alt+1-8), pretty markdown via [glow](https://github.com/charmbracelet/glow).
+
+## Status
+
+Pre-v1. Active development. v0 ships the renderer in standalone wrapper mode — `fnclaude-renderer ...` spawns claude internally, renders the stream.
+
+> Previously published as `fnclaude-renderer` on npm. Renamed to `@fnclaude/renderer` when imported into the [fnclaude monorepo](https://github.com/fnclaude/fnclaude).
+
+## Goals
+
+- Replace the Claude Code CLI's fixed output with **verbosity presets** (quiet / normal / verbose / debug) and **per-element show/hide toggles**.
+- **Repaint past content on toggle** — flip a filter and previously-hidden content appears in place; previously-shown content collapses to a header. The transcript is a live view of the event log under the current filter.
+- Pipe assistant markdown through `glow` when available; raw fallback otherwise.
+- One persistent `claude` subprocess per session, driven via `--input-format stream-json --output-format stream-json`. No `--resume`-per-turn latency.
+
+## Install
+
+### npm
+
+```sh
+npm install -g @fnclaude/renderer
+# then
+fnclaude-renderer ...
+```
+
+### Arch Linux (AUR)
+
+```sh
+yay -S fnclaude-renderer-bin
+```
+
+### Other platforms
+
+Download the pre-built binary for your platform from the [latest release](https://github.com/fnclaude/fnclaude/releases/latest):
+
+- Linux x86_64 / arm64
+- macOS x86_64 (Intel) / arm64 (Apple Silicon)
+- Windows x86_64 / arm64
+
+Extract and place `fnclaude-renderer` on your `$PATH`.
+
+### Optional: glow
+
+[glow](https://github.com/charmbracelet/glow) renders assistant markdown with syntax highlighting. If it's on your `$PATH` it gets used automatically; otherwise raw markdown is shown.
+
+## Keybinds
+
+| Keybind | Element toggled |
+|---|---|
+| `Alt+1` | `thinking` blocks |
+| `Alt+2` | `Bash.input` (commands) |
+| `Alt+3` | `Bash.output` |
+| `Alt+4` | `Edit.diff` |
+| `Alt+5` | `Read.content` |
+| `Alt+6` | `Write.content` |
+| `Alt+7` | `Task.nested` (subagent prompts) |
+| `Alt+8` | `errors` |
+| `Alt+0` / `Alt+9` | cycle preset forward / backward |
+| `Ctrl+L` | force repaint |
+| `Ctrl+D` | clean exit |
+
+See [docs/keybind-spec.md](docs/keybind-spec.md) for terminal-specific caveats (especially macOS Terminal.app's Option/Meta handling).
+
+## Architecture
+
+- [docs/stream-json-findings.md](docs/stream-json-findings.md) — empirical notes on `claude`'s stream-json mode (what works, what's a footgun).
+- [docs/event-spec.md](docs/event-spec.md) — the typed event contract between the process driver and the UI.
+- [docs/filter-state-spec.md](docs/filter-state-spec.md) — verbosity presets, per-element override mechanics, repaint semantics.
+- [docs/keybind-spec.md](docs/keybind-spec.md) — Alt+1-8 mapping, terminal caveats.
+
+## License
+
+MIT.

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@fnclaude/renderer",
-  "version": "0.0.1",
-  "description": "Placeholder; real package coming.",
-  "license": "MIT"
+  "version": "2.0.0",
+  "type": "module",
+  "description": "Configurable TUI front-end for Claude Code with stream-json driving, toggleable visibility filters, and glow-piped markdown.",
+  "license": "MIT",
+  "author": "fnrhombus",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fnclaude/fnclaude.git",
+    "directory": "packages/renderer"
+  },
+  "bin": {
+    "fnclaude-renderer": "./src/index.tsx"
+  },
+  "files": [
+    "src",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "bun run src/index.tsx",
+    "build": "bun build --compile --outfile=bin/fnclaude-renderer ./src/index.tsx",
+    "typecheck": "tsc --noEmit",
+    "check": "biome check .",
+    "fmt": "biome format --write .",
+    "lint": "biome lint .",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "ink": "^5.0.0",
+    "react": "^18.3.1",
+    "react-devtools-core": "^7.0.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.0",
+    "@types/react": "^18.3.0",
+    "bun-types": "^1.3.14",
+    "ink-testing-library": "^4.0.0",
+    "typescript": "^5.5.0"
+  },
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
 }

package/src/App.test.tsx

@@ -0,0 +1,130 @@
+import { describe, expect, test } from "bun:test";
+import { render } from "ink-testing-library";
+import { App } from "./App.tsx";
+import { fixtureSession } from "./__fixtures__/events.ts";
+import type { Key } from "./keybinds.ts";
+
+const baseKey: Key = {
+  upArrow: false,
+  downArrow: false,
+  leftArrow: false,
+  rightArrow: false,
+  pageDown: false,
+  pageUp: false,
+  return: false,
+  escape: false,
+  ctrl: false,
+  shift: false,
+  tab: false,
+  backspace: false,
+  delete: false,
+  meta: false,
+};
+
+/**
+ * Small helper: tick a few times so async useEffect / fixture ingestion
+ * settle before asserting frame content. ink-testing-library doesn't
+ * expose a "wait" helper — yielding the microtask queue is sufficient
+ * because our fixture iterator only awaits Promise.resolve().
+ */
+async function flush(): Promise<void> {
+  // Both microtask drain (for our awaited fixture iterator) and a real
+  // macrotask tick (for React's useEffect commit phase under
+  // ink-testing-library). Microtask-only flushing isn't sufficient — the
+  // testInputBus callback only fires after the effect commits.
+  for (let i = 0; i < 5; i++) await Promise.resolve();
+  await new Promise((resolve) => setTimeout(resolve, 10));
+}
+
+describe("<App />", () => {
+  test("renders initial status line with normal preset", async () => {
+    const instance = render(<App initialEvents={[]} />);
+    await flush();
+    const frame = instance.lastFrame() ?? "";
+    expect(frame).toContain("preset: normal");
+    instance.unmount();
+  });
+
+  test("ingests events and shows Bash command (input is `show` in normal)", async () => {
+    const instance = render(<App initialEvents={fixtureSession} />);
+    await flush();
+    const frame = instance.lastFrame() ?? "";
+    // Bash.input default in `normal` is `show` — slice C's BashInput
+    // renders the command with a "$ " prefix.
+    expect(frame).toContain("$ ls -la");
+    // Assistant text is always shown.
+    expect(frame).toContain("Listing files now.");
+    instance.unmount();
+  });
+
+  test("Bash.output is hidden under the `normal` preset by default", async () => {
+    const instance = render(<App initialEvents={fixtureSession} />);
+    await flush();
+    const frame = instance.lastFrame() ?? "";
+    // Bash.output default in `normal` is `hide` — BashOutput renders null.
+    expect(frame).not.toContain("total 0");
+    instance.unmount();
+  });
+
+  test("Alt+3 toggles Bash.output → repaints past content into view", async () => {
+    // Inject a fake-input handler so the test can drive useInput
+    // deterministically without depending on stdin TTY behaviour.
+    let dispatch: ((input: string, key: Key) => void) | null = null;
+    const instance = render(
+      <App
+        initialEvents={fixtureSession}
+        testInputBus={(handler) => {
+          dispatch = handler;
+        }}
+      />,
+    );
+    await flush();
+    // Sanity: hidden before toggle.
+    expect(instance.lastFrame() ?? "").not.toContain("total 0");
+    expect(dispatch).not.toBeNull();
+
+    // Simulate Alt+3 → toggle Bash.output (was `hide` in `normal`,
+    // override flips to `show`).
+    (dispatch as unknown as (i: string, k: Key) => void)("3", {
+      ...baseKey,
+      meta: true,
+    });
+    await flush();
+
+    const after = instance.lastFrame() ?? "";
+    // Repaint: past Bash output content now visible.
+    expect(after).toContain("total 0");
+    // Override count surfaces in the status line.
+    expect(after).toContain("1 override");
+    instance.unmount();
+  });
+
+  test("Alt+0 cycles preset forward and clears overrides", async () => {
+    let dispatch: ((input: string, key: Key) => void) | null = null;
+    const instance = render(
+      <App
+        initialEvents={fixtureSession}
+        testInputBus={(handler) => {
+          dispatch = handler;
+        }}
+      />,
+    );
+    await flush();
+    expect(dispatch).not.toBeNull();
+    const send = dispatch as unknown as (i: string, k: Key) => void;
+
+    // Set an override first via Alt+3.
+    send("3", { ...baseKey, meta: true });
+    await flush();
+    expect(instance.lastFrame() ?? "").toContain("1 override");
+
+    // Cycle: normal → verbose.
+    send("0", { ...baseKey, meta: true });
+    await flush();
+    const after = instance.lastFrame() ?? "";
+    expect(after).toContain("preset: verbose");
+    // Overrides cleared.
+    expect(after).not.toContain("1 override");
+    instance.unmount();
+  });
+});

package/src/App.tsx

@@ -0,0 +1,321 @@
+/**
+ * Top-level Ink component. Owns:
+ *
+ * - the in-memory event log (`ClaudeEvent[]`, append-only per session)
+ * - the filter state (`FilterState`)
+ * - input handling (Alt+1-8, Alt+0/9, Ctrl+L/D/C, typed text + Enter)
+ * - status surface (preset, override count, momentary toast)
+ *
+ * Filter applies at render time (see docs/filter-state-spec.md), so a
+ * toggle re-renders the whole transcript from the log through the new
+ * filter — Ink reconciles the screen diff.
+ *
+ * `subscribeToClaude` is imported from `./claude-process.ts` (slice A).
+ * The returned `ClaudeSubscription` exposes `.events` (the async iterable),
+ * `.sendUserTurn(text)`, and `.close()`.
+ * Per-element renderers are imported from `./renderers/` (slice C;
+ * stubbed locally until that slice merges).
+ */
+
+import { Box, Text, useInput } from "ink";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { type ClaudeSubscription, subscribeToClaude } from "./claude-process.ts";
+import {
+  cyclePreset,
+  defaultState,
+  overrideCount,
+  resolve,
+  toggleElement,
+} from "./filter-state.ts";
+import { type Key, dispatchKey } from "./keybinds.ts";
+import {
+  ErrorRenderer,
+  ResultRenderer,
+  TextRenderer,
+  ThinkingRenderer,
+  ToolResultRenderer,
+  ToolUseRenderer,
+} from "./renderers/index.ts";
+import type {
+  AssistantEvent,
+  ClaudeEvent,
+  ElementId,
+  FilterState,
+  ResultEvent,
+  UserEvent,
+  Visibility,
+} from "./types/events.ts";
+
+const TOAST_DURATION_MS = 2000;
+
+export interface AppProps {
+  /**
+   * Seed the event log. Omit (or pass `undefined`) to subscribe live to
+   * claude via slice A's `subscribeToClaude`. Tests pass a fixed array
+   * so they don't need a running subprocess.
+   */
+  initialEvents?: ClaudeEvent[];
+  /**
+   * Test hook: receives the same handler `useInput` registers, so a test
+   * can drive input deterministically without a TTY. Production code
+   * never passes this — Ink wires real stdin.
+   */
+  testInputBus?: (handler: (input: string, key: Key) => void) => void;
+}
+
+interface ToolCallInfo {
+  name: string;
+  input: Record<string, unknown>;
+}
+
+function AssistantRender({
+  event,
+  visibilityFor,
+}: {
+  event: AssistantEvent;
+  visibilityFor: (id: ElementId) => Visibility;
+}): React.ReactElement {
+  return (
+    <Box flexDirection="column">
+      {event.message.content.map((block, idx) => {
+        const k = `${event.uuid}-${idx}`;
+        if (block.type === "text") {
+          return <TextRenderer key={k} text={block.text} />;
+        }
+        if (block.type === "thinking") {
+          return (
+            <ThinkingRenderer
+              key={k}
+              thinking={block.thinking}
+              visibility={visibilityFor("thinking")}
+            />
+          );
+        }
+        if (block.type === "tool_use") {
+          return <ToolUseRenderer key={k} block={block} visibilityFor={visibilityFor} />;
+        }
+        return null;
+      })}
+    </Box>
+  );
+}
+
+function UserRender({
+  event,
+  toolCallById,
+  visibilityFor,
+}: {
+  event: UserEvent;
+  toolCallById: Map<string, ToolCallInfo>;
+  visibilityFor: (id: ElementId) => Visibility;
+}): React.ReactElement {
+  const content = event.message.content;
+  if (typeof content === "string") {
+    return <Text>{content}</Text>;
+  }
+  return (
+    <Box flexDirection="column">
+      {content.map((block, idx) => {
+        const k = `${event.uuid ?? "user"}-${idx}`;
+        if (block.type === "text") {
+          return <Text key={k}>{block.text}</Text>;
+        }
+        if (block.type === "tool_result") {
+          const call = toolCallById.get(block.tool_use_id);
+          return (
+            <ToolResultRenderer
+              key={k}
+              block={block}
+              toolName={call?.name ?? ""}
+              {...(call?.input ? { toolInput: call.input } : {})}
+              visibilityFor={visibilityFor}
+            />
+          );
+        }
+        return null;
+      })}
+    </Box>
+  );
+}
+
+function ResultRender({
+  event,
+}: {
+  event: ResultEvent;
+}): React.ReactElement {
+  if (event.is_error) {
+    return <ErrorRenderer message={event.result} />;
+  }
+  return <ResultRenderer event={event} />;
+}
+
+export function App(props: AppProps): React.ReactElement {
+  const { initialEvents, testInputBus } = props;
+  const [events, setEvents] = useState<ClaudeEvent[]>(() => initialEvents ?? []);
+  const [filter, setFilter] = useState<FilterState>(defaultState);
+  const [draft, setDraft] = useState<string>("");
+  const [toast, setToast] = useState<string | null>(null);
+  const toastTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const subRef = useRef<ClaudeSubscription | null>(null);
+
+  // Subscribe to slice A only when no initialEvents were provided — tests
+  // pass a static log; production starts empty and ingests live.
+  useEffect(() => {
+    if (initialEvents !== undefined) return;
+    let cancelled = false;
+    const sub = subscribeToClaude();
+    subRef.current = sub;
+    (async () => {
+      for await (const event of sub.events) {
+        if (cancelled) break;
+        setEvents((prev) => [...prev, event]);
+      }
+    })();
+    return () => {
+      cancelled = true;
+      sub.close().catch(() => undefined);
+      subRef.current = null;
+    };
+  }, [initialEvents]);
+
+  // Build a tool_use_id → { name, input } index for tool_result dispatch.
+  // Re-derived from the log on every render; cheap, log is in-memory.
+  // Slice C's ToolResultRenderer needs the original `input` for results
+  // that summarize against the call (e.g. Read.content's file_path).
+  const toolCallById = useMemo(() => {
+    const m = new Map<string, ToolCallInfo>();
+    for (const event of events) {
+      if (event.type === "assistant") {
+        for (const block of event.message.content) {
+          if (block.type === "tool_use") {
+            m.set(block.id, { name: block.name, input: block.input });
+          }
+        }
+      }
+    }
+    return m;
+  }, [events]);
+
+  const visibilityFor = useMemo(() => (id: ElementId) => resolve(id, filter), [filter]);
+
+  const flashToast = (msg: string) => {
+    setToast(msg);
+    if (toastTimer.current !== null) clearTimeout(toastTimer.current);
+    toastTimer.current = setTimeout(() => setToast(null), TOAST_DURATION_MS);
+  };
+
+  // Cleanup the toast timer on unmount.
+  useEffect(() => {
+    return () => {
+      if (toastTimer.current !== null) clearTimeout(toastTimer.current);
+    };
+  }, []);
+
+  const handleKey = (input: string, key: Key) => {
+    const action = dispatchKey(input, key);
+    if (action !== null) {
+      switch (action.kind) {
+        case "toggleElement":
+          setFilter((f) => toggleElement(f, action.element));
+          flashToast(`toggled ${action.element}`);
+          return;
+        case "cyclePreset":
+          setFilter((f) => cyclePreset(f, action.direction));
+          flashToast(action.direction === 1 ? "preset cycled forward" : "preset cycled backward");
+          return;
+        case "repaint":
+          // Force a no-op state update to trigger a fresh paint. The
+          // event log already lives in state, so React's reconciler
+          // walks it again on any state change.
+          setFilter((f) => ({ ...f }));
+          flashToast("repaint");
+          return;
+        case "closeStdin":
+          subRef.current?.close().catch(() => undefined);
+          flashToast("close stdin");
+          return;
+        case "interrupt":
+          flashToast("interrupt");
+          return;
+      }
+      return;
+    }
+    // Text input: typed chars go into the draft; Enter submits.
+    if (key.return) {
+      if (draft.length > 0) {
+        subRef.current?.sendUserTurn(draft);
+        setDraft("");
+      }
+      return;
+    }
+    if (key.backspace || key.delete) {
+      setDraft((d) => d.slice(0, -1));
+      return;
+    }
+    // Ignore control/meta-only inputs that didn't match a bind.
+    if (key.ctrl || key.meta) return;
+    if (input.length > 0) {
+      setDraft((d) => d + input);
+    }
+  };
+
+  // Production: register the handler with Ink. Tests: expose it via
+  // testInputBus instead so they don't need real stdin.
+  //
+  // `handleKey` closes over draft/filter state but reads them via
+  // setState callbacks where it matters — passing it through a ref
+  // avoids re-running the testInputBus effect on every render while
+  // still letting the test observe the latest closure.
+  const handleKeyRef = useRef(handleKey);
+  handleKeyRef.current = handleKey;
+  useInput((input, key) => handleKeyRef.current(input, key as unknown as Key), {
+    isActive: testInputBus === undefined,
+  });
+  useEffect(() => {
+    if (testInputBus !== undefined) {
+      testInputBus((input, key) => handleKeyRef.current(input, key));
+    }
+  }, [testInputBus]);
+
+  const statusLine = (() => {
+    const n = overrideCount(filter);
+    const parts = [`preset: ${filter.preset}`];
+    if (n > 0) parts.push(`${n} override${n === 1 ? "" : "s"}`);
+    if (toast !== null) parts.push(toast);
+    return parts.join("  |  ");
+  })();
+
+  return (
+    <Box flexDirection="column">
+      <Box flexDirection="column">
+        {events.map((event) => {
+          const key =
+            "uuid" in event && event.uuid ? event.uuid : `${event.type}-${events.indexOf(event)}`;
+          if (event.type === "assistant") {
+            return <AssistantRender key={key} event={event} visibilityFor={visibilityFor} />;
+          }
+          if (event.type === "user") {
+            return (
+              <UserRender
+                key={key}
+                event={event}
+                toolCallById={toolCallById}
+                visibilityFor={visibilityFor}
+              />
+            );
+          }
+          if (event.type === "result") {
+            return <ResultRender key={key} event={event} />;
+          }
+          // system / rate_limit_event: header-only, always shown.
+          if (event.type === "system") {
+            return null;
+          }
+          return null;
+        })}
+      </Box>
+      {draft.length > 0 ? <Text>{`> ${draft}`}</Text> : null}
+      <Text>{statusLine}</Text>
+    </Box>
+  );
+}

package/src/__fixtures__/events.ts

@@ -0,0 +1,66 @@
+/**
+ * Hand-rolled fixture events for App.test.tsx + the stub subscription.
+ *
+ * Keep these small and focused — they only need to be expressive enough to
+ * verify the renderer dispatch + filter repaint behaviour. Real captures
+ * live in slice A's recordings.
+ */
+
+import type { ClaudeEvent } from "../types/events.ts";
+
+export const fixtureSession: ClaudeEvent[] = [
+  {
+    type: "system",
+    subtype: "init",
+    session_id: "fixture-session",
+    uuid: "u-system-1",
+    cwd: "/tmp",
+    model: "claude-opus-4-7",
+    tools: ["Bash", "Read", "Edit", "Write", "Task"],
+  },
+  {
+    type: "assistant",
+    session_id: "fixture-session",
+    uuid: "u-asst-1",
+    message: {
+      role: "assistant",
+      model: "claude-opus-4-7",
+      content: [
+        { type: "text", text: "Listing files now." },
+        {
+          type: "tool_use",
+          id: "tool-1",
+          name: "Bash",
+          input: { command: "ls -la", description: "List files" },
+        },
+      ],
+    },
+  },
+  {
+    type: "user",
+    session_id: "fixture-session",
+    uuid: "u-user-1",
+    message: {
+      role: "user",
+      content: [
+        {
+          type: "tool_result",
+          tool_use_id: "tool-1",
+          content: "total 0\ndrwxr-xr-x 2 tom tom 60 May 19 04:59 .\n",
+        },
+      ],
+    },
+  },
+  {
+    type: "result",
+    subtype: "success",
+    is_error: false,
+    session_id: "fixture-session",
+    uuid: "u-result-1",
+    result: "Done.",
+    num_turns: 1,
+    duration_ms: 100,
+    duration_api_ms: 50,
+    total_cost_usd: 0.001,
+  },
+];