Merge branch 'feat/8x1z-agent-screenshots'

Author: alphaleonis

.gitignore

@@ -17,3 +17,4 @@ web/dist/
 /web/playwright-report/
 /nibs.exe
 
+/web/screenshots/output/

CLAUDE.md

@@ -18,6 +18,7 @@ All commands use [Task](https://taskfile.dev/) (`go-task/task`) as the task runn
 - `cd web && npx vitest run --reporter=agent` - Run web tests only
 - `task demo` - Serve the web UI with the sample-project fixture (temporary copy, safe to mutate)
 - `task demo:tui` - Run the TUI with the sample-project fixture
+- `task screenshots` - Capture web UI screenshots to `web/screenshots/output/` for visual verification
 - `task --list` - List all available tasks
 
 ## GraphQL Schema Changes
@@ -135,6 +136,7 @@ Before starting any new work, run `git fetch` (and `git -C .nibs fetch`) and che
 - Web test commands require `web/` as the working directory. If cwd has drifted, `cd` to the project root's `web/` directory first.
 - **Always use `--reporter=agent`** when running vitest — it keeps output concise. Never pipe vitest through grep; read the output once.
 - `task test` runs both Go and web tests. No need to run them separately unless debugging a specific failure.
+- **Visual verification of the web UI**: `task screenshots` captures PNGs of the key UI states (table at each view level, detail panel, editor modal, context menu) into `web/screenshots/output/` (gitignored), served from a temp copy of the sample fixture. Read the PNGs to *see* rendered changes — jsdom tests can't verify pixels. One-time setup: `cd web && npx playwright install chromium` (plain `install`, not `--with-deps` — that flag is apt-only and fails on Fedora). Extend `web/screenshots/capture.spec.ts` when new views or themes land.
 - **bits-ui timer flush**: `test-setup.ts` has an `afterAll` that waits 50ms so bits-ui's body-scroll-lock deferred cleanup (24ms setTimeout) fires while jsdom still exists. Without this, the timer fires after jsdom teardown causing a spurious "document is not defined" error.
 
 ## Architecture Reviews

Taskfile.yml

@@ -79,6 +79,13 @@ tasks:
     cmds:
       - npx playwright test
 
+  screenshots:
+    desc: Capture web UI screenshots for visual verification (web/screenshots/output)
+    deps: [web:build]
+    dir: web
+    cmds:
+      - npx playwright test --config=playwright.screenshots.config.ts
+
   demo:
     desc: Serve the web UI with the sample project fixture (temporary copy)
     # Task's built-in u-root mktemp defaults to /tmp (which doesn't exist on

web/playwright.screenshots.config.ts

@@ -0,0 +1,36 @@
+import { defineConfig } from "@playwright/test";
+import { cpSync, mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+// Screenshot captures run against a throwaway copy of the sample-project
+// fixture (same idea as `task demo`) so output is deterministic and never
+// touches real nibs data. The temp dir is left for the OS to clean up.
+const fixture = resolve(import.meta.dirname, "..", "testdata", "fixtures", "sample-project");
+const tmp = mkdtempSync(join(tmpdir(), "nibs-screenshots-"));
+cpSync(join(fixture, ".nibs"), join(tmp, ".nibs"), { recursive: true });
+cpSync(join(fixture, ".nibs.yml"), join(tmp, ".nibs.yml"));
+
+export default defineConfig({
+  testDir: "./screenshots",
+  timeout: 30_000,
+  retries: 0,
+  use: {
+    baseURL: "http://127.0.0.1:3132",
+    headless: true,
+    viewport: { width: 1440, height: 900 },
+  },
+  webServer: {
+    command: `cd .. && go run . serve --port 3132 --no-open --nibs-path "${join(tmp, ".nibs")}"`,
+    url: "http://127.0.0.1:3132",
+    // Never reuse: a leftover server could be pointed at real data.
+    reuseExistingServer: false,
+    timeout: 30_000,
+  },
+  projects: [
+    {
+      name: "chromium",
+      use: { browserName: "chromium" },
+    },
+  ],
+});

web/screenshots/capture.spec.ts

@@ -0,0 +1,62 @@
+import { test, expect, type Page } from "@playwright/test";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+// Captures PNGs of the key web UI states into web/screenshots/output/ so an
+// agent (or human) can visually verify UI changes. Run via `task screenshots`.
+//
+// When the theme engine lands (nibs-vmaq), extend this to loop the captures
+// once per theme. When the board view lands (nibs-sg09), add a capture for it.
+
+const OUT = join(import.meta.dirname, "output");
+mkdirSync(OUT, { recursive: true });
+
+const VIEW_LEVELS = ["milestones", "epics", "backlog"] as const;
+
+async function openApp(page: Page, viewLevel: (typeof VIEW_LEVELS)[number] = "milestones") {
+  await page.addInitScript(level => {
+    localStorage.setItem(
+      "nibs-filter-preferences",
+      JSON.stringify({ filter: {}, viewLevel: level }),
+    );
+  }, viewLevel);
+  await page.goto("/");
+  await expect(page.locator("tr[data-nib-id]").first()).toBeVisible({ timeout: 10_000 });
+}
+
+function shot(page: Page, name: string) {
+  return page.screenshot({ path: join(OUT, `${name}.png`), animations: "disabled" });
+}
+
+for (const level of VIEW_LEVELS) {
+  test(`table — ${level} view level`, async ({ page }) => {
+    await openApp(page, level);
+    await shot(page, `table-${level}`);
+  });
+}
+
+test("detail panel", async ({ page }) => {
+  await openApp(page);
+  await page.locator("tr[data-nib-id]").first().locator('[data-action="title"]').click();
+  await expect(page.locator('[data-testid="detail-panel"]')).toBeVisible({ timeout: 5_000 });
+  await expect(page.locator('[data-testid="detail-loading"]')).toBeHidden({ timeout: 5_000 });
+  await shot(page, "detail-panel");
+});
+
+test("editor modal", async ({ page }) => {
+  await openApp(page);
+  await page.locator("tr[data-nib-id]").first().click({ button: "right" });
+  await expect(page.locator('[data-testid="context-menu"]')).toBeVisible({ timeout: 3_000 });
+  await page.locator('[data-testid="ctx-edit"]').click();
+  await expect(page.locator('[data-testid="editor-modal"]')).toBeVisible({ timeout: 5_000 });
+  // Wait for the CodeMirror editor to mount so the body area isn't blank.
+  await expect(page.locator(".cm-content").first()).toBeVisible({ timeout: 5_000 });
+  await shot(page, "editor-modal");
+});
+
+test("context menu", async ({ page }) => {
+  await openApp(page);
+  await page.locator("tr[data-nib-id]").first().click({ button: "right" });
+  await expect(page.locator('[data-testid="context-menu"]')).toBeVisible({ timeout: 3_000 });
+  await shot(page, "context-menu");
+});