glassbox 0.11.0 → 0.12.0-beta.1

package/README.md

@@ -87,11 +87,15 @@ Then you run `glassbox` again. Your previous annotations carry forward — match
 
 - **Split and unified diffs** with syntax-colored add/remove/context lines
 - **Line-level annotations** — click any line to add feedback with a category
+- **Image and SVG diffs** — binary images and SVGs render side-by-side with a **difference overlay**, a **swipeable slice tool**, and pixel-precision zoom/pan. SVGs offer a *Code* / *Rendered* toggle so you can review either the source or the rasterized output.
+- **Compare any two paths** — `glassbox --diff <A> <B>` reviews two arbitrary files or two arbitrary folders by path — no git repository required.
 - **Drag and drop** annotations to different lines
 - **Double-click** to edit, click the category badge to reclassify
 - **Collapsible folder tree** in the sidebar with file filter
 - **Resizable sidebar** and word wrap toggle
 - **Keyboard navigation** — `j`/`k` to move between files, `Cmd+Enter` to save
+- **Go-to-definition and a nav stack** — click any symbol to jump to its definition, with back/forward through your trail
+- **Themes** — built-in Dark, Light, High Contrast, Dracula, and Tokyo Night, plus a custom theme editor with live preview
 - **Session persistence** — reviews survive restarts, pick up where you left off
 - **Smart review reuse** — re-running `glassbox` on the same commit updates diffs in place and migrates annotations to their new line positions
 - **Stale annotation detection** — comments that can't be matched to the updated diff are flagged with a visual indicator
@@ -130,6 +134,8 @@ If you're learning a new language, onboarding to an unfamiliar codebase, or new
 
 Guided Review works in all three sidebar modes (folder, risk, and narrative) and runs independently of risk or narrative analysis. When enabled, risk and narrative analysis also adjust their output to be more detailed and educational.
 
+<img src="assets/demo-guided-review.png" alt="Guided review notes inline with the diff" width="720">
+
 ### How to use it
 
 Click the shield or book icon in the sidebar to switch from the default folder view to risk or narrative mode. If you haven't configured an API key yet, a settings dialog will prompt you. Analysis runs once and results are cached for the session. To enable Guided Review, open the Settings dialog (gear icon) and check "Enable guided review."
@@ -216,6 +222,9 @@ glassbox --files "src/**/*.ts,lib/*.js"
 # Review entire codebase
 glassbox --all
 
+# Compare two arbitrary files or folders by path (no git repo required)
+glassbox --diff ./dist-old ./dist-new
+
 # Resume a previous review
 glassbox --resume
 ```
@@ -233,6 +242,7 @@ glassbox --resume
 | `--branch <name>`      | Current branch vs the named branch                 |
 | `--files <patterns>`   | Specific files (comma-separated globs)             |
 | `--all`                | Entire codebase (all tracked files)                |
+| `--diff <a> <b>`       | Compare two arbitrary files or folders by path — no git repo required |
 | `--port <number>`      | Port to run on (default: 4183)                     |
 | `--resume`             | Resume the latest in-progress review for this mode |
 | `--browser`            | Open in browser instead of desktop window          |
@@ -254,6 +264,49 @@ Create `.glassbox/settings.json` in your project directory to configure per-proj
 |-----|-------------|
 | `appName` | Custom window title and Dock name (defaults to "Glassbox — _folder name_") |
 
+### Use as `git difftool`
+
+Glassbox installs a companion binary, `glassbox-difftool`, that lets you register it as your `git difftool` so `git difftool --dir-diff <refA> <refB>` opens the diff in Glassbox automatically.
+
+The easiest way to register it is to let the CLI do it for you:
+
+```bash
+glassbox --register-difftool          # writes the three keys at --global scope
+glassbox --register-difftool --local  # only inside the current repo
+glassbox --unregister-difftool        # remove (only touches keys we set)
+```
+
+If you already have a different `diff.tool` configured, `--register-difftool` refuses to clobber it; pass `--force` to overwrite. The same controls live under **Settings → General** in the app (Register / Re-register / Unregister buttons).
+
+If you'd rather wire it up by hand, the equivalent config is:
+
+```bash
+git config --global diff.tool glassbox
+git config --global difftool.glassbox.cmd 'glassbox-difftool "$LOCAL" "$REMOTE"'
+git config --global difftool.prompt false
+```
+
+Then:
+
+```bash
+git difftool --dir-diff HEAD~1 HEAD
+```
+
+**Use `--dir-diff`, not the per-file mode.** Glassbox is a session-based reviewer; the per-file mode would launch a separate Glassbox instance for each changed file (and collide on the instance lock). `--dir-diff` invokes Glassbox once with both snapshots.
+
+**Under the hood:** `git difftool --dir-diff` materializes its two snapshot directories asymmetrically — the right side is symlinks pointing into your working tree, which trips up plain `git diff --no-index`. `glassbox-difftool` dereferences those symlinks into a temp tree before handing the dirs to `glassbox --diff`, then cleans up on exit. Without the wrapper you'd see every modified file show up as a "deleted + added" pair instead of a modified entry.
+
+**Alternative: skip git difftool entirely.** Glassbox's native ref-aware modes already cover the workflows `git difftool` is for and produce cleaner diffs (real `git diff`, not `--no-index`):
+
+```bash
+glassbox --commit <sha>          # review one commit
+glassbox --range <from>..<to>    # review a range
+glassbox --branch main           # current branch vs main
+glassbox                         # uncommitted changes
+```
+
+Most users will find the native modes preferable. The `git difftool` integration exists for muscle memory.
+
 ---
 
 ## AI integration

package/dist/cli-difftool.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+// src/cli-difftool.ts
+import { spawnSync } from "child_process";
+import { cpSync, mkdtempSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+var args = process.argv.slice(2);
+if (args.length < 2 || args[0].startsWith("-") || args[1].startsWith("-")) {
+  console.error("usage: glassbox-difftool <local-dir> <remote-dir> [extra glassbox args...]");
+  console.error("");
+  console.error("Configure as a git difftool:");
+  console.error("  git config --global diff.tool glassbox");
+  console.error(`  git config --global difftool.glassbox.cmd 'glassbox-difftool "$LOCAL" "$REMOTE"'`);
+  console.error("  git config --global difftool.prompt false");
+  console.error("");
+  console.error("Then use `--dir-diff` (per-file mode collides with Glassbox's instance lock):");
+  console.error("  git difftool --dir-diff HEAD~1 HEAD");
+  process.exit(1);
+}
+var [local, remote, ...extra] = args;
+var work = mkdtempSync(join(tmpdir(), "glassbox-difftool-"));
+var resolvedLocal = join(work, "left");
+var resolvedRemote = join(work, "right");
+function cleanup() {
+  try {
+    rmSync(work, { recursive: true, force: true });
+  } catch {
+  }
+}
+var signalExit = (code) => () => {
+  cleanup();
+  process.exit(code);
+};
+process.on("SIGINT", signalExit(130));
+process.on("SIGTERM", signalExit(143));
+try {
+  cpSync(local, resolvedLocal, { recursive: true, dereference: true });
+  cpSync(remote, resolvedRemote, { recursive: true, dereference: true });
+  const here = dirname(fileURLToPath(import.meta.url));
+  const cli = join(here, "cli.js");
+  const res = spawnSync(process.execPath, [cli, "--diff", resolvedLocal, resolvedRemote, ...extra], {
+    stdio: "inherit"
+  });
+  process.exit(res.status ?? 0);
+} finally {
+  cleanup();
+}
+//# sourceMappingURL=cli-difftool.js.map