maddox-engine 0.4.0 → 0.5.0

package/README.md

@@ -24,6 +24,7 @@ Options:
 - `--motion <path>` — path to a JSON file of motion tokens (e.g. a vendored copy of your motion-tokens export)
 - `--states <path>` — path to a state-contract JSON file (see below). No effect in `--url` mode.
 - `--tokens-studio <path>` — path to a Tokens Studio / W3C Design Tokens JSON export (see below); merged with, and taking precedence over, `@theme` on any path both define
+- `--figma-file <file-key>` — pull color/spacing tokens from a Figma file's Variables (see below); requires an Enterprise Figma plan
 - `--url <page-url>` — scan a deployed page instead of local source (see below); pass a placeholder like `-` for `<target-source-dir>` when using this alone
 - `--apply-fixes` — write near-miss color/font-size/spacing suggestions back into source files (see below); not available with `--url`
 - `--format text|json|markdown` — output format (default: `text`)
@@ -52,6 +53,19 @@ Ground truth is explicit — nothing is inferred about which states a component
 
 If your tokens live in Figma via the Tokens Studio plugin rather than (or alongside) a Tailwind `@theme` block, export them to JSON and point `--tokens-studio` at the file. A single-set export (the whole file is one token tree) and a multi-set export (top-level keys are set names, e.g. `global`, `dark`) are both supported — for a multi-set export, every set is merged, later sets overriding earlier ones by path. `{alias}` references are resolved automatically. Only token types that resolve to a single comparable value (`color`, `spacing`, `sizing`, `fontSizes`, `borderRadius`, `dimension`) are used — composite types like `typography` or `boxShadow` describe a bundle of properties, not one value to diff against, and are skipped rather than misclassified.
 
+### Figma Variables ground truth
+
+If your tokens live in native Figma Variables rather than Tokens Studio, `--figma-file <file-key>` pulls them directly from Figma's Variables REST API. **This requires an Enterprise Figma plan** — the endpoint returns a 403 for any other plan, regardless of the token's own permissions. Get the file key from the file's URL (`figma.com/design/:file_key/...`).
+
+```bash
+export MADDOX_FIGMA_TOKEN=figd_...   # a personal access token with file_variables:read scope
+npx maddox-engine ./src ./src/app/globals.css --figma-file abc123XYZ
+```
+
+The token is read from `MADDOX_FIGMA_TOKEN` (a personal access token, sent via the `X-Figma-Token` header) or `MADDOX_FIGMA_OAUTH_TOKEN` (an OAuth2 access token, sent via `Authorization: Bearer`) — never pass it as a CLI flag, which would leak it into shell history and process listings.
+
+Only `COLOR` and `FLOAT`-typed variables are used, resolved to each variable's default mode, following alias references to their underlying value. `FLOAT` variables have no unit in Figma's API — treated as pixels, matching Figma's own UI default for spacing/sizing/radius scales; a variable actually meant as a unitless multiplier will resolve wrong. `STRING`/`BOOLEAN` variables are skipped, same policy as Tokens Studio's composite types. When more than one ground-truth source is given, Figma Variables take precedence over Tokens Studio, which takes precedence over `@theme` CSS — Figma sits earliest in a real design-to-code pipeline, so a later step is more likely to be the stale one.
+
 ### Scanning a live page
 
 ```bash
@@ -90,6 +104,38 @@ This is a real edit to your working tree, not a dry run — review the diff (`gi
 
 `match` counts fully, `near-miss` counts half (it drifted, but is still recognizably close to a real token), `unrecognized` and a missing required state count for nothing. A scan with zero checks scores 100.
 
