@erclx/canon 4.104.0 → 4.106.0

package/tooling/astro/configs/card-src/pages/og-card.astro

@@ -0,0 +1,98 @@
+---
+/**
+ * The social card as a route the project keeps, rather than a scratch page a
+ * render deletes. `canon capture` drives it through the server this config
+ * serves, so the composition reads the project's own stylesheet, tokens and
+ * fonts instead of carrying typed copies of each. Renaming the project is then
+ * an edit to one string here and a re-capture, not another pass through the
+ * pick loop with an operator in it.
+ *
+ * `canon:draft-identity` writes the picked composition into the `.card`
+ * element below and leaves everything around it alone. What ships is a working
+ * placeholder, so the route serves before any pick has been taken.
+ *
+ * The card is declared at half of 1200x630. `canon capture` opens every page at
+ * a fixed 2x device scale factor and screenshots the element at that scale, so
+ * a 600x315 element is what lands the captured PNG on the literal target size.
+ * Declaring it at 1200x630 captures at 2400x1260.
+ *
+ * `card.config.mjs` is the only config whose page router reaches this file, and
+ * `scripts/check-card-exclusion.sh` fails a build that carries the marker
+ * below, which is what keeps the route out of the published site.
+ */
+import '@/styles/global.css'
+
+// Retarget the import above when this project keeps its global stylesheet
+// somewhere else. An unresolved path refuses the card server by name, which is
+// the loud direction: a card captured against no stylesheet renders as an
+// unstyled box and reports success.
+---
+
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Social card</title>
+    <!-- Read by scripts/check-card-exclusion.sh. A build carrying this tag
+         published the card route. Do not reword it. -->
+    <meta name="og-card-marker" content="og-card-marker" />
+    <style>
+      body {
+        margin: 0;
+      }
+      .card {
+        box-sizing: border-box;
+        width: 600px;
+        height: 315px;
+        display: flex;
+        flex-direction: column;
+        justify-content: center;
+        gap: 0.5rem;
+        padding: 3rem;
+        /* These two names are what `canon design css` emits, so a project
+           carrying the design files resolves both and neither fallback fires.
+           A name the design system does not emit would take its fallback,
+           capture cleanly and report success, which is the silent failure this
+           route exists to close. Check the names against the stylesheet when
+           retargeting the import above.
+
+           Written as rgb() rather than hex so the shipped-reference gate does
+           not read a six-digit hex fallback as a pull request number. */
+        background: var(--color-background, rgb(255 255 255));
+        color: var(--color-text, rgb(17 17 17));
+        /* No font-family here on purpose. The design system emits no font
+           token, so the card inherits the project's own body font rather than
+           reading a custom property that does not exist. `canon capture` reads
+           the computed family off this element, so inheritance still gives it
+           a family to check and it refuses when that family cannot resolve. */
+      }
+      .mark {
+        width: 64px;
+        height: 64px;
+      }
+      .title {
+        margin: 0;
+        font-size: 2.25rem;
+        line-height: 1.1;
+      }
+      .tagline {
+        margin: 0;
+        font-size: 1.125rem;
+        opacity: 0.75;
+      }
+    </style>
+  </head>
+  <body>
+    <div class="card">
+      <svg
+        class="mark"
+        viewBox="0 0 64 64"
+        role="img"
+        aria-label="Project mark"
+      >
+        <rect width="64" height="64" rx="12" fill="currentColor"></rect>
+      </svg>
+      <h1 class="title">REPLACE_WITH_PROJECT_NAME</h1>
+      <p class="tagline">REPLACE_WITH_PROJECT_TAGLINE</p>
+    </div>
+  </body>
+</html>

package/tooling/astro/configs/card.config.mjs

