critique 0.1.12 → 0.1.28

package/AGENTS.md

@@ -79,3 +79,36 @@ NEVER update existing changelog bullet points for previous version unless you ad
 - minimize number of props. do not use props if you can use zustand state instead. the app has global zustand state that lets you get a piece of state down from the component tree by using something like `useStore(x => x.something)` or `useLoaderData<typeof loader>()` or even useRouteLoaderData if you are deep in the react component tree
 
 - do not consider local state truthful when interacting with server. when interacting with the server with rpc or api calls never use state from the render function as input for the api call. this state can easily become stale or not get updated in the closure context. instead prefer using zustand `useStore.getState().stateValue`. notice that useLoaderData or useParams should be fine in this case.
+
+## cli
+
+the main cli functionality is in src/cli.tsx
+
+the main command shows the git diff in a tui. the web command uploads the terminal output to html to domain critique.work
+
+the command review helps the user review agents diffs, reordering and splitting diff hunks to create a progressive disclosure document with explanations and diagrams. it also supports using --web to upload the result to critique.work
+
+this command takes a long time to run, because it uses ACP to generate the result using an LLM. so to test styles changes we will usually modify scripts/preview-review.tsx instead, which let you preview how the cli looks like. and passing --web to that script to also preview how the website looks like
+
+<!-- opensrc:start -->
+
+## Source Code Reference
+
+Source code for dependencies is available in `opensrc/` for deeper understanding of implementation details.
+
+See `opensrc/sources.json` for the list of available packages and their versions.
+
+Use this source code when you need to understand how a package works internally, not just its types/interface.
+
+### Fetching Additional Source Code
+
+To fetch source code for a package or repository you need to understand, run:
+
+```bash
+npx opensrc <package>           # npm package (e.g., npx opensrc zod)
+npx opensrc pypi:<package>      # Python package (e.g., npx opensrc pypi:requests)
+npx opensrc crates:<package>    # Rust crate (e.g., npx opensrc crates:serde)
+npx opensrc <owner>/<repo>      # GitHub repo (e.g., npx opensrc vercel/ai)
+```
+
+<!-- opensrc:end -->

package/CHANGELOG.md

