@erclx/canon 4.0.0

package/tooling/vite-react/reference.md

@@ -0,0 +1,55 @@
+# Tooling vite-react reference
+
+> Extends: `web`. Apply web stack first.
+
+## Overview
+
+The vite-react stack covers Vite + React + TypeScript projects: web apps and Chrome extensions. It ships golden configs for `vite.config.ts`, `vitest.config.ts` (merging from vite config), `playwright.config.ts`, and a unified `tsconfig.json` with `@/` path alias. Shared web tooling (ESLint, screenshot template, VS Code, CI, verify script) comes from the `web` layer.
+
+## Scaffold checklist
+
+1. Scaffold with `bunx create-vite@latest <name> --template react-ts` (web apps) or `bunx create-crxjs@latest` (Chrome extensions).
+2. Install base and web tooling: `canon tooling sync web . --write`
+3. Install vite-react deps and configs: `canon tooling sync vite-react . --write`
+4. Extend the `ci` and `development` context entries under `.claude/context/` per the web reference's extend sections plus the vite-react rows below.
+5. Run `bun run lint:fix` then `bun run check`.
+
+## What ships as golden configs
+
+- `vite.config.ts`: `@vitejs/plugin-react`, `@tailwindcss/vite`, `@` path alias to `./src`, `VITE_BASE_URL` env for base path. Dev port `5173` and preview port `4173`, each plus `WORKTREE_PORT_OFFSET`, both with `strictPort`.
+- `vitest.config.ts`: merges from `vite.config.ts`, jsdom, globals, setup file, `passWithNoTests: true`, v8 coverage.
+- `playwright.config.ts`: all browsers, `webServer` on `bun run dev` at port `5173` plus `WORKTREE_PORT_OFFSET`, `reuseExistingServer: false`, trace under `use`.
+- `tsconfig.json`: unified, `noEmit: true`, `skipLibCheck: true`, `@/` paths, `vitest/globals` and `@testing-library/jest-dom` in types.
+
+## Chrome extension variant
+
+When scaffolding a Chrome extension, override the installed golden configs:
+
+- `vite.config.ts`: use `crx({ manifest })` and `zip()` from `@crxjs/vite-plugin` instead of `react()` alone. Keep the derived `server.port` and `server.strictPort: true`, set `server.hmr.clientPort` to the same derived value, and add `chrome-extension://` to CORS origins. Drop `VITE_BASE_URL`.
+- `vitest.config.ts`: use a standalone `defineConfig` (no `mergeConfig`). crxjs plugin breaks Vitest. Declare `@vitejs/plugin-react` and `@tailwindcss/vite` directly. Add `**/release/**` to excludes and `manifest.config.ts`, `**/*.d.ts` to coverage excludes.
+- `playwright.config.ts`: chromium-only (Firefox and WebKit cannot run extensions). Bundled `chromium` channel. No `baseURL` or `webServer`. Tests load the built extension directly from `dist/`.
+- `e2e/fixtures.ts`: extend Playwright base `test` with `context` (persistent context loading the extension from `dist/`) and `extensionId` (extracted from service worker URL). Rename `use` to `apply` to avoid the React hooks ESLint rule. `waitForEvent('serviceworker')` blocks until the MV3 service worker registers.
+- `manifest.config.ts`: use `defineManifest` from `@crxjs/vite-plugin`. Read `name` and `version` from `package.json`. Entry points `src/popup/index.html`, `src/sidepanel/index.html`, `src/background/index.ts`, `src/content/main.tsx`. Permissions `sidePanel`, `contentSettings`, `storage`. Icon `public/logo.png` at size 48.
+- `screenshot` script: `bun run build && bun e2e/screenshot.ts` (no preview server).
+- Additional gitignore entries: `*.crx`, `*.pem`, `release/`.
+
+## Setup script
+
+- File: `scripts/setup.sh`. Destructive: deletes `.git` and self-removes after running. Run once immediately after scaffolding.
+- Prompt for project name, normalize to kebab-case, derive title-cased display name.
+- Update `package.json` name and version, inject verify/clean/update scripts, remove setup.
+- Update `<title>` tags in HTML files.
+- Wipe `.git`, re-init, make scripts executable, commit as `chore(root): initialize <name>`.
+
+## Development docs (extend)
+
+Append to the `## Scripts` table:
+
+| `bun run dev` | Start the Vite dev server on port 5173, plus this worktree's port offset. |
+| `bun run build` | Typecheck then build the production bundle. |
+| `bun run preview` | Serve the built bundle locally. |
+| `bun run typecheck` | Run `tsc --noEmit`. |
+
+## CI docs (extend)
+
+In `.claude/context/ci.md`, the Typecheck row's assertion reads: `` `tsc --noEmit` passes ``.

