basalt-ui 1.19.1 → 1.21.0

package/dist/guard/index.js

@@ -1,7 +1,7 @@
 const HEX = /#[0-9a-fA-F]{3,8}\b/g;
-const FUNC = /\b(?:rgba?|hsla?)\(/g;
+const FUNC = /\b(?:rgba?|hsla?)\((?!\s*\$\{)/g;
 const LOCALSTORAGE_THEME = /localStorage\s*\.\s*getItem\s*\(\s*['"]theme['"]\s*\)/g;
-const RAW_FONT_FAMILY_VAR_ESCAPE = /var\(\s*--(?:basalt-font-|mantine-font-family-)/.source;
+const RAW_FONT_FAMILY_VAR_ESCAPE = /var\(\s*--/.source;
 const RAW_FONT_FAMILY_KEYWORD = /(?:inherit|initial|unset|revert)\b/.source;
 const RAW_FONT_FAMILY = new RegExp(
   `\\bfontFamily\\s*[:=]\\s*\\{?(?!['"\`]?\\s*${RAW_FONT_FAMILY_VAR_ESCAPE})(?!['"\`]?\\s*${RAW_FONT_FAMILY_KEYWORD})['"\`][^'"\`]+['"\`]|\\bfont-family\\s*:\\s*(?!['"\`]?\\s*${RAW_FONT_FAMILY_VAR_ESCAPE})(?!['"\`]?\\s*${RAW_FONT_FAMILY_KEYWORD})(?:['"\`][^'"\`]+['"\`]|[A-Za-z][\\w-]*)`,
@@ -9,14 +9,42 @@ const RAW_FONT_FAMILY = new RegExp(
 );
 const SURFACE_BORDER = /\bborder(?:Top|Bottom|Left|Right)?\s*:\s*(?!['"`]?[^'"`]*(?:var\(|\$\{))(?!['"`]?(?:none|transparent|inherit|unset|revert)\b)['"`][^'"`]+['"`]/g;
 const SURFACE_RADIUS = /\bborderRadius\s*:\s*(?:[0-9]+|['"`](?!\s*var\()[^'"`]*[0-9])/g;
-const SURFACE_SHADOW = /\bboxShadow\s*:\s*(?!['"`]?[^'"`]*(?:var\(|\$\{))['"`][^'"`]+['"`]/g;
+const SHADOW_DECL = /\b(?:boxShadow|box-shadow)\s*:\s*(['"`])((?:[^'"`\\]|\\.)*)\1/g;
+const SHADOW_KEEPS_CARD_DEPTH = /--vx-shadow-|\bVX\.shadow/;
+const SHADOW_IS_COMPOSED = /var\(|\$\{/;
+const CSS_SURFACE_RADIUS = /(?<![\w-])border-radius\s*:\s*([^;}]+)/g;
+const CSS_SURFACE_SHADOW = /(?<![\w-])box-shadow\s*:\s*([^;}]+)/g;
+const MICRO_RADIUS_CEILING_PX = 3;
+const SHAPE_RADIUS_VALUES = /* @__PURE__ */ new Set(["50%", "9999px", "999px", "100%"]);
+function isAllowedCssRadius(value) {
+  const rest = value.replace(/var\([^)]*\)/g, " ").trim();
+  if (rest === "") return true;
+  return rest.split(/\s+/).every((part) => {
+    if (SHAPE_RADIUS_VALUES.has(part)) return true;
+    const literal = /^[-+]?(\d+(?:\.\d+)?|\.\d+)(px|rem)?$/.exec(part);
+    if (literal === null) return false;
+    const px = literal[2] === "rem" ? Number(literal[1]) * ROOT_FONT_SIZE_PX : Number(literal[1]);
+    return px <= MICRO_RADIUS_CEILING_PX;
+  });
+}
+const INLINE_FONT_SIZE = /(?<![\w-;])font-?[Ss]ize\s*:\s*['"]?(\d+(?:\.\d+)?)(?:px)?['"]?(?=[,;\s}]|$)/g;
 const CARD_SURFACE_TAG = /<(?:Card|Paper)(?![\w.])(?:=>|[^>])*?>/g;
 const WITH_BORDER_PROP = /\bwithBorder\b(?!\s*=\s*\{\s*false\s*\})/;
 const OFF_SYSTEM_SURFACE_VAR = /var\(--mantine-color-(gray|dark)-\d/g;
 const MANTINE_SHADE_INDEX = /\b(?:color|c|bg|backgroundColor|borderColor)\s*=\s*\{?\s*['"][a-z]+\.\d\b|var\(--mantine-color-(?!gray-|dark-)[a-z]+-\d/g;
-const RAW_HTML_TAG = /<(?:div|span|section|header|nav|footer|aside|main|article|ul|ol)\b/;
+const RAW_HTML_TAG_NAME = "<(?:div|span|section|header|nav|footer|aside|main|article|ul|ol)\\b";
+const RAW_HTML_TAG = new RegExp(RAW_HTML_TAG_NAME);
+const RAW_HTML_LAYOUT_TAG = new RegExp(`${RAW_HTML_TAG_NAME}(?:=>|[^>])*?>`, "g");
 const INLINE_STYLE = /style=\{\{/;
+const STYLE_IDENTIFIER = /style=\{\s*([A-Za-z_$][\w$]*)\s*\}/;
 const LAYOUT_SURFACE_PROP = /\b(?:display|padding|margin|gap|flex|grid|border|background|width|height)\b/;
+function hoistedObjectBody(codeText, name) {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const decl = new RegExp(`\\b(?:const|let|var)\\s+${escaped}\\b[^=;]*=\\s*\\{([^}]*)\\}`).exec(
+    codeText
+  );
+  return decl?.[1] ?? "";
+}
 const BOX_SIDE = "(?:Top|Bottom|Left|Right|Block|Inline)(?:Start|End)?";
 const BOX_SIDE_KEBAB = "(?:top|bottom|left|right|block|inline)(?:-(?:start|end))?";
 const SPACING_PROP = `(?:padding|margin)(?:${BOX_SIDE}|-${BOX_SIDE_KEBAB})?|gap|rowGap|columnGap|row-gap|column-gap`;
@@ -26,6 +54,38 @@ const INLINE_SPACING = new RegExp(
   "g"
 );
 const MICRO_SPACING_CEILING_PX = 10;
+const STYLE_ATTRIBUTE_OPENER = /\b(?:style|styles|sx|css)\s*=\s*\{?\s*$/;
+const OBJECT_DECLARATION = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::([^=]*))?=\s*$/;
+const STYLE_OBJECT_NAME = /(?:Style|Styles|Css)$|^(?:style|styles|css|sx)$/;
+const STYLE_OBJECT_TYPE = /\bCSS(?:Properties|Object)\b|\bStyle(?:s|Prop)?\b/;
+const STYLE_BOUND_IDENTIFIER = /\b(?:style|styles|sx|css)=\{\s*([A-Za-z_$][\w$]*)\s*\}/g;
+const NESTED_OBJECT_KEY = /(?:[\w$]+|'[^']*'|"[^"]*"|\[[^\]]*\])\s*:\s*$/;
+const MAX_STYLE_CONTEXT_SCAN = 4e3;
+function isStyleObjectContext(codeText, at, styleIdentifiers) {
+  let depth = 0;
+  const stop = Math.max(0, at - MAX_STYLE_CONTEXT_SCAN);
+  for (let i = at - 1; i >= stop; i--) {
+    const ch = codeText[i];
+    if (ch === "}") depth++;
+    else if (ch === "{") {
+      if (depth > 0) {
+        depth--;
+        continue;
+      }
+      const before = codeText.slice(Math.max(0, i - 120), i);
+      if (STYLE_ATTRIBUTE_OPENER.test(before)) return true;
+      const declaration = OBJECT_DECLARATION.exec(before);
+      if (declaration !== null) {
+        const [, name = "", annotation = ""] = declaration;
+        return STYLE_OBJECT_NAME.test(name) || STYLE_OBJECT_TYPE.test(annotation) || styleIdentifiers.has(name);
+      }
+      if (before.endsWith("{")) continue;
+      if (NESTED_OBJECT_KEY.test(before)) continue;
+      return false;
+    }
+  }
+  return false;
+}
 const ROOT_FONT_SIZE_PX = 16;
 function isSubScaleCssSpacing(line, matchIndex) {
   const colon = line.indexOf(":", matchIndex);
@@ -77,9 +137,15 @@ const DEFAULT_GUARD_CONFIG = {
   exemptRules: {},
   severity: {}
 };
-const GRACE_PERIOD_KINDS = {};
+const GRACE_PERIOD_KINDS = {
+  "theme-allow-unscoped": "introduced in the round-4 guard minor \u2014 promote to error one minor later. Every consumer has bare `theme-allow` comments today (basalt itself has ~20), and landing this as an error would fail every one of their builds on an upgrade they took for the fixes.",
+  "surface-shadow-override": "introduced in the round-4 guard minor \u2014 promote to error one minor later. Catches the shape a TOKEN-FLUENT consumer writes, so the code it rejects is code that looks correct and passed every previous release.",
+  "css-raw-surface": 'introduced in the round-4 guard minor \u2014 promote to error one minor later. The surface kinds reaching CSS at all is the "existing kind, new file type" case the doctrine names explicitly.',
+  "inline-font-size": "introduced in the round-4 guard minor \u2014 promote to error one minor later. The oxlint plugin has enforced the same thing as `basalt/no-raw-font-size` for a while, so a consumer running both sees nothing new; one running check-theme alone gets a minor of runway.",
+  "hidden-inline-style": "introduced in the round-4 guard minor \u2014 promote by DELETING the kind and folding its two scans into `raw-html-layout`, which is where they belong once the widening has had its minor."
+};
 function severityOf(kind, cfg) {
-  return cfg.severity?.[kind] ?? (kind in GRACE_PERIOD_KINDS ? "warn" : "error");
+  return cfg.severity?.[kind] ?? (Object.hasOwn(GRACE_PERIOD_KINDS, kind) ? "warn" : "error");
 }
 const FINDING_TEXT_MAX_LENGTH = 100;
 function textForFinding(sourceLine, fallbackToken) {
@@ -90,18 +156,241 @@ function textForFinding(sourceLine, fallbackToken) {
 function isChartFile(relPath) {
   return relPath.includes("/charts/") && !AXIS_WRAPPER_FILE.test(relPath);
 }
+const EXEMPT_RULE_ALIASES = {
+  "hidden-inline-style": "raw-html-layout",
+  "surface-shadow-override": "raw-surface",
+  "css-raw-surface": "raw-surface"
+};
+function normalizeExemptPattern(pattern) {
+  return pattern.trim().replace(/^\.\//, "").replace(/\/+$/, "");
+}
+function exemptGlobToRegExp(pattern) {
+  const body = pattern.split(/(\*\*\/|\*\*|\*|\?)/).map((part) => {
+    if (part === "**/") return "(?:.*/)?";
+    if (part === "**") return ".*";
+    if (part === "*") return "[^/]*";
+    if (part === "?") return "[^/]";
+    return part.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  }).join("");
+  return new RegExp(`^${body}$`);
+}
+function exemptPatternMatches(pattern, relPath) {
+  const p = normalizeExemptPattern(pattern);
+  if (p === "") return false;
+  if (relPath === p || relPath.startsWith(`${p}/`)) return true;
+  if (/[*?]/.test(p)) {
+    const re = exemptGlobToRegExp(p);
+    if (re.test(relPath)) return true;
+    if (!p.includes("/") && re.test(relPath.split("/").pop() ?? "")) return true;
+    return false;
+  }
+  return !p.includes("/") && relPath.split("/").includes(p);
+}
 function isRuleExempt(kind, relPath, exemptRules) {
+  const alias = EXEMPT_RULE_ALIASES[kind];
+  if (alias !== void 0 && isRuleExempt(alias, relPath, exemptRules)) return true;
   const patterns = exemptRules?.[kind];
   if (patterns === void 0 || patterns.length === 0) return false;
-  const segments = relPath.split("/");
-  return patterns.some((pattern) => segments.includes(pattern.replace(/\/$/, "")));
+  return patterns.some((pattern) => exemptPatternMatches(pattern, relPath));
 }
-function isSkippedLine(line, cfg) {
-  return line.includes(cfg.allowComment);
+function unmatchedExemptPatterns(cfg, scannedRelPaths) {
+  const out = [];
+  for (const [kind, patterns] of Object.entries(cfg.exemptRules ?? {})) {
+    const known = Object.hasOwn(GUARD_RULES, kind);
+    for (const pattern of patterns ?? []) {
+      if (!known) {
+        out.push({ kind, pattern, reason: "unknown-kind" });
+        continue;
+      }
+      if (scannedRelPaths.some((relPath) => exemptPatternMatches(pattern, relPath))) continue;
+      out.push({ kind, pattern, reason: "no-match" });
+    }
+  }
+  return out;
+}
+const PLUGIN_RULE_IDS = /* @__PURE__ */ new Set([
+  "no-raw-font-size",
+  "raw-size-literal",
+  "card-inset",
+  "chart-in-raw-surface",
+  "hand-rolled-plot",
+  "chart-legend-literal",
+  "hand-rolled-shell",
+  "shadow-basalt-export",
+  "raw-scroll-container",
+  "visx-boundary",
+  "visx-tooltip",
+  "token-layer-boundary",
+  // These three honour `basalt-agent-allow`, never `theme-allow` — but they are still REAL ids, so
+  // a `theme-allow ai-sdk-major` must parse as a (useless) scoped annotation rather than as prose.
+  "agent-resume-guard",
+  "agent-no-raw-usechat",
+  "ai-sdk-major"
+]);
+const MIN_ALLOW_REASON_LENGTH = 4;
+function parseAllowAnnotation(rest, scope) {
+  const rules = [];
+  const unknownRules = [];
+  let remainder = rest.replace(/^[\s,]+/, "");
+  let inIdSlot = true;
+  for (; ; ) {
+    const token = /^(?:basalt\/)?([a-z][a-z0-9-]*)(?=$|[\s,:—–])/.exec(remainder);
+    const id = token?.[1];
+    if (token === null || id === void 0) break;
+    if (!(Object.hasOwn(GUARD_RULES, id) || PLUGIN_RULE_IDS.has(id))) {
+      if (inIdSlot) unknownRules.push(id);
+      break;
+    }
+    rules.push(id);
+    const after = remainder.slice(token[0].length);
+    remainder = after.replace(/^[\s,]+/, "");
+    inIdSlot = /^\s*,/.test(after);
+  }
+  const reason = remainder.replace(/^(?:—|–|-{1,2}|:)\s*/, "").trim();
+  return { rules, unknownRules, hasReason: reason.length >= MIN_ALLOW_REASON_LENGTH, scope };
+}
+const MAX_CSS_CONTINUATION_LINES = 8;
+const MAX_COMMENT_BLOCK_LINES = 8;
+const COMMENT_OPENER_BEFORE = /(?:\/\/|\/\*|<!--)\s*$/;
+const COMMENT_ONLY_LINE = /^\s*(?:\{\s*\/\*|\/\/|\/\*|\*|<!--)/;
+const ANNOTATION_PREFIX = /(?:^|\/\/|\/\*|<!--|^\s*\*)\s*$/;
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function allowTokenRe(allowComment) {
+  return new RegExp(`${escapeRegExp(allowComment)}(-file)?(?![\\w-])`, "g");
+}
+function jsonAllowKeyRe(allowComment) {
+  return new RegExp(`"basalt:${escapeRegExp(allowComment)}(-file)?"\\s*:\\s*"([^"]*)"`, "g");
+}
+function collectAllowAnnotations(lines, codeLines, allowComment, syntax) {
+  const byLine = /* @__PURE__ */ new Map();
+  const fileScoped = [];
+  const declared = [];
+  const add = (index, annotation) => {
+    const list = byLine.get(index) ?? [];
+    list.push(annotation);
+    byLine.set(index, list);
+  };
+  const record = (index, annotation, trailing) => {
+    declared.push({ line: index + 1, annotation });
+    if (annotation.scope === "file") {
+      fileScoped.push(annotation);
+      return;
+    }
+    add(index, annotation);
+    if (!trailing) {
+      for (let ahead = 1; ahead <= MAX_COMMENT_BLOCK_LINES; ahead++) {
+        const raw = lines[index + ahead] ?? "";
+        add(index + ahead, annotation);
+        if (raw.trim() !== "" && (codeLines[index + ahead] ?? "").trim() !== "") break;
+        if (raw.trim() === "") break;
+      }
+      return;
+    }
+    if (syntax !== "css") return;
+    for (let back = 1; back <= MAX_CSS_CONTINUATION_LINES; back++) {
+      const previous = (codeLines[index - back] ?? "").trim();
+      if (previous === "" || /[;{}]$/.test(previous)) break;
+      add(index - back, annotation);
+    }
+  };
+  const token = allowTokenRe(allowComment);
+  const jsonKey = jsonAllowKeyRe(allowComment);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    const stripped = codeLines[i] ?? "";
+    const isCommentOnlyLine = stripped.trim() === "" || COMMENT_ONLY_LINE.test(line);
+    if (syntax === "markup") {
+      for (const m of line.matchAll(jsonKey)) {
+        record(i, parseAllowAnnotation(m[2] ?? "", m[1] === void 0 ? "line" : "file"), false);
+      }
+    }
+    for (const m of line.matchAll(token)) {
+      const at = m.index;
+      const before = line.slice(0, at);
+      if (stripped[at] !== " " && !COMMENT_OPENER_BEFORE.test(before)) continue;
+      if (!ANNOTATION_PREFIX.test(before)) continue;
+      const rest = line.slice(at + m[0].length);
+      record(
+        i,
+        parseAllowAnnotation(rest, m[1] === void 0 ? "line" : "file"),
+        !isCommentOnlyLine
+      );
+    }
+  }
+  return { waivers: byLine, fileScoped, declared };
+}
+function annotationCovers(annotation, kind) {
+  if (annotation.rules.includes(kind)) return true;
+  if (annotation.scope === "file") return false;
+  return annotation.rules.length === 0 && annotation.unknownRules.length === 0;
+}
+function annotationsCover(annotations, kind) {
+  return (annotations ?? []).some((a) => annotationCovers(a, kind));
 }
 function guardSyntaxFor(relPath) {
-  return relPath.endsWith(".css") ? "css" : "ts";
+  if (relPath.endsWith(".css")) return "css";
+  if (/\.(?:html?|webmanifest|json)$/.test(relPath)) return "markup";
+  return "ts";
+}
+const MARKUP_KINDS = /* @__PURE__ */ new Set(["raw-hex", "raw-color-fn", "raw-font-family"]);
+function stripMarkupComments(text) {
+  return text.replace(/<!--[\s\S]*?-->/g, (m) => m.replace(/[^\n]/g, " "));
+}
+const GENERATED_HEADER_LINE = "/* @generated basalt-ui \u2014 do not edit; regenerate with the command on the next line */";
+const GENERATED_PROVENANCE_LINE = /^\/\* basalt-ui \d+\.\d+\.\d+[^\s]* — `basalt-ui (?:tokens:css|fonts:css)[^`]*` \*\/$/;
+const GENERATED_HEADER_LINES = 2;
+const GENERATED_COMMENT_LINE = /^\/\*(?:[^*]|\*(?!\/))*\*\/$/;
+const GENERATED_SELECTOR_LINE = /^[^{};]*[,{]$/;
+const GENERATED_DECL_LINE = /^(?:--(?:vx|basalt)-[A-Za-z0-9_-]*\s*:[^{};]*;|\})$/;
+const NO_GENERATED_LINES = /* @__PURE__ */ new Set();
+function braceDelta(line) {
+  let delta = 0;
+  for (const ch of line) {
+    if (ch === "{") delta++;
+    else if (ch === "}") delta--;
+  }
+  return delta;
+}
+function generatedTokenLines(relPath, lines, allowComment) {
+  if (!relPath.endsWith(".css")) return NO_GENERATED_LINES;
+  if ((lines[0] ?? "").trim() !== GENERATED_HEADER_LINE) return NO_GENERATED_LINES;
+  if (!GENERATED_PROVENANCE_LINE.test((lines[1] ?? "").trim())) return NO_GENERATED_LINES;
+  const skippable = /* @__PURE__ */ new Set([1, 2]);
+  let depth = 0;
+  for (let i = GENERATED_HEADER_LINES; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    const trimmed = line.trim();
+    const shaped = trimmed === "" || GENERATED_COMMENT_LINE.test(trimmed) || (depth === 0 ? GENERATED_SELECTOR_LINE : GENERATED_DECL_LINE).test(trimmed);
+    if (shaped && !line.includes(allowComment)) skippable.add(i + 1);
+    depth += braceDelta(line);
+    if (depth < 0) return NO_GENERATED_LINES;
+  }
+  return skippable;
 }
+const TOKENS_ONLY_DISABLED_KINDS = /* @__PURE__ */ new Set([
+  "localstorage-theme",
+  "off-identity-accent",
+  "mantine-shade-index",
+  "raw-spacing",
+  "raw-radius",
+  "card-with-border",
+  "off-system-surface-var",
+  "raw-html-layout",
+  // Same remedy as raw-html-layout, word for word ("use a Mantine layout primitive") — it is that
+  // kind's widening, so it has to share its gate here exactly as it shares it in
+  // EXEMPT_RULE_ALIASES. Splitting them told a Mantine-free consumer to import Box/Flex.
+  "hidden-inline-style",
+  "inline-spacing",
+  "inline-display",
+  "raw-visx-axis",
+  "raw-motion-value",
+  "unframed-chart",
+  "chart-missing-aria-label",
+  "raw-form-control",
+  "sub-16-input-font"
+]);
 const REGEX_PRECEDING_PUNCT = /* @__PURE__ */ new Set([
   "=",
   "(",
@@ -419,13 +708,63 @@ const GUARD_RULES = {
     // object literal — both JSX-shaped, neither appears in CSS text.
     appliesTo: (relPath) => !relPath.endsWith(".css"),
     message: "fontSize below 16 on a form control is dead code \u2014 the styles.css iOS floor is `!important` and always wins. Either drop the override, or be honest about 16px in the design."
+  },
+  "theme-allow-unscoped": {
+    kind: "theme-allow-unscoped",
+    pattern: /theme-allow/,
+    // handled inline (annotation pass); entry keeps the registry complete
+    message: "theme-allow without a usable rule id and a reason. Write `theme-allow <rule-id> \u2014 <why>`: the id scopes the exception to that one kind (a bare comment waives EVERY kind on the line, including ones added later), and the reason is what makes it reviewable in a diff. An id that names no rule is a typo, not a blanket waiver \u2014 it suppresses nothing. `theme-allow-file <rule-id> \u2014 <why>` declares the whole file, and must name its ids: a bare one waives nothing."
+  },
+  "surface-shadow-override": {
+    kind: "surface-shadow-override",
+    pattern: SHADOW_DECL,
+    // handled inline (value is judged, not just matched)
+    enabled: (cfg) => cfg.rawSurface,
+    message: "Token-composed boxShadow that REPLACES surface depth \u2014 a card whose shadow drops --vx-shadow-card is the one card in the app with no depth. Compose with the depth token for its tier (`${VX.shadowCard}, <your ring>`; a fixed/floating surface wants --vx-shadow-overlay) rather than instead of it."
+  },
+  "css-raw-surface": {
+    kind: "css-raw-surface",
+    pattern: CSS_SURFACE_RADIUS,
+    // handled inline (value is judged); entry keeps the registry complete
+    enabled: (cfg) => cfg.rawSurface,
+    // The kebab dialect only exists in CSS text; the camelCase half is `raw-surface`.
+    appliesTo: (relPath) => relPath.endsWith(".css"),
+    message: "Surface literal in CSS \u2014 use var(--vx-radius-card|--vx-radius-md) for a corner and var(--vx-shadow-card) for depth, the same tokens the TSX side is held to."
+  },
+  "hidden-inline-style": {
+    kind: "hidden-inline-style",
+    pattern: RAW_HTML_LAYOUT_TAG,
+    // handled inline (full-text tag-scoped scan + hoisted-const lookup)
+    enabled: (cfg) => cfg.rawHtmlLayout,
+    appliesTo: (relPath) => !isChartFile(relPath) && !relPath.endsWith(".css"),
+    message: "Raw HTML element with inline layout/surface styling that the line scan cannot see \u2014 the tag is formatted across lines, or the style object is hoisted to a const. Same violation as raw-html-layout: use a Mantine layout primitive (Box/Flex/Grid/Stack/Group). Its own kind for one minor so the widening lands as a warning; it merges into raw-html-layout at the promotion."
+  },
+  "inline-font-size": {
+    kind: "inline-font-size",
+    pattern: INLINE_FONT_SIZE,
+    message: "Raw font-size literal \u2014 route through VX.text.* (numbers) / --vx-text-* (CSS), or the Mantine fz token. Same rule the oxlint plugin enforces as basalt/no-raw-font-size; this is the half a check-theme-only CI can see."
   }
 };
+function guardKindRemedy(kind) {
+  return `${kind}: ${GUARD_RULES[kind].message}`;
+}
+const JSON_FAMILY_FILE = /\.(?:webmanifest|json)$/;
+function guardWaiverHint(relPath) {
+  if (relPath.endsWith(".webmanifest")) {
+    return 'A manifest cannot reference a CSS variable, so a hex here is a hand-copy that drifts: let basaltAppPlugin emit it (`manifest: { \u2026 }` in vite.config.ts) instead of hand-writing it. For a manifest basalt does not generate, declare the exception with a `"basalt:theme-allow-file": "raw-hex \u2014 <why>"` member.';
+  }
+  if (JSON_FAMILY_FILE.test(relPath)) {
+    return 'JSON has no comments \u2014 declare a deliberate exception with a `"basalt:theme-allow-file": "<rule-id> \u2014 <why>"` member.';
+  }
+  return "Add a `theme-allow <rule-id> \u2014 <why>` comment for a deliberate exception (`theme-allow-file` declares the whole file).";
+}
 function ruleApplies(kind, relPath) {
   const appliesTo = GUARD_RULES[kind].appliesTo;
   return appliesTo === void 0 || appliesTo(relPath);
 }
 function checkSource(text, relPath, cfg) {
+  const lines = text.split("\n");
+  const generatedLines = generatedTokenLines(relPath, lines, cfg.allowComment);
   const findings = [];
   const forbiddenAccentRe = GUARD_RULES["off-identity-accent"].pattern(cfg);
   const spacingPropRe = GUARD_RULES["raw-spacing"].pattern(cfg);
@@ -433,101 +772,179 @@ function checkSource(text, relPath, cfg) {
     GUARD_RULES["raw-radius"].pattern.source,
     GUARD_RULES["raw-radius"].pattern.flags
   );
-  const lines = text.split("\n");
   const syntax = guardSyntaxFor(relPath);
-  const codeText = stripComments(text, syntax);
+  const codeText = syntax === "markup" ? stripMarkupComments(text) : stripComments(text, syntax);
   const codeLines = codeText.split("\n");
+  const { waivers, fileScoped, declared } = collectAllowAnnotations(
+    lines,
+    codeLines,
+    cfg.allowComment,
+    syntax
+  );
+  const fileWaived = /* @__PURE__ */ new Set();
+  for (const annotation of fileScoped) {
+    for (const rule of annotation.rules) {
+      if (Object.hasOwn(GUARD_RULES, rule)) fileWaived.add(rule);
+    }
+  }
+  const isAllowed = (line, kind) => fileWaived.has(kind) || annotationsCover(waivers.get(line - 1), kind);
+  const isAllowedInRange = (start, end, kind) => {
+    for (let n = start; n <= end; n++) if (isAllowed(n, kind)) return true;
+    return false;
+  };
+  const push = (kind, line, token) => {
+    if (isAllowed(line, kind)) return;
+    findings.push({ relPath, line, token, kind });
+  };
+  for (const { line, annotation } of declared) {
+    if (annotation.unknownRules.length === 0 && annotation.rules.length > 0 && annotation.hasReason)
+      continue;
+    const unknown = `unknown rule id '${annotation.unknownRules.join("', '")}'`;
+    const missing = annotation.unknownRules.length > 0 ? annotation.rules.length === 0 ? `${unknown} \u2014 waives nothing` : `${unknown} \u2014 not waived` : annotation.rules.length === 0 ? "no rule id" : "no reason";
+    findings.push({
+      relPath,
+      line,
+      token: `${cfg.allowComment} (${missing})`,
+      kind: "theme-allow-unscoped"
+    });
+  }
+  const rawHtmlLayoutLines = /* @__PURE__ */ new Set();
+  const lineStarts = [];
+  for (let n = 0, i = 0; i < codeLines.length; i++) {
+    lineStarts.push(n);
+    n += (codeLines[i] ?? "").length + 1;
+  }
+  const styleIdentifiers = new Set(
+    [...codeText.matchAll(STYLE_BOUND_IDENTIFIER)].map((m) => m[1] ?? "")
+  );
   for (let i = 0; i < lines.length; i++) {
     const line = codeLines[i] ?? "";
-    if ((lines[i] ?? "").includes(cfg.allowComment)) continue;
     for (const m of line.matchAll(GUARD_RULES["raw-hex"].pattern)) {
-      findings.push({ relPath, line: i + 1, token: m[0], kind: "raw-hex" });
+      push("raw-hex", i + 1, m[0]);
     }
     for (const m of line.matchAll(GUARD_RULES["raw-color-fn"].pattern)) {
-      findings.push({ relPath, line: i + 1, token: m[0], kind: "raw-color-fn" });
+      push("raw-color-fn", i + 1, m[0]);
     }
     if (ruleApplies("localstorage-theme", relPath)) {
       for (const m of line.matchAll(GUARD_RULES["localstorage-theme"].pattern)) {
-        findings.push({ relPath, line: i + 1, token: m[0], kind: "localstorage-theme" });
+        push("localstorage-theme", i + 1, m[0]);
       }
     }
     for (const m of line.matchAll(GUARD_RULES["raw-font-family"].pattern)) {
-      findings.push({ relPath, line: i + 1, token: m[0], kind: "raw-font-family" });
+      push("raw-font-family", i + 1, m[0]);
+    }
+    for (const m of line.matchAll(GUARD_RULES["inline-font-size"].pattern)) {
+      push("inline-font-size", i + 1, m[0]);
     }
     if (ruleApplies("off-identity-accent", relPath)) {
       for (const m of line.matchAll(forbiddenAccentRe)) {
-        findings.push({ relPath, line: i + 1, token: m[1] ?? "", kind: "off-identity-accent" });
+        push("off-identity-accent", i + 1, m[1] ?? "");
       }
     }
     if (ruleApplies("raw-spacing", relPath)) {
-      for (const m of line.matchAll(spacingPropRe)) {
-        findings.push({ relPath, line: i + 1, token: m[0], kind: "raw-spacing" });
-      }
+      for (const m of line.matchAll(spacingPropRe)) push("raw-spacing", i + 1, m[0]);
     }
     if (GUARD_RULES["raw-radius"].enabled(cfg) && ruleApplies("raw-radius", relPath)) {
-      for (const m of line.matchAll(radiusPropRe)) {
-        findings.push({ relPath, line: i + 1, token: m[0], kind: "raw-radius" });
-      }
+      for (const m of line.matchAll(radiusPropRe)) push("raw-radius", i + 1, m[0]);
     }
     if (GUARD_RULES["raw-surface"].enabled(cfg)) {
-      for (const m of line.matchAll(SURFACE_BORDER)) {
-        findings.push({ relPath, line: i + 1, token: m[0], kind: "raw-surface" });
-      }
-      for (const m of line.matchAll(SURFACE_RADIUS)) {
-        findings.push({ relPath, line: i + 1, token: m[0], kind: "raw-surface" });
-      }
-      for (const m of line.matchAll(SURFACE_SHADOW)) {
-        findings.push({ relPath, line: i + 1, token: m[0], kind: "raw-surface" });
+      for (const m of line.matchAll(SURFACE_BORDER)) push("raw-surface", i + 1, m[0]);
+      for (const m of line.matchAll(SURFACE_RADIUS)) push("raw-surface", i + 1, m[0]);
+      if (syntax === "css") {
+        for (const m of line.matchAll(CSS_SURFACE_RADIUS)) {
+          const value = m[1] ?? "";
+          if (!/\d/.test(value) || isAllowedCssRadius(value)) continue;
+          push("css-raw-surface", i + 1, m[0].trim());
+        }
+        for (const m of line.matchAll(CSS_SURFACE_SHADOW)) {
+          const value = m[1] ?? "";
+          if (SHADOW_IS_COMPOSED.test(value) || /^\s*none\s*$/.test(value)) continue;
+          push("css-raw-surface", i + 1, m[0].trim());
+        }
+      } else {
+        for (const m of line.matchAll(SHADOW_DECL)) {
+          const value = m[2] ?? "";
+          if (!SHADOW_IS_COMPOSED.test(value)) {
+            push("raw-surface", i + 1, m[0]);
+            continue;
+          }
+          if (SHADOW_KEEPS_CARD_DEPTH.test(value)) continue;
+          push("surface-shadow-override", i + 1, m[0]);
+        }
       }
     }
     if (GUARD_RULES["off-system-surface-var"].enabled(cfg)) {
       for (const m of line.matchAll(GUARD_RULES["off-system-surface-var"].pattern)) {
-        findings.push({ relPath, line: i + 1, token: m[0], kind: "off-system-surface-var" });
+        push("off-system-surface-var", i + 1, m[0]);
       }
     }
     if (GUARD_RULES["mantine-shade-index"].enabled(cfg)) {
       for (const m of line.matchAll(GUARD_RULES["mantine-shade-index"].pattern)) {
-        findings.push({ relPath, line: i + 1, token: m[0], kind: "mantine-shade-index" });
+        push("mantine-shade-index", i + 1, m[0]);
       }
     }
     if (GUARD_RULES["raw-html-layout"].enabled(cfg) && ruleApplies("raw-html-layout", relPath) && RAW_HTML_TAG.test(line) && INLINE_STYLE.test(line) && LAYOUT_SURFACE_PROP.test(line)) {
-      findings.push({ relPath, line: i + 1, token: "<raw-html style>", kind: "raw-html-layout" });
+      rawHtmlLayoutLines.add(i + 1);
+      push("raw-html-layout", i + 1, "<raw-html style>");
     }
     if (GUARD_RULES["inline-spacing"].enabled(cfg)) {
       for (const m of line.matchAll(GUARD_RULES["inline-spacing"].pattern)) {
         if (syntax === "css" && isSubScaleCssSpacing(line, m.index)) continue;
-        findings.push({ relPath, line: i + 1, token: m[0], kind: "inline-spacing" });
+        const hasUnit = /^[a-z%]/.test(line.slice(m.index + m[0].length));
+        if (syntax === "ts" && !hasUnit && !isStyleObjectContext(codeText, lineStarts[i] + m.index, styleIdentifiers))
+          continue;
+        push("inline-spacing", i + 1, m[0]);
       }
     }
     if (GUARD_RULES["inline-display"].enabled(cfg) && ruleApplies("inline-display", relPath)) {
       for (const m of line.matchAll(GUARD_RULES["inline-display"].pattern)) {
-        findings.push({ relPath, line: i + 1, token: m[0], kind: "inline-display" });
+        push("inline-display", i + 1, m[0]);
       }
     }
     if (GUARD_RULES["raw-visx-axis"].enabled(cfg) && GUARD_RULES["raw-visx-axis"].appliesTo(relPath)) {
       for (const m of line.matchAll(GUARD_RULES["raw-visx-axis"].pattern)) {
-        findings.push({ relPath, line: i + 1, token: m[0], kind: "raw-visx-axis" });
+        push("raw-visx-axis", i + 1, m[0]);
       }
     }
     if (GUARD_RULES["raw-motion-value"].enabled(cfg) && ruleApplies("raw-motion-value", relPath)) {
-      for (const m of line.matchAll(MOTION_TRANSITION_NUMERIC)) {
-        findings.push({ relPath, line: i + 1, token: m[0], kind: "raw-motion-value" });
-      }
+      for (const m of line.matchAll(MOTION_TRANSITION_NUMERIC))
+        push("raw-motion-value", i + 1, m[0]);
       for (const m of line.matchAll(MOTION_TRANSITION_EASE_ARRAY)) {
-        findings.push({ relPath, line: i + 1, token: m[0], kind: "raw-motion-value" });
+        push("raw-motion-value", i + 1, m[0]);
       }
     }
     if (GUARD_RULES["raw-form-control"].enabled(cfg) && ruleApplies("raw-form-control", relPath)) {
       for (const m of line.matchAll(GUARD_RULES["raw-form-control"].pattern)) {
-        findings.push({ relPath, line: i + 1, token: m[0], kind: "raw-form-control" });
+        push("raw-form-control", i + 1, m[0]);
       }
     }
   }
+  if (GUARD_RULES["hidden-inline-style"].enabled(cfg) && ruleApplies("hidden-inline-style", relPath)) {
+    for (const m of codeText.matchAll(RAW_HTML_LAYOUT_TAG)) {
+      const tagText = m[0];
+      let styleBody = "";
+      if (INLINE_STYLE.test(tagText)) styleBody = tagText;
+      else {
+        const ident = STYLE_IDENTIFIER.exec(tagText)?.[1];
+        if (ident !== void 0) styleBody = hoistedObjectBody(codeText, ident);
+      }
+      if (styleBody === "" || !LAYOUT_SURFACE_PROP.test(styleBody)) continue;
+      const startLine = codeText.slice(0, m.index ?? 0).split("\n").length;
+      if (rawHtmlLayoutLines.has(startLine)) continue;
+      const endLine = startLine + (tagText.split("\n").length - 1);
+      if (isAllowedInRange(startLine, endLine, "hidden-inline-style")) continue;
+      findings.push({
+        relPath,
+        line: startLine,
+        token: "<raw-html style>",
+        kind: "hidden-inline-style"
+      });
+    }
+  }
   if (GUARD_RULES["unframed-chart"].enabled(cfg) && ruleApplies("unframed-chart", relPath)) {
     for (const m of codeText.matchAll(RAW_CHART_LEGEND_ARRAY)) {
       const lineNo = codeText.slice(0, (m.index ?? 0) + m[0].length).split("\n").length;
-      if (isSkippedLine(lines[lineNo - 1] ?? "", cfg)) continue;
-      findings.push({ relPath, line: lineNo, token: "items={[", kind: "unframed-chart" });
+      push("unframed-chart", lineNo, "items={[");
     }
   }
   if (GUARD_RULES["chart-missing-aria-label"].enabled(cfg) && ruleApplies("chart-missing-aria-label", relPath)) {
@@ -536,14 +953,7 @@ function checkSource(text, relPath, cfg) {
       if (HAS_ARIA_LABEL_PROP.test(tagText)) continue;
       const startLine = codeText.slice(0, m.index ?? 0).split("\n").length;
       const endLine = startLine + (tagText.split("\n").length - 1);
-      let skipped = false;
-      for (let n = startLine; n <= endLine; n++) {
-        if (isSkippedLine(lines[n - 1] ?? "", cfg)) {
-          skipped = true;
-          break;
-        }
-      }
-      if (skipped) continue;
+      if (isAllowedInRange(startLine, endLine, "chart-missing-aria-label")) continue;
       findings.push({
         relPath,
         line: startLine,
@@ -557,8 +967,7 @@ function checkSource(text, relPath, cfg) {
       const withBorder = WITH_BORDER_PROP.exec(m[0]);
       if (withBorder === null) continue;
       const lineNo = codeText.slice(0, (m.index ?? 0) + withBorder.index).split("\n").length;
-      if (isSkippedLine(lines[lineNo - 1] ?? "", cfg)) continue;
-      findings.push({ relPath, line: lineNo, token: "withBorder", kind: "card-with-border" });
+      push("card-with-border", lineNo, "withBorder");
     }
   }
   if (GUARD_RULES["sub-16-input-font"].enabled(cfg) && ruleApplies("sub-16-input-font", relPath)) {
@@ -570,8 +979,7 @@ function checkSource(text, relPath, cfg) {
       const value = Number.parseFloat(fontSizeMatch[1] ?? "");
       if (!Number.isFinite(value) || value >= 16) continue;
       const lineNo = codeText.slice(0, (m.index ?? 0) + tagText.length).split("\n").length;
-      if (isSkippedLine(lines[lineNo - 1] ?? "", cfg)) continue;
-      findings.push({ relPath, line: lineNo, token: fontSizeMatch[0], kind: "sub-16-input-font" });
+      push("sub-16-input-font", lineNo, fontSizeMatch[0]);
     }
     for (const m of codeText.matchAll(STYLES_INPUT_PART)) {
       const inputBody = m[1] ?? "";
@@ -580,11 +988,10 @@ function checkSource(text, relPath, cfg) {
       const value = Number.parseFloat(fontSizeMatch[1] ?? "");
       if (!Number.isFinite(value) || value >= 16) continue;
       const lineNo = codeText.slice(0, (m.index ?? 0) + m[0].length).split("\n").length;
-      if (isSkippedLine(lines[lineNo - 1] ?? "", cfg)) continue;
-      findings.push({ relPath, line: lineNo, token: fontSizeMatch[0], kind: "sub-16-input-font" });
+      push("sub-16-input-font", lineNo, fontSizeMatch[0]);
     }
   }
-  return findings.filter((f) => !isRuleExempt(f.kind, f.relPath, cfg.exemptRules)).map((f) => ({
+  return findings.filter((f) => !generatedLines.has(f.line)).filter((f) => !isRuleExempt(f.kind, f.relPath, cfg.exemptRules)).filter((f) => syntax !== "markup" || MARKUP_KINDS.has(f.kind)).filter((f) => cfg.profile !== "tokens-only" || !TOKENS_ONLY_DISABLED_KINDS.has(f.kind)).map((f) => ({
     ...f,
     text: textForFinding(lines[f.line - 1], f.token),
     severity: severityOf(f.kind, cfg)
@@ -592,6 +999,11 @@ function checkSource(text, relPath, cfg) {
 }
 export {
   DEFAULT_GUARD_CONFIG,
+  GENERATED_HEADER_LINE,
   GUARD_RULES,
-  checkSource
+  TOKENS_ONLY_DISABLED_KINDS,
+  checkSource,
+  guardKindRemedy,
+  guardWaiverHint,
+  unmatchedExemptPatterns
 };