@@ -1,3 +1,185 @@
+# 0.1.28
+
+- Default command:
+  - Add `--stdin` option to read diff from stdin (for lazygit pager integration)
+  - Faster scroll acceleration (`A: 1.5`, `maxMultiplier: 10`)
+- `review` command:
+  - Remove hunk ID prefix (`#1`, `#2`) from hunk headers
+  - Faster scroll acceleration (`A: 1.5`, `maxMultiplier: 10`)
+  - Code blocks now use `wrapMode: "none"` to prevent word-wrapping (content truncates at viewport edge instead)
+  - Prose max width now respects terminal width: `Math.min(80, width)`
+  - Code blocks use full terminal width minus padding
+- Tests:
+  - Added test for code block wrapMode behavior with renderer
+
+# 0.1.27
+
+- GitHub theme:
+  - Reduce intensity of diff added/removed background colors for softer appearance
+
+# 0.1.26
+
+- `review` command:
+  - Make filename bold in hunk header
+  - Add gap of 1 between filename header and diff
+
+# 0.1.25
+
+- Default command:
+  - Change file picker shortcut from `ctrl p` to plain `p`
+  - Make `--web` bold in footer for better visibility
+- `review` command:
+  - Make `--web` bold in footer for better visibility
+
+# 0.1.24
+
+- Default command:
+  - Add `--web [title]` flag to generate web preview instead of TUI
+  - Add `--open` flag to open in browser (with `--web`)
+  - Add `--theme <name>` flag to set theme (works for both TUI and web)
+  - Add `--cols` and `--mobile-cols` flags for web render dimensions
+  - Show all files in scrollable view instead of one-at-a-time pagination
+  - `ctrl p` dropdown now scrolls to selected file
+  - Add "--web to share & collaborate" tip to footer
+- `review` command:
+  - Add "--web to share & collaborate" tip to footer
+- Deprecate `web` command (use `--web` flag instead)
+
+# 0.1.23
+
+- `review` command:
+  - Add `gap` prop to `ReviewAppView` to control spacing between markdown descriptions and hunks (default: 2)
+
+# 0.1.22
+
+- Use `<markdown>` component instead of `<code filetype="markdown">` for rendering markdown content:
+  - `review` command: MarkdownBlock component
+  - `stream-display`: Message blocks
+- Update opentui to PR #433 with MarkdownRenderable support
+- Variable-width markdown rendering in `review` command:
+  - Prose (headings, paragraphs, lists) constrained to 80 chars, centered
+  - Code blocks and tables expand to full available width, centered
+  - Uses `renderNode` callback to customize block rendering
+  - Added test for wide code blocks and tables
+- Add example diagrams and tables to `scripts/preview-review.tsx`
+
+# 0.1.21
+
+- `review` command:
+  - Add clack spinners for analysis start and tool call activity
+  - Show file names for read/write/edit tool logs
+  - Show animated "generating..." indicator in the TUI footer
+  - Add spinner while loading session context
+  - Upgrade `@clack/prompts` for taskLog support
+
+# 0.1.20
+
+- Add theme picker to `review` command:
+  - Press `t` to open theme picker with live preview
+  - Theme selection persisted and shared with main diff view
+- Extract zustand store to `src/store.ts`:
+  - Shared state between main diff view and review view
+  - Theme changes auto-persist to `~/.critique/state.json`
+- Fix diff background colors:
+  - Wrap diff component in box with theme background color
+  - Ensures no black/transparent gaps in diff view
+- Fix theme reactivity in DiffView:
+  - Memoize resolved theme and syntax style properly
+- Fix Dropdown component:
+  - Add `focused` prop for proper focus management
+  - Fix stale closure issue in move/onFocus callbacks
+  - Separate useEffect for selection changes to fix theme preview reactivity
+- Fix hardcoded colors in review UI:
+  - Scrollbar, footer, and hunk headers now use theme colors
+- Add `scripts/preview-review.tsx` for standalone review component testing
+- Simplify generating indicator (show only animated dots)
+
+# 0.1.19
+
+- `review` command:
+  - Pass `_meta: { critique: true }` when creating review sessions for future filtering support
+  - Filter out critique-generated sessions from context selection (by `_meta` or title pattern)
+
+# 0.1.18
+
+- Replace `@xmorse/bun-pty` with `bun-pty` (official package)
+- Remove unused dependencies: `react-error-boundary`, `node-pty`, `shiki`, `@shikijs/langs`, `@shikijs/themes`
+- Remove unused `highlight.tsx` example file
+
+# 0.1.17
+
+- Rename `explain` command to `review`
+- Add Claude Code support:
+  - `critique review --agent claude` to use Claude Code instead of OpenCode
+  - Session listing works for both agents
+- `web` command:
+  - Use Fira Code font from Google Fonts for better box drawing character rendering
+- Update `ghostty-opentui` to v1.3.12
+
+# 0.1.16
+
+- `explain` command:
+  - Add explicit instruction that diagrams must be wrapped in code blocks
+
+# 0.1.15
+
+- `explain` command:
+  - Add `--web` flag to generate web preview instead of TUI
+  - Add `--open` flag to open web preview in browser
+  - Web mode waits for full AI generation before rendering
+  - Hide keyboard shortcuts footer in web mode
+- New `src/web-utils.ts` module:
+  - Shared utilities for web preview generation
+  - `captureToHtml` - PTY capture and ANSI to HTML conversion
+  - `captureResponsiveHtml` - Generate desktop and mobile versions
+  - `uploadHtml` - Upload to critique.work worker
+  - `openInBrowser` - Platform-specific browser opening
+  - `writeTempFile` / `cleanupTempFile` - Temp file helpers
+- Refactored `web` command to use shared utilities
+- Fix markdown syntax highlighting in review mode:
+  - Add markdown colors to theme resolution
+  - Add Tree-sitter markdown scopes (markup.heading, markup.bold, etc.)
+- Fix empty space in web preview rendering:
+  - Add `minHeight: 0` to scrollbox contentOptions
+  - Replace `height: 100%` with `flexGrow: 1` for flexible layout
+  - Add `showFooter` prop to ReviewAppView for web mode
+
+# 0.1.14
+
+- New `explain` command:
+  - AI-powered diff explanation and review using ACP (Agent Client Protocol)
+  - Usage: `critique explain [base] [head]`
+  - Options:
+    - `--agent <name>` - AI agent to use (default: opencode)
+    - `--staged` - Explain staged changes
+    - `--commit <ref>` - Explain changes from a specific commit
+    - `--filter <pattern>` - Filter files by glob pattern
+  - Features:
+    - Parses git diff into indexed hunks with unique IDs
+    - Connects to opencode via ACP to analyze changes
+    - AI groups related hunks and generates markdown descriptions
+    - Streams results as YAML file is updated
+    - Renders scrollable TUI with prose descriptions above each hunk group
+    - Supports keyboard navigation (j/k or arrows) between groups
+    - Uses split view for hunks with both additions and deletions
+    - Centers prose descriptions with max-width 80
+  - New dependencies: `js-yaml`, `@agentclientprotocol/sdk`
+- New `src/review/` module:
+  - `acp-client.ts` - ACP client for opencode communication
+  - `hunk-parser.ts` - Parse diffs into indexed hunks with `buildPatch`/`createHunk` helpers
+  - `session-context.ts` - Compress sessions for AI context
+  - `yaml-watcher.ts` - Watch and parse streaming YAML output
+  - `review-app.tsx` - TUI component for review mode
+  - `review-app.test.tsx` - Inline snapshot tests using opentui test renderer
+- New `src/components/` module:
+  - `diff-view.tsx` - Shared DiffView component extracted from cli.tsx
+
+# 0.1.13
+
+- Docs:
+  - Enhance web preview section in README
+  - Add `/v/` short URL alias documentation
+
 # 0.1.12
 
 - Web preview:

