@hyperframes/studio 0.8.50 → 0.8.53-desktop.0

package/src/styles/classCandidates.ts

@@ -0,0 +1,281 @@
+// Pulls Tailwind class candidates out of a TS/TSX file: only strings unambiguously used as class lists
+// (className/class attributes, cn/clsx/cva-style calls, `*class` properties, identifiers those use,
+// `*Styles`/`*Classes` bindings). Bare strings are ignored so prose and paths never become "classes".
+// Pure: text in, candidates out.
+
+import { escapeRegex } from "../utils/sourcePatcher";
+
+/** A class candidate and where it came from. */
+export interface ClassCandidate {
+  /** The utility with its variant prefixes removed (`hover:bg-x` -> `bg-x`). */
+  readonly base: string;
+  /** The token exactly as it was written, for the failure message. */
+  readonly raw: string;
+  /** True when the utility carries a bracketed arbitrary value. */
+  readonly arbitrary: boolean;
+}
+
+const OPEN: Record<string, string> = { "{": "}", "(": ")", "[": "]" };
+
+// Index of the last char of the non-code span (string, template, line or block comment) starting at
+// `i`, else -1. Known limit: a regex literal containing a quote reads as a string; the cost is a
+// spurious candidate, which the gate reports.
+function endOfSpan(text: string, i: number): number {
+  const ch = text[i];
+  if (ch === '"' || ch === "'" || ch === "`") {
+    return Math.min(endOfString(text, i), text.length - 1);
+  }
+  if (ch !== "/") return -1;
+  if (text[i + 1] === "/") {
+    const end = text.indexOf("\n", i);
+    return end === -1 ? text.length - 1 : end - 1;
+  }
+  if (text[i + 1] === "*") {
+    const end = text.indexOf("*/", i + 2);
+    return end === -1 ? text.length - 1 : end + 1;
+  }
+  return -1;
+}
+
+// Index just past the region starting at `start` (an opening bracket), skipping strings, templates
+// and comments; `text.length` when it never closes.
+function endOfRegion(text: string, start: number): number {
+  const stack: string[] = [];
+  for (let i = start; i < text.length; i += 1) {
+    const span = endOfSpan(text, i);
+    if (span >= i) {
+      i = span;
+      continue;
+    }
+    const ch = text[i];
+    if (OPEN[ch]) {
+      stack.push(OPEN[ch]);
+    } else if (stack.length > 0 && ch === stack[stack.length - 1]) {
+      stack.pop();
+      if (stack.length === 0) return i + 1;
+    }
+  }
+  return text.length;
+}
+
+/** Index of the closing quote of the string that opens at `start`. */
+function endOfString(text: string, start: number): number {
+  const quote = text[start];
+  for (let i = start + 1; i < text.length; i += 1) {
+    if (text[i] === "\\") {
+      i += 1;
+      continue;
+    }
+    if (text[i] === quote) return i;
+    if (quote === "`" && text[i] === "$" && text[i + 1] === "{") {
+      i = endOfRegion(text, i + 1) - 1;
+    }
+  }
+  return text.length;
+}
+
+// Splits a template literal body into safe chunks. A chunk touching an interpolation is dropped at
+// that edge (`w-${size}` claims no class `w-`) unless whitespace separates it from the hole.
+function templateChunks(body: string): string[] {
+  const chunks: string[] = [];
+  let cursor = 0;
+  let precededByHole = false;
+  while (cursor <= body.length) {
+    const hole = body.indexOf("${", cursor);
+    const end = hole === -1 ? body.length : hole;
+    let chunk = body.slice(cursor, end);
+    if (precededByHole && !/^\s/.test(chunk)) chunk = chunk.replace(/^\S+/, "");
+    if (hole !== -1 && !/\s$/.test(chunk)) chunk = chunk.replace(/\S+$/, "");
+    chunks.push(chunk);
+    if (hole === -1) break;
+    cursor = endOfRegion(body, hole + 1);
+    precededByHole = true;
+  }
+  return chunks;
+}
+
+// A same-length copy with comment and string bodies blanked, so offsets line up. Anchors match
+// against it to keep out prose (one apostrophe in a comment opens a string that swallows the rest)
+// and generated code (`captions/generator.ts` writes `x.className = 'word'` into a string).
+function maskLiterals(text: string): string {
+  let out = "";
+  for (let i = 0; i < text.length; i += 1) {
+    const span = endOfSpan(text, i);
+    if (span < i) {
+      out += text[i];
+      continue;
+    }
+    // A comment goes entirely, newlines kept so line numbers survive. A string
+    // keeps its quotes, so the region scan still finds where it ends.
+    const body = " ".repeat(span - i - 1);
+    out +=
+      text[i] === "/"
+        ? text.slice(i, span + 1).replace(/[^\n]/g, " ")
+        : text[i] + body + text[span];
+    i = span;
+  }
+  return out;
+}
+
+// `activeTool === "razor" ? a : b` inside a `className=` region: the operand
+// of a comparison is a value being tested, never a class list.
+const COMPARISON = /(?:[=!]==?|\bcase)\s*$/;
+// A class list never carries a declaration, so `position: absolute; ...` in a
+// constant called `visualStyles` is a stylesheet, not classes.
+const CSS_TEXT = /[a-z-]+\s*:\s*[^;]+;/;
+// The calls whose arguments are class lists.
+const CLASS_BUILDER = /^(?:cn|clsx|classnames|classNames|twMerge|twJoin|cva|tv)$/;
+
+// Written with escapes, not literal quotes: `maskLiterals` reads a quote in
+// a regular-expression literal as the start of a string, and this file is
+// one of the files the gate scans.
+const CLOSE = /[)\]}]/;
+const QUOTE = /[\u0022\u0027\u0060]/;
+
+/**
+ * A string is a class list unless it is being compared against or is a sheet
+ * of CSS text.
+ */
+function isClassList(mask: string, start: number, i: number, body: string): boolean {
+  return !COMPARISON.test(mask.slice(Math.max(start, i - 8), i)) && !CSS_TEXT.test(body);
+}
+
+/**
+ * Does a string inside the bracket that opens at `i` hold classes? A bracket opened by a
+ * non-class-builder name closes the door: `T[f.inlineStyles["font-weight"]]` has a lookup key.
+ */
+function opensClassContext(mask: string, from: number, i: number): boolean {
+  const name = /([A-Za-z_$][\w$]*)\s*$/.exec(mask.slice(Math.max(from, i - 40), i))?.[1];
+  return name === undefined || CLASS_BUILDER.test(name);
+}
+
+/**
+ * Every string and template body inside a source region. Where the strings are
+ * is decided on the mask; what they contain is read from the real text.
+ */
+function stringsIn(text: string, mask: string, start: number, end: number): string[] {
+  const found: string[] = [];
+  const classy: boolean[] = [];
+  for (let i = start; i < end; i += 1) {
+    const ch = mask[i];
+    if (OPEN[ch]) classy.push(opensClassContext(mask, start, i));
+    else if (CLOSE.test(ch)) classy.pop();
+    else if (QUOTE.test(ch)) {
+      const close = endOfString(mask, i);
+      const body = text.slice(i + 1, close);
+      if (classy.at(-1) !== false && isClassList(mask, start, i, body)) {
+        found.push(...(ch === "`" ? templateChunks(body) : [body]));
+      }
+      i = close;
+    }
+  }
+  return found;
+}
+
+/** Split on `:` that sits outside brackets, so `[&:hover]:x` yields `x`. */
+function stripVariants(token: string): string {
+  let depth = 0;
+  let last = 0;
+  for (let i = 0; i < token.length; i += 1) {
+    const ch = token[i];
+    if (ch === "[" || ch === "(") depth += 1;
+    else if (ch === "]" || ch === ")") depth -= 1;
+    else if (ch === ":" && depth === 0) last = i + 1;
+  }
+  return token.slice(last);
+}
+
+// A utility starts with a letter, a digit, `-` (negative), `@` (container
+// query) or `[` (fully arbitrary), and never contains a quote or a backslash.
+// The quotes are written as escapes so this file can be read by its own
+// comment stripper, which treats a quote in a regex literal as a string.
+const TOKEN = /^[-@[a-z0-9][^\s\u0022\u0027\u0060\\]*$/;
+
+// Class contexts: each anchor's balanced region is read for strings. The first `CLASS_POSITIONS` are
+// places a class lands, so identifiers used inside them are followed to their bindings.
+const ANCHORS = [
+  // className={...} / className="..." / class="..."
+  /\bclass(?:Name)?\s*=\s*/g,
+  // cn("..."), clsx(...), twMerge(...), cva(...)
+  /\b(?:cn|clsx|classnames|classNames|twMerge|twJoin|cva|tv)\s*\(/g,
+  // { className: "...", itemClass: "..." }
+  /\b\w*[Cc]lass(?:Names?)?\s*:\s*/g,
+  // const sizeStyles: Record<Size, string> = { ... } / baseClasses = "..." (exported maps used elsewhere)
+  // Prefix and plural both required: bare `style=` is the JSX attribute, `fxPresetStyle` is CSS text.
+  // The optional group is a type annotation; without it the gap spans `computedStyles["z-index"] !== "auto"`.
+  /\b\w+(?:Styles|Classes|ClassNames?)\b(?:\s*:[^=;{}()[\]]*)?\s*=(?!=)\s*/g,
+] as const;
+
+const CLASS_POSITIONS = 3;
+
+/** Bare identifiers in a region of the mask; property accesses excluded. */
+const REFERENCE = /(?<![.\w$])[A-Za-z_$][\w$]*/g;
+
+// A subscript, i.e. the `[variant]` of `variantStyles[variant]`. In
+// `cn(variantStyles[variant])` the class list is the map; the key is a value
+// being looked up, and `variant = "secondary"` is a default, not a class.
+const SUBSCRIPT = /(?<=[\w$)\]])\s*\[[^[\]]*\]/g;
+
+// End of the bracketed region or string at `at`, else -1: `const styles = getComputedStyle(el)`
+// matches the binding-name anchor but is not a class list.
+function regionAfter(mask: string, at: number): number {
+  if (OPEN[mask[at]]) return endOfRegion(mask, at);
+  if (QUOTE.test(mask[at])) return endOfString(mask, at) + 1;
+  return -1;
+}
+
+/** Split one class list into candidates, keeping the first spelling of each. */
+function collect(byRaw: Map<string, ClassCandidate>, list: string): void {
+  for (const raw of list.split(/\s+/)) {
+    if (raw === "" || !TOKEN.test(raw) || byRaw.has(raw)) continue;
+    const base = stripVariants(raw);
+    if (base === "") continue;
+    byRaw.set(raw, { base, raw, arbitrary: base.includes("[") });
+  }
+}
+
+// Every `[start, end)` an anchor opens. `lastIndex` jumps past each region so a nested `cn()`
+// inside a `className=` is not read twice.
+function regionsAfter(mask: string, anchor: RegExp): [number, number][] {
+  const pattern = new RegExp(anchor.source, "g");
+  const regions: [number, number][] = [];
+  let match: RegExpExecArray | null;
+  while ((match = pattern.exec(mask)) !== null) {
+    const start = match.index + match[0].length - (match[0].endsWith("(") ? 1 : 0);
+    const end = regionAfter(mask, start);
+    if (end <= start) continue;
+    regions.push([start, end]);
+    pattern.lastIndex = Math.max(pattern.lastIndex, end);
+  }
+  return regions;
+}
+
+// Every string bound to `name` by an assignment in this file. A name with no literal binding
+// (parameter, import, call result) yields nothing, so an over-broad reference scan is safe.
+function boundStrings(text: string, mask: string, name: string): string[] {
+  const anchor = new RegExp(
+    `(?<![\\w$])${escapeRegex(name)}(?![\\w$])(?:\\s*:[^=;{}()[\\]]*)?\\s*=(?!=)\\s*`,
+  );
+  return regionsAfter(mask, anchor).flatMap(([start, end]) => stringsIn(text, mask, start, end));
+}
+
+/** Every class candidate claimed by one source file. */
+export function extractClassCandidates(source: string): ClassCandidate[] {
+  // Anchors and region bounds come from the mask (code only); the strings
+  // themselves are read back out of the real text.
+  const mask = maskLiterals(source);
+  const byRaw = new Map<string, ClassCandidate>();
+  const referenced = new Set<string>();
+  for (const [index, anchor] of ANCHORS.entries()) {
+    for (const [start, end] of regionsAfter(mask, anchor)) {
+      for (const text of stringsIn(source, mask, start, end)) collect(byRaw, text);
+      if (index >= CLASS_POSITIONS) continue;
+      const used = mask.slice(start, end).replace(SUBSCRIPT, "");
+      for (const [name] of used.matchAll(REFERENCE)) referenced.add(name);
+    }
+  }
+  for (const name of referenced) {
+    for (const text of boundStrings(source, mask, name)) collect(byRaw, text);
+  }
+  return [...byRaw.values()];
+}

