@erclx/canon 5.35.0 → 5.37.0

package/tooling/claude/seeds/canon/DESIGN.md

@@ -1,57 +1,44 @@
 # Design
 
-Authoring guidance: the design standard.
+Authoring guidance: the design standard. Values live in `<your stylesheet>`, such as `src/styles/tokens.css` or a Tailwind `@theme` block. A project with none writes them under `.claude/design/project/`, beside the installed base stylesheet.
 
-## Personality
+## Overview
 
 One paragraph. Voice, tone, and the feeling a user should have. The same content a design intake form asks for.
 
-## Color
+## Colors
 
-One row per role. Intent is a short phrase a human can picture. Value is a hex or a named system token.
+Up to three rules a developer could get wrong.
 
-| Role       | Intent                        | Value |
-| ---------- | ----------------------------- | ----- |
-| background | page canvas                   |       |
-| surface    | cards, panels, raised blocks  |       |
-| text       | primary body text             |       |
-| muted      | secondary text, captions      |       |
-| accent     | links, primary action         |       |
-| success    | confirmations, positive state |       |
-| warning    | cautions, pending state       |       |
-| error      | failures, destructive action  |       |
+One row per role, naming its custom property. Intent is a short phrase a human can picture.
 
-## Typography
+| Role       | Property             | Intent                        |
+| ---------- | -------------------- | ----------------------------- |
+| background | `--color-background` | page canvas                   |
+| surface    | `--color-surface`    | cards, panels, raised blocks  |
+| text       | `--color-text`       | primary body text             |
+| muted      | `--color-muted`      | secondary text, captions      |
+| accent     | `--color-accent`     | links, primary action         |
+| success    | `--color-success`    | confirmations, positive state |
+| warning    | `--color-warning`    | cautions, pending state       |
+| error      | `--color-error`      | failures, destructive action  |
 
-One row per role. Size and line height in pixels or rem. Family names use their product casing.
+## Typography
 
-| Role    | Family | Weight | Size | Line height |
-| ------- | ------ | ------ | ---- | ----------- |
-| display |        |        |      |             |
-| heading |        |        |      |             |
-| body    |        |        |      |             |
-| label   |        |        |      |             |
-| code    |        |        |      |             |
+Up to three rules. How the roles divide between families, and any role that breaks the pattern.
 
 ## Spacing
 
-Base unit and scale. The renderer draws a swatch per step.
+One line. The base unit and how the scale steps.
 
-| Step | Multiplier | Value |
-| ---- | ---------- | ----- |
-| xs   | 0.5        |       |
-| sm   | 1          |       |
-| md   | 2          |       |
-| lg   | 3          |       |
-| xl   | 5          |       |
+## Shapes
 
-## Borders
+One row per role, naming its radius property.
 
-| Role    | Radius | Width | When used             |
-| ------- | ------ | ----- | --------------------- |
-| default |        |       | cards, inputs         |
-| pill    |        |       | tags, status chips    |
-| none    | 0      | 0     | edge-to-edge surfaces |
+| Role    | Property           | When used          |
+| ------- | ------------------ | ------------------ |
+| default | `--radius-default` | cards, inputs      |
+| pill    | `--radius-pill`    | tags, status chips |
 
 ## Motion
 

package/tooling/shell/configs/.github/workflows/shell.yml

@@ -0,0 +1,30 @@
+name: Shell
+# canon-no-seed: an add-on stack's workflow with no root counterpart by design, since the toolkit checks its own shell inside verify.yml.
+
+on:
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  shell-checks:
+    name: 🐚 Shell Checks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - 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: Check Shell
+        run: bun run check:shell

package/tooling/shell/manifest.toml

@@ -0,0 +1,12 @@
+[stack]
+name = "shell"
+extends = ""
+runtime = "bun"
+scaffold = ""
+
+[sync]
+source = "configs"
+
+[scripts]
+"check:shell" = "find scripts -name '*.sh' -exec shfmt --diff --indent 2 {} + && find scripts -name '*.sh' -exec shellcheck --severity=warning {} +"
+"format:shell" = "find scripts -name '*.sh' -exec shfmt --write --indent 2 {} +"

package/tooling/shell/reference.md