package/tooling/vite-react/seeds/.cspell/project-terms.txt

@@ -0,0 +1 @@
+

package/tooling/vite-react/seeds/.cspell/tech-stack.txt

@@ -0,0 +1 @@
+Vite

package/tooling/web/configs/.github/workflows/verify.yml

@@ -0,0 +1,134 @@
+name: Verify
+
+on:
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  static-checks:
+    name: 🔍 Static Checks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install Dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Install Shell Tools
+        run: sudo apt-get install -y shfmt shellcheck
+
+      - name: Typecheck
+        run: bun run typecheck
+
+      - name: Lint
+        run: bun run lint
+
+      - name: Check Formatting
+        run: bun run check:format
+
+      - name: Check Spelling
+        run: bun run check:spell
+
+      - name: Check Shell
+        run: bun run check:shell
+
+  unit-tests:
+    name: 🧪 Unit Tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install Dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Run Tests
+        run: bun run test:coverage
+
+  build-verify:
+    name: 🏗️ Build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install Dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build
+        run: bun run build
+
+  e2e-tests:
+    name: 🎭 E2E Tests
+    runs-on: ubuntu-latest
+    needs: [static-checks, unit-tests, build-verify]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install Dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Cache Playwright Browsers
+        id: playwright-cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-${{ hashFiles('**/package.json') }}
+
+      - name: Install Playwright Chromium
+        if: steps.playwright-cache.outputs.cache-hit != 'true'
+        run: bunx playwright install chromium
+
+      - name: Run E2E Tests
+        run: bun run test:e2e --project=chromium
+
+      - name: Upload E2E Report
+        uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 7

package/tooling/web/configs/.vscode/extensions.json

@@ -0,0 +1,13 @@
+{
+  "recommendations": [
+    "esbenp.prettier-vscode",
+    "streetsidesoftware.code-spell-checker",
+    "mkhl.shfmt",
+    "timonwong.shellcheck",
+    "mads-hartmann.bash-ide-vscode",
+    "dbaeumer.vscode-eslint",
+    "bradlc.vscode-tailwindcss",
+    "ms-playwright.playwright",
+    "vitest.explorer"
+  ]
+}

package/tooling/web/configs/.vscode/settings.json

@@ -0,0 +1,10 @@
+{
+  "shellcheck.customArgs": ["--severity=warning"],
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit"
+  },
+  "files.associations": {
+    "*.css": "tailwindcss"
+  }
+}

package/tooling/web/configs/e2e/home.spec.ts

@@ -0,0 +1,6 @@
+import { expect, test } from '@playwright/test'
+
+test('home page loads', async ({ page }) => {
+  await page.goto('/')
+  await expect(page).toHaveTitle(/.+/)
+})

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

@@ -0,0 +1,53 @@
+import type { Page } from '@playwright/test'
+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()
+
+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)
+
+  await page.goto(`${BASE_URL}${captureCase.route}`)
+  await page.waitForLoadState('networkidle')
+
+  const sectionDir = path.join(OUT_DIR, captureCase.section)
+  await mkdir(sectionDir, { recursive: true })
+
+  const file = path.join(sectionDir, `${captureCase.theme}.png`)
+  await page.screenshot({ path: file, fullPage: true })
+  console.log(`captured ${file}`)
+
+  await context.close()
+}
+
+await browser.close()

