@epilot/volt-ui-experimental-griffel 0.2.3 → 0.3.0

package/scripts/migration-diagnostics.mjs

@@ -0,0 +1,353 @@
+/**
+ * fs-bound migration-diagnostics ORCHESTRATION for a migrated (v1 -> Griffel) consumer tree —
+ * directory/file walking, symlink boundary checks, hashing, package identity resolution, and
+ * TypeScript resolution from the local filesystem. The actual rule logic (what counts as a
+ * defect) lives in the sibling `migration-diagnostics-core.mjs`, which this module delegates every
+ * read file to via `analyzeSource` — see that module for the rule catalogue and the
+ * supported-analysis-boundary documentation. This split exists so a future non-fs caller (e.g. a
+ * remote tool analyzing a submitted string) can reuse the identical rule implementation without
+ * pulling in any of this module's filesystem/process access (WP6B-2 extraction — see
+ * `WP6B-DECISION-CORE-EXTRACTION.md`; no such caller is wired up yet).
+ *
+ * Used by the CLI wrapper (`migration-sweep.mjs`) and by tests. Importing this module has no
+ * side effects (no process.exit, no argv parsing, no eager TypeScript import — see below).
+ *
+ * TypeScript itself is resolved LAZILY from the consumer's own installation (see
+ * `resolveConsumerTypeScript`) — this package does not depend on or bundle `typescript` at
+ * runtime. If it cannot be resolved, rules `legacy-volt-class` and `hand-written-volt-css-var`
+ * (pure text, no TypeScript needed) still run; `unestablished-palette-install` is skipped with an
+ * explicit, actionable note rather than crashing the whole scan.
+ */
+import { createHash } from "node:crypto"
+import { createRequire } from "node:module"
+import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs"
+import { join, relative } from "node:path"
+import { pathToFileURL } from "node:url"
+
+import { analyzeSource, makeFinding, RULES, SCRIPT_EXT_RE } from "./migration-diagnostics-core.mjs"
+
+// Re-exported so existing imports of `RULES` from this module keep working unchanged — the rule
+// catalogue itself now lives in the core (single source of truth), per WP6B-2.
+export { RULES }
+
+// ---------------------------------------------------------------------------
+// Package/token-family identity — derived from the built package, never hardcoded
+// ---------------------------------------------------------------------------
+
+function sha256(content) {
+  return createHash("sha256").update(content).digest("hex")
+}
+
+function readGeneratedFamilies(packageDir, file) {
+  const full = join(packageDir, "dist/tokens", file)
+  if (!existsSync(full)) {
+    throw new Error(
+      `Missing generated token file: dist/tokens/${file} under ${packageDir}. The package is not built — run \`bun run build\` there first.`
+    )
+  }
+  const content = readFileSync(full, "utf8")
+  const families = new Set([...content.matchAll(/--volt2-[a-z0-9]+-([a-z]+)-/g)].map((m) => m[1]))
+  if (families.size === 0) {
+    throw new Error(
+      `Generated token file dist/tokens/${file} under ${packageDir} contains no recognizable family declarations. ` +
+        "It exists but is empty or malformed (does not match the expected --volt2-<hash>-<family>- pattern) — " +
+        "the package build is likely stale or broken. Re-run `bun run build` there, do not proceed with an empty family set."
+    )
+  }
+  return { families, content }
+}
+
+/**
+ * Resolves package name/version, its core/palette token family sets, and a deterministic hash of
+ * the generated-token inputs those sets were read from, from a built package directory. Throws
+ * (never silently falls back to empty sets) on a missing/unreadable package.json, missing
+ * generated token files, or generated files with no recognizable family declarations — "invalid
+ * package selection" is a hard error, not a quietly-disabled rule.
+ */
+export function resolvePackageIdentity(packageDir) {
+  const pkgJsonPath = join(packageDir, "package.json")
+  if (!existsSync(pkgJsonPath)) {
+    throw new Error(`Invalid package selection: no package.json at ${packageDir}`)
+  }
+  let pkgJson
+  try {
+    pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf8"))
+  } catch (err) {
+    throw new Error(`Invalid package selection: could not parse ${pkgJsonPath}: ${err.message}`)
+  }
+  if (!pkgJson.name || !pkgJson.version) {
+    throw new Error(`Invalid package selection: ${pkgJsonPath} is missing "name" or "version"`)
+  }
+
+  const coreRead = readGeneratedFamilies(packageDir, "core.generated.js")
+  const paletteRead = readGeneratedFamilies(packageDir, "palette.generated.js")
+  const core = coreRead.families
+  const palette = new Set([...paletteRead.families].filter((f) => !core.has(f)))
+  const generatedInputHash = sha256(`${coreRead.content}\u0000${paletteRead.content}`)
+
+  return {
+    packageDir,
+    packageName: pkgJson.name,
+    packageVersion: pkgJson.version,
+    core,
+    palette,
+    generatedInputHash,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// TypeScript — lazily resolved from the consumer's own installation, never bundled/depended-on
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolves `typescript` using Node's own module resolution, searching from each of `searchRoots`
+ * in order (first match wins). Never installs anything. Throws a clear, actionable error — never
+ * a cryptic MODULE_NOT_FOUND — naming exactly what to do, if none of the roots have it.
+ */
+export async function resolveConsumerTypeScript(searchRoots) {
+  const roots = searchRoots.filter(Boolean)
+  const req = createRequire(join(roots[0] ?? process.cwd(), "noop-resolver.cjs"))
+  let tsPath
+  for (const root of roots) {
+    try {
+      tsPath = req.resolve("typescript", { paths: [root] })
+      break
+    } catch {
+      // try the next root
+    }
+  }
+  if (!tsPath) {
+    throw new Error(
+      'Could not resolve a "typescript" installation from: ' +
+        roots.join(", ") +
+        '. The "unestablished-palette-install" rule parses source with your project\'s own TypeScript — ' +
+        "it is not bundled with this package. Install it as a devDependency in the project being scanned " +
+        "(`npm install -D typescript` or `bun add -d typescript`) and re-run. " +
+        "legacy-volt-class and hand-written-volt-css-var do not need TypeScript and are unaffected."
+    )
+  }
+  const mod = await import(pathToFileURL(tsPath).href)
+  return { ts: mod.default ?? mod, tsPath }
+}
+
+// ---------------------------------------------------------------------------
+// File walking
+// ---------------------------------------------------------------------------
+
+const SCAN_EXT_RE = /\.(tsx?|jsx?|s?css)$/
+/** `*.generated.*` build output — the generator's own emitted source of truth, never
+ * "hand-written" by a consumer. See §4 of the WP6A report. */
+const GENERATED_FILE_RE = /\.generated\.[a-z]+$/i
+/** A leading `/* GENERATED ... *\/` / `// GENERATED ...` marker — this repo's own convention
+ * (`packages/tokens/scripts/build.ts`), and common generally; catches generated files that don't
+ * follow the filename convention (e.g. tokens/index.ts). */
+const GENERATED_HEADER_RE = /^\s*(\/\*|\/\/|<!--)\s*generated\b/i
+
+function isExcluded(rel, excludes) {
+  return excludes.some((ex) => rel === ex || rel.startsWith(`${ex}/`))
+}
+
+function isGeneratedByHeader(filePath) {
+  try {
+    const fd = readFileSync(filePath, { encoding: "utf8", flag: "r" }).slice(0, 200)
+    return GENERATED_HEADER_RE.test(fd.split("\n")[0] ?? "")
+  } catch {
+    return false
+  }
+}
+
+function walk(dir, { excludes, root, skippedSymlinks, skippedGenerated }) {
+  const out = []
+  let entries
+  try {
+    entries = readdirSync(dir, { withFileTypes: true })
+  } catch (err) {
+    throw new Error(`Cannot read directory ${dir}: ${err.message}`)
+  }
+  for (const entry of entries) {
+    if (entry.name === "node_modules" || entry.name.startsWith(".")) continue
+    const full = join(dir, entry.name)
+    const rel = relative(root, full)
+    if (isExcluded(rel, excludes)) continue
+    if (entry.isSymbolicLink()) {
+      skippedSymlinks.push(rel)
+      continue
+    }
+    if (entry.isDirectory()) {
+      out.push(...walk(full, { excludes, root, skippedSymlinks, skippedGenerated }))
+    } else if (SCAN_EXT_RE.test(entry.name)) {
+      if (GENERATED_FILE_RE.test(entry.name) || isGeneratedByHeader(full)) {
+        skippedGenerated.push(rel)
+        continue
+      }
+      out.push(full)
+    }
+  }
+  return out
+}
+
+/** Reads one file and delegates the actual analysis to the core's `analyzeSource` — this function
+ * is the ENTIRE fs-touching surface for per-file analysis; `analyzeSource` itself never reads a
+ * file. `relPath` doubles as `analyzeSource`'s `fileNameHint` (parse-mode detection + the `file`
+ * label on findings) — the same string was already used for both purposes before this split. */
+function analyzeFile(ts, identity, filePath, relPath) {
+  const raw = readFileSync(filePath, "utf8")
+  const findings = analyzeSource(raw, { identity, ts, fileNameHint: relPath })
+  return { findings, contentHash: sha256(raw) }
+}
+
+// ---------------------------------------------------------------------------
+// Public entrypoint
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolves `targetPath` into a boundary-checked root: rejects a target (or its auto-selected
+ * `src/`) that is itself a symlink, rather than silently following it (which could escape the
+ * requested scope entirely). Supports both a directory target and a single FILE target.
+ */
+function resolveScanRoot(targetPath) {
+  const targetLstat = lstatSync(targetPath)
+  if (targetLstat.isSymbolicLink()) {
+    return { error: `Target path is a symlink (${targetPath} -> ${realpathSync(targetPath)}); point directly at the real path instead of a symlink.` }
+  }
+  if (targetLstat.isFile()) {
+    return { file: targetPath }
+  }
+  if (!targetLstat.isDirectory()) {
+    return { error: `Target path is neither a file nor a directory: ${targetPath}` }
+  }
+  const srcDir = join(targetPath, "src")
+  if (existsSync(srcDir)) {
+    const srcLstat = lstatSync(srcDir)
+    if (srcLstat.isSymbolicLink()) {
+      return {
+        error: `The target's auto-selected src/ is a symlink (${srcDir} -> ${realpathSync(srcDir)}); this would scan outside the requested scope. Point the target directly at the real directory to scan, or pass it as the target itself.`,
+      }
+    }
+    if (srcLstat.isDirectory()) {
+      return { root: srcDir }
+    }
+  }
+  return { root: targetPath }
+}
+
+/**
+ * Scans one target (a repo root, whose `src/` is scanned if present; any directory directly; or a
+ * single file) and returns `{ target, filesScanned, targetInputHash, skippedSymlinks,
+ * skippedGenerated, toolingWarning?, findings }` on success, or `{ target, error }` for a
+ * missing/unreadable path, a symlinked target/src boundary, or an internal walk failure — never a
+ * silent "skipped" a caller could read as success by checking only `findings`.
+ */
+export async function analyzeTarget(targetPath, { identity, excludes = [], resolveTs } = {}) {
+  if (!identity) {
+    throw new Error("analyzeTarget requires a resolved package `identity` — see resolvePackageIdentity()")
+  }
+  if (!existsSync(targetPath)) {
+    return { target: targetPath, error: `Target path does not exist: ${targetPath}` }
+  }
+
+  let scanRoot
+  try {
+    scanRoot = resolveScanRoot(targetPath)
+  } catch (err) {
+    return { target: targetPath, error: `Target path is not readable: ${targetPath} (${err.message})` }
+  }
+  if (scanRoot.error) {
+    return { target: targetPath, error: scanRoot.error }
+  }
+
+  let files
+  const skippedSymlinks = []
+  const skippedGenerated = []
+  if (scanRoot.file) {
+    if (GENERATED_FILE_RE.test(scanRoot.file) || isGeneratedByHeader(scanRoot.file)) {
+      skippedGenerated.push(relative(targetPath, scanRoot.file) || scanRoot.file)
+      files = []
+    } else if (SCAN_EXT_RE.test(scanRoot.file)) {
+      files = [scanRoot.file]
+    } else {
+      return { target: targetPath, error: `Target file has an unsupported extension for scanning: ${scanRoot.file}` }
+    }
+  } else {
+    try {
+      files = walk(scanRoot.root, { excludes, root: targetPath, skippedSymlinks, skippedGenerated })
+    } catch (err) {
+      return { target: targetPath, error: err.message }
+    }
+  }
+
+  // unestablished-palette-install only applies to script files — a CSS/SCSS-only target never
+  // needs TypeScript at all, and must not report a tooling problem for a rule that could not have
+  // run there anyway. Reuses the core's own SCRIPT_EXT_RE so this check can never drift from what
+  // analyzeSource itself treats as script-parseable.
+  const hasScriptFiles = files.some((f) => SCRIPT_EXT_RE.test(f))
+
+  let ts = null
+  let toolingWarning
+  let resolvedTypeScript
+  let analysisIncomplete = false
+  if (hasScriptFiles) {
+    // No explicit resolver from the caller does NOT mean "skip rule 3 silently" — the engine's
+    // own default path still attempts real resolution (cwd, the target, the package dir) so a
+    // caller of the public API who simply omits `resolveTs` gets the same honest
+    // toolingWarning/analysisIncomplete signal a CLI invocation would.
+    const resolver = resolveTs ?? (() => resolveConsumerTypeScript([process.cwd(), targetPath, identity.packageDir]))
+    try {
+      const resolved = await resolver()
+      ts = resolved.ts
+      let tsVersion
+      try {
+        tsVersion = JSON.parse(readFileSync(join(resolved.tsPath, "..", "..", "package.json"), "utf8")).version
+      } catch {
+        tsVersion = undefined
+      }
+      resolvedTypeScript = { path: resolved.tsPath, version: tsVersion }
+    } catch (err) {
+      toolingWarning = err.message
+      // A required rule could not run at all for this target — the scan is INCOMPLETE, not clean.
+      // A caller must not read `findings` alone (which may still be a truthful, non-empty result
+      // for the two textual rules) as proof "everything was checked."
+      analysisIncomplete = true
+    }
+  }
+
+  const findings = []
+  const perFileHashes = []
+  for (const file of files) {
+    const rel = relative(targetPath, file) || file.split("/").pop()
+    try {
+      const { findings: fileFindings, contentHash } = analyzeFile(ts, identity, file, rel)
+      findings.push(...fileFindings)
+      perFileHashes.push(`${rel}:${contentHash}`)
+    } catch (err) {
+      findings.push(
+        makeFinding(identity, {
+          code: "analysis-error",
+          severity: "error",
+          confidence: "high",
+          file: rel,
+          line: 1,
+          column: 1,
+          evidence: String(err?.message ?? err),
+          explanation: "The diagnostic engine could not parse or read this file.",
+          suggestion:
+            "Fix the underlying syntax/read error, or pass --exclude for this path if it is intentionally out of scope (e.g. generated code).",
+        })
+      )
+    }
+  }
+
+  const targetInputHash = sha256(perFileHashes.sort().join("\n"))
+
+  return {
+    target: targetPath,
+    filesScanned: files.length,
+    targetInputHash,
+    skippedSymlinks,
+    skippedGenerated,
+    ...(toolingWarning ? { toolingWarning } : {}),
+    ...(resolvedTypeScript ? { resolvedTypeScript } : {}),
+    ...(analysisIncomplete ? { analysisIncomplete: true } : {}),
+    findings,
+  }
+}

package/scripts/migration-sweep.mjs

@@ -0,0 +1,179 @@
+/**
+ * CLI for the migration-diagnostics engine — checks a migrated consumer for the defects that
+ * survive every other gate (see migration-diagnostics.mjs for the rule catalogue and the
+ * analysis-boundary documentation; this file is argv parsing and output formatting only).
+ *
+ *   bun scripts/migration-sweep.mjs [--json] [--package <dir>] [--exclude <path>]... <path> [...]
+ *
+ * Exit code: 2 if any target has a hard input/argument error OR the requested analysis was
+ * INCOMPLETE (a script-file target whose TypeScript could not be resolved — a required rule did
+ * not run, which is not the same as "it ran and found nothing"); else 1 if any finding has
+ * severity "error" (legacy-volt-class / hand-written-volt-css-var — definite, unconditional textual
+ * defects); else 0. unestablished-palette-install never reports severity "error" — single-file
+ * analysis cannot prove a defect it might be wrong about (a bootstrap/provider elsewhere), so its
+ * findings are always "warning" and never independently produce a nonzero exit.
+ */
+import { resolve } from "node:path"
+import { analyzeTarget, resolveConsumerTypeScript, resolvePackageIdentity, RULES } from "./migration-diagnostics.mjs"
+
+const DEFAULT_PACKAGE_DIR = resolve(import.meta.dirname, "..")
+const KNOWN_FLAGS = new Set(["--json", "--package", "--exclude"])
+
+function usage() {
+  return (
+    "usage: node migration-sweep.mjs [--json] [--package <dir>] [--exclude <path>]... <path> [...]\n" +
+    "  <path>            a repo root (scans its src/), a directory, or a single source file\n" +
+    "  --json            machine-readable JSON output instead of text (errors too)\n" +
+    "  --package <dir>   Griffel package to read token families from (default: this package)\n" +
+    "  --exclude <path>  path relative to the target to skip, repeatable\n" +
+    "  During a flag-gated migration, point it at the NEW tree:\n" +
+    "    node migration-sweep.mjs src/components/<name>-griffel src/surface"
+  )
+}
+
+/** Returns `{ targets, excludes, json, packageDir }` or `{ argError }` for a missing operand or
+ * an unrecognized `--flag` — never silently treats either as a target path. */
+function parseArgs(argv) {
+  const targets = []
+  const excludes = []
+  let json = false
+  let packageDir = DEFAULT_PACKAGE_DIR
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (!a.startsWith("--")) {
+      targets.push(a)
+      continue
+    }
+    if (!KNOWN_FLAGS.has(a)) {
+      return { argError: `Unknown flag: ${a}` }
+    }
+    if (a === "--json") {
+      json = true
+      continue
+    }
+    const operand = argv[i + 1]
+    if (operand === undefined || operand.startsWith("--")) {
+      return { argError: `Missing operand for ${a}` }
+    }
+    i++
+    if (a === "--package") packageDir = resolve(operand)
+    else if (a === "--exclude") excludes.push(operand)
+  }
+
+  return { targets, excludes, json, packageDir }
+}
+
+function emitError(json, message, extra = {}) {
+  if (json) {
+    console.log(JSON.stringify({ schemaVersion: 1, error: message, ...extra }, null, 2))
+  } else {
+    console.error(message)
+    if (extra.usage) console.error(extra.usage)
+  }
+}
+
+export async function runCli(argv) {
+  const parsed = parseArgs(argv)
+  // Flag parsing errors can occur before we know whether --json was requested (e.g. an unknown
+  // flag before --json itself) — best-effort: honor --json if it appears anywhere in argv.
+  const jsonRequested = parsed.json ?? argv.includes("--json")
+
+  if (parsed.argError) {
+    emitError(jsonRequested, parsed.argError, { usage: usage() })
+    return 2
+  }
+
+  const { targets, excludes, json, packageDir } = parsed
+  if (!targets.length) {
+    emitError(json, "No target path(s) given.", { usage: usage() })
+    return 2
+  }
+
+  let identity
+  try {
+    identity = resolvePackageIdentity(packageDir)
+  } catch (err) {
+    emitError(json, String(err?.message ?? err))
+    return 2
+  }
+
+  const resolveTs = () => resolveConsumerTypeScript([process.cwd(), ...targets.map((t) => resolve(t)), packageDir])
+
+  const results = []
+  for (const t of targets) {
+    results.push(await analyzeTarget(resolve(t), { identity, excludes, resolveTs }))
+  }
+
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          schemaVersion: 1,
+          package: {
+            name: identity.packageName,
+            version: identity.packageVersion,
+            generatedInputHash: identity.generatedInputHash,
+          },
+          rules: RULES,
+          results,
+        },
+        null,
+        2
+      )
+    )
+  } else {
+    for (const r of results) {
+      const name = r.target.split("/").pop()
+      if (r.error) {
+        console.log(`  ✗ ${name} — ${r.error}`)
+        continue
+      }
+      if (r.resolvedTypeScript) {
+        console.log(`      typescript: ${r.resolvedTypeScript.version ?? "unknown version"} (${r.resolvedTypeScript.path})`)
+      }
+      if (r.skippedGenerated?.length) {
+        console.log(`      skipped as generated: ${r.skippedGenerated.join(", ")}`)
+      }
+      if (r.skippedSymlinks?.length) {
+        console.log(`      skipped symlinks: ${r.skippedSymlinks.join(", ")}`)
+      }
+      if (r.toolingWarning) {
+        // Never a green check here, even if findings is empty — the required rule did not run,
+        // so "no findings" means "not fully checked", not "checked and clean".
+        console.log(
+          `  ! ${name} — INCOMPLETE ANALYSIS: ${r.toolingWarning}` +
+            (r.findings.length ? ` (${r.findings.length} finding(s) from the rules that did run, below)` : "")
+        )
+        for (const f of r.findings) {
+          console.log(
+            `      [${f.severity}] ${f.code.padEnd(28)} ${f.file}:${f.line}:${f.column}  ${f.evidence}`
+          )
+        }
+        continue
+      }
+      if (!r.findings.length) {
+        console.log(`  ✓ ${name} (${r.filesScanned} file(s) scanned, targetInputHash ${r.targetInputHash.slice(0, 12)}…)`)
+        continue
+      }
+      console.log(`  ✗ ${name} — ${r.findings.length} finding(s)`)
+      for (const f of r.findings) {
+        console.log(
+          `      [${f.severity}] ${f.code.padEnd(28)} ${f.file}:${f.line}:${f.column}  ${f.evidence}`
+        )
+      }
+    }
+    console.log("")
+  }
+
+  const hasIncompleteOrInputError = results.some((r) => r.error || r.analysisIncomplete)
+  if (hasIncompleteOrInputError) return 2
+
+  const hasHardFailure = results.some((r) => r.findings?.some((f) => f.severity === "error"))
+  return hasHardFailure ? 1 : 0
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const code = await runCli(process.argv.slice(2))
+  process.exit(code)
+}

