glassbox 0.17.0 → 0.18.0-beta.1

package/README.md

@@ -87,7 +87,10 @@ 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.
+- **Image and SVG diffs** — binary images and SVGs render in a **side-by-side** layout (with a left/right or over/under toggle), a **difference overlay**, a **swipeable slice tool**, and pixel-precision synced zoom/pan. SVGs offer a *Code* / *Rendered* toggle so you can review either the source or the rasterized output.
+- **Comment on images** — leave a general comment on any image, or **draw a rectangle region** to anchor feedback to a specific spot (per A/B side), just like a line annotation.
+- **Ground-truth image comparison** — `glassbox --ground-truth <manifest>` compares an **actual** render against an **expected** one (a design spec, a reference, or a previous baseline — even outside the repo), scores the perceptual difference, sorts most-changed-first, and lets you **promote** a new actual to the baseline. Great for catching visual regressions.
+- **Attach files to any comment** — drag, paste, or browse to attach screenshots, logs, or any file to a line comment, image comment, or note reply. Image attachments show a thumbnail and open in a lightbox; the export lists each file's path so your AI tool can read it.
 - **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
@@ -96,13 +99,13 @@ Then you run `glassbox` again. Your previous annotations carry forward — match
 - **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
+- **Themes** — ten built-in themes (Dark, Light, High Contrast Dark/Light, Dracula, Tokyo Night, One Dark Pro, Solarized Dark/Light, Monokai), 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
 - **Review history** — browse, reopen, or delete past reviews
 - **Structured export** — markdown output with file paths, line numbers, categories, and instructions for AI consumption
-- **Automatic .gitignore prompt** — reminds you to exclude `.glassbox/` from version control
+- **Automatic .gitignore** — keeps `.glassbox/` out of version control for you at launch, while leaving the per-project `.glassbox/settings.json` tracked
 - **Auto port selection** — if the default port is busy, it finds an open one
 - **Fully local** — no network calls (unless you opt into AI features), no accounts, no telemetry. Your code stays on your machine.
 - **AI review notes** _(optional)_ — render the generating AI's line-anchored rationale and proof, committed alongside the code in `.pr-notes/`, right in the diff — and reply to any note inline
@@ -110,6 +113,18 @@ Then you run `glassbox` again. Your previous annotations carry forward — match
 
 ---
 
+## Review more than code
+
+Diffs aren't only text. Glassbox reviews **images** as a first-class diff: a side-by-side layout, a pixel **difference overlay**, and a swipeable slice tool — with synced zoom/pan. Leave a comment on the whole image or draw a region to anchor it to a spot.
+
+<img src="assets/demo-image-comparison.png" alt="Image diff with a pixel difference overlay" width="720">
+
+And when "correct" means "matches the design," **ground-truth comparison** (`glassbox --ground-truth <manifest>`) puts each **actual** render next to its **expected** one — a design spec, a reference render, or a previous baseline, even outside the repo. Glassbox scores the perceptual difference, hides identical pairs, sorts the rest most-changed-first, and lets you **promote** a new actual to the baseline once a change is intentional. Multi-step flows render as ordered, named sets.
+
+<img src="assets/demo-ground-truth.png" alt="Ground-truth comparison: expected vs actual with a perceptual difference score" width="720">
+
+---
+
 ## AI-Powered Review Intelligence
 
 > Entirely optional. Glassbox is fully functional without it.
@@ -188,6 +203,12 @@ See [docs/20-ai-review-notes.md](docs/20-ai-review-notes.md) for the format and
 
 ---
 
+## For AI tools: integrating with Glassbox
+
+If you're an AI coding tool or agent working in a project that uses Glassbox, **[docs/ai-integration.md](docs/ai-integration.md)** is the integration hub — how to launch a review, record line-anchored rationale/proof (`glassbox note`), export ground-truth image proof, consume the exported feedback (`.glassbox/latest-review.md`), and respond to the MCP/Claude channel. The repo's [AGENTS.md](AGENTS.md) is a one-screen router to it (and, separately, to the contributor docs for agents hacking on Glassbox itself).
+
+---
+
 ## Install
 
 ### Desktop app (recommended)
@@ -249,6 +270,9 @@ glassbox --all
 # Compare two arbitrary files or folders by path (no git repo required)
 glassbox --diff ./dist-old ./dist-new
 
+# Compare actual images against expected/ground-truth images (no git repo required)
+glassbox --ground-truth ./screenshots/manifest.json
+
 # Resume a previous review
 glassbox --resume
 ```
@@ -267,6 +291,7 @@ glassbox --resume
 | `--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 |
+| `--ground-truth <m>`   | Compare actual vs expected images from a manifest — 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          |

package/dist/channel.js

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 #!/usr/bin/env node
+import { createRequire as __createRequire } from 'module';
+const require = __createRequire(import.meta.url);
 
 // src/channel.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";

package/dist/cli-difftool.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import { createRequire as __createRequire } from 'module';
+const require = __createRequire(import.meta.url);
 var __defProp = Object.defineProperty;
 var __export = (target2, all) => {
   for (var name in all)
@@ -14697,6 +14699,13 @@ function planSnapshot(local2, remote2, work, isFile, basename2) {
     ]
   };
 }
+function isDirDiffInvocation(local2, stat) {
+  try {
+    return stat(local2).isDirectory();
+  } catch {
+    return false;
+  }
+}
 function launcherShimName(platform) {
   if (platform === "darwin") return "glassbox";
   if (platform === "linux") return "glassbox-linux";
@@ -14742,11 +14751,8 @@ if (args.length < 2 || args[0].startsWith("-") || args[1].startsWith("-")) {
   process.exit(1);
 }
 var [local, remote, merged, ...extra] = args;
-var localIsFile = false;
-try {
-  localIsFile = statSync2(local).isFile();
-} catch {
-}
+var isDirDiff = isDirDiffInvocation(local, statSync2);
+var isPerFile = !isDirDiff;
 var here = dirname(fileURLToPath(import.meta.url));
 var target = resolveLaunchTarget(
   here,
@@ -14779,7 +14785,7 @@ async function runThinClient(start, timeoutMs) {
 }
 function runBlockingLaunch() {
   const work = mkdtempSync(join3(tmpdir(), "glassbox-difftool-"));
-  const plan = planSnapshot(local, remote, work, localIsFile, basename);
+  const plan = planSnapshot(local, remote, work, isPerFile, basename);
   const cleanup = () => {
     try {
       rmSync2(work, { recursive: true, force: true });
@@ -14819,7 +14825,7 @@ var onThinClientError = (err) => {
   console.error(err instanceof Error ? err.message : String(err));
   return process.exit(1);
 };
-if (localIsFile && target.kind === "browser") {
+if (isPerFile && target.kind === "browser") {
   const cliPath = target.cli;
   void runThinClient(() => {
     spawnDetachedBrowserServer(cliPath, process.cwd());
@@ -14827,7 +14833,7 @@ if (localIsFile && target.kind === "browser") {
     onThinClientDone,
     onThinClientError
   );
-} else if (localIsFile && target.kind === "desktop") {
+} else if (isPerFile && target.kind === "desktop") {
   const launcher = target.launcher;
   void runThinClient(
     () => {