package/tooling/web/configs/eslint.config.js

@@ -0,0 +1,82 @@
+import js from '@eslint/js'
+import { defineConfig, globalIgnores } from 'eslint/config'
+import prettier from 'eslint-config-prettier'
+import checkFile from 'eslint-plugin-check-file'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import simpleImportSort from 'eslint-plugin-simple-import-sort'
+import vitest from 'eslint-plugin-vitest'
+import globals from 'globals'
+import tseslint from 'typescript-eslint'
+
+export default defineConfig([
+  globalIgnores([
+    'dist',
+    'dist-ssr',
+    'coverage',
+    'release',
+    '.claude',
+    '.vscode',
+    '.husky',
+    'test-results',
+    'playwright-report',
+    'blob-report',
+    'playwright/.cache',
+  ]),
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    files: ['**/*.{ts,tsx,js,jsx}'],
+    plugins: {
+      'react-hooks': reactHooks,
+      'react-refresh': reactRefresh,
+      'simple-import-sort': simpleImportSort,
+      'check-file': checkFile,
+    },
+    languageOptions: {
+      globals: {
+        ...globals.browser,
+      },
+    },
+    rules: {
+      ...reactHooks.configs.recommended.rules,
+      'react-refresh/only-export-components': [
+        'warn',
+        { allowConstantExport: true },
+      ],
+      'simple-import-sort/imports': 'error',
+      'simple-import-sort/exports': 'error',
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        { varsIgnorePattern: '^_', argsIgnorePattern: '^_' },
+      ],
+      'check-file/filename-naming-convention': [
+        'error',
+        { '**/!(App).{ts,tsx}': 'KEBAB_CASE' },
+        { ignoreMiddleExtensions: true },
+      ],
+      'check-file/folder-naming-convention': [
+        'error',
+        { 'src/**/!(__tests__)': 'KEBAB_CASE' },
+      ],
+    },
+  },
+  {
+    files: ['**/*.test.{ts,tsx}', '**/*.spec.{ts,tsx}'],
+    ...vitest.configs.recommended,
+  },
+  {
+    files: [
+      '*.config.{js,mjs,cjs,ts}',
+      'vite.config.ts',
+      'vitest.config.ts',
+      'playwright.config.ts',
+    ],
+    languageOptions: {
+      globals: {
+        ...globals.node,
+      },
+    },
+  },
+  prettier,
+])

package/tooling/web/configs/scripts/screenshot.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+: "${PREVIEW_PORT:=4173}"
+
+if curl -sSf "http://localhost:$PREVIEW_PORT/" >/dev/null 2>&1; then
+  echo "Port $PREVIEW_PORT already in use. Stop the listening process or set PREVIEW_PORT." >&2
+  exit 1
+fi
+
+bun run build
+bun run preview >/dev/null 2>&1 &
+PREVIEW_PID=$!
+trap 'kill "$PREVIEW_PID" 2>/dev/null; wait "$PREVIEW_PID" 2>/dev/null || true' EXIT
+
+for _ in $(seq 1 40); do
+  if curl -sSf "http://localhost:$PREVIEW_PORT/" >/dev/null 2>&1; then
+    break
+  fi
+  sleep 0.25
+done
+
+if ! curl -sSf "http://localhost:$PREVIEW_PORT/" >/dev/null 2>&1; then
+  echo "Preview server not responding on port $PREVIEW_PORT after 10s." >&2
+  exit 1
+fi
+
+SCREENSHOT_BASE_URL="http://localhost:$PREVIEW_PORT" bun e2e/screenshot.ts

package/tooling/web/configs/scripts/verify.sh

