@erclx/aitk 0.96.0 → 0.97.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "0.96.0",
+  "version": "0.97.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/governance/rules/ui/440-surface-capture.md

@@ -0,0 +1,26 @@
+---
+description: Require a route capture against a running preview after a page or route surface changes
+paths:
+  - '**/routes/**/*.{tsx,jsx,vue,svelte,astro}'
+  - '**/pages/**/*.{tsx,jsx,vue,svelte,astro}'
+  - '**/app/**/page.{tsx,jsx}'
+---
+
+# Surface capture standards
+
+## When to capture
+
+- Run `bun run screenshot` after changing what a route renders.
+- Capture against a running preview server. Do not capture against a dev server.
+- Capture every theme the route ships. Do not capture the default theme alone.
+
+## What a capture covers
+
+- Capture the full page at the viewport its case declares. Do not capture a component in isolation.
+- Add a case to the capture record when adding a route.
+- Remove a route's case in the change that removes the route.
+
+## Sharing a capture
+
+- Attach a capture to the pull request by hand when a reviewer needs to see it.
+- Do not commit a capture. Do not remove the capture folder from `.gitignore`.

package/governance/stacks/astro.toml

@@ -1,2 +1,2 @@
 extends = "node"
-rules = ["210-astro", "350-security-web", "400-ui", "410-a11y", "430-ux-completeness"]
+rules = ["210-astro", "350-security-web", "400-ui", "410-a11y", "430-ux-completeness", "440-surface-capture"]

package/governance/stacks/react.toml

@@ -1,2 +1,2 @@
 extends = "node"
-rules = ["200-react", "230-nextjs", "250-tailwind", "300-testing-ts", "310-zod", "350-security-web", "400-ui", "410-a11y", "420-forms", "430-ux-completeness"]
+rules = ["200-react", "230-nextjs", "250-tailwind", "300-testing-ts", "310-zod", "350-security-web", "400-ui", "410-a11y", "420-forms", "430-ux-completeness", "440-surface-capture"]

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "0.96.0",
+  "version": "0.97.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/tooling/base/reference.md

@@ -4,6 +4,8 @@
 
 The base layer covers every project the toolkit scaffolds, whatever language sits on top. It ships formatting, spelling, shell linting, conventional commits, git hooks, CI, and three maintenance scripts. Every other stack extends it, so a decision made here is one every stack inherits.
 
+A repository with several language roots layers this stack once at the root and skips it per subtree, since git honors only one `core.hooksPath` and a re-dropped husky silently breaks. `docs/target-projects.md` carries the recipe.
+
 ## What ships as golden configs
 
 Golden config files live in `tooling/base/configs/` and are copied into the target on `aitk tooling sync base .`. They are the source of truth. The reference covers rationale and tradeoffs. Configs show the concrete setup.

package/tooling/web/configs/e2e/screenshot.ts

@@ -1,41 +1,53 @@
 import type { Page } from '@playwright/test'
-
-const ROUTES = [{ name: 'home', path: '/', width: 1280, height: 800 }]
-
-type State = { name: string; setup?: (page: Page) => Promise<void> }
-const STATES: State[] = [
-  { name: 'default' },
-  { name: 'dark', setup: async (p) => p.emulateMedia({ colorScheme: 'dark' }) },
-]
-
 import { chromium } from '@playwright/test'
 import { mkdir } from 'fs/promises'
 import path from 'path'
 
+interface CaptureCase {
+  section: string
+  theme: string
+  route: string
+  width: number
+  height: number
+  setup?: (page: Page) => Promise<void>
+}
+
+const CASES: CaptureCase[] = [
+  { section: 'home', theme: 'default', route: '/', width: 1280, height: 800 },
+  {
+    section: 'home',
+    theme: 'dark',
+    route: '/',
+    width: 1280,
+    height: 800,
+    setup: (page) => page.emulateMedia({ colorScheme: 'dark' }),
+  },
+]
+
 const BASE_URL = process.env.SCREENSHOT_BASE_URL ?? 'http://localhost:4173'
 const OUT_DIR = 'screenshots'
 
 const browser = await chromium.launch()
