basalt-ui 1.19.1 → 1.21.0

package/src/guard/index.ts

@@ -1,7 +1,7 @@
 /**
  * ./guard — headless policy core. Mantine-free, dependency-free.
  *
- * GUARD_RULES: the closed registry of all 19 violation kinds.
+ * GUARD_RULES: the closed registry of all 25 violation kinds.
  * checkSource:  pure (text, relPath, cfg) → Finding[]. No FS, no walk, no console.
  */
 import type { Finding, GuardConfig, GuardKind, GuardSeverity } from './types'
@@ -11,17 +11,32 @@ export type { Finding, GuardConfig, GuardKind, GuardSeverity }
 // ── Static regex consts ──────────────────────────────────────────────────────────────────────────
 
 const HEX = /#[0-9a-fA-F]{3,8}\b/g
-const FUNC = /\b(?:rgba?|hsla?)\(/g
+
+/**
+ * A raw `rgb()`/`rgba()`/`hsl()`/`hsla()` color function.
+ *
+ * The `(?!\s*\$\{)` guard drops a call whose FIRST channel is a `${…}` interpolation — that is a
+ * color being COMPUTED, not chosen: an imaging app reporting a sampled pixel
+ * (`` `rgb(${px[0]}, ${px[1]}, ${px[2]})` ``), a debug log quoting one, a readout label. There is
+ * no token that could be correct for a measurement, and the three cases image-gen reported were
+ * all this shape. A literal first channel (`rgba(0, 0, 0, ${o})`) is still a hardcoded color with
+ * a variable alpha, and still flags — `alpha(token, a)` is exactly the escape for it.
+ */
+const FUNC = /\b(?:rgba?|hsla?)\((?!\s*\$\{)/g
 const LOCALSTORAGE_THEME = /localStorage\s*\.\s*getItem\s*\(\s*['"]theme['"]\s*\)/g
 
 // A hardcoded fontFamily/font-family literal — camelCase (JSX prop / object property, quoted
 // value) or kebab-case (CSS text in a template literal, quoted OR bare value — kebab-case is never
 // a valid unquoted JS identifier, so a bare `font-family: Inter` can only be literal CSS text).
-// The escape is a `var(...)` reference restricted to the two entry-point prefixes
-// (`--basalt-font-*` / `--mantine-font-family-*`) — any OTHER var() reference still flags, so the
-// single-entry-point invariant holds. A CSS-wide keyword (inherit/initial/unset/revert) never
-// flags either: it defers to the cascade rather than hardcoding a font.
-const RAW_FONT_FAMILY_VAR_ESCAPE = /var\(\s*--(?:basalt-font-|mantine-font-family-)/.source
+// The escape is ANY `var(--…)` reference. It used to be restricted to the two entry-point prefixes
+// (`--basalt-font-*` / `--mantine-font-family-*`), which reported `font-family: var(--font-sans)`
+// — a variable REFERENCE — as "a hardcoded fontFamily literal", with a fix pointing at the
+// React-only `createBasaltTheme`. A framework-free consumer defining its own custom property IS
+// routing through a variable; the single-entry-point invariant is a doctrine for basalt's own
+// theme layer, not something this regex can tell apart from a legitimate consumer indirection.
+// A CSS-wide keyword (inherit/initial/unset/revert) never flags either: it defers to the cascade
+// rather than hardcoding a font.
+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})['"\`][^'"\`]+['"\`]` +
@@ -39,7 +54,77 @@ 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
+
+/**
+ * A `boxShadow` / `box-shadow` declaration with its whole value captured, so the value can be
+ * JUDGED rather than merely pattern-excluded.
+ *
+ * The old `SURFACE_SHADOW` skipped any value containing `var(` or `${`, which reads as "already
+ * system-routed" and is wrong for the shape a token-fluent consumer actually writes:
+ * `` boxShadow: `0 0 0 2px ${VX.accent}` `` on a `Paper` is built entirely from tokens and still
+ * REPLACES `--vx-shadow-card`, leaving that one card with no depth while every other card in the
+ * app has it. Composing WITH card depth (`` `${VX.shadowCard}, 0 0 0 1px …` ``) is the legitimate
+ * shape and the one this must not touch — so the discriminator is whether the value still names
+ * card depth, not whether it contains a token at all. See `surface-shadow-override`.
+ */
+const SHADOW_DECL = /\b(?:boxShadow|box-shadow)\s*:\s*(['"`])((?:[^'"`\\]|\\.)*)\1/g
+/** A shadow value that still carries basalt's card depth — composes with it rather than replacing it. */
+const SHADOW_KEEPS_CARD_DEPTH = /--vx-shadow-|\bVX\.shadow/
+/** A shadow value routed through SOME variable/interpolation (vs. a hardcoded literal). */
+const SHADOW_IS_COMPOSED = /var\(|\$\{/
+
+/**
+ * The kebab-case surface literals a CSS Module writes. `raw-surface` is camelCase-only — the TSX
+ * inline-style dialect — so `border-radius: 4px` beside a flagged `borderRadius: 2` was invisible.
+ * `src/guard/index.ts`'s `INLINE_SPACING` records that the same asymmetry was deliberately fixed
+ * for spacing; this is that fix for the surface kinds.
+ *
+ * Reaching CSS is a NEW file type for these checks, so they land under their own kind
+ * (`css-raw-surface`, warn for one minor) instead of widening `raw-surface` — see
+ * {@link GuardSeverity}. `border`/`border-top` are deliberately NOT covered: nearly every CSS
+ * module in every consumer declares one, and the token answer (`var(--vx-surface-border)`) is a
+ * COLOR, not a whole shorthand, so the rule would be advice nobody can act on line-by-line.
+ */
+const CSS_SURFACE_RADIUS = /(?<![\w-])border-radius\s*:\s*([^;}]+)/g
+const CSS_SURFACE_SHADOW = /(?<![\w-])box-shadow\s*:\s*([^;}]+)/g
+
+/** The largest CSS radius literal treated as a sub-scale micro-corner, in px — below the 4px floor. */
+const MICRO_RADIUS_CEILING_PX = 3
+/** Radius values that name a SHAPE rather than a surface corner — a circle and the pill idiom. */
+const SHAPE_RADIUS_VALUES = new Set(['50%', '9999px', '999px', '100%'])
+
+/**
+ * Is this `border-radius` value already system-routed or sub-scale? `var(...)` components are
+ * dropped first (same treatment as `isSubScaleCssSpacing`), then a value survives when every
+ * remaining literal is a shape keyword or a length at/below {@link MICRO_RADIUS_CEILING_PX}.
+ */
+function isAllowedCssRadius(value: string): boolean {
+  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
+  })
+}
+
+/**
+ * An inline `fontSize` / `font-size` literal — the `check-theme` counterpart to the oxlint plugin's
+ * `basalt/no-raw-font-size`. A consumer whose CI runs only `check-theme` (the documented
+ * `configs/check.yml` step) never saw a `style={{ fontSize: 11 }}` at all.
+ *
+ * Unitless integers and `px` only, matching React's inline-style convention and CSS's absolute
+ * form. `rem`/`em`/`%` are deliberately out: they are ratios against something else, and the type
+ * scale has no opinion on a relative step.
+ */
+// The `(?<![\w-;])` guard is what keeps this out of query strings and URL fragments: argo builds a
+// Static Maps legend as `…;fontSize:10;dpi:96`, which is a REMOTE renderer's parameter, not a type
+// choice, and no `--vx-text-*` could be correct for it. A declaration written by a formatter always
+// has whitespace or an opening brace in front of the property; a packed key/value string does not.
+const INLINE_FONT_SIZE =
+  /(?<![\w-;])font-?[Ss]ize\s*:\s*['"]?(\d+(?:\.\d+)?)(?:px)?['"]?(?=[,;\s}]|$)/g
 
 // A `Card` / `Paper` opening tag carrying `withBorder`. Card depth is `--vx-shadow-card`, whose 1px
 // ring lives INSIDE the shadow value; `withBorder` therefore adds a SECOND, real `border` property
@@ -72,12 +157,42 @@ 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
 
-// Raw lowercase JSX layout/surface element with inline style and layout/surface prop — line-scoped.
-const RAW_HTML_TAG = /<(?:div|span|section|header|nav|footer|aside|main|article|ul|ol)\b/
+/**
+ * A raw lowercase JSX layout/surface element's own OPENING TAG — bounded full-text scan, the same
+ * shape `CARD_SURFACE_TAG` uses.
+ *
+ * This kind used to be a three-condition conjunction evaluated per LINE, so the identical
+ * violation was reported or not depending purely on how the formatter had broken the tag:
+ * `<div style={{ position: 'relative', … }}>` on one line fired, while the same `<div>` with
+ * `className=` and `style=` on separate lines did not. `card-with-border` already had the answer.
+ */
+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=\{\{/
+/** `style={someStyleConst}` — the hoisted form that defeats every text-local check. */
+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/
 
+/**
+ * The object body of a `const <name> = { … }` declaration, or `''` when there is none.
+ *
+ * Hoisting the style object out of the tag (`const wrapperStyle: CSSProperties = {…}` then
+ * `style={wrapperStyle}`) is the general escape from every text-local kind, and it is what a
+ * formatter nudges people toward. One non-nested lookup closes the common case; a style object
+ * assembled across statements is out of reach of a regex scanner and stays out of reach.
+ */
+function hoistedObjectBody(codeText: string, name: string): string {
+  // `name` comes from source text and reaches a RegExp — a `$`-prefixed identifier is legal JS and
+  // is an anchor in a pattern, so it gets escaped rather than trusted.
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const decl = new RegExp(`\\b(?:const|let|var)\\s+${escaped}\\b[^=;]*=\\s*\\{([^}]*)\\}`).exec(
+    codeText,
+  )
+  return decl?.[1] ?? ''
+}
+
 // Spacing/sizing literals — anchored on the property name; `var()` and a plain `0` pass.
 //
 // Composed rather than written out because it must cover BOTH spellings of the same property: the
@@ -132,11 +247,93 @@ const INLINE_SPACING = new RegExp(
  * there is no prop form, and the emitted `--vx-space-*` set is basalt's own component one-offs
  * (`--vx-space-toc-sub-indent`), not a consumer surface. Without this escape a consumer's CSS
  * module had no legal way to write a 4px cluster gap: no token to reach for, `theme-allow` on every
- * line (which `basalt-tokens.md` explicitly warns against), or `exemptRules` — which matches whole
- * path segments and so cannot express `*.module.css`.
+ * line (which `basalt-tokens.md` explicitly warns against), or `exemptRules` — which at the time
+ * matched whole path segments only and so could not express `*.module.css` (it can now, see
+ * `exemptPatternMatches`; the escape stays because a per-file exemption is still the wrong shape
+ * for a value that has no token).
  */
 const MICRO_SPACING_CEILING_PX = 10
 
+/**
+ * Object-literal openers that make the properties under them CSS.
+ *
+ * A UNITLESS spacing number is only a length by React's inline-style convention, and that
+ * convention only holds inside a style object. `const FIT_BOUNDS_OPTIONS = { padding: 48, duration:
+ * 0 }` is a maplibre viewport inset measured in MAP pixels — there is no Mantine token that could
+ * express it, and "use p/m/gap with xs..xl" is not a thing that can be done to it. The same shape
+ * arrives from every canvas/map/layout library a consumer wraps, so this is a class, not a case.
+ *
+ * A value carrying a UNIT (`'12px'`, `1.5rem`) is exempt from this test entirely — a unit IS the
+ * evidence that the number is CSS, wherever it was written.
+ */
+/** `style={{`, `styles={{`, `sx={{`, `css={{` — the object under it IS CSS by construction. */
+const STYLE_ATTRIBUTE_OPENER = /\b(?:style|styles|sx|css)\s*=\s*\{?\s*$/
+
+/** `const wrapperStyle: CSSProperties = {` — the hoisted form; name and type are both evidence. */
+const OBJECT_DECLARATION = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*(?::([^=]*))?=\s*$/
+
+/** A name that says "these are styles" on its own, without a `style={…}` use site to confirm it. */
+const STYLE_OBJECT_NAME = /(?:Style|Styles|Css)$|^(?:style|styles|css|sx)$/
+
+/** A type annotation that says the same thing — `CSSProperties`, `CSSObject`, `MantineStyleProp`. */
+const STYLE_OBJECT_TYPE = /\bCSS(?:Properties|Object)\b|\bStyle(?:s|Prop)?\b/
+
+/** `style={someStyleConst}` / `styles={parts}` — collected file-wide, so a hoisted object is known. */
+const STYLE_BOUND_IDENTIFIER = /\b(?:style|styles|sx|css)=\{\s*([A-Za-z_$][\w$]*)\s*\}/g
+
+/** A property key introducing a nested object — `input: {`, `'&:hover': {`, `root: {`. */
+const NESTED_OBJECT_KEY = /(?:[\w$]+|'[^']*'|"[^"]*"|\[[^\]]*\])\s*:\s*$/
+
+/** How far back {@link isStyleObjectContext} walks before giving up. Bounded so a huge file can't stall. */
+const MAX_STYLE_CONTEXT_SCAN = 4000
+
+/**
+ * Is the match at `at` inside an inline-style object literal?
+ *
+ * Walks out through enclosing `{` openers (a nested part like `styles={{ input: { … } }}` keeps
+ * walking) and asks what introduced the outermost one: a style ATTRIBUTE, or a `const` whose name
+ * says styles or which some `style={…}` in the file binds. Everything else — a call argument, an
+ * options bag, a plain record — is not CSS.
+ *
+ * Consulted only for a UNITLESS number, where the alternative is reporting a violation with no
+ * possible remedy. A value carrying a unit is CSS wherever it was written and never reaches here.
+ */
+function isStyleObjectContext(
+  codeText: string,
+  at: number,
+  styleIdentifiers: ReadonlySet<string>,
+): boolean {
+  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)
+        )
+      }
+      // `{{` — a JSX expression container around the style object; keep walking out to the `=`.
+      if (before.endsWith('{')) continue
+      // A nested style part (`styles={{ input: { … } }}`) — the key names a part, not a context.
+      if (NESTED_OBJECT_KEY.test(before)) continue
+      return false
+    }
+  }
+  return false
+}
+
 /** The root font size `rem` values resolve against — the same 16 the token layer's `pxRem` uses. */
 const ROOT_FONT_SIZE_PX = 16
 
@@ -281,26 +478,42 @@ export const DEFAULT_GUARD_CONFIG: GuardConfig = {
  * someone remembering. Adding a kind here is part of shipping it; removing the entry IS the
  * promotion, and belongs in its own commit so the changelog says enforcement got stricter.
  *
- * `mantine-shade-index` landed in 1.7.0 and is the sole entry — it rejects `c="yellow.7"`, which
- * previously passed, and the one real consumer has several. Its promotion is **deferred to 1.10.0**,
- * for the second time and for the same reason both times: the runway is measured in consumer
- * upgrades, not in version numbers. 1.8.0 shipped the same day as 1.7.0, so promoting there would
- * have given no runway at all. 1.9.0 then carried the chart-layer batch the same consumer asked
- * for — bundling a build-breaking promotion into the minor they upgrade for the fixes turns a
- * routine bump into an unplanned refactor, which is precisely what the grace minor exists to
- * prevent. 1.10.0 is the first minor they can take the promotion on its own. Promote it by deleting
- * the entry (its own commit).
+ * The runway is measured in consumer UPGRADES, not in version numbers: `mantine-shade-index`
+ * (the table's first tenant, promoted and gone) sat here across two minors because 1.8.0 shipped
+ * the same day as 1.7.0 and 1.9.0 carried the chart batch the same consumer was upgrading for —
+ * bundling a build-breaking promotion into the minor they take for the fixes turns a routine bump
+ * into an unplanned refactor, which is exactly what the grace minor exists to prevent. The five
+ * entries below all landed together in the round-4 guard minor and all promote one minor later.
  *
  * @example
  * const GRACE: Partial<Record<GuardKind, string>> = {
  *   'raw-font-family': 'introduced 1.4.0 — promote to error in 1.5.0',
  * }
  */
-const GRACE_PERIOD_KINDS: Partial<Record<GuardKind, string>> = {}
+const GRACE_PERIOD_KINDS: Partial<Record<GuardKind, string>> = {
+  'theme-allow-unscoped':
+    'introduced in the round-4 guard minor — 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 — 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 — 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 — 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 — 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.',
+}
 
 /** A kind's effective severity: consumer override first, then the grace table, then `error`. */
 function severityOf(kind: GuardKind, cfg: GuardConfig): GuardSeverity {
-  return cfg.severity?.[kind] ?? (kind in GRACE_PERIOD_KINDS ? 'warn' : 'error')
+  return cfg.severity?.[kind] ?? (Object.hasOwn(GRACE_PERIOD_KINDS, kind) ? 'warn' : 'error')
 }
 
 /** The `Finding.text` cap, in characters — a minified CSS line must not blow up the report. */
@@ -325,47 +538,626 @@ function isChartFile(relPath: string): boolean {
   return relPath.includes('/charts/') && !AXIS_WRAPPER_FILE.test(relPath)
 }
 
+/**
+ * Kinds that inherit another kind's `exemptRules` entry. A grace-minor kind that exists only to
+ * carry a WIDENING of an established kind is the same rule to a consumer, so an exemption written
+ * for the parent must cover it — otherwise the widening arrives as noise in exactly the paths
+ * someone already decided the rule does not apply to. The entry disappears with the merge.
+ */
+const EXEMPT_RULE_ALIASES: Partial<Record<GuardKind, GuardKind>> = {
+  'hidden-inline-style': 'raw-html-layout',
+  'surface-shadow-override': 'raw-surface',
+  'css-raw-surface': 'raw-surface',
+}
+
+/** `./` and any trailing `/` are noise — `'agent'`, `'agent/'` and `'./agent'` are one pattern. */
+function normalizeExemptPattern(pattern: string): string {
+  return pattern.trim().replace(/^\.\//, '').replace(/\/+$/, '')
+}
+
+/** `*` stops at a `/`, `**` does not, `?` is one non-`/` character. Everything else is literal. */
+function exemptGlobToRegExp(pattern: string): RegExp {
+  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}$`)
+}
+
+/**
+ * Does one `exemptRules` pattern match `relPath`?
+ *
+ * Three shapes, tried in the order a consumer reaches for them:
+ *
+ * 1. **A relative path** — `public/site.webmanifest` for one file, `public` or `src/agent` for
+ *    everything under a directory.
+ * 2. **A glob** — `public/*.webmanifest`, `**\/*.module.css`; a glob with no `/` in it is also
+ *    tried against the BASENAME, so `*.module.css` works the way `site.webmanifest` does.
+ * 3. **A bare path segment** — the legacy shape, matching a whole segment anywhere in the path.
+ *
+ * Only (3) existed, and it was the one shape nobody guesses: rollhook wrote the obvious, correct
+ * `"public/site.webmanifest"`, matched nothing, got no diagnostic, and kept reporting. That is a
+ * silent no-op exemption, and it became load-bearing the minute `.webmanifest`/`.json` entered the
+ * scan — see {@link unmatchedExemptPatterns} for the other half of the fix.
+ */
+function exemptPatternMatches(pattern: string, relPath: string): boolean {
+  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)
+}
+
 /**
  * Whether `kind` is exempted at `relPath` via `cfg.exemptRules` — the config-driven, per-rule
- * counterpart to `isChartFile`'s hardcoded path scoping. A pattern matches when `relPath` split on
- * `/` includes it as a WHOLE segment (a trailing `/` is stripped first, so `'agent'` and `'agent/'`
- * are equivalent); a substring match against one longer segment (e.g. `'age'` against `agent`)
- * never counts.
+ * counterpart to `isChartFile`'s hardcoded path scoping.
  */
 function isRuleExempt(
   kind: GuardKind,
   relPath: string,
   exemptRules: GuardConfig['exemptRules'],
 ): boolean {
+  const alias = EXEMPT_RULE_ALIASES[kind]
+  if (alias !== undefined && isRuleExempt(alias, relPath, exemptRules)) return true
   const patterns = exemptRules?.[kind]
   if (patterns === undefined || patterns.length === 0) return false
-  const segments = relPath.split('/')
-  return patterns.some((pattern) => segments.includes(pattern.replace(/\/$/, '')))
+  return patterns.some((pattern) => exemptPatternMatches(pattern, relPath))
+}
+
+/** One `exemptRules` entry that suppressed nothing, and why — see {@link unmatchedExemptPatterns}. */
+export type UnmatchedExemptPattern = {
+  readonly kind: string
+  readonly pattern: string
+  readonly reason: 'unknown-kind' | 'no-match'
 }
 
 /**
- * The allow-comment skip the full-text tag-scoped scans re-apply on their own resolved report
- * line: a line carrying the allow-comment is never a violation. Pure-comment lines need no
- * special case here anymore — they are handled upstream by `stripComments` (matches simply can't
- * land on blanked-out comment text), so this only ever runs against the ORIGINAL (unstripped)
- * line, since the allow-comment annotation itself lives inside a comment.
+ * Every `exemptRules` entry that matched no scanned file, so a run can say so instead of passing.
+ *
+ * An exemption is a claim ("this rule does not apply here"), and a claim that resolves to nothing is
+ * not harmless — it reads as coverage in a config review while enforcing exactly as much as an empty
+ * object. rollhook's `["public/site.webmanifest"]` was correct, matched nothing under the
+ * segments-only matcher, and reported no diagnostic; the finding it was written for kept failing the
+ * build with the config sitting right there looking like the answer. A silent no-op exemption is the
+ * same false-green family as a guard that reports green while enforcing nothing.
+ *
+ * Called once per run by the CLI with every relative path it scanned. Kind keys are checked too: a
+ * typo'd kind name is an exemption for a rule that does not exist.
  */
-function isSkippedLine(line: string, cfg: GuardConfig): boolean {
-  return line.includes(cfg.allowComment)
+export function unmatchedExemptPatterns(
+  cfg: GuardConfig,
+  scannedRelPaths: readonly string[],
+): UnmatchedExemptPattern[] {
+  const out: UnmatchedExemptPattern[] = []
+  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
 }
 
-/** The 2 comment/regex dialects the stripper understands, resolved from the file's own extension. */
-type GuardSyntax = 'ts' | 'css'
+// ── theme-allow annotations ──────────────────────────────────────────────────────────────────────
+
+/**
+ * The oxlint plugin's rule ids. Not guard kinds — they can never suppress a `checkSource` finding —
+ * but they ARE valid ids in a `theme-allow`, so an annotation scoped to one of them must parse as
+ * accountable rather than be reported as unscoped. Kept as a literal list because the plugin is a
+ * standalone `.js` file this module must not import (see the plugin's own header).
+ */
+const PLUGIN_RULE_IDS: ReadonlySet<string> = 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',
+])
+
+/** The shortest string accepted as a written reason — enough to exclude a stray separator. */
+const MIN_ALLOW_REASON_LENGTH = 4
+
+/**
+ * How far one annotation reaches.
+ *
+ * `line` is the default and covers the placements in {@link collectAllowAnnotations}. `file` is the
+ * whole-file declaration, and it has to be SPELLED (`theme-allow-file`) rather than inferred: at
+ * 1.20.0 a `theme-allow <id> — <reason>` written anywhere in a file was silently promoted to a file
+ * declaration by the oxlint plugin, so naming a rule AND giving a reason — the exact shape the
+ * guard's own message asks for — was the only legal annotation and it was always whole-file. A
+ * consumer who wanted to waive one node and stay policed on the rest could not say so.
+ */
+type AllowScope = 'line' | 'file'
+
+/**
+ * One parsed `theme-allow` annotation.
+ *
+ * `rules` empty AND `unknownRules` empty is the legacy bare form, and only that covers every kind —
+ * and only at `line` scope, never `file` (see {@link annotationCovers}).
+ * `unknownRules` holds words that occupied the rule-id slot but name no rule — a typo. Its presence
+ * is what makes the parse FAIL CLOSED: `theme-allow raw-hexx — reason` used to consume no id, fall
+ * through to `rules: []`, and be read as the blanket form, so one mistyped character escalated a
+ * scoped waiver into a whole-line one. A waiver that names a rule must never be more permissive
+ * than the same waiver spelled correctly.
+ */
+type AllowAnnotation = {
+  readonly rules: readonly string[]
+  readonly unknownRules: readonly string[]
+  readonly hasReason: boolean
+  readonly scope: AllowScope
+}
+
+/** One annotation at the (1-based) line it was WRITTEN on — where `theme-allow-unscoped` reports. */
+type AllowDeclaration = { readonly line: number; readonly annotation: AllowAnnotation }
+
+/**
+ * Parse the text following the allow token on one line.
+ *
+ * The grammar is `theme-allow [<rule-id>[, <rule-id>]…] [<separator>] <reason>`. Ids are consumed
+ * while they are KNOWN (a guard kind or a plugin rule, optionally `basalt/`-prefixed). A word that
+ * occupies the id slot but names no rule ENDS the list as an UNKNOWN id rather than starting the
+ * reason — see {@link AllowAnnotation.unknownRules} for why that direction is the safe one.
+ *
+ * A prose reason therefore has to be introduced the way every annotation in the wild already writes
+ * it — with a separator (`—`, `–`, `-`, `:`) — which is what keeps `theme-allow: bespoke mono
+ * micro-label` a blanket waiver while `theme-allow raw-hexx — …` waives nothing.
+ *
+ * **The id slot closes at the first space that no comma opened.** The FIRST word after the token
+ * always sits in the id slot, because that is where a typo'd id lands and failing closed there is
+ * the whole point. After a resolved id, only a `,` keeps the list open: an unknown word arriving
+ * across a comma is a claimed id (`raw-hex, raw-surfacee`) and gets recorded, an unknown word
+ * arriving across a space is prose (`raw-surface sub-scale legend corner`, one em-dash away from
+ * annotations this package itself ships) and starts the reason. Reporting the second as a typo was
+ * a live false-positive class on a waiver that was in fact scoped and reasoned.
+ *
+ * `Object.hasOwn`, not `in`: `in` walks the prototype chain, so a reason beginning with the word
+ * `constructor` (or `toString`, `valueOf`, …) resolved as a real rule id and silently scoped the
+ * waiver to a kind that does not exist.
+ */
+function parseAllowAnnotation(rest: string, scope: AllowScope): AllowAnnotation {
+  const rules: string[] = []
+  const unknownRules: string[] = []
+  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 === undefined) 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 }
+}
+
+/** How far back a trailing CSS annotation reaches for the declaration it terminates. */
+const MAX_CSS_CONTINUATION_LINES = 8
+
+/** How far a comment-only annotation reaches forward through the rest of its own comment block. */
+const MAX_COMMENT_BLOCK_LINES = 8
+
+/**
+ * A comment opener sitting immediately before the annotation token.
+ *
+ * `stripComments` is the primary evidence that an occurrence is inside a comment, but it is
+ * deliberately biased toward treating an ambiguous `/` as division (see its own doc), and JSX makes
+ * that bias fire constantly: in `<Box p={18} /> // theme-allow` the `/` of `/>` follows a `}`, so
+ * the stripper reads a regex literal and the trailing comment survives unstripped. This prefix test
+ * is the second witness — cheap, local, and exact for every shape that actually occurs.
+ */
+const COMMENT_OPENER_BEFORE = /(?:\/\/|\/\*|<!--)\s*$/
+
+/** A line that is NOTHING but a comment — the placement that waives the line below it. */
+const COMMENT_ONLY_LINE = /^\s*(?:\{\s*\/\*|\/\/|\/\*|\*|<!--)/
+
+/**
+ * Everything allowed between the comment opener (or the start of the line) and the annotation
+ * token, for the token to count as an ANNOTATION rather than prose that mentions one.
+ *
+ * **This gates WAIVING as well as reporting.** It used to gate only `theme-allow-unscoped`, on the
+ * argument that a stricter waiver could take a build down over comment placement. The cost of that
+ * asymmetry was the opposite and worse: a comment that merely MENTIONS the token in prose parsed as
+ * the bare blanket form and switched every kind off on the line below it. linewatch documented its
+ * own waivers in a docblock and thereby disarmed the file — the third hole found in this contract
+ * in two rounds, and the only one that was a false NEGATIVE.
+ *
+ * So an annotation must START its comment, or start a line inside one: after `//`, `/*`, `<!--`, a
+ * block-comment gutter `*`, or nothing but leading whitespace. Everything a consumer actually
+ * writes qualifies; a sentence about the escape hatch does not.
+ *
+ * What the annotation then WAIVES is a separate, fail-closed question — see
+ * {@link parseAllowAnnotation}. A word in the id slot that names no rule waives nothing, so
+ * `// theme-allow legacy vendor asset` (a prose reason with no separator introducing it) no longer
+ * suppresses. That IS a break, deliberately: the alternative is one mistyped character silently
+ * widening a scoped waiver into a blanket one. No consumer writes that shape today — every
+ * annotation across all seven repos introduces its reason with `—`, `–`, `-` or `:` — which is why
+ * it ships as a documented break rather than a `GRACE_PERIOD_KINDS` entry. Grace could not express
+ * it anyway: the kind that fires is the UNSUPPRESSED one (`raw-hex`), not `theme-allow-unscoped`,
+ * and downgrading `raw-hex` to waive-by-default is the hole this closed.
+ */
+const ANNOTATION_PREFIX = /(?:^|\/\/|\/\*|<!--|^\s*\*)\s*$/
+
+/** Escape a config-supplied string for literal use inside a RegExp. */
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/**
+ * The annotation token itself, with its optional `-file` suffix.
+ *
+ * `(?![\w-])` is what keeps the two forms apart and keeps a longer word from being read as the bare
+ * form: `theme-allow-file` is the file declaration, `theme-allow-unscoped` (the KIND NAME, written
+ * in prose constantly) is neither — before this it consumed no id, fell through to `rules: []` and
+ * parsed as a blanket waiver.
+ */
+function allowTokenRe(allowComment: string): RegExp {
+  return new RegExp(`${escapeRegExp(allowComment)}(-file)?(?![\\w-])`, 'g')
+}
+
+/**
+ * The JSON dialect of the annotation — `"basalt:theme-allow-file": "<ids> — <why>"`.
+ *
+ * JSON has no comments, so from 1.20.0 (when the scan reached `.webmanifest` / `.json`) every
+ * finding in that file class was permanently unwaivable and the printed remedy prescribed a comment
+ * the file cannot carry. Two consumers were pushed into a blanket `exemptRules` entry instead — the
+ * un-reviewable shape this contract exists to retire. A member key is the one annotation JSON can
+ * hold, it carries ids and a reason exactly like the comment form, and every manifest consumer
+ * ignores members it does not know.
+ */
+function jsonAllowKeyRe(allowComment: string): RegExp {
+  return new RegExp(`"basalt:${escapeRegExp(allowComment)}(-file)?"\\s*:\\s*"([^"]*)"`, 'g')
+}
+
+/**
+ * Every line an allow annotation WAIVES, keyed by 0-based line index, plus the file-scoped
+ * declarations and every annotation as WRITTEN (for `theme-allow-unscoped`).
+ *
+ * **The grammar, in full:**
+ *
+ * ```text
+ * theme-allow                                  → this placement, EVERY kind   (reports unscoped)
+ * theme-allow <id>[, <id>…] [— <why>]          → this placement, those kinds  (unscoped without a why)
+ * theme-allow-file <id>[, <id>…] — <why>       → the WHOLE FILE, those kinds
+ * "basalt:theme-allow[-file]": "<id>… — <why>" → the same two, for JSON/.webmanifest
+ * ```
+ *
+ * Three rules make it unambiguous: the token must START its comment (see {@link ANNOTATION_PREFIX});
+ * `-file` is part of the token, not the first word of the reason (see {@link allowTokenRe}); and a
+ * bare `theme-allow-file` waives NOTHING, because whole-file blanket immunity off one unnamed
+ * comment is the exact thing this contract exists to price (see {@link annotationCovers}).
+ *
+ * Line scope has three placements, each one a shape people actually write — and the union of them
+ * is what makes the escape survive a formatter.
+ *
+ * 1. **Its own line.** The original rule, unchanged.
+ * 2. **The first CODE line below, when the annotation line is a comment and nothing else.** This is
+ *    the placement the oxlint plugin has always honored and the only one JSX can express: the
+ *    reported line is usually a multi-line opening tag or a `{expr}` child, where a trailing `//` is
+ *    a syntax error or renders as visible text. Requiring the annotation line to be comment-ONLY is
+ *    what keeps a TRAILING comment scoped to its own line — otherwise
+ *    `const a = '#f00' // theme-allow` would silently waive the next line too. The rest of the
+ *    comment BLOCK is walked through rather than counted as the target line: a docblock's `*\/`, or
+ *    a reason that wrapped onto a second line, used to absorb the whole waiver and the natural
+ *    shape silently waived nothing. A blank line ends the block — that separation is how people say
+ *    "this comment is not about the next statement".
+ * 3. **The rest of the CSS declaration it terminates.** The shipped `oxfmt` reflows
+ *    `background-color: var(--x, #232326); /* theme-allow *\/` into four lines with the hex on one
+ *    and the comment on another — two shipped tools pulling in opposite directions, and the
+ *    exception silently stopped working. Walking back over the continuation lines (stopping at the
+ *    first `;` / `{` / `}`, which CSS actually has) restores it. Deliberately CSS-only: oxfmt emits
+ *    NO semicolons in TS, so there is no statement terminator to stop at and the same walk would
+ *    waive arbitrary code above.
+ *
+ * An occurrence only counts when it sits inside a COMMENT, which is read off the stripped text:
+ * `stripComments` replaces comment characters 1:1 with spaces, so a position that is non-space in
+ * the source and space in the stripped copy was a comment. That is what keeps a `'theme-allow'`
+ * inside a string literal (or in this file's own rule table) from silently disabling a rule.
+ */
+function collectAllowAnnotations(
+  lines: readonly string[],
+  codeLines: readonly string[],
+  allowComment: string,
+  syntax: GuardSyntax,
+): {
+  waivers: Map<number, AllowAnnotation[]>
+  fileScoped: AllowAnnotation[]
+  declared: AllowDeclaration[]
+} {
+  const byLine = new Map<number, AllowAnnotation[]>()
+  const fileScoped: AllowAnnotation[] = []
+  const declared: AllowDeclaration[] = []
+  const add = (index: number, annotation: AllowAnnotation): void => {
+    const list = byLine.get(index) ?? []
+    list.push(annotation)
+    byLine.set(index, list)
+  }
+
+  /** Place one parsed annotation: file declarations reach everywhere, line ones the 3 placements. */
+  const record = (index: number, annotation: AllowAnnotation, trailing: boolean): void => {
+    declared.push({ line: index + 1, annotation })
+    if (annotation.scope === 'file') {
+      fileScoped.push(annotation)
+      return
+    }
+    add(index, annotation)
+    if (!trailing) {
+      // The first line below that is not itself comment. A docblock's `*/` (or the rest of a
+      // wrapped reason) sits between the annotation and the code it is about, so `index + 1` alone
+      // meant the natural multi-line shape silently waived nothing — argo hit it three times in one
+      // upgrade, each looking like a correct annotation. A BLANK line still ends the block: that is
+      // the separation people use to mean "this comment is not about the next statement".
+      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)
+
+    // The JSON member form. Markup-only: in TS/CSS that string would be code, not an annotation.
+    if (syntax === 'markup') {
+      for (const m of line.matchAll(jsonKey)) {
+        record(i, parseAllowAnnotation(m[2] ?? '', m[1] === undefined ? 'line' : 'file'), false)
+      }
+    }
+
+    for (const m of line.matchAll(token)) {
+      const at = m.index
+      const before = line.slice(0, at)
+      // Not inside a comment (neither witness agrees) → real code, e.g. this file's own rule table.
+      if (stripped[at] !== ' ' && !COMMENT_OPENER_BEFORE.test(before)) continue
+      // Inside a comment, but not at the START of one → prose that mentions the token, not an
+      // annotation. See ANNOTATION_PREFIX: this is what stops a file documenting its own waivers
+      // from disarming itself.
+      if (!ANNOTATION_PREFIX.test(before)) continue
+      const rest = line.slice(at + m[0].length)
+      record(
+        i,
+        parseAllowAnnotation(rest, m[1] === undefined ? 'line' : 'file'),
+        !isCommentOnlyLine,
+      )
+    }
+  }
+  return { waivers: byLine, fileScoped, declared }
+}
+
+/**
+ * Does one annotation cover `kind`?
+ *
+ * Only a BARE **line** annotation (no ids at all, known or unknown) covers every kind. One that
+ * reached for a rule id and missed covers exactly the ids it got right — nothing widens on a typo.
+ *
+ * A bare `theme-allow-file` covers NOTHING. The blanket form is tolerable on one line, where a
+ * reader sees what it sits on; over a whole file it is `exemptRules` without the config review, and
+ * the widest waiver in the contract must be the one that has to name what it waives.
+ */
+function annotationCovers(annotation: AllowAnnotation, kind: GuardKind): boolean {
+  if (annotation.rules.includes(kind)) return true
+  if (annotation.scope === 'file') return false
+  return annotation.rules.length === 0 && annotation.unknownRules.length === 0
+}
+
+/** Does any annotation on this line cover `kind`? */
+function annotationsCover(annotations: AllowAnnotation[] | undefined, kind: GuardKind): boolean {
+  return (annotations ?? []).some((a) => annotationCovers(a, kind))
+}
+
+/** The 3 comment dialects the stripper understands, resolved from the file's own extension. */
+type GuardSyntax = 'ts' | 'css' | 'markup'
 
 /**
  * CSS (including `.module.css`) has no `//` line-comment syntax at all — an unquoted `//`, e.g.
  * inside `url(https://…)`, is real CSS text, never a comment opener. Match on the `.css` suffix
  * (not a naive `split('.')`) so `foo.module.css` resolves the same as `foo.css`.
+ *
+ * `markup` covers the two files whose colors nothing re-derives on a theme change and which the
+ * scan never reached — `index.html` and `*.webmanifest` (plus plain `.json`, which a webmanifest
+ * often is). Only the color/typography kinds apply there; see `MARKUP_KINDS`.
  */
 function guardSyntaxFor(relPath: string): GuardSyntax {
-  return relPath.endsWith('.css') ? 'css' : 'ts'
+  if (relPath.endsWith('.css')) return 'css'
+  if (/\.(?:html?|webmanifest|json)$/.test(relPath)) return 'markup'
+  return 'ts'
+}
+
+/** The only kinds meaningful in an HTML document or a JSON manifest — no JSX, no CSS-in-JS. */
+const MARKUP_KINDS: ReadonlySet<GuardKind> = new Set(['raw-hex', 'raw-color-fn', 'raw-font-family'])
+
+/** Blanks out `<!-- … -->` 1:1 with spaces, preserving every offset. JSON has no comment syntax. */
+function stripMarkupComments(text: string): string {
+  return text.replace(/<!--[\s\S]*?-->/g, (m) => m.replace(/[^\n]/g, ' '))
 }
 
+/**
+ * The exact first line of every stylesheet the CLI emits — the contract between `basalt-ui
+ * tokens:css` / `fonts:css` and this scanner, and the single source of truth for it (`src/cli`
+ * imports this rather than keeping its own copy, which is how the two used to drift apart).
+ *
+ * The marker exists because `check-theme` reported the file a sibling command had just written:
+ * 116 of rollhook's 117 violations were inside the emitted token stylesheet, which is nothing but
+ * hex and `rgba()` by construction.
+ *
+ * **Command-NEUTRAL by necessity.** Line 1 is compared verbatim, so it cannot name the command
+ * that produced the file without needing one accepted marker per command — and a second accepted
+ * marker is a second forgery surface. It points at the provenance line instead, which does name
+ * the command. It used to say `regenerate with \`bunx basalt-ui tokens:css\`` on a `fonts:css`
+ * file too: following that instruction overwrote a font sheet with the palette sheet.
+ */
+export const GENERATED_HEADER_LINE =
+  '/* @generated basalt-ui — do not edit; regenerate with the command on the next line */'
+
+/** Line 2 of the header: the emitting version and the exact invocation that produced the file. */
+const GENERATED_PROVENANCE_LINE =
+  /^\/\* basalt-ui \d+\.\d+\.\d+[^\s]* — `basalt-ui (?:tokens:css|fonts:css)[^`]*` \*\/$/
+
+/** The header is exactly the two lines `generatedHeader()` writes — nothing further in counts. */
+const GENERATED_HEADER_LINES = 2
+
+/** A comment that OPENS AND CLOSES on its own line — the only comment shape the emitters write. */
+const GENERATED_COMMENT_LINE = /^\/\*(?:[^*]|\*(?!\/))*\*\/$/
+
+/** Outside a block: a selector, a selector-list continuation ending in `,`, or an at-rule opener. */
+const GENERATED_SELECTOR_LINE = /^[^{};]*[,{]$/
+
+/** Inside a block: a declaration of a custom property in basalt's OWN namespace, or the close. */
+const GENERATED_DECL_LINE = /^(?:--(?:vx|basalt)-[A-Za-z0-9_-]*\s*:[^{};]*;|\})$/
+
+/** No line is skipped in a file that is not one basalt emitted — the shared empty answer. */
+const NO_GENERATED_LINES: ReadonlySet<number> = new Set()
+
+/** Net brace depth a line moves the parser by — CSS blocks, counted the cheap way. */
+function braceDelta(line: string): number {
+  let delta = 0
+  for (const ch of line) {
+    if (ch === '{') delta++
+    else if (ch === '}') delta--
+  }
+  return delta
+}
+
+/**
+ * The (1-based) lines of a stylesheet basalt itself emitted, which the scan may skip. Empty for
+ * every other file.
+ *
+ * The marker used to be honoured on its own: any file whose first five lines contained the string
+ * `@generated basalt-ui` was skipped ENTIRELY. That made a two-word comment a whole-file guard
+ * bypass — prepend it to any `.tsx` and every finding in it disappears. The replacement gated the
+ * whole file on a header plus a line-shape allowlist, and the allowlist was loose enough to forge:
+ * `--vx-pad: 0; box-shadow: 0 0 0 1px #ff0000;` passed as "a basalt custom property" because the
+ * value pattern permitted `;`, and `/* x *\/ .btn { color: #ff0000; }` passed as "a comment"
+ * because the comment pattern never required the comment to close. Both are browser-effective CSS,
+ * and either one bought a whole-file exemption.
+ *
+ * Two changes close that, and the second is the structural one:
+ *
+ * 1. **The exemption is PER LINE, not per file.** A line-shape allowlist that misses now costs one
+ *    line, not the whole file — the blast radius of the next mistake is bounded by construction.
+ *    It also reports the smuggled line precisely instead of burying it under 300 token values.
+ * 2. **The allowlist is brace-depth-aware.** CSS declarations only take effect INSIDE a block, so
+ *    at depth ≥ 1 the only skippable line is a `--vx-*`/`--basalt-*` declaration whose value
+ *    carries no `;`, a `}`, a self-closing comment, or a blank. `box-shadow: … #ff0000,` is a
+ *    depth-1 line and is scanned no matter how it is shaped. At depth 0 a loose selector pattern
+ *    is safe precisely because nothing there is a declaration.
+ *
+ * Three conditions still gate the file itself: a `.css` path (the CLI emits CSS and nothing else,
+ * so the marker is ignored in `.ts`/`.tsx`/`.html`/`.json`, which is where the guard has its
+ * teeth), the canonical header verbatim on line 1, and the provenance line on line 2.
+ *
+ * A line carrying the allow comment is never skipped: an emitted sheet contains no `theme-allow`,
+ * and skipping one would suppress the `theme-allow-unscoped` report of a waiver hidden in a file
+ * wearing the header.
+ *
+ * Residual, knowingly accepted: at depth 0 a forger can hide a finding inside something shaped
+ * like a selector (`.a[data-x='#ff0000'] {`), and inside a block they can hide the value of a
+ * custom property they declare in basalt's own namespace. Neither is browser-effective as a style
+ * and the second IS the artifact class this exemption exists for.
+ */
+function generatedTokenLines(
+  relPath: string,
+  lines: readonly string[],
+  allowComment: string,
+): ReadonlySet<number> {
+  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 = new Set<number>([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)
+    // Unbalanced braces mean this is not the emitters' output at all — fail closed on the rest.
+    if (depth < 0) return NO_GENERATED_LINES
+  }
+  return skippable
+}
+
+/**
+ * Kinds disabled under `profile: 'tokens-only'` — every kind whose remedy is a Mantine component,
+ * a Mantine prop, or the React theme factory. See {@link GuardConfig.profile}.
+ *
+ * Exported so the CLI can name the profile in `--help`/`doctor` output without re-deriving the
+ * list, and so a test can assert the two halves (disabled vs. surviving) partition the registry.
+ */
+export const TOKENS_ONLY_DISABLED_KINDS: ReadonlySet<GuardKind> = 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',
+])
+
 // A `/` opens a regex literal (not division) when the previous significant token is one of these
 // punctuation marks, or one of the REGEX_PRECEDING_KEYWORDS below, or nothing has been scanned yet
 // (start of input) — the standard JS lexer disambiguation. `ts`-syntax only; CSS has no regexes.
@@ -435,7 +1227,7 @@ const WORD_CHAR = /[A-Za-z0-9_$]/
  * regex-open would swallow real code as "protected regex content" and could hide a genuine
  * violation — the failure mode BUG 1 already showed is unacceptable.
  */
-function stripComments(text: string, syntax: GuardSyntax): string {
+function stripComments(text: string, syntax: 'ts' | 'css'): string {
   const out: string[] = Array.from<string>({ length: text.length })
   let inLineComment = false
   let inBlockComment = false
@@ -584,7 +1376,7 @@ type GuardRule = {
 }
 
 /**
- * The closed registry of all 20 guard kinds. The triad test asserts
+ * The closed registry of all 25 guard kinds. The triad test asserts
  * `surface.guardKinds ⊆ keyof GUARD_RULES` at runtime.
  *
  * raw-surface, raw-html-layout, and sub-16-input-font are handled inline in checkSource
@@ -775,8 +1567,92 @@ export const GUARD_RULES = {
     message:
       'fontSize below 16 on a form control is dead code — 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> — <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 — it suppresses nothing. `theme-allow-file <rule-id> — <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: GuardConfig) => cfg.rawSurface,
+    message:
+      'Token-composed boxShadow that REPLACES surface depth — 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: GuardConfig) => 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 — 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: GuardConfig) => cfg.rawHtmlLayout,
+    appliesTo: (relPath) => !isChartFile(relPath) && !relPath.endsWith('.css'),
+    message:
+      'Raw HTML element with inline layout/surface styling that the line scan cannot see — 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 — 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.',
+  },
 } as const satisfies Record<GuardKind, GuardRule>
 
+/**
+ * The one-line remedy for `kind`, as a report reads it: `raw-hex: Route color through VX.* / …`.
+ *
+ * The registry has always carried a remedy per kind; `check-theme`'s `Fix:` epilogue read a
+ * hand-duplicated subset instead, and the subset was missing every kind added at 1.20.0. Since all
+ * five of those ship `warn` under grace, the findings whose whole argument is "this looks correct
+ * and is not" arrived with no argument at all — just "add a `theme-allow`", which reads as advice to
+ * waive. Sourcing the epilogue from here retires the duplicate rather than extending it.
+ */
+export function guardKindRemedy(kind: GuardKind): string {
+  return `${kind}: ${(GUARD_RULES[kind] as GuardRule).message}`
+}
+
+/** JSON and its manifest dialect — the file class with no comment syntax to carry an annotation. */
+const JSON_FAMILY_FILE = /\.(?:webmanifest|json)$/
+
+/**
+ * How to waive a finding **in this file's syntax** — the closer a report prints under `Fix:`.
+ *
+ * `check-theme` printed one closer for every file class, and from 1.20.0 (when the scan reached
+ * `.webmanifest` / `.json`) it prescribed a `theme-allow` comment to files that cannot hold a
+ * comment. Two consumers read that, found no route, and fell back to a blanket `exemptRules` entry —
+ * the un-reviewable shape the release was spent retiring.
+ *
+ * A manifest gets the sharper answer first, because a hex there can never be *right*: a manifest
+ * cannot reference a CSS custom property, so the value is a hand-copy of a token that drifts the day
+ * the palette moves (which is exactly what both consumers found — two dead colours). The remedy is
+ * to stop hand-writing the file: `basaltAppPlugin` emits it from `SURFACE.bg`. The annotation is the
+ * fallback for a manifest basalt does not generate.
+ */
+export function guardWaiverHint(relPath: string): string {
+  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: { … }` 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 — <why>"` member.'
+    )
+  }
+  if (JSON_FAMILY_FILE.test(relPath)) {
+    return (
+      'JSON has no comments — declare a deliberate exception with a ' +
+      '`"basalt:theme-allow-file": "<rule-id> — <why>"` member.'
+    )
+  }
+  return 'Add a `theme-allow <rule-id> — <why>` comment for a deliberate exception (`theme-allow-file` declares the whole file).'
+}
+
 /** Whether `kind`'s rule fires for `relPath` — `appliesTo` is opt-in; absent means always applies. */
 function ruleApplies(kind: GuardKind, relPath: string): boolean {
   const appliesTo = (GUARD_RULES[kind] as GuardRule).appliesTo
@@ -796,9 +1672,16 @@ function ruleApplies(kind: GuardKind, relPath: string): boolean {
  * if (findings.some((f) => f.kind === 'raw-hex')) { ... }
  */
 export function checkSource(text: string, relPath: string, cfg: GuardConfig): Finding[] {
+  const lines = text.split('\n')
+
+  // Lines basalt itself generated are not consumer source — `tokens:css` emits nothing BUT hex and
+  // rgba() by construction. See generatedTokenLines for why the marker alone is not enough, and
+  // why the exemption is per line rather than per file.
+  const generatedLines = generatedTokenLines(relPath, lines, cfg.allowComment)
+
   // Severity and text are stamped once at the end rather than at each of the ~20 push sites — both
   // are derived from state the push sites don't need: severity from the KIND and the config, text
-  // from the finding's own `line` against the source split below.
+  // from the finding's own `line` against the source split above.
   const findings: Omit<Finding, 'severity' | 'text'>[] = []
 
   // Derive the 3 dynamic regexes via GUARD_RULES pattern builders.
@@ -813,70 +1696,157 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
   )
 
   // Comment-stripped text drives every match below; `lines` (the ORIGINAL, unstripped split) is
-  // kept only to resolve the allow-comment escape, since that annotation lives inside a comment
-  // the stripped text has already blanked out. Same length / same newline positions as `text`, so
-  // line numbers computed off either one agree.
-  const lines = text.split('\n')
+  // kept to resolve the allow-comment escape, since that annotation lives inside a comment the
+  // stripped text has already blanked out. Same length / same newline positions as `text`, so line
+  // numbers computed off either one agree.
   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,
+  )
+
+  /** Kinds a `theme-allow-file` declared for the whole file — resolved once, not per finding. */
+  const fileWaived = new Set<GuardKind>()
+  for (const annotation of fileScoped) {
+    for (const rule of annotation.rules) {
+      if (Object.hasOwn(GUARD_RULES, rule)) fileWaived.add(rule as GuardKind)
+    }
+  }
+
+  /** Is `kind` waived at (1-based) `line`? See `collectAllowAnnotations` for the full grammar. */
+  const isAllowed = (line: number, kind: GuardKind): boolean =>
+    fileWaived.has(kind) || annotationsCover(waivers.get(line - 1), kind)
+
+  const isAllowedInRange = (start: number, end: number, kind: GuardKind): boolean => {
+    for (let n = start; n <= end; n++) if (isAllowed(n, kind)) return true
+    return false
+  }
+
+  const push = (kind: GuardKind, line: number, token: string): void => {
+    if (isAllowed(line, kind)) return
+    findings.push({ relPath, line, token, kind })
+  }
+
+  // theme-allow accountability. Reported directly rather than through `push`: a bare annotation
+  // covers every kind, so routing it through the waiver check would let it waive the report of its
+  // own unaccountability. `basalt.severity` / `exemptRules` are the ways to turn it down.
+  for (const { line, annotation } of declared) {
+    if (annotation.unknownRules.length === 0 && annotation.rules.length > 0 && annotation.hasReason)
+      continue
+    // "waives nothing" is only true when NO id resolved. With one that did, the typo costs its own
+    // id and nothing else — saying otherwise contradicts the findings the same run suppressed.
+    const unknown = `unknown rule id '${annotation.unknownRules.join("', '")}'`
+    const missing =
+      annotation.unknownRules.length > 0
+        ? annotation.rules.length === 0
+          ? `${unknown} — waives nothing`
+          : `${unknown} — not waived`
+        : annotation.rules.length === 0
+          ? 'no rule id'
+          : 'no reason'
+    findings.push({
+      relPath,
+      line,
+      token: `${cfg.allowComment} (${missing})`,
+      kind: 'theme-allow-unscoped',
+    })
+  }
+
+  /** Lines the line-scoped `raw-html-layout` already owns, so `hidden-inline-style` can't double-report. */
+  const rawHtmlLayoutLines = new Set<number>()
+
+  /** Offset of each line's start in `codeText` — lets a line-scoped match ask about its surroundings. */
+  const lineStarts: number[] = []
+  for (let n = 0, i = 0; i < codeLines.length; i++) {
+    lineStarts.push(n)
+    n += (codeLines[i] ?? '').length + 1
+  }
+
+  /** Every identifier the file hands to a `style=`/`styles=` prop — see `isStyleObjectContext`. */
+  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] ?? ''
 
-    // Skip lines with the allow-comment (checked against the ORIGINAL line text).
-    if ((lines[i] ?? '').includes(cfg.allowComment)) continue
-
     // Always-on kinds (raw-hex, raw-color-fn, localstorage-theme) — patterns from GUARD_RULES.
     for (const m of line.matchAll(GUARD_RULES['raw-hex'].pattern as RegExp)) {
-      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 as RegExp)) {
-      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 as RegExp)) {
-        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 as RegExp)) {
-      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 as RegExp)) {
+      push('inline-font-size', i + 1, m[0])
     }
 
     // Dynamic-regex kinds — patterns already resolved above.
     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])
     }
 