+## Programmatic use: route mapping
+
+The CLI's own text/markdown/JSON output stays a flat file:line list — the right shape for a PR comment or a CI log. If you're building your own dashboard or report on top of this package, `fileToRoute(file)` and `groupByRoute(findings)` are also exported for grouping findings by the actual Next.js App Router route a file belongs to, rather than its raw path:
+
+```ts
+import { audit, loadGroundTruth, fileToRoute, groupByRoute } from "maddox-engine";
+
+const groundTruth = loadGroundTruth("./src/app/globals.css", {});
+const { findings } = await audit("./src", groundTruth);
+
+fileToRoute("app/dashboard/page.tsx"); // "/dashboard"
+fileToRoute("app/(auth)/login/page.tsx"); // "/login" — route groups are invisible in the real URL
+fileToRoute("app/work/[id]/page.tsx"); // "/work/[id]" — dynamic segments kept as Next.js represents them
+fileToRoute("components/Button.tsx"); // "Shared (non-route files)"
+
+groupByRoute(findings); // [{ route, findings }, ...], real routes first, shared bucket last
+```
+
+Only `page.*`/`layout.*` files directly under an `app/` (or `src/app/`) directory get a real route — this deliberately does not trace the import graph to attribute a shared component to the page(s) that render it, since a component used by five different pages has no single "real" route, and guessing one would misattribute drift. Everything else lands in a `"Shared (non-route files)"` bucket instead. A layout keeps its route group in its own label (`/(auth) (layout)`) even though a page at the same URL doesn't, since two different layouts can legitimately wrap the same URL from different subtrees.
+
+### Using this from a React client component
+
+`import ... from "maddox-engine"` pulls in everything, including `scan.ts`/`groundTruth.ts`/`tokensStudio.ts`/`applyFixes.ts` — all of which read the filesystem (`node:fs`, `node:path`). A bundler building a browser/client bundle (Next.js's `"use client"`, Vite, etc.) can't resolve those, and the build fails even if the client code never actually calls a Node-dependent function — a bundler loads a module's own top-level imports regardless of which export is used.
+
+If you're grouping or diffing findings inside a client component (e.g. rendering `fileToRoute`/`groupByRoute` output, or re-running `diffUsages` against data already fetched server-side), import from the `/client` subpath instead — it only re-exports modules with zero `node:*` imports anywhere in their own graph:
+
+```ts
+import { fileToRoute, groupByRoute, diffUsages, healthScore } from "maddox-engine/client";
+```
+
+`audit`/`auditUrl`/`loadGroundTruth`/anything that reads a file or fetches a URL still needs the package root, and stays server-side (an API route, a server component, a build script) — `/client` only has the pure data-transformation half.
+
 ## Using in CI
 
 This repo is also a GitHub Action — `omrdev1/maddox-cli` — that runs a scan, posts the markdown report as a PR comment (updating the same comment on later pushes rather than piling up new ones), and optionally fails the build via `fail-below`.
@@ -111,6 +157,7 @@ Inputs:
 - `motion-tokens` — path to a motion-tokens JSON file
 - `states` — path to a state-contract JSON file. No effect when `url` is set.
 - `tokens-studio` — path to a Tokens Studio / W3C Design Tokens JSON export
+- `figma-file` / `figma-token` / `figma-token-type` — pull tokens from a Figma file's Variables; requires an Enterprise Figma plan. `figma-token` should be a secret (`${{ secrets.FIGMA_TOKEN }}`), never a literal value.
 - `url` — a deployed page URL to scan instead of local source
 - `github-token` *(required)* — for posting the PR comment, usually `${{ secrets.GITHUB_TOKEN }}`
 - `fail-below` — fail the build below this health score; omit for comment-only

package/package.json

@@ -1,9 +1,21 @@
 {
   "name": "maddox-engine",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Scans source code or a live deployed page for design-token, motion, and component-state drift against your own design system — the same engine behind Maddox Engine's CI checks.",
   "license": "MIT",
   "type": "module",
+  "main": "./src/core.ts",
+  "types": "./src/core.ts",
+  "exports": {
+    ".": {
+      "types": "./src/core.ts",
+      "default": "./src/core.ts"
+    },
+    "./client": {
+      "types": "./src/client.ts",
+      "default": "./src/client.ts"
+    }
+  },
   "bin": {
     "maddox": "./src/cli.ts"
   },

package/src/cli.ts

@@ -1,7 +1,16 @@
 #!/usr/bin/env -S npx tsx
 
 import { readFileSync } from "node:fs";
-import { applyFixes, audit, auditUrl, healthScore, loadGroundTruth, loadStateContract } from "./core.js";
+import {
+  applyFixes,
+  audit,
+  auditUrl,
+  FigmaVariablesUnavailableError,
+  healthScore,
+  loadGroundTruth,
+  loadGroundTruthWithFigma,
+  loadStateContract,
+} from "./core.js";
 import { summarize, toJson, toMarkdown, toText, type ScanSummary } from "./format.js";
 
 async function uploadResult(apiUrl: string, apiKey: string, projectName: string, summary: ScanSummary) {
@@ -44,13 +53,17 @@ async function main() {
         "[--project <name>] [--motion <path-to-motion-tokens.json>] " +
         "[--states <path-to-state-contract.json>] [--format text|json|markdown] " +
         "[--fail-below <0-100>] [--tokens-studio <path-to-tokens-studio-export.json>] " +
-        "[--url <live-page-url>] [--apply-fixes]\n" +
+        "[--url <live-page-url>] [--apply-fixes] [--figma-file <file-key>]\n" +
         "  --url scans a deployed page's rendered HTML/CSS instead of local source " +
         "(pass a placeholder for <target-source-dir>, e.g. '-', when using --url alone). " +
         "--states has no effect in --url mode: state-completeness is a source-code check.\n" +
         "  --apply-fixes writes near-miss color/font-size/spacing suggestions back into " +
         "source files (color/font-size/spacing only — motion and state findings are " +
-        "never auto-applied). Not available with --url, which has no source to write to."
+        "never auto-applied). Not available with --url, which has no source to write to.\n" +
+        "  --figma-file <file-key> pulls color/spacing tokens from a Figma file's " +
+        "Variables (the file key from its URL). Requires an Enterprise Figma plan and " +
+        "MADDOX_FIGMA_TOKEN set to a personal access token (or MADDOX_FIGMA_OAUTH_TOKEN " +
+        "for an OAuth2 token) — never pass the token as a CLI flag."
     );
     process.exit(1);
   }
@@ -71,7 +84,35 @@ async function main() {
   const stateContract = statesPath ? loadStateContract(statesPath) : undefined;
 
   const tokensStudioPath = flagValue("--tokens-studio");
-  const groundTruth = loadGroundTruth(themeCssPath, motionTokens, tokensStudioPath);
+
+  const figmaFileKey = flagValue("--figma-file");
+  let groundTruth;
+  if (figmaFileKey) {
+    const patToken = process.env.MADDOX_FIGMA_TOKEN;
+    const oauthToken = process.env.MADDOX_FIGMA_OAUTH_TOKEN;
+    if (!patToken && !oauthToken) {
+      console.error(
+        "\n--figma-file requires MADDOX_FIGMA_TOKEN (a personal access token) or " +
+          "MADDOX_FIGMA_OAUTH_TOKEN (an OAuth2 access token) to be set."
+      );
+      process.exit(1);
+    }
+    try {
+      groundTruth = await loadGroundTruthWithFigma(themeCssPath, motionTokens, tokensStudioPath, {
+        fileKey: figmaFileKey,
+        token: (patToken ?? oauthToken)!,
+        authMode: patToken ? "pat" : "oauth",
+      });
+    } catch (err) {
+      if (err instanceof FigmaVariablesUnavailableError) {
+        console.error(`\n${err.message}`);
+        process.exit(1);
+      }
+      throw err;
+    }
+  } else {
+    groundTruth = loadGroundTruth(themeCssPath, motionTokens, tokensStudioPath);
+  }
 
   const result = url ? await auditUrl(url, groundTruth) : await audit(targetDir, groundTruth, stateContract);
   const summary = summarize(result.findings, result.filesScanned);

package/src/client.ts

@@ -0,0 +1,19 @@
+// Browser-safe subset of this package, for a "use client" React component
+// in a consuming app. Only re-exports modules with no node:* import
+// anywhere in their own import graph (verified by hand for each — see the
+// comment at the top of scan.ts for why a re-export from a Node-dependent
+// file, even of a browser-safe name, still breaks a client bundle).
+//
+// Import this as "maddox-engine/client", never the package root
+// ("maddox-engine") — the root barrel (core.ts) also exports
+// audit()/auditUrl() and re-exports scan.ts/groundTruth.ts/
+// tokensStudio.ts/applyFixes.ts, all of which import node:fs/node:path.
+export * from "./types.js";
+export * from "./extract.js";
+export * from "./diff.js";
+export * from "./stateCheck.js";
+export * from "./healthScore.js";
+export * from "./routeMap.js";
+export * from "./crawl.js";
+export * from "./suggestFix.js";
+export * from "./figmaVariables.js";

package/src/core.ts

@@ -1,6 +1,8 @@
 export * from "./types.js";
+export * from "./extract.js";
 export * from "./groundTruth.js";
 export * from "./tokensStudio.js";
+export * from "./figmaVariables.js";
 export * from "./scan.js";
 export * from "./crawl.js";
 export * from "./diff.js";
@@ -8,6 +10,7 @@ export * from "./stateCheck.js";
 export * from "./healthScore.js";
 export * from "./suggestFix.js";
 export * from "./applyFixes.js";
+export * from "./routeMap.js";
 
 import { scanSource, scanFiles } from "./scan.js";
 import { crawlUrl } from "./crawl.js";

package/src/crawl.ts

@@ -1,4 +1,4 @@
-import { extractFromContent, type RawUsage } from "./scan.js";
+import { extractFromContent, type RawUsage } from "./extract.js";
 
 // Only ever follow relative/absolute-path stylesheet links resolved
 // against the page's own origin — never a third-party CDN's CSS, since

package/src/diff.ts

@@ -1,4 +1,4 @@
-import type { RawUsage } from "./scan.js";
+import type { RawUsage } from "./extract.js";
 import type { Finding, GroundTruth } from "./types.js";
 
 const NEAR_MISS_RGB_THRESHOLD = 25;

package/src/extract.ts

@@ -0,0 +1,87 @@
+// Browser-safe extraction — no Node built-ins (fs/path), so this module
+// (and anything that only imports from it) can be bundled into a "use
+// client" component without breaking a webpack/browser build. Keep it
+// that way: this file must never gain a `node:` import. Filesystem
+// walking (scanSource/scanFiles) lives in scan.ts instead, which does
+// import Node built-ins and is meant only for server-side/CLI use.
+
+export interface RawUsage {
+  file: string;
+  line: number;
+  kind: "color" | "spacing" | "font-size" | "motion";
+  rawValue: string;
+}
+
+// A single scanned file's relative path + raw content — produced by
+// scan.ts's filesystem walk, but the shape itself has no Node dependency
+// so it lives here where anything (including a client component) can
+// reference the type.
+export interface ScannedFile {
+  file: string; // relative to rootDir
+  content: string;
+}
+
+const HEX_RE = /#([a-f0-9]{3}|[a-f0-9]{6})\b/gi;
+const FONT_SIZE_RE = /font-size:\s*([\d.]+(?:px|rem|em))/gi;
+const MOTION_DURATION_RE = /duration:\s*([\d.]+)/gi;
+const MOTION_EASE_RE = /ease:\s*['"]([\w-]+)['"]/gi;
+
+function lineNumberAt(content: string, index: number): number {
+  return content.slice(0, index).split("\n").length;
+}
+
+/**
+ * Extracts raw color/font-size/motion literals from a single blob of
+ * content. Used both by scan.ts's filesystem walk and by crawl.ts's
+ * fetched-HTML/CSS path — the same extraction either way, source doesn't
+ * matter.
+ */
+export function extractFromContent(file: string, content: string): RawUsage[] {
+  const usages: RawUsage[] = [];
+
+  for (const re of [HEX_RE]) {
+    re.lastIndex = 0;
+    let m: RegExpExecArray | null;
+    while ((m = re.exec(content)) !== null) {
+      usages.push({
+        file,
+        line: lineNumberAt(content, m.index),
+        kind: "color",
+        rawValue: m[0].toLowerCase(),
+      });
+    }
+  }
+
+  FONT_SIZE_RE.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = FONT_SIZE_RE.exec(content)) !== null) {
+    usages.push({
+      file,
+      line: lineNumberAt(content, m.index),
+      kind: "font-size",
+      rawValue: m[1],
+    });
+  }
+
+  MOTION_DURATION_RE.lastIndex = 0;
+  while ((m = MOTION_DURATION_RE.exec(content)) !== null) {
+    usages.push({
+      file,
+      line: lineNumberAt(content, m.index),
+      kind: "motion",
+      rawValue: m[1],
+    });
+  }
+
+  MOTION_EASE_RE.lastIndex = 0;
+  while ((m = MOTION_EASE_RE.exec(content)) !== null) {
+    usages.push({
+      file,
+      line: lineNumberAt(content, m.index),
+      kind: "motion",
+      rawValue: m[1],
+    });
+  }
+
+  return usages;
+}

package/src/figmaVariables.ts

@@ -0,0 +1,182 @@
+import type { TokenMap } from "./types.js";
+
+// The Variables REST API is an Enterprise-plan-only Figma feature — a
+// request against a file on a lower plan returns a real error, not an
+// empty result. Surfaced as a specific error rather than a generic fetch
+// failure so a caller can tell "you can't use this" apart from "the
+// network broke" or "your token is wrong".
+export class FigmaVariablesUnavailableError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "FigmaVariablesUnavailableError";
+  }
+}
+
+interface FigmaRGBA {
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+}
+
+interface FigmaVariableAlias {
+  type: "VARIABLE_ALIAS";
+  id: string;
+}
+
+type FigmaVariableValue = boolean | number | string | FigmaRGBA | FigmaVariableAlias;
+
+function isAlias(value: FigmaVariableValue): value is FigmaVariableAlias {
+  return typeof value === "object" && value !== null && "type" in value && value.type === "VARIABLE_ALIAS";
+}
+
+function isRgba(value: FigmaVariableValue): value is FigmaRGBA {
+  return typeof value === "object" && value !== null && "r" in value;
+}
+
+interface FigmaVariable {
+  id: string;
+  name: string;
+  variableCollectionId: string;
+  resolvedType: "BOOLEAN" | "FLOAT" | "STRING" | "COLOR";
+  valuesByMode: Record<string, FigmaVariableValue>;
+}
+
+interface FigmaVariableCollection {
+  id: string;
+  name: string;
+  defaultModeId: string;
+}
+
+interface FigmaVariablesResponse {
+  status: number;
+  error: boolean;
+  meta?: {
+    variables: Record<string, FigmaVariable>;
+    variableCollections: Record<string, FigmaVariableCollection>;
+  };
+}
+
+// 0-1 float channel (Figma's RGBA convention) -> a 2-digit hex pair.
+function channelToHex(value: number): string {
+  const clamped = Math.max(0, Math.min(1, value));
+  return Math.round(clamped * 255).toString(16).padStart(2, "0");
+}
+
+function rgbaToHex(rgba: FigmaRGBA): string {
+  // Alpha is dropped for a fully-opaque color (the common case, and the
+  // same #rrggbb shape the rest of the codebase's TokenMap already
+  // expects) — only emit an 8-digit #rrggbbaa when the variable is
+  // genuinely translucent, so an opaque color's hex stays comparable
+  // against a hand-written 6-digit literal in diff.ts's exact-match path.
+  const { r, g, b, a } = rgba;
+  const hex = `#${channelToHex(r)}${channelToHex(g)}${channelToHex(b)}`;
+  return a >= 0.999 ? hex : `${hex}${channelToHex(a)}`;
+}
+
+// Resolves a variable's default-mode value to a raw CSS-comparable string,
+// following VariableAlias references. depth guards against a circular
+// alias chain (shouldn't exist in a real Figma file, but a corrupted one
+// or an API bug shouldn't infinite-loop this).
+function resolveValue(
+  variable: FigmaVariable,
+  variables: Record<string, FigmaVariable>,
+  collections: Record<string, FigmaVariableCollection>,
+  depth = 0
+): string | undefined {
+  if (depth > 10) return undefined;
+
+  const collection = collections[variable.variableCollectionId];
+  if (!collection) return undefined;
+
+  const raw = variable.valuesByMode[collection.defaultModeId];
+  if (raw === undefined) return undefined;
+
+  if (isAlias(raw)) {
+    const target = variables[raw.id];
+    if (!target) return undefined;
+    return resolveValue(target, variables, collections, depth + 1);
+  }
+
+  if (isRgba(raw)) return rgbaToHex(raw);
+
+  if (variable.resolvedType === "FLOAT" && typeof raw === "number") {
+    // Figma's Variables API has no unit on a FLOAT value — it's a bare
+    // number. Figma's own UI treats spacing/sizing/radius scales as
+    // pixel values by default, so this assumes px; a variable that's
+    // actually meant as a unitless multiplier or a different unit will
+    // be wrong here. Documented, not silently guessed past.
+    return `${raw}px`;
+  }
+
+  // STRING and BOOLEAN resolvedTypes don't reduce to a single comparable
+  // CSS value the way color/spacing do (a string variable might be a
+  // font-family name, an ID reference, anything) — skipped rather than
+  // misclassified, same policy tokensStudio.ts uses for composite types.
+  return undefined;
+}
+
+/**
+ * Fetches a Figma file's local Variables (Enterprise plan only) and
+ * flattens color/spacing-typed variables, resolved to their default
+ * mode, into the same TokenMap shape parseThemeTokens/
+ * loadTokensStudioFile produce. Each variable's own name becomes its
+ * token key, `--`-prefixed and slash/space-normalized to match the
+ * existing --token-name convention.
+ *
+ * Only ever reads the DEFAULT mode of each variable's collection — a
+ * collection with light/dark or brand-A/B modes has one value per mode,
+ * but Maddox's ground truth is a single flat TokenMap, the same
+ * constraint loadTokensStudioFile's multi-set merge already has to work
+ * within. Non-default modes are not read at all, not even as a fallback.
+ *
+ * @param fileKey - the file key from a Figma file's URL
+ *   (figma.com/design/:file_key/...)
+ * @param token - a Personal Access Token or OAuth2 access token
+ * @param authMode - "pat" sends the token via X-Figma-Token (the header
+ *   Figma's own PAT documentation specifies); "oauth" sends it via
+ *   Authorization: Bearer (the OAuth2 convention). Both are real,
+ *   independently-confirmed-working auth mechanisms against the live
+ *   Figma API — which one to use depends on how the token was obtained,
+ *   not a fixed choice this function can make for the caller.
+ */
+export async function loadFigmaVariables(
+  fileKey: string,
+  token: string,
+  authMode: "pat" | "oauth" = "pat"
+): Promise<TokenMap> {
+  const headers: Record<string, string> =
+    authMode === "pat" ? { "X-Figma-Token": token } : { Authorization: `Bearer ${token}` };
+
+  const response = await fetch(`https://api.figma.com/v1/files/${fileKey}/variables/local`, { headers });
+
+  if (response.status === 403) {
+    throw new FigmaVariablesUnavailableError(
+      "Figma Variables API access denied (403) — this endpoint requires an Enterprise Figma plan " +
+        "and a token with the file_variables:read scope. Free/Professional/Organization plans cannot use it."
+    );
+  }
+  if (!response.ok) {
+    throw new Error(`Figma Variables API request failed: ${response.status} ${response.statusText}`);
+  }
+
+  const body = (await response.json()) as FigmaVariablesResponse;
+  if (body.error || !body.meta) {
+    throw new Error(`Figma Variables API returned an error response (status ${body.status})`);
+  }
+
+  const { variables, variableCollections } = body.meta;
+  const tokens: TokenMap = {};
+
+  for (const variable of Object.values(variables)) {
+    if (variable.resolvedType !== "COLOR" && variable.resolvedType !== "FLOAT") continue;
+
+    const value = resolveValue(variable, variables, variableCollections);
+    if (value === undefined) continue;
+
+    const key = `--${variable.name.replace(/[\s/]+/g, "-").toLowerCase()}`;
+    tokens[key] = value;
+  }
+
+  return tokens;
+}