package/README.md

@@ -74,6 +74,74 @@ Then use:
 git difftool HEAD~1
 ```
 
+### Lazygit Integration
+
+Use critique as a custom pager in [lazygit](https://github.com/jesseduffield/lazygit):
+
+```yaml
+# ~/.config/lazygit/config.yml
+git:
+  paging:
+    pager: critique --stdin
+```
+
+For more details, see [lazygit's Custom Pagers documentation](https://github.com/jesseduffield/lazygit/blob/master/docs/Custom_Pagers.md).
+
+### AI-Powered Diff Explanation
+
+Generate AI-powered explanations of code changes using [OpenCode](https://opencode.ai) or [Claude Code](https://www.anthropic.com/claude-code) as the backend agent.
+
+**What it does:**
+- Orders hunks in logical reading order (types before implementation, etc.)
+- Splits large hunks into digestible chunks with focused explanations
+- Explains each change with diagrams, tables, and markdown
+- Groups related changes across files
+
+**Best for reviewing AI-generated changes:** Pass `--session` to include the coding session context, so the AI understands *why* changes were made and can explain them better.
+
+```bash
+# Review unstaged changes (uses OpenCode by default)
+critique review
+
+# Use Claude Code instead
+critique review --agent claude
+
+# Review staged changes
+critique review --staged
+
+# Review the last commit
+critique review HEAD
+
+# Review a specific commit
+critique review --commit HEAD~1
+critique review --commit abc1234
+
+# Review commit range (like a PR): critique review <base> <head>
+# Shows what <head> added since diverging from <base>
+critique review main HEAD          # what current branch added vs main
+critique review main feature-branch
+
+# Include session context (from opencode or claude sessions)
+critique review --agent opencode --session <session-id>
+critique review --agent claude --session <session-id>
+
+# Generate web preview instead of TUI
+critique review --web
+critique review --web --open
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--agent <name>` | AI agent to use: `opencode` (default) or `claude` |
+| `--staged` | Review staged changes |
+| `--commit <ref>` | Review changes from a specific commit |
+| `--session <id>` | Include session(s) as context (can be repeated) |
+| `--web` | Generate web preview instead of TUI |
+| `--open` | Open web preview in browser (with --web) |
+| `--filter <pattern>` | Filter files by glob pattern |
+
 ### Pick Files from Another Branch
 
 Selectively apply changes from another branch to your current HEAD:
@@ -86,7 +154,13 @@ Use the interactive UI to select files. Selected files are immediately applied a
 
 ### Web Preview
 
-Generate a shareable web preview of your diff that you can send to anyone - no installation required:
+Generate a shareable web preview of your diff that you can send to anyone - no installation required.
+
+**Example:** [critique.work/v/b8faf4362c247bfc46f5098a028e00f0](https://critique.work/v/b8faf4362c247bfc46f5098a028e00f0)
+
+Great for background agents that can't render terminal UIs, like [kimaki.xyz](https://kimaki.xyz) which runs OpenCode in Discord.
+
+![Web Preview](screenshot-web.png)
 
 ```bash
 # Upload to critique.work and get a shareable URL