-    // raw-surface: 3 separate regex checks, one kind — gated via GUARD_RULES entry.
+    // raw-surface + its two younger siblings, all gated on the same `rawSurface` knob:
+    //   • raw-surface            — the camelCase (TSX inline-style) literals, unchanged;
+    //   • css-raw-surface        — the kebab dialect, which the camelCase patterns never saw;
+    //   • surface-shadow-override — a shadow built FROM tokens that still drops card depth.
     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] ?? ''
+          // A var-composed shadow in a CSS MODULE is deliberately not judged. `surface-shadow-
+          // override` is about a Card/Paper losing `--vx-shadow-card`; a module's own
+          // `box-shadow: var(--field-depth)` is a focus ring, an inset, a notch — component
+          // styling with no card identity at stake. Only the CSS-in-JS dialect, where the shadow
+          // sits on a Mantine surface prop, carries that claim.
+          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])
+        }
       }
     }
 
     // off-system-surface-var — pattern + gating from GUARD_RULES.
     if (GUARD_RULES['off-system-surface-var'].enabled!(cfg)) {
       for (const m of line.matchAll(GUARD_RULES['off-system-surface-var'].pattern as RegExp)) {
-        findings.push({ relPath, line: i + 1, token: m[0], kind: 'off-system-surface-var' })
+        push('off-system-surface-var', i + 1, m[0])
       }
     }
 