package/src/groundTruth.ts

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import { loadTokensStudioFile } from "./tokensStudio.js";
+import { loadFigmaVariables } from "./figmaVariables.js";
 import type { GroundTruth, MotionToken, StateContract, TokenMap } from "./types.js";
 
 /**
@@ -71,3 +72,39 @@ export function loadGroundTruth(
     motion: flattenMotionTokens(motionTokensObj),
   };
 }
+
+export interface FigmaVariablesSource {
+  fileKey: string;
+  token: string;
+  authMode?: "pat" | "oauth";
+}
+
+/**
+ * Same as loadGroundTruth, but with a fourth, optional live Figma
+ * Variables source — necessarily async, since it's a real network call,
+ * unlike the CSS/Tokens Studio file reads loadGroundTruth wraps. Kept as
+ * a separate function rather than making loadGroundTruth itself async,
+ * so every existing synchronous call site stays unaffected.
+ *
+ * Precedence when more than one source defines the same token path:
+ * Figma Variables wins over Tokens Studio, which wins over @theme CSS —
+ * Figma is the earliest point in a real design-to-code pipeline, and
+ * each step after it is more likely to be stale than the one before.
+ */
+export async function loadGroundTruthWithFigma(
+  themeCssPath: string,
+  motionTokensObj: Record<string, unknown>,
+  tokensStudioPath?: string,
+  figma?: FigmaVariablesSource
+): Promise<GroundTruth> {
+  const tokens = {
+    ...parseThemeTokens(themeCssPath),
+    ...(tokensStudioPath ? loadTokensStudioFile(tokensStudioPath) : {}),
+    ...(figma ? await loadFigmaVariables(figma.fileKey, figma.token, figma.authMode) : {}),
+  };
+
+  return {
+    tokens,
+    motion: flattenMotionTokens(motionTokensObj),
+  };
+}