@@ -0,0 +1,46 @@
+# Tooling shell reference
+
+## Overview
+
+The shell stack is an add-on that formats and lints the shell scripts a project writes. It extends nothing and syncs beside any other stack at the same root with `canon tooling sync shell . --write`, so a project that writes no shell never installs shfmt or shellcheck.
+
+## Install
+
+- Install `shfmt` and `shellcheck` by hand, through `sudo apt-get install shfmt shellcheck` or `brew install shfmt shellcheck`. Injection runs only `bun add -D`, and neither tool ships through the registry.
+- `scripts/verify.ts` probes both before the `Shell` phase and names the install command when one is missing, rather than letting `find` report a missing executable.
+
+## shfmt
+
+- Indent with 2 spaces, set through `--indent 2` on every call.
+- `.editorconfig` carries an `[*.sh]` block with `indent_style = space` and `indent_size = 2`, so the editor and shfmt agree. Dropping the block because shfmt already sets indentation produces spurious diffs.
+
+## shellcheck
+
+- Run at warning severity.
+- `.shellcheckrc` sets `external-sources=true`, which shellcheck needs to follow `source` directives.
+
+## Coverage
+
+- Both tools take their files from `find scripts -name '*.sh'`, since `scripts/` can mix shell with TypeScript and shellcheck has no directory mode.
+- A shell script with a shebang and no `.sh` extension is covered by neither, so give it the extension.
+- Keep shell scripts in `scripts/`. A `.sh` file elsewhere, such as a seeded `.claude/hooks/` script, is left out on purpose.
+
+## Verify
+
+- `scripts/verify.ts` runs `check:shell` in its `Shell` phase wherever `package.json` declares it, between the format check and the unit tests. No stack's `scripts/verify.json` requires it, so a folder that never synced this stack skips the phase.
+
+## lint-staged
+
+- `.lintstagedrc` is a base seed this stack cannot reach once written. Add a `**/*.sh` entry by hand, running `shfmt --write --indent 2` then `shellcheck --severity=warning`, to run the checks on commit.
+- Do NOT copy that glob into a `package.json` script. lint-staged expands its own globs and passes matched files as arguments, which a bare shell script does not.
+
+## CI
+
+- `.github/workflows/shell.yml` runs on pull requests targeting `main` and on `workflow_dispatch`: checkout, setup Bun, `bun install --frozen-lockfile`, install both tools through apt, then `check:shell`.
+
+## CLI
+
+| Script                 | What it does                                                    |
+| ---------------------- | --------------------------------------------------------------- |
+| `bun run check:shell`  | Asserts shfmt formatting, then runs shellcheck at warning level |
+| `bun run format:shell` | Writes shfmt formatting in place                                |

package/tooling/vite-react/configs/tsconfig.json