@@ -886,11 +1856,12 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
     // pattern's own comment for why this kind carries no appliesTo gate.
     if (GUARD_RULES['mantine-shade-index'].enabled!(cfg)) {
       for (const m of line.matchAll(GUARD_RULES['mantine-shade-index'].pattern as RegExp)) {
-        findings.push({ relPath, line: i + 1, token: m[0], kind: 'mantine-shade-index' })
+        push('mantine-shade-index', i + 1, m[0])
       }
     }
 
     // raw-html-layout: 3-condition conjunction on the same line — gated via GUARD_RULES entry.
+    // Its widened, formatting-independent half is `hidden-inline-style`, scanned below.
     if (
       GUARD_RULES['raw-html-layout'].enabled!(cfg) &&
       ruleApplies('raw-html-layout', relPath) &&
@@ -898,21 +1869,30 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
       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>')
     }
 
-    // inline-spacing — pattern + gating from GUARD_RULES, plus the CSS-only sub-scale escape.
+    // inline-spacing — pattern + gating from GUARD_RULES, plus the CSS-only sub-scale escape and
+    // the TS-only style-object test for a unitless number (see isStyleObjectContext).
     if (GUARD_RULES['inline-spacing'].enabled!(cfg)) {
       for (const m of line.matchAll(GUARD_RULES['inline-spacing'].pattern as RegExp)) {
         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])
       }
     }
 
     // inline-display — pattern + gating from GUARD_RULES.
     if (GUARD_RULES['inline-display'].enabled!(cfg) && ruleApplies('inline-display', relPath)) {
       for (const m of line.matchAll(GUARD_RULES['inline-display'].pattern as RegExp)) {
-        findings.push({ relPath, line: i + 1, token: m[0], kind: 'inline-display' })
+        push('inline-display', i + 1, m[0])
       }
     }
 