package/src/routeMap.ts

@@ -0,0 +1,102 @@
+import type { Finding } from "./types.js";
+
+// File basenames Next.js's App Router treats as route-owning — a page
+// renders the route itself; a layout wraps every route beneath it. Both
+// are real "this route" attributions; anything else under app/ (loading,
+// error, not-found, template, route.ts API handlers) is left out
+// deliberately — those aren't the page's own content and attributing a
+// color/token finding to them would be misleading.
+const ROUTE_OWNING_BASENAMES = new Set(["page", "layout"]);
+const APP_ROUTER_EXTENSIONS = new Set([".tsx", ".ts", ".jsx", ".js"]);
+
+const SHARED_BUCKET = "Shared (non-route files)";
+
+/**
+ * Converts a file path segment sequence into the URL path Next.js's App
+ * Router would actually serve it at: route groups "(name)" are stripped
+ * (they don't appear in the URL), everything else — including dynamic
+ * segments like "[id]" or "[...slug]" — is kept exactly as Next.js
+ * itself represents them, since that IS the real route shape.
+ */
+function segmentsToRoute(segments: string[]): string {
+  const kept = segments.filter((s) => !(s.startsWith("(") && s.endsWith(")")));
+  return "/" + kept.join("/");
+}
+
+/**
+ * Finds the "app" (or "src/app") directory within a file's own path
+ * segments and returns the index right after it — the point from which
+ * App Router route segments begin. Returns -1 if this file isn't under
+ * an app/ directory at all (a plain components/lib layout, or a Pages
+ * Router project — this module only understands App Router).
+ */
+function appDirIndex(segments: string[]): number {
+  const i = segments.lastIndexOf("app");
+  return i === -1 ? -1 : i + 1;
+}
+
+/**
+ * Maps a single scanned file's path (relative to the project rootDir, as
+ * Finding.file already is) to the route it belongs to, or the shared
+ * bucket if it isn't a page/layout file under app/. Deliberately does
+ * NOT trace imports — a component imported by five different pages has
+ * no single "real" route, and guessing one would misattribute drift to
+ * routes that don't actually render it. Only page.tsx/layout.tsx (and
+ * their .ts/.jsx/.js variants) get a real route; everything else is
+ * "Shared (non-route files)".
+ */
+export function fileToRoute(file: string): string {
+  const segments = file.split("/");
+  const filename = segments[segments.length - 1];
+  const dotIndex = filename.lastIndexOf(".");
+  if (dotIndex === -1) return SHARED_BUCKET;
+
+  const basename = filename.slice(0, dotIndex);
+  const ext = filename.slice(dotIndex);
+  if (!ROUTE_OWNING_BASENAMES.has(basename) || !APP_ROUTER_EXTENSIONS.has(ext)) {
+    return SHARED_BUCKET;
+  }
+
+  const startIndex = appDirIndex(segments);
+  if (startIndex === -1) return SHARED_BUCKET;
+
+  const routeSegments = segments.slice(startIndex, segments.length - 1);
+
+  if (basename === "layout") {
+    // A layout's identity is its position in the file tree, not the URL
+    // it happens to share with a route — app/layout.tsx and
+    // app/(auth)/layout.tsx both wrap "/", but they're different files
+    // wrapping different subtrees, so route groups are kept here (unlike
+    // segmentsToRoute's page-route stripping) to keep the two distinct.
+    const label = routeSegments.length === 0 ? "/" : "/" + routeSegments.join("/");
+    return `${label} (layout)`;
+  }
+
+  return segmentsToRoute(routeSegments);
+}
+
+export interface RouteGroup {
+  route: string;
+  findings: Finding[];
+}
+
+/**
+ * Groups findings by the route (or the shared bucket) their file maps
+ * to, via fileToRoute. Route order: real routes first (alphabetical),
+ * then the shared bucket last — shared files are real drift too, but a
+ * route-focused view should lead with actual pages.
+ */
+export function groupByRoute(findings: Finding[]): RouteGroup[] {
+  const groups = new Map<string, Finding[]>();
+  for (const finding of findings) {
+    const route = fileToRoute(finding.file);
+    const existing = groups.get(route) ?? [];
+    existing.push(finding);
+    groups.set(route, existing);
+  }
+
+  const routes = [...groups.keys()].filter((r) => r !== SHARED_BUCKET).sort();
+  if (groups.has(SHARED_BUCKET)) routes.push(SHARED_BUCKET);
+
+  return routes.map((route) => ({ route, findings: groups.get(route)! }));
+}