@@ -0,0 +1,39 @@
+import react from '@astrojs/react'
+import tailwindcss from '@tailwindcss/vite'
+import { defineConfig } from 'astro/config'
+import path from 'path'
+
+const portOffset = Number(process.env.WORKTREE_PORT_OFFSET) || 0
+
+// Never read by `bun run build`. srcDir keeps this config's page router off
+// src/pages entirely, which is what excludes the social card from the published
+// build structurally rather than by a filename convention. A pageExtensions
+// regex over a filename was the alternative, and it leaks the moment a route is
+// renamed.
+//
+// The base port sits outside the band `astro.config.mjs` serves from, so a card
+// server and a dev server of one worktree never contend, and two worktrees
+// separate here the way they separate there.
+export default defineConfig({
+  srcDir: './card-src',
+  outDir: './card-dist',
+  publicDir: './public',
+  integrations: [react()],
+  server: {
+    port: 4421 + portOffset,
+  },
+  vite: {
+    plugins: [tailwindcss()],
+    resolve: {
+      alias: {
+        '@': path.resolve('./src'),
+      },
+    },
+    server: {
+      strictPort: true,
+    },
+    preview: {
+      strictPort: true,
+    },
+  },
+})

package/tooling/astro/configs/scripts/check-card-exclusion.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+set -e
+set -o pipefail
+
+# `card.config.mjs` keeps the social card route out of the published build by
+# never pointing its srcDir at it. A later config change that widens srcDir, or
+# a card file moving under src/pages/, would publish a half-size scaffolding
+# page to a live domain with every other check still green.
+#
+# The card route has three consumers: the card server reads it, the capture
+# reads it, and the published build must not carry it. This is the only one of
+# the three a check can enforce, so the route's exclusion is a check rather than
+# a convention.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/.." && pwd)}"
+
+DIST="$PROJECT_ROOT/dist"
+CARD_CONFIG="$PROJECT_ROOT/card.config.mjs"
+MARKER='name="og-card-marker"'
+
+# No card route installed, so there is nothing to exclude. Reported rather than
+# passed silently, since a check that says nothing is indistinguishable from one
+# that looked and found nothing.
+if [ ! -f "$CARD_CONFIG" ]; then
+  echo "check-card-exclusion: no card.config.mjs, so no card route to exclude"
+  exit 0
+fi
+
+# Nothing to grep without a build. Callers run this after `bun run build`, so an
+# absent dist here means the build itself failed rather than something this
+# check can verify.
+if [ ! -d "$DIST" ]; then
+  echo "No $DIST. Run bun run build first." >&2
+  exit 1
+fi
+
+# The marker is a fixed <meta> tag the card route carries for exactly this, so
+# asserting it survives in the route's own source is what turns a dropped marker
+# into a loud failure here rather than a blind spot in the test below. A prose
+# notice is not load-bearing: rewording it silently retires the leak check it
+# backed with every workflow still green.
+if ! grep -rl "$MARKER" "$PROJECT_ROOT/card-src" >/dev/null 2>&1; then
+  echo "No $MARKER under $PROJECT_ROOT/card-src. The card route dropped its own marker, which is what the leak test below reads for." >&2
+  exit 1
+fi
+
+if grep -rl "$MARKER" "$DIST" >/dev/null 2>&1; then
+  echo "The card route's marker ($MARKER) reached $DIST. See card.config.mjs's srcDir." >&2
+  exit 1
+fi
+
+if find "$DIST" -iname '*og-card*' | grep -q .; then
+  echo "A file named for the card route reached $DIST. See card.config.mjs's srcDir." >&2
+  exit 1
+fi
+
+echo "check-card-exclusion: card marker present in card-src, absent from $DIST"

package/tooling/astro/manifest.toml