@@ -923,37 +1903,63 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
       GUARD_RULES['raw-visx-axis'].appliesTo!(relPath)
     ) {
       for (const m of line.matchAll(GUARD_RULES['raw-visx-axis'].pattern as RegExp)) {
-        findings.push({ relPath, line: i + 1, token: m[0], kind: 'raw-visx-axis' })
+        push('raw-visx-axis', i + 1, m[0])
       }
     }
 
     // raw-motion-value: 2 separate regex checks, one kind — gated via GUARD_RULES entry.
     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])
       }
     }
 
     // raw-form-control — pattern + gating from GUARD_RULES.
     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 as RegExp)) {
-        findings.push({ relPath, line: i + 1, token: m[0], kind: 'raw-form-control' })
+        push('raw-form-control', i + 1, m[0])
       }
     }
   }
 
+  // hidden-inline-style — the formatting-independent half of raw-html-layout. Bounded full-text tag
+  // scan (the `card-with-border` model), plus one hoisted-const lookup, so neither `<div\n  style=`
+  // nor `style={wrapperStyle}` walks past a rule that catches the identical single-line form.
+  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 !== undefined) 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',
+      })
+    }
+  }
+
   // unframed-chart — full-text tag-scoped scan (not per-line, see RAW_CHART_LEGEND_ARRAY comment).
   // Scans `codeText` (comment-stripped) so a legend example inside a comment can't match; reports