package/AGENTS.md

@@ -1,153 +0,0 @@
-# Agent rules — `@epilot/volt-ui-experimental-griffel`
-
-These rules govern every file under `packages/experimental-griffel/`. They are normative: where any
-other document in this package disagrees with this file, **this file wins** and the other one is a
-bug worth fixing.
-
-`packages/experimental/AGENTS.md` does **not** apply here. It governs
-`@epilot/volt-ui-experimental-css-modules`, a different package with a different styling engine, and
-its rules on CSS Modules, `var(--volt-*)` tokens and `bun run *:experimental` scripts are all wrong
-for this one. The two are siblings, not parent and child.
-
-**What the other documents are for.** `AUTHORING.md` explains the defect behind each rule — read it
-when you want to know _why_, not _what_. `DECISIONS.md` records architecture rationale as a dated
-log. `STATUS.md` is a snapshot of measurements and progress at a point in time; treat every number
-in it as of its commit, never as a live fact. This file holds no counts and no measurements on
-purpose, because those are what rot.
-
-## Architecture, as it is now
-
-- **Primitives are Radix**, at the same versions v1 pins, plus `sonner` for Toast and `cmdk` for
-  Command. There is no `@base-ui/react` in this package — not in the manifest, not in `src`.
-  Anything telling you to use Base UI primitives, or to prefer `data-checked` over Radix's
-  `data-state="checked"`, is describing an abandoned detour. Radix state attributes are
-  **value-based**: `&[data-state='checked']`, not `&[data-checked]`.
-- **Styling is Griffel**, emitted as runtime atoms. No Tailwind, no `cn`, no `tailwind-merge`, no
-  shipped stylesheet. Use `mergeClasses` from `@epilot/volt-ui-runtime` — this package
-  does not import `@griffel/core` anywhere, and `gate:one-bare-specifier` enforces that.
-- **The runtime target is React 18**, while the repo compiles against `@types/react@19`. Both suites
-  must stay green.
-- ESM only. `react` and `react-dom` are peers; everything else is vendored into `dist`.
-  `sideEffects: false`.
-
-## Authoring rules
-
-1. **`&` must be the first token of every selector.** Griffel prepends its class to the whole
-   selector and substitutes `&` nowhere else, so `"[data-pressed] &"` emits
-   `.hash[data-pressed] .hash` and can never match. No warning, no error, no failing test. To style a
-   descendant from an ancestor's state, declare the rule on the _ancestor's_ slot and reach down via
-   `SLOT_ATTR`. A selector list is fine when each part is legal alone.
-   `src/ancestor-selector.test.ts` enforces this.
-
-2. **Declaration order inside a slot encodes precedence, and v1's order does not.** Griffel emits
-   atoms in source order, so the later rule wins. v1's precedence comes from Tailwind's utility
-   layer, where `aria-invalid:` beats `disabled:` regardless of class order. Transcribing v1's order
-   inverts the outcome. Put the state that must **win** last.
-
-3. **Match a neighbour's property shape, not just its value.** Griffel dedupes only when expanded
-   property keys match, so `paddingLeft`/`paddingRight` against a neighbour's
-   `shorthands.paddingInline` leaves both standing and the cascade picks the wrong one.
-
-4. **No CSS shorthands** — an atom is one declaration, so a shorthand cannot be resolved against a
-   longhand. Use `shorthands.*`. Griffel only warns at runtime, so the warnings-as-errors test is
-   what catches it.
-
-5. **Animations use the object form**, `animationName: { from: {…}, to: {…} }`. Griffel hashes
-   keyframe names from content but does **not** apply the class-name salt to them, so a hand-authored
-   global `@keyframes` collides across co-resident copies silently.
-
-6. **`forwardRef` is required.** `ref`-as-a-plain-prop is React 19; every consumer runs React 18,
-   where a function component without `forwardRef` never receives `ref`.
-
-7. **`asChild` is supported and should stay supported.** Components wrapping a Radix primitive
-   inherit it through `React.ComponentProps<typeof Primitive.X>` and need no work. Components that
-   render their own element — Button and BreadcrumbItem — implement it with Radix's `Slot`. v1
-   exposes it on thirteen components and consumers use it to wrap router links, so dropping it
-   breaks call sites. It was briefly removed while this package was on Base UI; that reason no
-   longer exists. Do not expose Base UI's `render` prop, which is a different thing.
-
-8. **Colour is a value, never part of a class name.** Components with a `color` prop follow Badge:
-   atoms read inline custom properties the component sets. Never emit a per-colour rule.
-
-9. **Call `ensurePaletteTokens()` whenever you reference any family outside
-   accent / gray / error / warning / success / info** — whether or not the component has a `color`
-   prop. Those six are in the core sheet; every other family is in the palette sheet, which is not
-   loaded by default, and referencing it without installing gives an invalid computed value and no
-   error.
-
-10. **No module-scope DOM or stylesheet mutation.** Installing tokens, inserting styles or touching
-    `document` must happen lazily at first render, never at import time — that is what makes
-    `sideEffects: false` true and keeps an unused import free.
-    `src/components/avatar/avatar.tsx` currently calls `ensurePaletteTokens()` at module scope. **That
-    is a known defect, not a precedent.** Do not copy it.
-
-11. **`SLOT_ATTR` for selectors, `data-slot` for diagnostics.** Emit both, and never write a selector
-    keyed on `data-slot` — those values are shared with v1, so such a rule also matches v1-rendered
-    DOM. Portalled parts each carry their own styling class and their own slot marker; a class on an
-    ancestor outside the portal does not reach them.
-
-12. **Preserve the caller's `className` and forward DOM refs.**
-
-## Tokens
-
-- Use a token wherever one exists (`tokens.textSm`, `tokens.spacingElement2`, `tokens.grayA11`).
-  Where none exists, a literal is correct — say so in your report. Never
-  `calc(var(--spacing) * n)`: reintroducing Tailwind's numeric scale is what this rebuild exists to
-  avoid.
-- **Spacing and size are different axes.** There is no dimension token family, so `width: "0.75rem"`
-  on an svg stays a literal even though `spacingElement3` shares the number.
-- **Never edit a generated token file, and never hardcode a namespace or salt hash.** Run
-  `bun run tokens`.
-- Core and palette carry **independent** namespaces, so a palette-only change does not rename core
-  properties. `GRIFFEL_CLASS_SALT` covers the pinned Griffel version and nothing else — token
-  isolation is the namespaces' job, not the salt's.
-
-## Rule 0 — v1's rendered OUTPUT is the fidelity target
-
-Not v1's source, and not a task file's summary of it. Where a task file and v1 disagree on a visual
-value, v1 wins; where v1's source and what v1 actually renders disagree, **what it renders wins**.
-Reproduce v1's defects when they are cosmetic, and say so. Do not reproduce one that makes a
-component non-functional. Every intentional difference needs an explicit, reviewed VR exception.
-
-There is one standing exception, and it is the only one: **leading**. v1's shipped sheet references
-every `--text-*--line-height` unprefixed and so applies none of them, and v2 follows what v1
-declares instead of what it renders. That is decided in `DECISIONS.md` D9, corrected on the v1 arm of
-the VR harness by `V1_DECLARED_LEADING_SHIM`, and dated by `vr/v1-leading-references.test.ts`. Pair
-every `fontSize: tokens.text*` with the matching `lineHeight: tokens.leading*` in the same slot; do
-not read it as licence to prefer v1's source anywhere else.
-
-## Verifying
-
-Run these, by name — not against a remembered count:
-
-```sh
-bun run build          # tokens, tsc, vite
-bun run test           # React 19
-bun run react18:test   # React 18
-bun run gate:vr        # visual regression against v1
-bun run gates          # all architecture gates, fail-fast
-```
-
-Wire your component into `src/index.ts` **before** running the gates: several build the package from
-its entrypoint, so an unexported component is invisible to them and they will pass without having
-seen it.
-
-**A green gate is evidence for the assertions that gate actually makes, and nothing wider.** Every
-gate here has a `GATE_NEGATIVE_CONTROL` mode, documented in its own header, demonstrated to trip
-exactly the checks it should. If you add or strengthen an architectural claim, add a control that
-breaks the property under test and show it failing. A check that cannot fail is worse than no check,
-because it reads as coverage — this suite had two such checks for months.
-
-## Done means
-
-Exported from `src/index.ts`, both suites green, tsc clean, VR specimens covering the component's
-**states** and not merely its default, and gates green. A component with no state-bearing specimens
-is not finished.
-
-## Working agreements
-
-- Do not add dependencies or edit `package.json` unless the task says so explicitly.
-- Do not commit, push, or run any git write command unless asked.
-- Put throwaway probes in `.scratch/` (gitignored) inside this package, never in `/tmp`.
-- Report: file paths, the vitest and tsc results, any literal used for want of a token, any behaviour
-  delta from v1, and anything you were unsure about.