package/src/styles/hex-baseline.json

@@ -0,0 +1,84 @@
+{
+  "total": 394,
+  "files": {
+    "packages/studio/src/captions/components/CaptionOverlay.tsx": 5,
+    "packages/studio/src/captions/components/CaptionTimeline.tsx": 11,
+    "packages/studio/src/captions/generator.ts": 1,
+    "packages/studio/src/captions/parser.ts": 1,
+    "packages/studio/src/captions/types.ts": 4,
+    "packages/studio/src/components/StudioToast.tsx": 10,
+    "packages/studio/src/components/TimelineToolbar.tsx": 2,
+    "packages/studio/src/components/editor/ArcPathControls.tsx": 1,
+    "packages/studio/src/components/editor/BorderRadiusEditor.tsx": 10,
+    "packages/studio/src/components/editor/DomEditCropHandles.tsx": 1,
+    "packages/studio/src/components/editor/EaseCurveSection.tsx": 2,
+    "packages/studio/src/components/editor/FileTree.tsx": 2,
+    "packages/studio/src/components/editor/FileTreeIcons.tsx": 17,
+    "packages/studio/src/components/editor/FileTreeNodes.tsx": 4,
+    "packages/studio/src/components/editor/GestureTrailOverlay.tsx": 1,
+    "packages/studio/src/components/editor/GridOverlay.tsx": 4,
+    "packages/studio/src/components/editor/InlineTextToolbar.tsx": 2,
+    "packages/studio/src/components/editor/KeyframeDiamond.tsx": 2,
+    "packages/studio/src/components/editor/KeyframeNavigation.tsx": 2,
+    "packages/studio/src/components/editor/MotionPathNode.tsx": 5,
+    "packages/studio/src/components/editor/SnapGuideOverlay.tsx": 3,
+    "packages/studio/src/components/editor/TimelineFxPopover.tsx": 1,
+    "packages/studio/src/components/editor/Transform3DCube.tsx": 6,
+    "packages/studio/src/components/editor/colorValue.ts": 3,
+    "packages/studio/src/components/editor/domEditingElement.ts": 1,
+    "packages/studio/src/components/editor/easeCurveSvg.tsx": 2,
+    "packages/studio/src/components/editor/gradientValue.ts": 6,
+    "packages/studio/src/components/editor/panelTokens.ts": 4,
+    "packages/studio/src/components/editor/propertyPanelColor.tsx": 7,
+    "packages/studio/src/components/editor/propertyPanelColorCurveGraph.tsx": 17,
+    "packages/studio/src/components/editor/propertyPanelColorScopes.tsx": 8,
+    "packages/studio/src/components/editor/propertyPanelColorWheels.tsx": 8,
+    "packages/studio/src/components/editor/propertyPanelFlatEffectsSection.tsx": 5,
+    "packages/studio/src/components/editor/propertyPanelFlatStyleSections.tsx": 2,
+    "packages/studio/src/components/editor/propertyPanelFxCarveModule.tsx": 1,
+    "packages/studio/src/components/editor/propertyPanelFxFamily.ts": 1,
+    "packages/studio/src/components/editor/propertyPanelFxPresetStyle.ts": 24,
+    "packages/studio/src/components/editor/propertyPanelHelpers.ts": 4,
+    "packages/studio/src/components/editor/propertyPanelPrimitives.tsx": 1,
+    "packages/studio/src/components/editor/propertyPanelSections.tsx": 1,
+    "packages/studio/src/components/editor/propertyPanelStyleSections.tsx": 3,
+    "packages/studio/src/components/editor/transform3dProjection.ts": 3,
+    "packages/studio/src/components/feedback/StudioFeedbackCard.tsx": 10,
+    "packages/studio/src/components/panels/VariablesBindElement.tsx": 2,
+    "packages/studio/src/components/panels/VariablesValueControls.tsx": 2,
+    "packages/studio/src/components/sidebar/AudioRow.tsx": 2,
+    "packages/studio/src/components/ui/HyperframesMark.tsx": 4,
+    "packages/studio/src/hooks/useInlineTextEdit.ts": 1,
+    "packages/studio/src/player/components/AudioWaveform.tsx": 6,
+    "packages/studio/src/player/components/BeatStrip.tsx": 6,
+    "packages/studio/src/player/components/CompositionThumbnail.tsx": 2,
+    "packages/studio/src/player/components/ImageThumbnail.tsx": 6,
+    "packages/studio/src/player/components/LayerDisclosureRow.tsx": 3,
+    "packages/studio/src/player/components/Player.tsx": 2,
+    "packages/studio/src/player/components/PlayerControls.tsx": 1,
+    "packages/studio/src/player/components/PlayheadIndicator.tsx": 3,
+    "packages/studio/src/player/components/ShortcutsPanel.tsx": 7,
+    "packages/studio/src/player/components/SpeedMenu.tsx": 2,
+    "packages/studio/src/player/components/TimelineAutomationLane.tsx": 4,
+    "packages/studio/src/player/components/TimelineCanvas.tsx": 13,
+    "packages/studio/src/player/components/TimelineClip.tsx": 2,
+    "packages/studio/src/player/components/TimelineClipDiamonds.tsx": 2,
+    "packages/studio/src/player/components/TimelineDiamondConnectors.tsx": 2,
+    "packages/studio/src/player/components/TimelineEmptyState.tsx": 1,
+    "packages/studio/src/player/components/TimelineFxButton.tsx": 8,
+    "packages/studio/src/player/components/TimelineGroupHeader.tsx": 6,
+    "packages/studio/src/player/components/TimelineGroupLaneLabels.tsx": 1,
+    "packages/studio/src/player/components/TimelineGroupRow.tsx": 1,
+    "packages/studio/src/player/components/TimelineRazorInteraction.tsx": 1,
+    "packages/studio/src/player/components/TimelineRuler.tsx": 1,
+    "packages/studio/src/player/components/TimelineShortcutHint.tsx": 2,
+    "packages/studio/src/player/components/TimelineTrackHeader.tsx": 2,
+    "packages/studio/src/player/components/TimelineTrackPlainHeader.tsx": 2,
+    "packages/studio/src/player/components/VideoThumbnail.tsx": 6,
+    "packages/studio/src/player/components/timelineTheme.ts": 5,
+    "packages/studio/src/player/components/trackHeaderLabelRows.tsx": 6,
+    "packages/studio/src/styles/studio.css": 70,
+    "packages/studio/src/telemetry/client.ts": 1,
+    "packages/studio/src/webmcp/webmcpTestUtils.ts": 1
+  }
+}