-  // at the line of the `items={[` token itself, honoring the same allow-comment escape as every
-  // per-line kind by checking the ORIGINAL reported line directly.
+  // at the line of the `items={[` token itself.
   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={[')
     }
   }
 
@@ -973,14 +1979,7 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
       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,
@@ -998,8 +1997,7 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
       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')
     }
   }
 
@@ -1016,8 +2014,7 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
       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)) {
@@ -1027,20 +2024,26 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
       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])
     }
   }
 
-  // Per-rule, per-path exemption post-filter (§exemptRules) — applied once here so it uniformly
-  // covers every kind regardless of whether it was emitted via the GUARD_RULES registry loop above
-  // or one of the inline-handled kinds (raw-surface, raw-html-layout, sub-16-input-font, …).
+  // Post-filters, applied once here so they uniformly cover every kind regardless of whether it was
+  // emitted via the GUARD_RULES registry loop above or one of the inline-handled kinds:
+  //   • generated     — the lines of a stylesheet basalt itself emitted (empty for every other file);
+  //   • §exemptRules — per-rule, per-path consumer exemptions;
+  //   • markup       — an HTML document / JSON manifest has no JSX and no CSS-in-JS, so only the
+  //                    color/typography kinds are meaningful there;
+  //   • profile      — a tokens-only consumer is not told to install @mantine/core.
   //
   // `text` is stamped here too, in the same single post-pass, off the ORIGINAL (unstripped) `lines`
   // split — never `codeLines` — so a finding on a line whose comment was stripped still reports the
   // real source text a human would read.
   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),