@@ -0,0 +1,80 @@
+#!/bin/bash
+set -e
+set -o pipefail
+
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+WHITE='\033[1;37m'
+GREY='\033[0;90m'
+NC='\033[0m'
+
+NESTED="${VERIFY_NESTED:-false}"
+
+log_info() { echo -e "${GREY}│${NC} ${GREEN}✓${NC} $1"; }
+log_error() {
+  echo -e "${GREY}│${NC} ${RED}✗${NC} $1"
+  exit 1
+}
+log_step() { echo -e "${GREY}│${NC}\n${GREY}├${NC} ${WHITE}$1${NC}"; }
+
+pipe_output() { while IFS= read -r line; do echo -e "${GREY}│${NC}  $line"; done; }
+
+check_dependencies() {
+  command -v bun >/dev/null 2>&1 || log_error "bun is not installed"
+}
+
+run_check() {
+  local cmd=$1
+  local err_msg=$2
+  local output
+  if ! output=$(eval "$cmd" 2>&1); then
+    echo "$output" | pipe_output
+    log_error "$err_msg"
+  fi
+  echo "$output" | pipe_output
+}
+
+main() {
+  check_dependencies
+
+  if [ "$NESTED" = false ]; then echo -e "${GREY}┌${NC}"; fi
+
+  echo -e "${GREY}├${NC} ${WHITE}Typecheck${NC}"
+  run_check "bun run typecheck" "Typecheck failed"
+  log_info "Typecheck passed"
+
+  log_step "Lint"
+  run_check "bun run lint" "Lint failed"
+  log_info "Lint passed"
+
+  log_step "Formatting"
+  run_check "bun run format" "Format failed"
+  log_info "Format applied"
+
+  log_step "Format check"
+  run_check "bun run check:format" "Format check failed"
+  log_info "Format check passed"
+
+  log_step "Spelling"
+  run_check "bun run check:spell" "Spell check failed"
+  log_info "Spell check passed"
+
+  log_step "Shell"
+  run_check "bun run check:shell" "Shell check failed"
+  log_info "Shell check passed"
+
+  log_step "Unit tests"
+  run_check "bun run test:run" "Unit tests failed"
+  log_info "Unit tests passed"
+
+  log_step "Build"
+  run_check "bun run build" "Build failed"
+  log_info "Build passed"
+
+  if [ "$NESTED" = false ]; then
+    echo -e "${GREY}└${NC}\n"
+    echo -e "${GREEN}✓ Verification passed${NC}"
+  fi
+}
+
+main "$@"

package/tooling/web/configs/scripts/worktree-port.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Prints a port for this working directory: the base itself in a normal
+# checkout, and the base plus a per-worktree offset in a linked git worktree,
+# so two worktrees of one repository never serve on one port. A folder left
+# behind after its worktree was removed is refused rather than served, since
+# every port it derives lands on the one the main checkout wanted.
+
+base="${1:-0}"
+band=50
+worktrees_dir=".claude/worktrees"
+
+refuse() {
+  echo "worktree-port: $1 is a leftover worktree folder, because $2." >&2
+  echo "worktree-port: a port derived here collides with the main checkout, so remove the folder, or set WORKTREE_PORT_OFFSET to serve from it anyway." >&2
+}
+
+offset() {
+  if [[ -n "${WORKTREE_PORT_OFFSET:-}" ]]; then
+    echo "$WORKTREE_PORT_OFFSET"
+    return
+  fi
+
+  local here git_dir common_dir toplevel dir name
+  here=$(pwd -P)
+
+  if ! git_dir=$(git rev-parse --git-dir 2>/dev/null); then
+    # Git refuses outright when a `.git` file names an administrative directory
+    # that is gone, which is what removing a worktree by hand leaves behind.
+    # Outside a repository there is no pointer at all and the base is correct.
+    dir=$here
+    while [[ "$dir" != / ]]; do
+      if [[ -f "$dir/.git" ]]; then
+        refuse "$dir" "its .git file names an administrative directory that is gone"
+        return 1
+      fi
+      [[ -d "$dir/.git" ]] && break
+      dir=$(dirname "$dir")
+    done
+    echo 0
+    return
+  fi
+
+  common_dir=$(git rev-parse --git-common-dir 2>/dev/null) || {
+    echo 0
+    return
+  }
+  toplevel=$(git rev-parse --show-toplevel 2>/dev/null) || {
+    echo 0
+    return
+  }
+  toplevel=$(cd "$toplevel" && pwd -P)
+
+  if [[ "$(cd "$git_dir" && pwd -P)" == "$(cd "$common_dir" && pwd -P)" ]]; then
+    # The main checkout answers here, and so does every directory under it,
+    # including a folder whose `.git` was deleted along with its worktree,
+    # since git then walks upward and reports the parent repository. Location
+    # is the only signal separating the two, so a directory sitting under the
+    # worktrees folder is refused rather than handed the base port.
+    if [[ "$here/" == "$toplevel/$worktrees_dir/"?* ]]; then
+      refuse "$here" "no worktree is registered for it"
+      return 1
+    fi
+    echo 0
+    return
+  fi
+
+  name=$(basename "$toplevel")
+  echo $(($(printf '%s' "$name" | cksum | cut -d' ' -f1) % band + 1))
+}
+
+value=$(offset) || exit 1
+echo $((base + value))