@@ -21,6 +21,8 @@ packages = [
 "astro" = "astro"
 "typecheck" = "astro check"
 "setup" = "./scripts/setup.sh"
+"card:dev" = "WORKTREE_PORT_OFFSET=$(bash scripts/worktree-port.sh) && export WORKTREE_PORT_OFFSET && astro dev --config card.config.mjs"
+"card:check" = "bash scripts/check-card-exclusion.sh"
 
 [scripts.override]
 "screenshot" = "PREVIEW_PORT=$(bash scripts/worktree-port.sh 4321) && export PREVIEW_PORT && bash scripts/screenshot.sh"
@@ -30,6 +32,7 @@ packages = [
 
 [gitignore]
 "# Astro" = [".astro/"]
+"# Social card" = ["card-dist/"]
 
 [verify]
 prepare = "bunx astro add react --yes"

package/tooling/astro/reference.md

@@ -21,6 +21,7 @@ The astro stack covers Astro + TypeScript projects: content sites, marketing sit
 - `vitest.config.ts`: uses `getViteConfig` from `astro/config` (not `mergeConfig`). jsdom, globals, setup file, `passWithNoTests: true`, v8 coverage, `**/*.astro` in coverage excludes.
 - `playwright.config.ts`: all browsers, `webServer` runs `bun run build && bun run preview` on port `4321` plus `WORKTREE_PORT_OFFSET`, `reuseExistingServer: false`. Astro's dev/prod gap is wide (MDX, island hydration, asset optimization), so E2E always tests the built `dist/`. `DIST_PREBUILT` set in the environment drops the `build` half, running `bun run preview` alone against a `dist/` a prior CI job already produced.
 - `tsconfig.json`: extends `astro/tsconfigs/strict`, adds `skipLibCheck`, `vitest/globals` and `@testing-library/jest-dom` in types, `@/` paths.
+- `card.config.mjs`, `card-src/pages/og-card.astro`, and `scripts/check-card-exclusion.sh`: the social card route, its structural build exclusion, and the check enforcing it. See `## Social card route` below.
 - `eslint.config.js`: overrides the web layer. Adds `eslint-plugin-astro` (`.astro` parser via `astro-eslint-parser`). React-hooks scoped to `.jsx`/`.tsx` only (`.astro` is not React). The shared block's `files` selector includes `.astro`, so `check-file/filename-naming-convention` reaches `.ts`, `.tsx`, and `.astro` under `KEBAB_CASE`, overriding Astro's own PascalCase component convention deliberately, on the ground that a component's name in markup comes from the import binding rather than the filename. `.js` and `.jsx` stay out of the rule's own pattern, matching `web` and `nextjs`. `check-file/folder-naming-convention` reaches every `src/**` folder except `__tests__` and the whole `pages/` subtree, which carries its own off-block for the bracket-named dynamic routes and nested slug folders Astro's file-based routing produces. See `canon/context/tooling.md` for the measurement.
 
 ## Typecheck
@@ -59,11 +60,37 @@ Append to the `## Scripts` table:
 
 In `canon/context/ci.md`, the Typecheck row's assertion reads: `` `astro check` passes ``. The Build row's assertion reads: `` `astro build` succeeds ``.
 
+## Social card route
+
+The social card is a route the project keeps rather than a page a render writes and deletes, so re-rendering it after a rename is an edit to one string and a re-capture instead of another pass through `draft-identity`'s pick loop with an operator in it. `canon:draft-identity` writes the picked composition into the route and captures it through the server below.
+
+### What ships
+
+- `card.config.mjs`: a second Astro config whose `srcDir` points at `./card-src`, which the main config's page router never reads. That is what excludes the card from the published build structurally rather than by a filename convention, the same mechanism `scenarios.astro` reaches for with `import.meta.env.DEV`. Its base port is `4421` plus `WORKTREE_PORT_OFFSET`, outside the band `astro.config.mjs` serves from, so a card server and a dev server of one worktree never contend.
+- `card-src/pages/og-card.astro`: the route, shipped as a working placeholder so it serves before any pick has been taken. It imports the project's own global stylesheet, which is what lets the composition read real tokens and real fonts instead of typed copies. It reads `--color-background` and `--color-text`, the names `canon design css` emits, and sets no `font-family` at all so the card inherits the project's body font rather than reading a font token the design system does not emit.
+- `scripts/check-card-exclusion.sh`: fails when the route's `<meta name="og-card-marker">` tag reaches `dist/`, and fails when the route dropped that tag, since the marker is what the leak test reads for.
+- `bun run card:dev` serves the route. `bun run card:check` runs the exclusion check, which the web layer's `scripts/verify.sh` also runs after its build stage whenever the script is installed.
+
+### Why each piece is shaped that way
+
+The stylesheet import points at `@/styles/global.css`. A project keeping its stylesheet elsewhere retargets that one line, and an unresolved path then refuses the card server by name, which is the loud direction rather than the convenient one. The quiet failure it replaces is a card captured against no stylesheet at all: it renders as an unstyled box and reports success.
+
+A custom property the stylesheet does not define is the same silent failure in a second costume. It takes its fallback, captures cleanly and reports success, so the card ships on typed values while reading as though it read real ones. That is why the route names only properties `canon design css` emits, and why a project retargeting the stylesheet import checks the names against what its own stylesheet defines.
+
+The exclusion is a check rather than a convention because the route has three consumers and only one of them can be enforced. The card server reads it, the capture reads it, and the published build must not carry it.
+
+`.card` is declared at 600x315, half of the 1200x630 target. `canon capture` opens every page at a fixed 2x device scale factor with no flag to change it, so a half-size element is what lands the captured PNG on the literal size. Declaring it at 1200x630 captures at 2400x1260.
+
+### Why v1 is Astro-only
+
+Astro is the one web stack whose config gives a route a structural build exclusion. Next's App Router has no build-time route exclusion at all, and it needs none on the path it will take, since `ImageResponse` is that framework's own production mechanism and a card route there is meant to be served. `vite-react` builds a single-page app with no page router, so a card is a second Rollup entry rather than a route.
+
 ## Gitignore (extend)
 
 `[gitignore]` groups this stack edits, restated here per the manifest-to-reference symmetry:
 
 - `"# Astro" = [".astro/"]`
+- `"# Social card" = ["card-dist/"]`
 
 ## Scenario switcher
 

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

@@ -71,6 +71,15 @@ main() {
   run_check "bun run build" "Build failed"
   log_info "Build passed"
 
+  # Runs whenever the stack shipped a card exclusion check, which keeps the
+  # stage stack-agnostic here and the check itself in the stack that owns the
+  # card route's shape. It reads the build above, so it sits after it.
+  if [ -f scripts/check-card-exclusion.sh ]; then
+    log_step "Card exclusion"
+    run_check "bash scripts/check-card-exclusion.sh" "Card exclusion check failed"
+    log_info "Card exclusion passed"
+  fi
+
   if [ "$NESTED" = false ]; then
     echo -e "${GREY}└${NC}\n"
     echo -e "${GREEN}✓ Verification passed${NC}"

package/tooling/web/reference.md

@@ -19,7 +19,7 @@ Golden config files live in `tooling/web/configs/` and are copied into the targe
 - `.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/ci/700-ci-workflow.md` states the test.
 - `.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.
+- `scripts/verify.sh`: extends base verify with typecheck, lint, unit tests, and build in the full order. Its last stage runs `scripts/check-card-exclusion.sh` whenever that file is installed, which puts the social card route's build exclusion on the default path rather than behind a flag nobody passes. The stage tests for the script rather than for a framework, so this layer owns when the check runs and the stack shipping a card route owns what it reads. The astro reference carries the route itself.
 - `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.
 
 ## What stays in per-stack adapters
@@ -128,4 +128,6 @@ The sweep under `screenshots/` is ignored again, and only a flagged case's `evid
 
 ## Verify script
 
-The web layer's `scripts/verify.sh` replaces the base version. Order: typecheck, lint, format, spelling, shell, unit tests, build. Stack adapters may override if their typecheck or build differs.
+The web layer's `scripts/verify.sh` replaces the base version. Order: typecheck, lint, format, spelling, shell, unit tests, build, then the card exclusion check where one is installed. Stack adapters may override if their typecheck or build differs.
+
+The card stage is conditional on `scripts/check-card-exclusion.sh` existing rather than on the stack, so a project with no card route runs one less stage and needs no override to skip it. A stack that ships a card route ships that script, and the check reads the build the stage before it produced.