package/src/styles/hexRatchet.test.ts

@@ -0,0 +1,201 @@
+// The hex ratchet (R12, AE2): a per-file baseline of colour literals that only ever goes down.
+// Per file so two sweep PRs touching one file conflict on its line and force a recount.
+// The baseline is never regenerated by a normal run: a missing one fails, and rewriting it needs
+// the named flag, so the number in git is one a human accepted.
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { describe, expect, it } from "vitest";
+import { listSourceFiles, REPO_ROOT, STYLES_DIR } from "./styleSources";
+
+const BASELINE_PATH = path.join(STYLES_DIR, "hex-baseline.json");
+
+const WRITE_FLAG = "HEX_BASELINE_WRITE";
+const LOWER_COMMAND = `${WRITE_FLAG}=1 bunx vitest run src/styles/hexRatchet.test.ts`;
+
+// A literal colour: `#abc`, `#aabbcc`, `#aabbccdd`, or functional notation. This test owns the
+// regex, so the baseline is whatever this rule sees.
+const COLOR_LITERAL = /#(?:[0-9a-f]{8}|[0-9a-f]{6}|[0-9a-f]{3,4})\b|\b(?:rgba?|hsla?)\(/gi;
+
+/** Files whose whole job is to hold colour values. */
+function isTokenSource(relative: string): boolean {
+  return /styles\/(theme\.css|tailwind-preset\.shared\.js|tailwind-preset\.ts)$/.test(relative);
+}
+
+function isScanned(relative: string): boolean {
+  if (isTokenSource(relative) || /\.test\.tsx?$/.test(relative)) return false;
+  return /\.(tsx?|css)$/.test(relative);
+}
+
+/** Strings match first and are kept, so `"image/*"` or `"a//b"` never opens a comment. */
+const STRING_OR_COMMENT =
+  /("(?:\\.|[^"\\\n])*"|'(?:\\.|[^'\\\n])*'|`(?:\\.|[^`\\])*`)|\/\*[\s\S]*?\*\/|\/\/[^\n]*/g;
+
+/** Comments hold issue numbers like `#2291` that read as hex; count code only. */
+function stripComments(text: string, lineComments: boolean): string {
+  return text.replace(STRING_OR_COMMENT, (match, string?: string) => {
+    if (string !== undefined) return match;
+    return match.startsWith("//") && !lineComments ? match : "";
+  });
+}
+
+function countColorLiterals(text: string, lineComments = true): number {
+  return [...stripComments(text, lineComments).matchAll(COLOR_LITERAL)].length;
+}
+
+/** Repository-relative path to colour-literal count, for every scanned file. */
+function scan(): Map<string, number> {
+  const counts = new Map<string, number>();
+  for (const [file, text] of listSourceFiles(isScanned, REPO_ROOT)) {
+    const count = countColorLiterals(text, !file.endsWith(".css"));
+    if (count > 0) counts.set(file, count);
+  }
+  return counts;
+}
+
+interface Baseline {
+  readonly total: number;
+  readonly files: Readonly<Record<string, number>>;
+}
+
+function toBaseline(counts: ReadonlyMap<string, number>): Baseline {
+  const files: Record<string, number> = {};
+  let total = 0;
+  for (const key of [...counts.keys()].sort()) {
+    files[key] = counts.get(key) ?? 0;
+    total += files[key];
+  }
+  return { total, files };
+}
+
+/** Every file whose count moved, split by direction. */
+function compare(counts: ReadonlyMap<string, number>, baseline: Baseline) {
+  const risen: string[] = [];
+  const fallen: string[] = [];
+  // A file missing from the baseline has a baseline of zero, so a rename
+  // cannot smuggle its colours past the ratchet.
+  for (const [file, count] of counts) {
+    const allowed = baseline.files[file] ?? 0;
+    if (count > allowed) risen.push(`${file}: ${count} colour literals, baseline ${allowed}`);
+    if (count < allowed) fallen.push(`${file}: ${count}, baseline ${allowed}`);
+  }
+  for (const [file, allowed] of Object.entries(baseline.files)) {
+    if (!counts.has(file)) fallen.push(`${file}: now 0, baseline ${allowed}`);
+  }
+  return { risen, fallen };
+}
+
+// A rise is a failure. A fall is reported with the command that banks it, because a baseline
+// left high is a budget the next change can spend.
+function verdict(counts: ReadonlyMap<string, number>, baseline: Baseline | undefined): string[] {
+  if (baseline === undefined) {
+    return [`src/styles/hex-baseline.json is missing. Write it with: ${LOWER_COMMAND}`];
+  }
+  const { risen, fallen } = compare(counts, baseline);
+  if (risen.length > 0) {
+    return [
+      "Colour literals belong in src/styles/theme.css.",
+      ...risen,
+      `If these are unavoidable, lower is the only direction: ${LOWER_COMMAND}`,
+    ];
+  }
+  if (fallen.length > 0) return [`Colour literals went down. Bank it: ${LOWER_COMMAND}`, ...fallen];
+  return [];
+}
+
+function readBaseline(): Baseline | undefined {
+  if (!existsSync(BASELINE_PATH)) return undefined;
+  return JSON.parse(readFileSync(BASELINE_PATH, "utf8")) as Baseline;
+}
+
+describe("colour literal counter", () => {
+  it("counts a hex in a style object, in canvas code and in a stylesheet", () => {
+    expect(countColorLiterals(`<div style={{ background: "#161618" }} />`)).toBe(1);
+    expect(countColorLiterals(`context.fillStyle = "#090b0e";`)).toBe(1);
+    expect(countColorLiterals(`.ring { box-shadow: 0 0 0 1px rgb(110 231 183); }`)).toBe(1);
+    expect(countColorLiterals(`a { color: rgba(0, 0, 0, 0.5); border-color: hsl(0 0% 4%); }`)).toBe(
+      2,
+    );
+  });
+
+  it("does not mistake a fragment or an issue number for a colour", () => {
+    // Known limit: an identifier that is exactly 3, 4, 6 or 8 hex characters
+    // in code reads as a colour; the baseline absorbs it.
+    expect(countColorLiterals(`href="#section-two" // see #12345`)).toBe(0);
+  });
+
+  it("keeps a colour that follows comment-shaped text inside a string", () => {
+    expect(countColorLiterals(`accept="image/*"; const c = "#161618"; x = "*/";`)).toBe(1);
+    expect(countColorLiterals("const u = `x//y`; const c = '#161618';")).toBe(1);
+    expect(countColorLiterals(`.a { background: url(//cdn.test/a.png) #161618; }`, false)).toBe(1);
+  });
+
+  it("ignores a colour-shaped issue number in a line or block comment", () => {
+    expect(countColorLiterals(`const a = 1; // decision (#2291)`)).toBe(0);
+    expect(countColorLiterals(`/** see #2291 and rgba(0,0,0,1) */\nconst a = 1;`)).toBe(0);
+    expect(countColorLiterals(`fetch("https://x.test/#abc"); const c = "#161618"; // #2291`)).toBe(
+      2,
+    );
+  });
+
+  it("leaves the token sources and the tests out of the scan", () => {
+    expect(isScanned("packages/studio/src/styles/theme.css")).toBe(false);
+    expect(isScanned("packages/studio/src/styles/tailwind-preset.shared.js")).toBe(false);
+    expect(isScanned("packages/studio/src/styles/theme.test.ts")).toBe(false);
+    expect(isScanned("packages/studio/src/components/ui/Button.tsx")).toBe(true);
+  });
+});
+
+describe("hex ratchet", () => {
+  const baseline: Baseline = { total: 2, files: { "a.tsx": 2 } };
+
+  it("fails when a file's count rises, naming the file and both numbers", () => {
+    // Covers AE2.
+    const message = verdict(new Map([["a.tsx", 3]]), baseline).join("\n");
+
+    expect(message).toContain("a.tsx: 3 colour literals, baseline 2");
+    expect(message).toContain(LOWER_COMMAND);
+  });
+
+  it("passes when a count falls and says how to bank it", () => {
+    const message = verdict(new Map([["a.tsx", 1]]), baseline).join("\n");
+
+    expect(message).toContain("Colour literals went down");
+    expect(message).toContain(LOWER_COMMAND);
+  });
+
+  it("treats a file the baseline has never seen as a baseline of zero", () => {
+    const empty: Baseline = { total: 0, files: {} };
+
+    expect(verdict(new Map([["new.tsx", 0]]), empty)).toEqual([]);
+    expect(verdict(new Map([["new.tsx", 1]]), empty).join("\n")).toContain(
+      "new.tsx: 1 colour literals, baseline 0",
+    );
+  });
+
+  it("round-trips: a baseline written from a scan accepts that same scan", () => {
+    const counts = new Map([
+      ["b.css", 4],
+      ["a.tsx", 2],
+    ]);
+    const written = toBaseline(counts);
+
+    expect(Object.keys(written.files)).toEqual(["a.tsx", "b.css"]);
+    expect(written.total).toBe(6);
+    expect(verdict(counts, written)).toEqual([]);
+  });
+
+  it("fails with the flag named when there is no baseline at all", () => {
+    expect(verdict(new Map([["a.tsx", 0]]), undefined).join("\n")).toContain(`${WRITE_FLAG}=1`);
+  });
+
+  it("holds Studio at or below its committed colour-literal baseline", () => {
+    const counts = scan();
+    if (process.env[WRITE_FLAG] === "1") {
+      writeFileSync(BASELINE_PATH, `${JSON.stringify(toBaseline(counts), null, 2)}\n`);
+    }
+    const committed = readBaseline();
+
+    expect(verdict(counts, committed)).toEqual([]);
+  });
+});