-await mkdir(OUT_DIR, { recursive: true })
 
-for (const route of ROUTES) {
-  for (const state of STATES) {
-    const ctx = await browser.newContext({
-      viewport: { width: route.width, height: route.height },
-    })
-    const page = await ctx.newPage()
+for (const captureCase of CASES) {
+  const context = await browser.newContext({
+    viewport: { width: captureCase.width, height: captureCase.height },
+  })
+  const page = await context.newPage()
+
+  if (captureCase.setup) await captureCase.setup(page)
 
-    if (state.setup) await state.setup(page)
+  await page.goto(`${BASE_URL}${captureCase.route}`)
+  await page.waitForLoadState('networkidle')
 
-    await page.goto(`${BASE_URL}${route.path}`)
-    await page.waitForLoadState('networkidle')
+  const sectionDir = path.join(OUT_DIR, captureCase.section)
+  await mkdir(sectionDir, { recursive: true })
 
-    const file = path.join(OUT_DIR, `${route.name}-${state.name}.png`)
-    await page.screenshot({ path: file, fullPage: true })
-    console.log(`captured ${file}`)
+  const file = path.join(sectionDir, `${captureCase.theme}.png`)
+  await page.screenshot({ path: file, fullPage: true })
+  console.log(`captured ${file}`)
 
-    await ctx.close()
-  }
+  await context.close()
 }
 
 await browser.close()

package/tooling/web/reference.md

@@ -12,7 +12,7 @@ Golden config files live in `tooling/web/configs/` and are copied into the targe
 
 - `eslint.config.js`: flat config with `@eslint/js`, `typescript-eslint`, React hooks, import sort, check-file, vitest rules scoped to test files, `eslint-config-prettier` last.
 - `src/test/setup.ts`: `@testing-library/jest-dom` import, `cleanup` after each test.
-- `e2e/screenshot.ts`: capture template. `ROUTES` and `STATES` consts at the top carry one route in a default and a dark state, and the loop below them writes `screenshots/<name>-<state>.png`. Per-project routes and states extend the two consts.
+- `e2e/screenshot.ts`: capture template. A single `CASES` record at the top carries one entry per output file, each naming a section, a theme, a route, and its own viewport, and the loop below writes `screenshots/<section>/<theme>.png`. Per-project cases extend the one record. A route's themes sit together under its section folder, so the filename carries the theme alone.
 - `.vscode/extensions.json` and `.vscode/settings.json`: editor wiring for ESLint, Tailwind, Playwright, Vitest.
 - `.github/workflows/verify.yml`: `static-checks`, `unit-tests`, `build-verify`, and `e2e-tests` jobs.
 - `scripts/verify.sh`: extends base verify with typecheck, lint, unit tests, and build in the full order.
@@ -102,7 +102,9 @@ Append rows:
 | `bun run test:e2e` | Run Playwright E2E tests. |
 | `bun run screenshot` | Build, preview, then capture screenshots. |
 
-`aitk tooling verify <stack>` is the only automated caller of `bun run screenshot`, running it for any stack whose `package.json` declares the script and asserting that PNG files land under `screenshots/`. No ship chain captures a screenshot, so the output path the seed writes is a contract that one verifier reads rather than a default a ship step depends on.
+`aitk tooling verify <stack>` is the only automated caller of `bun run screenshot`, running it for any stack whose `package.json` declares the script and asserting that PNG files land under `screenshots/`. It counts them with a recursive find carrying no depth limit, so the section folders the seed writes satisfy the assertion without a change to it. Do not flatten the layout to protect that check. No ship chain captures a screenshot, so the output path the seed writes is a contract that one verifier reads rather than a default a ship step depends on.
+
+`governance/rules/ui/440-surface-capture.md` is what asks a session to run the capture after a route changes. It fires on route and page files rather than on every component, so a shared component changing every screen fires nothing and the operator runs the capture by hand.
 
 ## Verify script