package/tooling/web/configs/src/test/setup.ts

@@ -0,0 +1,8 @@
+import '@testing-library/jest-dom'
+
+import { cleanup } from '@testing-library/react'
+import { afterEach } from 'vitest'
+
+afterEach(() => {
+  cleanup()
+})

package/tooling/web/manifest.toml

@@ -0,0 +1,58 @@
+[stack]
+name = "web"
+extends = "base"
+runtime = "bun"
+scaffold = ""
+
+[dependencies.dev]
+packages = [
+  "eslint@^9",
+  "eslint-config-prettier",
+  "eslint-plugin-check-file",
+  "eslint-plugin-react-hooks",
+  "eslint-plugin-react-refresh",
+  "eslint-plugin-simple-import-sort",
+  "eslint-plugin-vitest",
+  "globals",
+  "typescript-eslint",
+  "@eslint/js",
+  "typescript",
+  "react",
+  "react-dom",
+  "@types/react",
+  "@types/react-dom",
+  "@types/node",
+  "vitest@^3",
+  "@vitest/coverage-v8@^3",
+  "@vitest/ui@^3",
+  "jsdom",
+  "@testing-library/react",
+  "@testing-library/jest-dom",
+  "@testing-library/user-event",
+  "@playwright/test",
+  "tailwindcss",
+  "@tailwindcss/vite",
+  "prettier-plugin-tailwindcss",
+]
+
+[scripts]
+"lint" = "eslint . --max-warnings 0"
+"lint:fix" = "eslint . --fix --max-warnings 0"
+"test" = "vitest"
+"test:run" = "vitest run --reporter=verbose"
+"test:ui" = "vitest --ui"
+"test:coverage" = "vitest run --coverage"
+"test:e2e" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && playwright test"
+"test:e2e:changed" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && playwright test --only-changed"
+"test:e2e:ui" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && playwright test --ui"
+"test:e2e:report" = "playwright show-report"
+"check:full" = "./scripts/verify.sh && bun run test:e2e"
+
+[scripts.override]
+"screenshot" = "PREVIEW_PORT=$(bash scripts/worktree-port.sh 4173) && export PREVIEW_PORT && bash scripts/screenshot.sh"
+
+[gitignore]
+"# Build" = ["dist/"]
+"# Coverage" = ["coverage/"]
+"# Playwright" = ["test-results/", "playwright-report/", "blob-report/", "playwright/.cache/", "screenshots/"]
+"# VSCode" = [".vscode/*", "!.vscode/extensions.json", "!.vscode/settings.json"]