@@ -18,7 +18,7 @@
     "types": [
       "vite/client",
       "vitest/globals",
-      "@testing-library/jest-dom",
+      "@testing-library/jest-dom/vitest",
       "node"
     ],
     "paths": {

package/tooling/vite-react/configs/vitest.config.ts

@@ -1,6 +1,6 @@
 import { defineConfig, mergeConfig } from 'vitest/config'
 
-import viteConfig from './vite.config'
+import viteConfig from './vite.config.ts'
 
 export default mergeConfig(
   viteConfig,

package/tooling/vite-react/manifest.toml

@@ -15,7 +15,6 @@ packages = [
 "build" = "tsc --noEmit && vite build"
 "preview" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && vite preview"
 "typecheck" = "tsc --noEmit"
-"setup" = "./scripts/setup.sh"
 
 [scripts.override]
 "build" = "tsc --noEmit && vite build"

package/tooling/vite-react/reference.md

@@ -17,9 +17,9 @@ The vite-react stack covers Vite + React + TypeScript projects: web apps and Chr
 ## 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.
+- `vitest.config.ts`: merges from `vite.config.ts` (imported with its `.ts` extension, which Vite 8 requires), 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.
+- `tsconfig.json`: unified, `noEmit: true`, `skipLibCheck: true`, `@/` paths, `vitest/globals` and `@testing-library/jest-dom/vitest` in types.
 
 ## Chrome extension variant
 
@@ -33,14 +33,6 @@ When scaffolding a Chrome extension, override the installed golden configs:
 - `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:

package/tooling/web/configs/.github/workflows/readme-screenshot.yml

@@ -95,11 +95,9 @@ jobs:
         # and stops here without pushing a second time.
         if: steps.diff.outputs.changed == 'true'
         # The hooks are off because this commit carries nothing they can read.
-        # `pre-push` runs the full verify, whose format step shells out to
-        # `shfmt`, which the runner does not install, so a push through them
-        # exits 127. The jobs in verify.yml already run those checks against
-        # the source, and what this step pushes is PNG bytes a capture
-        # produced.
+        # `pre-push` runs the full verify, which reruns every check the jobs
+        # in verify.yml already ran against the source, and what this step
+        # pushes is PNG bytes a capture produced.
         env:
           HUSKY: 0
         run: |

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

@@ -30,9 +30,6 @@ jobs:
       - 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
 
@@ -42,9 +39,6 @@ jobs:
       - name: Check Formatting
         run: bun run check:format
 
-      - name: Check Shell
-        run: bun run check:shell
-
   unit-tests:
     name: 🧪 Unit Tests
     runs-on: ubuntu-latest

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

@@ -1,4 +1,4 @@
-import '@testing-library/jest-dom'
+import '@testing-library/jest-dom/vitest'
 
 import { cleanup } from '@testing-library/react'
 import { afterEach } from 'vitest'

package/tooling/web/manifest.toml

@@ -22,9 +22,9 @@ packages = [
   "@types/react",
   "@types/react-dom",
   "@types/node",
-  "vitest@^3",
-  "@vitest/coverage-v8@^3",
-  "@vitest/ui@^3",
+  "vitest@^5",
+  "@vitest/coverage-v8@^5",
+  "@vitest/ui@^5",
   "jsdom",
   "@testing-library/react",
   "@testing-library/jest-dom",
@@ -46,7 +46,7 @@ packages = [
 "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"
+"check:full" = "bun scripts/verify.ts && bun run test:e2e"
 "smoke:prod" = "bun e2e/screenshot.ts --check-console-clean --require-base-url"
 
 [scripts.override]

package/tooling/web/reference.md

@@ -11,12 +11,12 @@ The web layer covers web-universal tooling shared across Vite + React, Astro, an
 Golden config files live in `tooling/web/configs/` and are copied into the target on `canon tooling sync web . --write`, replacing whatever sits at those paths. They are the source of truth. The reference covers rationale and tradeoffs. Configs show the concrete setup.
 
 - `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.
+- `src/test/setup.ts`: `@testing-library/jest-dom/vitest` import, `cleanup` after each test.
 - `e2e/screenshot.ts`: capture template. A single `CASES` record at the top carries one entry per output file, each naming a section, a theme, and a route, and the loop below crosses every case with the `VIEWPORTS` array and writes `screenshots/<hostname>/<section>/<width>--<theme>.png`, keyed on `SCREENSHOT_BASE_URL`'s hostname so a local and a deployed run land in different folders. `VIEWPORTS` holds four breakpoint buckets named by width, 320, 768, 1280 and 1536, with 320 as the base a page has to hold without wrapping or clipping. A case flagged `evidence: true` additionally writes `evidence/<section>/<width>--<theme>.png`, with no hostname segment, at the viewports flagged `evidence` alone, which are 320 and 1280. Committing all four multiplies the tracked frames by the width count, so the flag is what keeps the tracked set at twice the sections rather than four times. A case may name `excludeViewports` to skip a width, for a route whose long-form prose reflows at 320 instead of breaking. `SCREENSHOT_FILTER` narrows a run to the cases whose label, `<section>/<width>--<theme>`, contains any comma-separated term, exits 1 when nothing matches and lists the labels that exist, and leaves the rest of the sweep alone. `--require-base-url` skips a flagged case entirely, so a production smoke run neither writes to the committed path nor counts an evidence route in its console-clean check, and exits 1 when that leaves zero cases run, so flagging every case cannot silence the production check without saying so. Per-project cases extend the one record. A route's widths and themes sit together under its section folder, so the filename carries both. A case may also name `sections`, one `{ name, selector }` per addressable part of the route, and each writes its own frame at `screenshots/<hostname>/<section>/<name>/<width>--<theme>.png` beside the whole-page one, plus `evidence/<section>/<name>/<width>--<theme>.png` where the case is flagged and the width carries `evidence`. The field is optional, so a case that names none captures the page alone as before, and a selector matching nothing is reported and skipped rather than raised, since `CASES` is a template a project rewrites and a target that syncs this file before editing its own list would otherwise capture nothing at all. Testing that every named section resolves belongs to the project that owns the selectors, beside its own page. A case may also name `mask`, a list of selectors whose boxes are painted over in every frame the case writes, whole-page and section alike, for a value that moves between runs with no code change, so a double capture still compares everything else. A mask selector matching nothing is reported and skipped the same way. Every case settles before anything is shot: the context is created with `reducedMotion: 'reduce'`, each named section is scrolled into view so an `IntersectionObserver` fires and a frame marked `loading="lazy"` loads, the page returns to the top, and fonts, images and same-origin frames are waited out on a bounded condition rather than on a second `networkidle`, which is a lifecycle event of the navigation and does not re-arm for a load a scroll started. A section frame drops the page's floating chrome, being whatever computes to `position: sticky` or `fixed`, because a section taller than the viewport is scrolled into view to be cut and a sticky bar otherwise rides that scroll into the middle of the frame. The whole-page frame is shot first and keeps its chrome. `--check-console-clean` collects `console`-level error messages per case and exits 1 with the list if any fired, turning the capture into a smoke check. `--require-base-url` exits 1 before launching a browser when `SCREENSHOT_BASE_URL` is unset, guarding a script meant to run against a real deployment from silently capturing `localhost`.
 - `scripts/screenshot.sh`: sources `scripts/lib/preview-server.sh`, then runs the capture against the served preview.
 - `scripts/lib/preview-server.sh`: sourced, never executed. Builds, serves on `PREVIEW_PORT`, blocks until the port answers, and traps the whole process group on exit, including the detached grandchild `lsof` finds. Both capture scripts source it so the startup lives once.
 - `scripts/readme-screenshot.sh`: captures one case under `SCREENSHOT_FILTER` and copies its light and dark frames to `assets/evidence/readme/`. `README_FILTER` ships empty with `header/1280` as its example, and the script exits 1 until a project fills it, since a shipped default would capture the wrong part of the page in every project but one. Its copy reads from `screenshots/<hostname>/`, which is where the harness writes.
-- `.github/workflows/readme-screenshot.yml`: refreshes that frame on a pull request and commits it back to the branch. The path list ships as `REPLACE_WITH_PROJECT_PATHS`, and the job's first step after checkout exits 1 while it stays, since a job that never fires leaves no run and no diff to notice. The workflow's own path is in the list so the installing pull request reaches that step. When a commit-back is right and when a report is, `governance/rules/tooling/700-ci-workflow.md` states the test.
+- `.github/workflows/readme-screenshot.yml`: refreshes that frame on a pull request and commits it back to the branch. The path list ships as `REPLACE_WITH_PROJECT_PATHS`, and the job's first step after checkout exits 1 while it stays, since a job that never fires leaves no run and no diff to notice. The workflow's own path is in the list so the installing pull request reaches that step. When a commit-back is right and when a report is, `governance/rules/tooling/ci-workflow.md` states the test.
 - `.github/workflows/verify.yml`: `static-checks`, `unit-tests`, `build-verify`, and `e2e-tests` jobs.
 - `scripts/verify.json`: the phases base's verify runner requires here, being typecheck, lint, unit tests, and build. `## Verify script` covers the order and the card exclusion stage.
 - `scripts/worktree-port.sh`: prints a base port plus this working directory's offset. Called with no argument it prints the offset alone. It refuses a folder left under the worktrees directory after its worktree was removed, rather than printing a port for it.
@@ -113,7 +113,7 @@ Append rows:
 
 `canon 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 surface changes. It now fires on every component file too, reversing the route-and-page-only scope this reference once described, after a shipped batch of components carried no capture and a defect went unseen. The rule body states its own exemption for a component the production build strips out, so a reader chasing that case reads it there rather than here.
+`governance/rules/ui/surface-capture.md` is what asks a session to run the capture after a surface changes. It now fires on every component file too, reversing the route-and-page-only scope this reference once described, after a shipped batch of components carried no capture and a defect went unseen. The rule body states its own exemption for a component the production build strips out, so a reader chasing that case reads it there rather than here.
 
 The sweep under `screenshots/` is ignored again, and only a flagged case's `evidence/` output tracks in git, so the first capture a scaffolded target runs after this change is the baseline it commits there. A case naming sections commits a folder per section under that baseline rather than one file per theme, which is what lets a pull request comparison land on the part of the page that moved instead of on one image of the whole of it. The count is the section list times the themes, so a list is worth sizing against how many frames each later change has to regenerate and a reviewer has to read.
 
@@ -126,6 +126,6 @@ The sweep under `screenshots/` is ignored again, and only a flagged case's `evid
 
 ## Verify script
 
-The web layer's `scripts/verify.json` requires `typecheck`, `lint`, `test:run`, and `build`, and base's `scripts/verify.ts` runs them in its fixed order: typecheck, lint, format, shell, unit tests, build, markdown bans, then the card exclusion check where one is installed. astro, vite-react, and nextjs inherit the list, since the nearest stack's copy wins. An adapter whose phases differ ships its own `verify.json` rather than a script.
+The web layer's `scripts/verify.json` requires `typecheck`, `lint`, `test:run`, and `build`, and base's `scripts/verify.ts` runs them in its fixed order: typecheck, lint, format, shell where the `shell` stack declares it, unit tests, build, markdown bans, then the card exclusion check where one is installed. astro, vite-react, and nextjs inherit the list, since the nearest stack's copy wins. An adapter whose phases differ ships its own `verify.json` rather than a script.
 
 The card stage runs `scripts/check-card-exclusion.sh` whenever that file is installed, which keeps the social card route's build exclusion on the default path rather than behind a flag. It tests for the script rather than the stack, so a project with no card route runs one less stage with no override, and the stack shipping a card route owns what the check reads, being the build the stage before it produced. The astro reference carries the route itself.

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

@@ -1,2 +0,0 @@
-#!/bin/bash
-exec bun "$(dirname "$0")/verify.ts" "$@"