package/src/styles/iconTokens.ts

@@ -0,0 +1,20 @@
+import type { IconWeight } from "@phosphor-icons/react";
+
+const WEIGHTS = ["thin", "light", "regular", "bold", "fill", "duotone"] as const;
+
+function asWeight(value: string): IconWeight | null {
+  return (WEIGHTS as readonly string[]).includes(value) ? (value as IconWeight) : null;
+}
+
+/** Studio's Phosphor defaults, read off `theme.css` so size and weight have one
+ * owner instead of a CSS variable and a JS constant that drift. A missing or
+ * unrecognized value falls back to Phosphor's own default. */
+export function readIconTokens(root: Element = document.documentElement): {
+  size: string;
+  weight: IconWeight;
+} {
+  const styles = getComputedStyle(root);
+  const size = styles.getPropertyValue("--icon-size").trim();
+  const weight = asWeight(styles.getPropertyValue("--icon-weight").trim());
+  return { size: size || "1em", weight: weight ?? "regular" };
+}

package/src/styles/palette-reset.css

@@ -0,0 +1,6 @@
+/* Studio's own app clears Tailwind's stock palette so only Studio tokens are
+ * reachable from markup. Kept out of theme.css so a host importing the tokens
+ * keeps its own colours. Must be imported before theme.css. */
+@theme static {
+  --color-*: initial;
+}