@@ -95,29 +169,32 @@ critique web
 # View staged changes
 critique web --staged
 
-# View the last commit (works whether pushed or unpushed)
+# View the last commit
 critique web HEAD
 
 # View a specific commit
 critique web --commit HEAD~1
 
-# View combined changes from last N commits
-critique web HEAD~3 HEAD
+# Compare branches (PR-style diff)
+critique web main feature-branch
+
+# Filter specific files
+critique web -- src/api.ts src/utils.ts
+
+# Custom title for the HTML page
+critique web --title "Fix authentication bug"
 
 # Generate local HTML file instead of uploading
 critique web --local
-
-# Adjust rendering size (use ~100 cols for mobile-friendly output)
-critique web --cols 100 --rows 2000
 ```
 
-**How it works:**
+**Features:**
 
-1. Captures the terminal UI output using a PTY (pseudo-terminal)
-2. Converts ANSI escape codes to styled HTML with syntax highlighting
-3. Uploads the HTML to [critique.work](https://critique.work) (Cloudflare Worker + KV storage)
-4. Returns a shareable URL that expires after 7 days
-5. Automatically opens the preview in your browser
+- **Mobile optimized** - Automatically detects mobile devices and serves a unified diff view optimized for smaller screens. Add `?v=mobile` to any URL to force mobile view.
+- **Dark/Light mode** - Automatically adapts to your system's color scheme preference using CSS `prefers-color-scheme`.
+- **Syntax highlighting** - Full syntax highlighting for 18+ languages, same as the terminal UI.
+- **Split view** - Side-by-side diff on desktop, unified view on mobile.
+- **Fast loading** - HTML is streamed for quick initial render, cached for 24 hours.
 
 **Options:**
 
@@ -126,14 +203,24 @@ critique web --cols 100 --rows 2000
 | `--staged` | Show staged changes | - |
 | `--commit <ref>` | Show changes from a specific commit | - |
 | `--cols <n>` | Terminal width for rendering | `240` |
-| `--rows <n>` | Terminal height for rendering | `2000` |
+| `--mobile-cols <n>` | Terminal width for mobile version | `100` |
 | `--local` | Save HTML locally instead of uploading | - |
 | `--filter <pattern>` | Filter files by glob (can be used multiple times) | - |
+| `--title <text>` | Custom HTML document title | `Critique Diff` |
+| `--theme <name>` | Theme for rendering (disables auto dark/light mode) | - |
+
+**How it works:**
+
+1. Captures the terminal UI output using a PTY (pseudo-terminal)
+2. Converts ANSI escape codes to styled HTML with syntax highlighting
+3. Generates both desktop (240 cols, split view) and mobile (100 cols, unified view) versions
+4. Uploads to [critique.work](https://critique.work) (Cloudflare Worker + KV storage)
+5. Returns a shareable URL that expires after 7 days
 
 **Tips:**
 
-- Use `--cols 100` for mobile-friendly output (switches to unified diff view instead of split view)
 - The URL is based on a SHA-256 hash of the content, so identical diffs produce the same URL (deduplication)
+- Use `?v=desktop` or `?v=mobile` query params to force a specific version
 - If upload fails, critique automatically saves the HTML locally as a fallback
 
 ## Features