package/src/scan.ts

@@ -1,77 +1,15 @@
 import { readFileSync, readdirSync } from "node:fs";
 import { join, relative } from "node:path";
+import { extractFromContent, type RawUsage, type ScannedFile } from "./extract.js";
 
-export interface RawUsage {
-  file: string;
-  line: number;
-  kind: "color" | "spacing" | "font-size" | "motion";
-  rawValue: string;
-}
-
-const HEX_RE = /#([a-f0-9]{3}|[a-f0-9]{6})\b/gi;
-const FONT_SIZE_RE = /font-size:\s*([\d.]+(?:px|rem|em))/gi;
-const MOTION_DURATION_RE = /duration:\s*([\d.]+)/gi;
-const MOTION_EASE_RE = /ease:\s*['"]([\w-]+)['"]/gi;
-
-function lineNumberAt(content: string, index: number): number {
-  return content.slice(0, index).split("\n").length;
-}
-
-/**
- * Extracts raw color/font-size/motion literals from a single blob of
- * content. Exported directly (not just via scanSource's filesystem walk)
- * so callers with in-memory content — e.g. fetched HTML/CSS from a public
- * URL, with no local checkout — can run the same extraction.
- */
-export function extractFromContent(file: string, content: string): RawUsage[] {
-  const usages: RawUsage[] = [];
-
-  for (const re of [HEX_RE]) {
-    re.lastIndex = 0;
-    let m: RegExpExecArray | null;
-    while ((m = re.exec(content)) !== null) {
-      usages.push({
-        file,
-        line: lineNumberAt(content, m.index),
-        kind: "color",
-        rawValue: m[0].toLowerCase(),
-      });
-    }
-  }
-
-  FONT_SIZE_RE.lastIndex = 0;
-  let m: RegExpExecArray | null;
-  while ((m = FONT_SIZE_RE.exec(content)) !== null) {
-    usages.push({
-      file,
-      line: lineNumberAt(content, m.index),
-      kind: "font-size",
-      rawValue: m[1],
-    });
-  }
-
-  MOTION_DURATION_RE.lastIndex = 0;
-  while ((m = MOTION_DURATION_RE.exec(content)) !== null) {
-    usages.push({
-      file,
-      line: lineNumberAt(content, m.index),
-      kind: "motion",
-      rawValue: m[1],
-    });
-  }
-
-  MOTION_EASE_RE.lastIndex = 0;
-  while ((m = MOTION_EASE_RE.exec(content)) !== null) {
-    usages.push({
-      file,
-      line: lineNumberAt(content, m.index),
-      kind: "motion",
-      rawValue: m[1],
-    });
-  }
-
-  return usages;
-}
+// Deliberately NOT re-exporting RawUsage/ScannedFile/extractFromContent
+// here — anything that needs those and must stay browser-safe (crawl.ts,
+// diff.ts, or a future client component) should import them from
+// ./extract.js directly, not through this file. This file's own
+// node:fs/node:path imports are unconditional at module scope, so ANY
+// import from scan.ts — even just for a re-exported browser-safe name —
+// pulls those into a webpack client bundle and breaks it, exactly the
+// bug this split exists to prevent.
 
 const SKIP_DIRS = new Set(["node_modules", ".next", ".git", ".turbo", "dist"]);
 const SCAN_EXTENSIONS = new Set([".ts", ".tsx", ".css"]);
@@ -88,11 +26,6 @@ function walkDir(dir: string, out: string[]): void {
   }
 }
 
-export interface ScannedFile {
-  file: string; // relative to rootDir
-  content: string;
-}
-
 /**
  * Walks .ts/.tsx/.css files under `rootDir` (skipping node_modules/.next)
  * and returns each file's relative path and content. Shared by the

package/src/stateCheck.ts

@@ -1,4 +1,4 @@
-import type { ScannedFile } from "./scan.js";
+import type { ScannedFile } from "./extract.js";
 import type { Finding, StateContract } from "./types.js";
 
 // Heuristic identifiers that count as "this state is handled" when they