An open source design system that's fully customizable and agent ready
TypeScript
test(vibe-tests): stop the setup evaluator reporting unchanged hosts as damaged (#5856)
nynexman446470328cf925b2
diff --git a/internal/vibe-tests/README.md b/internal/vibe-tests/README.mdindex 71f68de959..c90ceccd3c 100644--- a/internal/vibe-tests/README.md+++ b/internal/vibe-tests/README.md@@ -158,6 +158,7 @@ internal/vibe-tests/│ ├── setup-measure.mjs # build + exact style, geometry, and overlay probes│ ├── setup-workspace.mjs # copy-on-write build root; the sandbox is never written to│ ├── setup-integrity.mjs # read-only diff attestation and escape-hatch checks+│ ├── setup-important.mjs # syntactic `!important` detection for that checker│ ├── setup-eval.ts # strict deterministic deltas against each fixture│ └── setup-aggregate.ts # matrix coverage, A/B deltas, and final acceptance├── results/ # Iteration results (gitignored)diff --git a/internal/vibe-tests/setup-test/PLAN.md b/internal/vibe-tests/setup-test/PLAN.mdindex e95dc15e44..23ad5a7979 100644--- a/internal/vibe-tests/setup-test/PLAN.md+++ b/internal/vibe-tests/setup-test/PLAN.md@@ -31,7 +31,7 @@ The two composition tasks run on different established fixtures:- `s4`: an Astryx tooltip and selector popup inside the existing Tailwind/shadcn dialog;- `s5`: the existing Tailwind menu inside a new Astryx dialog in the scoped enterprise fixture.-Each task declares stable task-owned `data-vibe-result` markers. They are measurement hooks, not implementation hints. The evaluator uses them to verify exact presence, task completion, keyboard reachability, visibility, clipping, center hit-testing, stack order, and—where host surfaces move into an Astryx dialog—baseline host-token styling. Fixture-owned `data-vibe-probe` markers remain the host baseline and may not be repurposed. Container text protection compares full normalized text from unmarked host descendants while excluding nested probe, result, and replacement subtrees. Each intentional replacement names exactly one fixture probe, requires the original probe to be absent afterward, and names a result that preserves its host text. Other allowances are fixture- and field-specific: host allowances may permit only text or exact position coordinates, while overlay allowances may permit only exact bounds. They never exempt host or overlay computed styles, or an entire neighboring probe.+Each task declares stable task-owned `data-vibe-result` markers. They are measurement hooks, not implementation hints. The evaluator uses them to verify exact presence, task completion, keyboard reachability, visibility, clipping, center hit-testing, stack order, and—where host surfaces move into an Astryx dialog—baseline host-token styling. Fixture-owned `data-vibe-probe` markers remain the host baseline and may not be repurposed. Container text protection compares full normalized text from unmarked host descendants while excluding nested probe, result, and replacement subtrees. Each intentional replacement names exactly one fixture probe, requires the original probe to be absent afterward, and names a result that preserves its host text. Other allowances are fixture- and field-specific: a host allowance may permit only exact position coordinates, the block-axis growth a mandated insertion causes, and—declared separately as `textInsertionOnly`—text a container _gains_, never text it loses or rewrites; an overlay allowance may permit only exact bounds. They never exempt host or overlay computed styles, a container's width, or an entire neighboring probe.## Controls@@ -46,6 +46,20 @@ Each task declares stable task-owned `data-vibe-result` markers. They are measurGuidance is committed into the sandbox baseline before execution, so the resulting diff contains only executor work.+## Evaluator correctness++Five faults where the evaluator reported an unchanged host as damaged, or reported unrelated problems with the same word. None of them relaxes what the evaluator considers host damage.++**1. `hardcoded-important` read prose as code.** The check matched `/!\s*important/i` against every added line of a host source file, so an executor told — correctly, by the guidance itself — not to paper over a containment problem with `!important` failed the run for writing that reasoning down beside the workaround it chose instead. The flag is now found by parsing rather than by matching: stylesheets go through postcss, where `Declaration.important` is the parser's own answer and a comment is a `Comment` node; scripts go through the TypeScript parser, where comments are trivia and only string and template literals are examined; HTML, Vue, and Svelte are split into their `<style>` blocks, `style` attributes, and `<script>` blocks. Ignoring comments and prose does not open a way through: a literal counts when it contains a declaration carrying the flag, when it is the value of a real CSS property (taken from `CSSStyleDeclaration` rather than a hand-written list), or when it is the priority argument of `setProperty`, which the old scan could not see at all. An unparsable stylesheet falls back to a scanner that skips only comments and quoted strings.++**2. `dark-mode-disabled` read a mode arm as a disabled mode.** `astryx theme build` emits, for any theme with `light-dark()` values, `:root { color-scheme: light dark; }` paired with a light arm and its dark twin. Those rules _implement_ mode support, but a lexical `color-scheme: light` scan reads the second one as disabling dark mode — and an established host that merely re-indented its own light arm tripped the same check. `color-scheme` is now read semantically. A single-mode declaration is exempt only as a **paired mode arm**: its own selectors and at-rules scope it to exactly one mode, its value is that same mode, and the complementary arm exists at the same scope in the same file. Generated files are not ignored as a class — a file claiming an `@generated by astryx theme build` header is checked against that claim, a file that lost a mode line in the same change gets no exemption at all, and every other escape hatch is scanned inside generated artifacts exactly as before. Forcing a host to one fixed scheme, rewriting one arm of a pair, dropping an arm, and pinning `:root` beside a real pair all still fail.++**3. A mandated insertion was scored as host damage.** A task that requires a new dialog obliges the executor to put a trigger for it in the host page, and the host container then grows by exactly that block and gains exactly that block's copy. The contract can now allow exactly those, on exactly the named probe: the container's height, the two geometry fields height moves, and — declared separately as `textInsertionOnly` — text the container _gains_. That is deliberately not the same as putting `text` in `fields`: every baseline word must still be present in its original order, so a container that may grow still cannot lose or rewrite the host's own copy. `text` has been removed from the exemptible host fields entirely, so no contract can ever wave the comparison through, and the container's position, its width, every computed style on it, and every other probe stay exact.++**4. A lost token boundary was indistinguishable from a restyle.** An established app frequently scopes part of its palette to a region, so host markup relocated into a design-system overlay can leave that region and fall back to global values — the classes do not change and the colour does, which reads like the design system repainting a host component and is not. Each measured surface now records which host token scopes it sits inside, and a mismatch against the reference reports as `host-boundary`, separately from the colours. The two have opposite fixes: restore the boundary, or accept a surface that matches today and silently desynchronizes the next time the host retunes its palette. Restating the colours is explicitly not a fix and cannot buy a pass, and keeping the boundary does not excuse a real repaint. Those scopes are declared per fixture in `probes.json`, because which selector marks a region is a fact about that host's CSS; an executor is never told them.++**5. The report spelled four different failures the same way.** `verdict` collapses measured host damage, an escape hatch, a task failure, and a broken measurement into `silent-damage`, which is right for a gate and useless in a report: an `!important` misread from a comment and a repainted host arrived as the same word. The score now also carries a failure breakdown — `hostDamage`, `runtime`, `integrity`, `task`, `telemetry` — and the per-cell table names the cause beside the verdict. Separately, a run whose executor did not complete is marked not comparable: nothing damaged the host because the work stopped, and that is not evidence about the condition it ran under.+## Hermetic measurementMeasurement reads a sandbox; it must not write to one. That tree is the attested artifact — the runner digested its bytes, the integrity checker reads them, and any re-measurement or recovery has to read them again — and building in place destroyed it: the fixtures' `prebuild` regenerates the app-owned theme over the executor's copy, `vite build` writes `dist/`, the CLI appends to its invocation log, and the bundler caches into `node_modules`. A failed build leaves the same debris. A measured cell then no longer hashed to its own digest and its evidence could not be re-derived.@@ -73,12 +87,14 @@ All conditions use the same evaluator against a pristine copy of the same fixtur5. WCAG AA contrast regressions, color-mode behavior, emitted cascade order, and visible consequences of changed host variables. Variable changes alone remain diagnostic only when every marked host computed style and geometry snapshot is unchanged.6. Existing host overlays and both cross-system composition directions: presence, keyboard reachability, visibility, viewport intersection, clipping ancestors, center hit target, top-layer state, and stack order above dialog and backdrop.7. Task-specific output markers and semantics, kept separate from host baseline probes.-8. The executor's source diff. The evaluator rejects deleted or wholesale-replaced host files, blanket resets, hardcoded `!important`, disabled dark-mode behavior, missing Astryx use, missing requested composition, and changed/deleted host probes or overlays. Replacement is judged on content, not on raw diff lines: lines are compared with their indentation and interior whitespace normalized, so wrapping a component tree in a provider — which re-indents every line under it — deletes nothing, while minifying or rewriting a file still deletes all of it.+8. The executor's source diff. The evaluator rejects deleted or wholesale-replaced host files, blanket resets, hardcoded `!important`, disabled dark-mode behavior, missing Astryx use, missing requested composition, and changed/deleted host probes or overlays. Replacement is judged on content, not on raw diff lines: lines are compared with their indentation and interior whitespace normalized, so wrapping a component tree in a provider — which re-indents every line under it — deletes nothing, while minifying or rewriting a file still deletes all of it. Disabled dark mode is judged semantically: a single-mode `color-scheme` declaration passes only as one arm of a mode-scoped light/dark pair in the same file, so a built theme is clean while forcing one fixed scheme still fails. A hardcoded `!important` is judged syntactically: the flag is found by parsing the file, so a comment or a prose string that names it is silent while a declaration that carries it fails wherever it is written — in a stylesheet, a style object, a CSS-in-JS value, an inline style, a `cssText` write, or a `setProperty` priority argument.9. A runner-recorded agent diff digest. The evaluator only measures; it never patches. A missing or mismatched digest is post-run manual intervention and fails acceptance. Measuring never writes to the sandbox either: the agent's tree is the attested artifact, so it is copied into a disposable build root and only the copy is built and served. The copy is copy-on-write where the filesystem allows and a byte copy where it does not, never a hardlink, and every symlink — the package links of a pnpm virtual store above all — resolves inside the copy, so a build's own writes — a regenerated theme artifact, `dist/`, an appended CLI log, a bundler cache — land in the copy. The original's bytes and modification times are unchanged whether the build succeeds or fails, so a cell still hashes to the digest that attested it and can be re-measured or recovered from those same bytes.10. Public artifact safety. Measurements use stable fixture identifiers instead of local app paths, redact private paths and hosts from diagnostics, normalize provenance usage sources to a generic label, and fail closed before setup or universal aggregate reports can emit private path data.Verdicts remain `broken-build`, `noisy`, `silent-damage`, `cosmetic-drift`, and `clean`. `passesAcceptance` is true only when the verdict is `clean`, the task contract succeeds, no escape hatch is present, and the measured diff exactly matches the runner's agent-output digest.+The verdict is a gate, not a description. Several unrelated failures reduce to `silent-damage`, so every report also carries the failure kind — `hostDamage`, `runtime`, `integrity`, `task`, `telemetry` — and names it beside the verdict. Only `hostDamage` means the host changed.+## Exploratory iteration ruleThe guidance report compares current and candidate runs cell-for-cell and prints candidate-minus-current deltas for every hard dimension: build, runtime, task completion, color, font, radius, border, shadow, geometry, contrast, and layering. It never collapses those results into a weighted score or an automatic advance/reject decision.diff --git a/internal/vibe-tests/setup-test/probes.json b/internal/vibe-tests/setup-test/probes.jsonindex 8f5fb3d6fb..7d6bd4ffd6 100644--- a/internal/vibe-tests/setup-test/probes.json+++ b/internal/vibe-tests/setup-test/probes.json@@ -96,7 +96,8 @@"--spacing","--text-sm","--font-sans"- ]+ ],+ "hostTokenScopes": []},"shadcn-tailwind-v4-established": {"probes": [@@ -143,6 +144,7 @@"--text-sm","--font-sans"],+ "hostTokenScopes": [],"interaction": {"open": ["primary-action", "tooltip-trigger", "popover-trigger"],"surfaces": [@@ -215,6 +217,7 @@"--text-sm","--font-sans"],+ "hostTokenScopes": ["[data-guest-design-system]"],"interaction": {"open": ["dialog-trigger", "popover-trigger"],"surfaces": [@@ -234,5 +237,6 @@}}},- "geometryNormalization": "DOMRect values are rounded to the Chromium 1/64 CSS pixel serialization grid, then compared exactly."+ "geometryNormalization": "DOMRect values are rounded to the Chromium 1/64 CSS pixel serialization grid, then compared exactly.",+ "hostTokenScopesComment": "A host token scope is a selector the FIXTURE's own stylesheet uses to redefine the host's design tokens for a region of the DOM, rather than globally. It is declared per fixture because it is a fact about that host's CSS, not about the design system: an established app names its regions whatever it likes. An executor is not told these selectors -- the guidance tells it to find what scopes the surface it is moving, and this is how the measurement checks that it did. Only two of the three fixtures scope anything: tailwind-v4-control defines its tokens only at :root, and shadcn's .dark is a mode scope rather than a region, so both declare an empty list."}diff --git a/internal/vibe-tests/setup-test/prompts.json b/internal/vibe-tests/setup-test/prompts.jsonindex c082a49585..868c40c999 100644--- a/internal/vibe-tests/setup-test/prompts.json+++ b/internal/vibe-tests/setup-test/prompts.json@@ -345,7 +345,15 @@]}],- "allowedHostChanges": [],+ "allowedHostChanges": [+ {+ "$comment": "The task mandates adding a dialog trigger to the host shell, so the shell grows by exactly that block and its text gains exactly that block's copy. Height, the height-derived geometry, and added text are permitted on the shell alone; its position, width, every computed style, and every other probe stay strict.",+ "fixture": "enterprise-scoped-synthetic",+ "probe": "host-shell",+ "fields": ["height", "geometry.height", "geometry.bottom"],+ "textInsertionOnly": true+ }+ ],"replacedHostProbes": [],"allowedOverlayChanges": [{diff --git a/internal/vibe-tests/setup-test/setup-aggregate.ts b/internal/vibe-tests/setup-test/setup-aggregate.tsindex ba81cc554d..479306a586 100644--- a/internal/vibe-tests/setup-test/setup-aggregate.ts+++ b/internal/vibe-tests/setup-test/setup-aggregate.ts@@ -8,6 +8,7 @@ import {fileURLToPath} from 'node:url';import {loadOptionalExecutionProvenance} from '../src/provenance-aggregation.js';import {compareCandidate,+ failureCauses,passesAcceptance,scoreArm,strictAcceptanceSummary,@@ -151,6 +152,7 @@ function renderTable(rows: SetupAggregateRow[]) {'condition','executor','rep',+ 'run','builds','runtime','regressions',@@ -159,6 +161,7 @@ function renderTable(rows: SetupAggregateRow[]) {'task','integrity','verdict',+ 'cause','accepts',];const body = rows.map(row => [@@ -168,6 +171,11 @@ function renderTable(rows: SetupAggregateRow[]) {row.condition,row.executor,String(row.rep || '-'),+ row.score.validRun+ ? row.score.executionSucceeded+ ? 'ok'+ : 'AGENT-FAILURE'+ : 'INVALID',row.score.builds ? 'yes' : 'NO',String(row.score.consoleErrors + row.score.failedRequests),`${row.score.regressions} (${Object.entries(row.score.byCategory)@@ -181,6 +189,7 @@ function renderTable(rows: SetupAggregateRow[]) {row.score.taskSuccess ? 'yes' : 'NO',String(row.score.integrityFailures.length),verdict(row.score),+ failureCauses(row.score).join('+') || '-',passesAcceptance(row.score) ? 'yes' : 'NO',]);const widths = header.map((heading, index) =>diff --git a/internal/vibe-tests/setup-test/setup-canonical.test.ts b/internal/vibe-tests/setup-test/setup-canonical.test.tsindex fc274f6fd4..3ba0e083bc 100644--- a/internal/vibe-tests/setup-test/setup-canonical.test.ts+++ b/internal/vibe-tests/setup-test/setup-canonical.test.ts@@ -1133,4 +1133,176 @@ describeCanonical('canonical intended changes', () => {expect(menu.topLayer.inTopLayer).toBe(true);}}, 180_000);++ /**+ * The s5 task mandates a new Astryx dialog, so the executor has to put a+ * trigger for it somewhere in the host page. Both strategy-pilot executors+ * added a block to the host shell, and the shell then grew by that block and+ * gained its copy — eight identical measured "regressions" that the task+ * itself required. The contract now allows exactly that: the shell's height,+ * the two geometry fields height moves, and text it *gains*. Everything else+ * about the shell, and every other probe, stays exact.+ *+ * The canonical composition above reuses the fixture's own trigger and so+ * never reflows the shell. This variant inserts a new one, the way the task+ * reads and the way the pilot's executors read it.+ */+ function insertShellDialogTrigger(arm: string) {+ edit(path.join(arm, 'src', 'App.tsx'), source =>+ source+ .replace(+ ` data-vibe-probe="dialog-trigger"+ data-vibe-result="astryx-dialog-trigger"`,+ ` data-vibe-probe="dialog-trigger"`,+ )+ .replace(+ ' </main>',+ ` <section className="rounded-lg border border-border bg-panel p-4">+ <h2 className="text-sm font-semibold">Escalation routing</h2>+ <button+ className="mt-3 rounded-md border border-border bg-panel px-3 py-2 text-sm font-medium"+ data-vibe-result="astryx-dialog-trigger"+ onClick={() => setDialogOpen(true)}+ type="button">+ Open service actions+ </button>+ </section>+ </main>`,+ ),+ );+ }++ let shellTriggerMeasurement: {+ baseline: Measurement;+ result: Measurement;+ } | null = null;++ function measureShellTriggerInsertion() {+ if (shellTriggerMeasurement) {+ return shellTriggerMeasurement;+ }+ const {+ root,+ baseline: baselineApp,+ arm,+ } = preparePair('enterprise-scoped-synthetic');+ applyEnterpriseComposition(arm);+ insertShellDialogTrigger(arm);+ const baseline = measure(+ baselineApp,+ 'enterprise-scoped-synthetic',+ path.join(root, 's5-shell-baseline.json'),+ );+ const provenance = provenanceFor(arm, 'enterprise-scoped-synthetic', 's5');+ const result = measure(+ arm,+ 'enterprise-scoped-synthetic',+ path.join(root, 's5-shell-arm.json'),+ provenance,+ );+ expect(+ result.build.ok,+ `${result.build.stdout}\n${result.build.stderr}`,+ ).toBe(true);+ shellTriggerMeasurement = {baseline, result};+ return shellTriggerMeasurement;+ }++ it('accepts the host-shell reflow the mandated trigger insertion causes', () => {+ const {baseline, result} = measureShellTriggerInsertion();+ const score = scoreArm(baseline, result);++ expect(score.regressionDetails, JSON.stringify(score, null, 2)).toEqual([]);+ expect(score.taskFailures).toEqual([]);+ expect(verdict(score)).toBe('clean');+ expect(passesAcceptance(score)).toBe(true);++ // The reflow the allowance covers really happened, in both modes, or this+ // case is proving nothing.+ for (const scheme of ['light', 'dark'] as const) {+ const before = baseline.schemes[scheme].probes['host-shell'];+ const after = result.schemes[scheme].probes['host-shell'];+ if ('missing' in before || 'missing' in after) {+ throw new Error('missing host-shell probe');+ }+ expect(after.geometry.height).toBeGreaterThan(before.geometry.height);+ expect(after.text.length).toBeGreaterThan(before.text.length);+ // and nothing the allowance does not name moved+ expect(after.geometry.y).toBe(before.geometry.y);+ expect(after.geometry.x).toBe(before.geometry.x);+ expect(after.geometry.width).toBe(before.geometry.width);+ // `height` is the one computed style the allowance names, and it is the+ // only one that may differ.+ expect(after.style.height).not.toBe(before.style.height);+ const {height: _afterHeight, ...afterStyle} = after.style;+ const {height: _beforeHeight, ...beforeStyle} = before.style;+ expect(afterStyle).toEqual(beforeStyle);+ }+ }, 180_000);++ /**+ * Mutation proofs over the accepted measurement above. Each one changes one+ * measured field of the real run and re-scores it: the allowance must be+ * narrow enough that every one of them fails.+ */+ it.each([+ {+ name: 'a computed style on the same probe',+ probe: 'host-shell',+ style: {color: 'rgb(1, 2, 3)'},+ },+ {+ name: "the shell's own width, which the allowance does not name",+ probe: 'host-shell',+ geometry: {width: 1_000},+ },+ {+ name: "another probe's height, which the allowance must not reach",+ probe: 'status',+ geometry: {height: 99},+ },+ ])(+ 'still reports $name as host damage',+ ({probe, style, geometry}) => {+ const {baseline, result} = measureShellTriggerInsertion();+ const mutated = JSON.parse(JSON.stringify(result)) as Measurement;+ for (const scheme of ['light', 'dark'] as const) {+ const reading = mutated.schemes[scheme].probes[probe] as {+ style: Record<string, string>;+ geometry: Record<string, number>;+ };+ Object.assign(reading.style, style ?? {});+ Object.assign(reading.geometry, geometry ?? {});+ }++ const score = scoreArm(baseline, mutated);++ expect(score.regressions).toBeGreaterThan(0);+ expect(passesAcceptance(score)).toBe(false);+ },+ 180_000,+ );++ it('still reports host text the shell lost, not just text it gained', () => {+ const {baseline, result} = measureShellTriggerInsertion();+ const mutated = JSON.parse(JSON.stringify(result)) as Measurement;+ for (const scheme of ['light', 'dark'] as const) {+ const reading = mutated.schemes[scheme].probes['host-shell'] as {+ text: string;+ };+ // Drop one word of the host's own copy while keeping the added block's+ // text: an insertion-only allowance must not cover this.+ reading.text = reading.text.replace('Portfolio console ', '');+ }++ const score = scoreArm(baseline, mutated);++ expect(+ score.regressionDetails.some(+ regression =>+ regression.probe === 'host-shell' && regression.property === 'text',+ ),+ ).toBe(true);+ expect(passesAcceptance(score)).toBe(false);+ }, 180_000);});diff --git a/internal/vibe-tests/setup-test/setup-eval.test.ts b/internal/vibe-tests/setup-test/setup-eval.test.tsindex 4a2af41e08..93266c2a35 100644--- a/internal/vibe-tests/setup-test/setup-eval.test.ts+++ b/internal/vibe-tests/setup-test/setup-eval.test.ts@@ -12,7 +12,11 @@ import {cascadeInverted,compareCandidate,contrastFailures,+ failureBreakdown,+ failureCauses,hardGateVector,+ isComparableRun,+ isTextInsertionOnly,nestedLayerFailures,passesAcceptance,regressions,@@ -841,3 +845,438 @@ describe('strict confirmation summary', () => {expect(summary.passes).toBe(false);});});++/**+ * The s5 intended-change allowance.+ *+ * A task that mandates inserting a control into a host container makes that+ * container taller and adds the control's copy to its text. Both measured `s5`+ * cells reported the identical eight "regressions" for doing what the task+ * said. The allowance is field-granular on purpose: it names the shell's height+ * and the two geometry fields height moves, and permits text the container+ * *gains* — and nothing else, on nothing else.+ */+describe('intended-change allowances for a mandated insertion', () => {+ const SHELL_ALLOWANCE: TaskContract = {+ ...TASK,+ allowedHostChanges: [+ {+ fixture: 'enterprise-scoped-synthetic',+ probe: 'host-shell',+ fields: ['height', 'geometry.height', 'geometry.bottom'],+ textInsertionOnly: true,+ },+ ],+ };++ const shellScheme = (+ overrides: {+ style?: Record<string, string>;+ geometry?: Record<string, number>;+ text?: string;+ } = {},+ ) =>+ scheme({+ probes: {+ 'host-shell': {+ style: {...STYLE, ...(overrides.style ?? {})},+ geometry: {...GEOMETRY, ...(overrides.geometry ?? {})},+ contrast: 12,+ text: overrides.text ?? 'Portfolio console Service controls',+ },+ status: probe({...STYLE, color: 'rgb(110, 231, 183)'}, 8.1, 'Ready'),+ },+ });++ const scored = (+ overrides: Parameters<typeof shellScheme>[0],+ contract: TaskContract = SHELL_ALLOWANCE,+ ) =>+ scoreArm(+ measurement({+ label: 'baseline',+ task: false,+ light: shellScheme(),+ dark: shellScheme(),+ }),+ measurement({+ fixture: 'enterprise-scoped-synthetic',+ contract,+ light: shellScheme(overrides),+ dark: shellScheme(overrides),+ }),+ );++ const REFLOW = {+ style: {height: '140px'},+ geometry: {height: 140, bottom: 160},+ text: 'Portfolio console Service controls Escalation routing Open service actions',+ };++ it('accepts the growth and added text the insertion causes', () => {+ const score = scored(REFLOW);+ expect(score.regressionDetails).toEqual([]);+ expect(verdict(score)).toBe('clean');+ });++ it('reports the same change with no allowance in the contract', () => {+ const score = scored(REFLOW, TASK);+ expect(+ score.regressionDetails+ .map(regression => regression.property)+ .sort()+ .filter((value, index, all) => all.indexOf(value) === index),+ ).toEqual(['geometry.bottom', 'geometry.height', 'height', 'text']);+ });++ it.each([+ {name: 'a computed style', overrides: {style: {color: 'rgb(1, 2, 3)'}}},+ {+ name: 'a geometry field the allowance does not name',+ overrides: {geometry: {width: 999}},+ },+ ])('still reports $name on the same probe', ({overrides}) => {+ const score = scored({+ ...REFLOW,+ style: {...REFLOW.style, ...(overrides.style ?? {})},+ geometry: {...REFLOW.geometry, ...(overrides.geometry ?? {})},+ });+ expect(score.regressions).toBeGreaterThan(0);+ expect(verdict(score)).not.toBe('clean');+ });++ it('permits added text but never lost or rewritten text', () => {+ expect(+ isTextInsertionOnly('Portfolio console', 'Portfolio console Escalation'),+ ).toBe(true);+ expect(+ isTextInsertionOnly('Portfolio console', 'Escalation Portfolio console'),+ ).toBe(true);+ expect(isTextInsertionOnly('Portfolio console', 'Portfolio')).toBe(false);+ expect(isTextInsertionOnly('Portfolio console', 'Portfolio desk')).toBe(+ false,+ );+ expect(isTextInsertionOnly('Portfolio console', 'console Portfolio')).toBe(+ false,+ );+ });++ it('reports host copy the container lost even under the allowance', () => {+ const score = scored({+ ...REFLOW,+ text: 'Service controls Escalation routing Open service actions',+ });+ expect(+ score.regressionDetails.some(+ regression =>+ regression.probe === 'host-shell' && regression.property === 'text',+ ),+ ).toBe(true);+ });++ it('does not leak the allowance to another probe', () => {+ const score = scoreArm(+ measurement({+ label: 'baseline',+ task: false,+ light: shellScheme(),+ dark: shellScheme(),+ }),+ measurement({+ fixture: 'enterprise-scoped-synthetic',+ contract: SHELL_ALLOWANCE,+ light: scheme({+ probes: {+ 'host-shell': {+ style: STYLE,+ geometry: GEOMETRY,+ contrast: 12,+ text: 'Portfolio console Service controls',+ },+ status: probe(+ {...STYLE, color: 'rgb(110, 231, 183)', height: '99px'},+ 8.1,+ 'Ready',+ ),+ },+ }),+ dark: shellScheme(),+ }),+ );+ expect(+ score.regressionDetails.some(+ regression =>+ regression.probe === 'status' && regression.property === 'height',+ ),+ ).toBe(true);+ });++ it('does not apply an allowance written for another fixture', () => {+ const score = scoreArm(+ measurement({+ label: 'baseline',+ task: false,+ light: shellScheme(),+ dark: shellScheme(),+ }),+ measurement({+ fixture: 'tailwind-v4-control',+ contract: SHELL_ALLOWANCE,+ light: shellScheme(REFLOW),+ dark: shellScheme(REFLOW),+ }),+ );+ expect(score.regressions).toBeGreaterThan(0);+ });+});++/**+ * The report distinction. `verdict` answers "is this acceptable"; it is not a+ * description of what went wrong, and the operator report read it as one.+ */+describe('failure kinds', () => {+ const withScore = (mutate: (value: ReturnType<typeof scoreArm>) => void) => {+ const value = scoreArm(baseline(), measurement());+ mutate(value);+ return value;+ };++ it('is empty for a clean completed run', () => {+ expect(failureBreakdown(scoreArm(baseline(), measurement()))).toEqual({+ hostDamage: 0,+ runtime: 0,+ integrity: 0,+ task: 0,+ telemetry: 0,+ });+ expect(failureCauses(scoreArm(baseline(), measurement()))).toEqual([]);+ });++ it.each([+ {+ kind: 'hostDamage',+ mutate: (value: ReturnType<typeof scoreArm>) => {+ value.regressions = 2;+ },+ },+ {+ kind: 'integrity',+ mutate: (value: ReturnType<typeof scoreArm>) => {+ value.integrityFailures = ['hardcoded-important'];+ },+ },+ {+ kind: 'task',+ mutate: (value: ReturnType<typeof scoreArm>) => {+ value.taskFailures = ['light:menu:host-style'];+ },+ },+ {+ kind: 'telemetry',+ mutate: (value: ReturnType<typeof scoreArm>) => {+ value.executionSucceeded = false;+ },+ },+ ])('attributes a $kind failure to that kind alone', ({kind, mutate}) => {+ expect(failureCauses(withScore(mutate))).toEqual([kind]);+ });++ it('counts a measurement error as telemetry, not as host damage', () => {+ const value = withScore(score => {+ score.measurementErrors = ['probe read failed'];+ });+ expect(failureBreakdown(value).telemetry).toBe(1);+ expect(failureBreakdown(value).hostDamage).toBe(0);+ });++ it('marks a run the executor did not finish as not comparable', () => {+ expect(isComparableRun(scoreArm(baseline(), measurement()))).toBe(true);+ expect(+ isComparableRun(+ withScore(score => {+ score.executionSucceeded = false;+ }),+ ),+ ).toBe(false);+ });+});++/**+ * Relocated host UI must stay inside the host token scope that was painting it.+ *+ * A task that composes existing host markup inside a design-system overlay+ * moves that markup in the DOM. An established app frequently scopes part of+ * its palette to a region — a settings panel, a guest area — so an element that+ * was inside the region resolves the region's values and the same element+ * outside it resolves the global ones. The classes do not change and the colour+ * does, which reads like the design system repainting a host component and is+ * not.+ *+ * `host-boundary` is reported apart from `host-style` because the two have+ * opposite fixes. Losing the boundary means the host's own rules stopped+ * reaching the element: restore the boundary. Restating the colours instead+ * produces a surface that matches today and silently desynchronizes the next+ * time the host retunes its palette — which is why the boundary is checked+ * structurally and not inferred from the colours agreeing.+ */+describe('relocated host surfaces keep their host token boundary', () => {+ const SCOPE = '[data-guest-design-system]';++ const relocated = ({+ tokenScopes,+ style = STYLE,+ }: {+ tokenScopes: string[];+ style?: Record<string, string>;+ }) => {+ const reference = interaction('host-baseline', {tokenScopes: [SCOPE]});+ const moved: InteractionReading = {+ id: 'host-menu-in-astryx-dialog',+ direction: 'host-in-astryx',+ opened: true,+ keyboardReached: {+ 'astryx-dialog-trigger': true,+ 'host-menu-trigger': true,+ },+ surfaces: {+ 'astryx-dialog-backdrop': layerSurface('backdrop', '40'),+ 'astryx-dialog-surface': layerSurface('dialog', '50'),+ 'host-menu-surface': layerSurface('popover', '70', {+ tokenScopes,+ style,+ }),+ },+ };+ const contract: TaskContract = {+ ...TASK,+ interactions: [+ {+ id: 'host-menu-in-astryx-dialog',+ direction: 'host-in-astryx',+ open: [+ {+ name: 'astryx-dialog-trigger',+ source: 'result',+ method: 'keyboard-activate',+ key: 'Enter',+ },+ {+ name: 'host-menu-trigger',+ source: 'result',+ method: 'keyboard-activate',+ key: 'Enter',+ },+ ],+ surfaces: [+ {+ name: 'astryx-dialog-backdrop',+ source: 'result',+ kind: 'backdrop',+ marker: 'astryx-dialog-surface',+ },+ {name: 'astryx-dialog-surface', source: 'result', kind: 'dialog'},+ {+ name: 'host-menu-surface',+ source: 'result',+ kind: 'popover',+ styleReference: 'popover-surface',+ },+ ],+ },+ ],+ };+ const armScheme = () =>+ scheme({taskInteractions: {'host-menu-in-astryx-dialog': moved}});+ return {+ baseline: measurement({+ light: scheme({interaction: reference}),+ dark: scheme({interaction: reference}),+ }),+ arm: measurement({+ light: armScheme(),+ dark: armScheme(),+ contract,+ }),+ };+ };++ it('accepts a relocated surface that kept the boundary and matches', () => {+ const {baseline, arm} = relocated({tokenScopes: [SCOPE]});+ const score = scoreArm(baseline, arm);+ expect(score.taskFailures).toEqual([]);+ expect(passesAcceptance(score)).toBe(true);+ });++ it('reports a lost boundary distinctly from the colours it changed', () => {+ // The measured failure: the executor carried the host's mode hooks onto the+ // moved menu but not the attribute scoping its palette.+ const {baseline, arm} = relocated({+ tokenScopes: [],+ style: {...STYLE, backgroundColor: 'rgb(255, 255, 255)'},+ });+ const score = scoreArm(baseline, arm);+ expect(score.taskFailures).toContain(+ 'light:host-menu-in-astryx-dialog:host-menu-surface:host-boundary',+ );+ expect(score.taskFailures).toContain(+ 'dark:host-menu-in-astryx-dialog:host-menu-surface:host-boundary',+ );+ expect(score.taskFailures).toContain(+ 'light:host-menu-in-astryx-dialog:host-menu-surface:host-style',+ );+ expect(passesAcceptance(score)).toBe(false);+ });++ it('still reports the lost boundary when the colours were restated to match', () => {+ // The mutation that matters. Copying the region's colours onto the moved+ // element makes every style comparison agree while the element is no longer+ // inside the region, so the next host palette change desynchronizes it+ // silently. Matching colours must not buy a pass.+ const {baseline, arm} = relocated({tokenScopes: []});+ const score = scoreArm(baseline, arm);+ expect(score.taskFailures).not.toContain(+ 'light:host-menu-in-astryx-dialog:host-menu-surface:host-style',+ );+ expect(score.taskFailures).toContain(+ 'light:host-menu-in-astryx-dialog:host-menu-surface:host-boundary',+ );+ expect(passesAcceptance(score)).toBe(false);+ });++ it('still reports a restyle that happened inside the right boundary', () => {+ // The converse mutation: keeping the boundary must not excuse a real+ // repaint of the host surface.+ const {baseline, arm} = relocated({+ tokenScopes: [SCOPE],+ style: {...STYLE, color: 'rgb(1, 2, 3)'},+ });+ const score = scoreArm(baseline, arm);+ expect(score.taskFailures).toContain(+ 'light:host-menu-in-astryx-dialog:host-menu-surface:host-style',+ );+ expect(score.taskFailures).not.toContain(+ 'light:host-menu-in-astryx-dialog:host-menu-surface:host-boundary',+ );+ expect(passesAcceptance(score)).toBe(false);+ });++ it('treats a fixture with no scoped regions as trivially satisfied', () => {+ // Two of the three fixtures define tokens only at the root, so every+ // surface records an empty scope list and this check never fires for them.+ const {baseline, arm} = relocated({tokenScopes: []});+ const unscopedBaseline = JSON.parse(+ JSON.stringify(baseline),+ ) as typeof baseline;+ for (const key of ['light', 'dark'] as const) {+ const surfaces = unscopedBaseline.schemes[key].interaction?.surfaces;+ const reference = surfaces?.['popover-surface'];+ if (reference && !('missing' in reference)) {+ reference.tokenScopes = [];+ }+ }+ const score = scoreArm(unscopedBaseline, arm);+ expect(+ score.taskFailures.filter(failure => failure.endsWith('host-boundary')),+ ).toEqual([]);+ });+});diff --git a/internal/vibe-tests/setup-test/setup-eval.ts b/internal/vibe-tests/setup-test/setup-eval.tsindex 2c6385b21b..b9a524d57b 100644--- a/internal/vibe-tests/setup-test/setup-eval.ts+++ b/internal/vibe-tests/setup-test/setup-eval.ts@@ -54,6 +54,12 @@ export type LayerSurfaceReading =clippingAncestor: string | null;centerHitSelf: boolean;centerHitProbe: string | null;+ /**+ * The host token-scoping selectors this surface is inside, nearest first,+ * discovered from the app's own emitted CSS. Absent on measurements taken+ * before this was recorded, which compare as an empty list.+ */+ tokenScopes?: string[];topLayer: {tagName: string;role: string | null;@@ -117,6 +123,20 @@ export type AllowedHostChange = {fixture: string;probe: string;fields: string[];+ /**+ * Whether this probe's accumulated text may *gain* content.+ *+ * A task that mandates inserting a control into an existing host container+ * necessarily adds that control's text to the container's text, so comparing+ * the container's text exactly reports the mandated insertion as host damage.+ * This permits added text and nothing else: every baseline word must still be+ * present, in its original order. Losing a word, changing one, or reordering+ * them is still a regression, so the container's existing content stays as+ * protected as it was. It is deliberately separate from `fields` — putting+ * `text` in `fields` would exempt the comparison outright and let an executor+ * delete host copy.+ */+ textInsertionOnly?: boolean;};export type ReplacedHostProbe = {@@ -213,12 +233,36 @@ export type Regression = {const stringValue = (value: unknown) =>value === undefined ? '(missing)' : String(value);+/**+ * Whether `after` is `before` with text added and nothing removed.+ *+ * Words are compared in order: every baseline word must still appear, in the+ * same sequence, with new words allowed between them. A deletion, a+ * substitution, and a reordering all fail, so a container whose text may grow+ * still cannot lose or rewrite the host's own copy.+ */+export function isTextInsertionOnly(before: string, after: string): boolean {+ const baseline = before.trim().split(/\s+/).filter(Boolean);+ const current = after.trim().split(/\s+/).filter(Boolean);+ if (current.length < baseline.length) {+ return false;+ }+ let index = 0;+ for (const word of current) {+ if (index < baseline.length && word === baseline[index]) {+ index += 1;+ }+ }+ return index === baseline.length;+}+/** Compare the complete captured style and geometry key union exactly. */export function regressions(before: SchemeReading,after: SchemeReading,allowedFields: ReadonlyMap<string, ReadonlySet<string>> = new Map(),replacedProbes: ReadonlySet<string> = new Set(),+ textInsertionProbes: ReadonlySet<string> = new Set(),): {changed: Regression[]; missing: string[]} {const changed: Regression[] = [];const missing: string[] = [];@@ -262,18 +306,29 @@ export function regressions(...Object.keys(beforeValues),...Object.keys(afterValues),])) {+ if (beforeValues[property] === afterValues[property]) {+ continue;+ }+ if (allowed.has(property)) {+ continue;+ }if (- beforeValues[property] !== afterValues[property] &&- !allowed.has(property)+ property === 'text' &&+ textInsertionProbes.has(probe) &&+ isTextInsertionOnly(+ stringValue(beforeValues.text),+ stringValue(afterValues.text),+ )) {- changed.push({- probe,- property,- category: categoryOf(property),- before: stringValue(beforeValues[property]),- after: stringValue(afterValues[property]),- });+ continue;}+ changed.push({+ probe,+ property,+ category: categoryOf(property),+ before: stringValue(beforeValues[property]),+ after: stringValue(afterValues[property]),+ });}}return {changed, missing};@@ -695,6 +750,31 @@ function taskContractFailures(`${scheme}:${interaction.id}:${surfaceContract.name}:host-style`,);}+ /**+ * Relocated host UI must still sit inside the host token scopes that+ * were painting it.+ *+ * Reported separately from `host-style` because they are different+ * problems with opposite fixes, and a style diff alone cannot tell them+ * apart. Losing the boundary means the host's own rules stopped+ * reaching the element: the fix is to restore the boundary, and+ * restating the colours instead produces a surface that matches today+ * and silently desynchronizes the next time the host retunes its+ * palette. A style difference *inside* the right scopes is a real+ * restyle. Neither is excused by the other, so both are reported.+ */+ if (+ surface &&+ reference &&+ !('missing' in surface) &&+ !('missing' in reference) &&+ JSON.stringify(reference.tokenScopes ?? []) !==+ JSON.stringify(surface.tokenScopes ?? [])+ ) {+ failures.push(+ `${scheme}:${interaction.id}:${surfaceContract.name}:host-boundary`,+ );+ }}}}@@ -801,6 +881,24 @@ function allowedHostFields(arm: Measurement) {return fields;}+/**+ * The probes whose accumulated text may gain the mandated insertion's own text,+ * and only gain it. See `AllowedHostChange.textInsertionOnly`.+ */+function textInsertionProbes(arm: Measurement) {+ if (!arm.fixture || !arm.task) {+ return new Set<string>();+ }+ return new Set(+ arm.task.contract.allowedHostChanges+ .filter(+ allowed =>+ allowed.fixture === arm.fixture && allowed.textInsertionOnly === true,+ )+ .map(allowed => allowed.probe),+ );+}+function replacedHostProbes(arm: Measurement) {if (!arm.fixture || !arm.task) {return new Set<string>();@@ -865,6 +963,7 @@ export function scoreArm(baseline: Measurement, arm: Measurement): SetupScore {const allowedFields = allowedHostFields(arm);const replacedProbes = replacedHostProbes(arm);const overlayFields = allowedOverlayFields(arm);+ const insertionProbes = textInsertionProbes(arm);const regressionDetails = uniqueObjects((['light', 'dark'] as const).flatMap(scheme =>[@@ -873,6 +972,7 @@ export function scoreArm(baseline: Measurement, arm: Measurement): SetupScore {arm.schemes[scheme],allowedFields,replacedProbes,+ insertionProbes,).changed,...overlayStyleRegressions(baseline.schemes[scheme],@@ -891,6 +991,7 @@ export function scoreArm(baseline: Measurement, arm: Measurement): SetupScore {arm.schemes[scheme],allowedFields,replacedProbes,+ insertionProbes,).missing,),),@@ -994,6 +1095,76 @@ export function passesAcceptance(score: SetupScore): boolean {);}+/**+ * The kinds of failure a run can have. They are different things and a report+ * that adds them together says nothing useful.+ *+ * - `hostDamage` — the measurement found the host changed: computed styles,+ * geometry, missing probes, contrast, layering, cascade order, mode+ * dependence. This is the thing the whole stage exists to detect.+ * - `runtime` — the built app logged errors or failed requests.+ * - `integrity` — an escape hatch or a broken attestation in the source diff.+ * The host may be pixel-perfect and this still fails.+ * - `task` — the run did not do what it was asked to do.+ * - `telemetry` — the run's own reporting is unusable: the executor was+ * classified as failing, the measurement errored, or the baseline capture was+ * incomplete. Nothing here says anything about the host; it says the cell has+ * to be run again.+ *+ * `verdict` deliberately collapses several of these into `silent-damage`,+ * because a run with any of them is not acceptable. That is right for a gate+ * and wrong for a report: `silent-damage` from a comment misread as an+ * `!important` and `silent-damage` from a repainted host are the same word for+ * two unrelated problems. Report the breakdown next to the verdict.+ */+export type FailureKind =+ 'hostDamage' | 'runtime' | 'integrity' | 'task' | 'telemetry';++export type FailureBreakdown = Record<FailureKind, number>;++export function failureBreakdown(score: SetupScore): FailureBreakdown {+ return {+ hostDamage:+ score.regressions ++ score.missingProbes.length ++ score.contrastFailures.length ++ score.layeringFailures.length ++ score.layerOrderFailures.length ++ score.modeDependent.length ++ (score.cascadeInverted ? 1 : 0),+ runtime: score.consoleErrors + score.failedRequests,+ integrity: score.integrityFailures.length,+ task: score.taskFailures.length,+ telemetry:+ (score.executionSucceeded ? 0 : 1) ++ score.measurementErrors.length ++ score.baselineFailures.length,+ };+}++/** The failure kinds actually present, in report order. */+export function failureCauses(score: SetupScore): FailureKind[] {+ const breakdown = failureBreakdown(score);+ return (Object.keys(breakdown) as FailureKind[]).filter(+ kind => breakdown[kind] > 0,+ );+}++/**+ * Whether this run's measurement may be compared with another run's.+ *+ * A run the executor did not complete is still measured and still scored — the+ * sandbox exists and the evaluator reads it — but its verdict describes an+ * unfinished attempt. An operator run produced exactly that: a cell scored+ * `clean` on a run whose executor stopped early, because nothing damaged the+ * host once the work stopped. Counting that as a clean run makes the condition+ * look better than the evidence supports, so comparison excludes it and says+ * so.+ */+export function isComparableRun(score: SetupScore): boolean {+ return score.validRun && score.executionSucceeded;+}+export type HardDimension =| 'build'| 'runtime'diff --git a/internal/vibe-tests/setup-test/setup-important.mjs b/internal/vibe-tests/setup-test/setup-important.mjsnew file mode 100644index 0000000000..b8300a977f--- /dev/null+++ b/internal/vibe-tests/setup-test/setup-important.mjs@@ -0,0 +1,641 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * Syntactic detection of a hardcoded `!important`.+ *+ * The `hardcoded-important` escape hatch used to be a lexical scan: any added+ * line matching `/!\s*important/i` failed the run. That reads prose as code. An+ * executor told — correctly, by the guidance itself — not to paper over a+ * containment problem with `!important` writes that sentence into a JSDoc block+ * above the workaround it chose instead, and the check fails the run for saying+ * the right thing. Three cells of one operator run failed exactly that way, all+ * three on a comment.+ *+ * A declaration is now found the way the browser finds one, by parsing:+ *+ * - CSS and CSS-like files go through **postcss**. `Declaration.important` is+ * the parser's own answer to "does this declaration carry the flag", so a+ * comment is a `Comment` node and never a declaration, and `content:+ * "!important"` is a value string rather than a flag.+ * - Scripts go through the **TypeScript** parser, which handles `.js`, `.jsx`,+ * `.ts`, and `.tsx` with one API. Comments are trivia and are not nodes, so+ * they cannot be found; only string and template literals are examined, and+ * only where the literal is applied as CSS.+ * - HTML, Vue, and Svelte are split into their `<style>` blocks, their+ * `style="…"` attributes, and their `<script>` blocks, and each part is handed+ * to the analyzer above that owns it. Comments and text content are neither.+ *+ * Ignoring comments and prose must not open a way to smuggle a real override+ * past the check, so a literal counts as CSS whenever it is applied as CSS:+ *+ * 1. it *contains* a declaration carrying the flag (`color: red !important`),+ * which covers CSS-in-JS templates, `cssText`, `insertRule`, and inline+ * style strings, including one assembled across a template's interpolations;+ * 2. it *is* the value of a CSS property — a style-object entry, a `style.*`+ * assignment, a JSX `style={{…}}` entry — where the property name is a real+ * CSS property, taken from `CSSStyleDeclaration` in the TypeScript DOM+ * library rather than from a hand-written list that could miss one;+ * 3. it is the priority argument of `setProperty(property, value, 'important')`,+ * which sets the same flag without ever spelling `!important`, and which the+ * old lexical scan could not see at all.+ *+ * Anything the parsers cannot read fails closed: an unparsable stylesheet falls+ * back to a scanner that skips only comments and quoted strings, and a file+ * whose CSS property vocabulary cannot be loaded treats every style-shaped+ * property as a CSS property. A file that cannot be understood is never given+ * the benefit of the doubt.+ */++import * as fs from 'node:fs';+import * as path from 'node:path';+import {createRequire} from 'node:module';+import postcss from 'postcss';+import ts from 'typescript';++/** The flag itself: `!important`, `! important`, `!IMPORTANT`. */+const IMPORTANT_FLAG = /!\s*important\b/gi;++/**+ * A declaration carrying the flag, inside arbitrary CSS text. The property may+ * be a custom property or an ordinary one, and the value may be anything that+ * does not close the declaration.+ */+const DECLARATION_WITH_FLAG =+ /(?:^|[;{}])\s*(?:--[\w-]+|[A-Za-z][\w-]*)\s*:\s*[^;{}]*?!\s*important\b/gi;++const CSS_EXTENSIONS = new Set(['.css', '.less', '.pcss', '.sass', '.scss']);+const SCRIPT_KINDS = new Map([+ ['.cjs', ts.ScriptKind.JS],+ ['.js', ts.ScriptKind.JS],+ ['.jsx', ts.ScriptKind.JSX],+ ['.mjs', ts.ScriptKind.JS],+ ['.ts', ts.ScriptKind.TS],+ ['.tsx', ts.ScriptKind.TSX],+]);+const MARKUP_EXTENSIONS = new Set(['.html', '.svelte', '.vue']);++/* ---------------------------------------------------------------------------+ * CSS property vocabulary+ *+ * `CSSStyleDeclaration` in TypeScript's DOM library is the browser's own list+ * of CSS properties in camelCase. Reading it keeps the check honest about+ * properties nobody thought to enumerate (`inset`, `scrollbarGutter`,+ * `anchorName`) instead of trusting a list that ages.+ * ------------------------------------------------------------------------- */++const kebab = name =>+ name+ .replace(/([a-z0-9])([A-Z])/g, '$1-$2')+ .replace(/^-(?=[a-z])/, '-')+ .toLowerCase();++let cssPropertyNames;++/**+ * Every CSS property name accepted in a style object, in camelCase and kebab+ * form, or `null` when the DOM library cannot be read.+ *+ * The interface that carries the properties has moved between TypeScript+ * versions — it is `CSSStyleProperties` today and was `CSSStyleDeclaration`+ * before — so both are read and unioned rather than assuming either.+ */+export function cssPropertyVocabulary() {+ if (cssPropertyNames !== undefined) {+ return cssPropertyNames;+ }+ cssPropertyNames = null;+ try {+ const require = createRequire(import.meta.url);+ const source = fs.readFileSync(+ require.resolve('typescript/lib/lib.dom.d.ts'),+ 'utf8',+ );+ const names = new Set();+ for (const interfaceName of ['CSSStyleProperties', 'CSSStyleDeclaration']) {+ const start = source.indexOf(`\ninterface ${interfaceName}`);+ if (start === -1) {+ continue;+ }+ const bodyStart = source.indexOf('{', start);+ const end = source.indexOf('\n}', bodyStart);+ const body = source.slice(bodyStart, end === -1 ? undefined : end);+ for (const match of body.matchAll(+ /^\s{4}(?:readonly\s+)?(?:"([^"]+)"|([A-Za-z][\w]*))\s*:/gm,+ )) {+ const name = match[1] ?? match[2];+ names.add(name);+ names.add(kebab(name));+ }+ }+ // A scrape that came back thin means the shape changed again; a thin list+ // would quietly stop recognizing style objects, so it is treated as no list+ // at all and the fail-closed branch takes over.+ cssPropertyNames = names.size >= 100 ? names : null;+ } catch {+ cssPropertyNames = null;+ }+ return cssPropertyNames;+}++/**+ * Whether `name` names a CSS property in a style-object position.+ *+ * A custom property always qualifies. Otherwise the DOM vocabulary decides, and+ * when that cannot be loaded every hyphenated or camelCase identifier is+ * treated as a property, so a missing vocabulary over-reports rather than+ * letting an override through.+ */+export function isCssPropertyName(name) {+ if (typeof name !== 'string' || name === '') {+ return false;+ }+ if (name.startsWith('--')) {+ return true;+ }+ const vocabulary = cssPropertyVocabulary();+ if (vocabulary === null) {+ return /^[A-Za-z][\w-]*$/.test(name);+ }+ return vocabulary.has(name) || vocabulary.has(kebab(name));+}++/* ---------------------------------------------------------------------------+ * Offsets and lines+ * ------------------------------------------------------------------------- */++function lineStarts(text) {+ const starts = [0];+ for (let index = 0; index < text.length; index += 1) {+ if (text[index] === '\n') {+ starts.push(index + 1);+ }+ }+ return starts;+}++function lineAt(starts, offset) {+ let low = 0;+ let high = starts.length - 1;+ while (low < high) {+ const middle = Math.ceil((low + high) / 2);+ if (starts[middle] <= offset) {+ low = middle;+ } else {+ high = middle - 1;+ }+ }+ return low + 1;+}++/** Every offset of the flag inside `text`, relative to `text`. */+function flagOffsets(text, base = 0) {+ const offsets = [];+ for (const match of text.matchAll(IMPORTANT_FLAG)) {+ offsets.push(base + match.index);+ }+ return offsets;+}++/** Offsets of the flag in every declaration that carries one, in CSS text. */+function declarationFlagOffsets(text, base = 0) {+ const offsets = [];+ for (const match of text.matchAll(DECLARATION_WITH_FLAG)) {+ const inner = /!\s*important\b/i.exec(match[0]);+ if (inner) {+ offsets.push(base + match.index + inner.index);+ }+ }+ return offsets;+}++/* ---------------------------------------------------------------------------+ * CSS+ * ------------------------------------------------------------------------- */++/**+ * Flag offsets in a stylesheet, via postcss.+ *+ * Returns `null` when the stylesheet cannot be parsed — SCSS `//` comments and+ * the indented Sass syntax both defeat the default parser — so the caller can+ * fall back rather than silently reporting nothing.+ */+function postcssFlagOffsets(text) {+ let root;+ try {+ root = postcss.parse(text, {from: undefined});+ } catch {+ return null;+ }+ const starts = lineStarts(text);+ const offsetOf = position => {+ if (position == null) {+ return null;+ }+ if (typeof position.offset === 'number') {+ return position.offset;+ }+ const start = starts[position.line - 1];+ return start === undefined ? null : start + position.column - 1;+ };+ const offsets = [];+ root.walkDecls(declaration => {+ if (!declaration.important) {+ return;+ }+ const start = offsetOf(declaration.source?.start);+ const end = offsetOf(declaration.source?.end);+ if (start === null) {+ return;+ }+ const slice = text.slice(start, end === null ? undefined : end + 1);+ const found = flagOffsets(slice, start);+ // `important` is set, so the flag is in this declaration's own text; if the+ // spelling defeats the search, report the declaration's start rather than+ // dropping the finding.+ offsets.push(found.length > 0 ? found.at(-1) : start);+ });+ return offsets;+}++/**+ * Flag offsets in text a parser could not read: everything outside comments and+ * quoted strings. Deliberately blunt — it is the fail-closed path.+ */+function scannedCssFlagOffsets(text) {+ let masked = '';+ let index = 0;+ while (index < text.length) {+ const character = text[index];+ if (character === '/' && text[index + 1] === '*') {+ const close = text.indexOf('*/', index + 2);+ const end = close === -1 ? text.length : close + 2;+ masked += ' '.repeat(end - index);+ index = end;+ continue;+ }+ if (character === '/' && text[index + 1] === '/') {+ const close = text.indexOf('\n', index);+ const end = close === -1 ? text.length : close;+ masked += ' '.repeat(end - index);+ index = end;+ continue;+ }+ if (character === '"' || character === "'") {+ const start = index;+ index += 1;+ while (index < text.length && text[index] !== '\n') {+ if (text[index] === '\\') {+ index += 2;+ continue;+ }+ if (text[index] === character) {+ index += 1;+ break;+ }+ index += 1;+ }+ masked += ' '.repeat(index - start);+ continue;+ }+ masked += character;+ index += 1;+ }+ return flagOffsets(masked);+}++function cssFlagOffsets(text) {+ return postcssFlagOffsets(text) ?? scannedCssFlagOffsets(text);+}++/** Flag offsets in the body of a `style="…"` attribute. */+function styleAttributeFlagOffsets(value) {+ const prefix = 'a{';+ const wrapped = `${prefix}${value}}`;+ const offsets = postcssFlagOffsets(wrapped);+ const found = offsets ?? scannedCssFlagOffsets(wrapped);+ return found+ .map(offset => offset - prefix.length)+ .filter(offset => offset >= 0 && offset < value.length);+}++/* ---------------------------------------------------------------------------+ * Scripts+ * ------------------------------------------------------------------------- */++/** `foo.style.color = '…'` / `foo.style.cssText = '…'` — the assigned property. */+function styleAssignmentProperty(node) {+ const parent = node.parent;+ if (+ !parent ||+ !ts.isBinaryExpression(parent) ||+ parent.operatorToken.kind !== ts.SyntaxKind.EqualsToken ||+ parent.right !== node ||+ !ts.isPropertyAccessExpression(parent.left)+ ) {+ return null;+ }+ const owner = parent.left.expression;+ const ownerName = ts.isPropertyAccessExpression(owner)+ ? owner.name.text+ : ts.isIdentifier(owner)+ ? owner.text+ : null;+ if (ownerName !== 'style') {+ return null;+ }+ return parent.left.name.text;+}++/** The property name a literal sits under in an object literal, if any. */+function objectPropertyName(node) {+ const parent = node.parent;+ if (+ !parent ||+ !ts.isPropertyAssignment(parent) ||+ parent.initializer !== node+ ) {+ return null;+ }+ const name = parent.name;+ if (ts.isIdentifier(name) || ts.isPrivateIdentifier(name)) {+ return name.text;+ }+ if (ts.isStringLiteralLike(name) || ts.isNumericLiteral(name)) {+ return name.text;+ }+ return null;+}++/**+ * Whether the object literal a property belongs to is a style object regardless+ * of its keys: a JSX `style={{…}}` value, or a `style`/`sx`/`css` property.+ */+function inDeclaredStyleObject(node) {+ let current = node.parent;+ while (current) {+ if (ts.isObjectLiteralExpression(current)) {+ const owner = current.parent;+ if (owner && ts.isJsxExpression(owner)) {+ const attribute = owner.parent;+ if (+ attribute &&+ ts.isJsxAttribute(attribute) &&+ ts.isIdentifier(attribute.name) &&+ /^(?:style|sx|css)$/i.test(attribute.name.text)+ ) {+ return true;+ }+ }+ if (+ owner &&+ ts.isPropertyAssignment(owner) &&+ (ts.isIdentifier(owner.name) || ts.isStringLiteralLike(owner.name)) &&+ /^(?:style|sx|css)$/i.test(owner.name.text)+ ) {+ return true;+ }+ if (+ owner &&+ ts.isBinaryExpression(owner) &&+ owner.operatorToken.kind === ts.SyntaxKind.EqualsToken &&+ ts.isPropertyAccessExpression(owner.left) &&+ /^(?:style|sx|css)$/i.test(owner.left.name.text)+ ) {+ return true;+ }+ return false;+ }+ if (ts.isBlock(current) || ts.isSourceFile(current)) {+ return false;+ }+ current = current.parent;+ }+ return false;+}++/** `element.style.setProperty('color', 'red', 'important')`. */+function isSetPropertyPriority(node) {+ const parent = node.parent;+ if (!parent || !ts.isCallExpression(parent)) {+ return false;+ }+ const callee = parent.expression;+ const name = ts.isPropertyAccessExpression(callee)+ ? callee.name.text+ : ts.isIdentifier(callee)+ ? callee.text+ : null;+ if (name !== 'setProperty') {+ return false;+ }+ const index = parent.arguments.indexOf(node);+ return index === 2 && /^\s*important\s*$/i.test(node.text);+}++/**+ * The cooked text of a template, with each interpolation replaced by a single+ * placeholder character, plus a map back to source offsets. A declaration split+ * across an interpolation — `` `color: ${value} !important` `` — is still a+ * declaration.+ */+function templateText(node) {+ const segments = [];+ let text = '';+ const push = (literal, contentStart) => {+ segments.push({+ start: text.length,+ end: text.length + literal.length,+ contentStart,+ });+ text += literal;+ };+ if (ts.isNoSubstitutionTemplateLiteral(node)) {+ push(node.text, node.getStart() + 1);+ return {text, segments};+ }+ push(node.head.text, node.head.getStart() + 1);+ for (const span of node.templateSpans) {+ text += '\u0001';+ push(span.literal.text, span.literal.getStart() + 1);+ }+ return {text, segments};+}++function mapTemplateOffset(segments, offset) {+ for (const segment of segments) {+ if (offset >= segment.start && offset < segment.end) {+ return segment.contentStart + (offset - segment.start);+ }+ }+ return null;+}++/**+ * Flag offsets in a script: only inside string and template literals, and only+ * where the literal is applied as CSS.+ */+function scriptFlagOffsets(text, fileName, scriptKind) {+ const source = ts.createSourceFile(+ fileName,+ text,+ ts.ScriptTarget.Latest,+ true,+ scriptKind,+ );+ const offsets = [];++ const considerPlainLiteral = node => {+ const content = node.text;+ if (!IMPORTANT_FLAG.test(content)) {+ IMPORTANT_FLAG.lastIndex = 0;+ return;+ }+ IMPORTANT_FLAG.lastIndex = 0;+ const contentStart = node.getStart() + 1;+ const declarationOffsets = declarationFlagOffsets(content, contentStart);+ if (declarationOffsets.length > 0) {+ offsets.push(...declarationOffsets);+ return;+ }+ const property = objectPropertyName(node) ?? styleAssignmentProperty(node);+ if (+ property !== null &&+ (property === 'cssText' ||+ isCssPropertyName(property) ||+ inDeclaredStyleObject(node))+ ) {+ offsets.push(...flagOffsets(content, contentStart));+ }+ };++ const considerTemplate = node => {+ const {text: cooked, segments} = templateText(node);+ for (const offset of declarationFlagOffsets(cooked)) {+ const mapped = mapTemplateOffset(segments, offset);+ if (mapped !== null) {+ offsets.push(mapped);+ }+ }+ const property = objectPropertyName(node) ?? styleAssignmentProperty(node);+ if (+ property !== null &&+ (property === 'cssText' ||+ isCssPropertyName(property) ||+ inDeclaredStyleObject(node))+ ) {+ for (const offset of flagOffsets(cooked)) {+ const mapped = mapTemplateOffset(segments, offset);+ if (mapped !== null) {+ offsets.push(mapped);+ }+ }+ }+ };++ const visit = node => {+ if (ts.isStringLiteral(node)) {+ if (isSetPropertyPriority(node)) {+ offsets.push(node.getStart());+ } else {+ considerPlainLiteral(node);+ }+ } else if (+ ts.isNoSubstitutionTemplateLiteral(node) ||+ ts.isTemplateExpression(node)+ ) {+ considerTemplate(node);+ }+ ts.forEachChild(node, visit);+ };+ visit(source);+ return offsets;+}++/* ---------------------------------------------------------------------------+ * Markup+ * ------------------------------------------------------------------------- */++/** The document with every `<!-- … -->` comment blanked, offsets preserved. */+function maskMarkupComments(text) {+ let masked = text;+ for (const match of text.matchAll(/<!--[\s\S]*?(?:-->|$)/g)) {+ masked =+ masked.slice(0, match.index) ++ ' '.repeat(match[0].length) ++ masked.slice(match.index + match[0].length);+ }+ return masked;+}++function* taggedBlocks(text, tag) {+ const pattern = new RegExp(`<${tag}\\b[^>]*>([\\s\\S]*?)</${tag}>`, 'gi');+ for (const match of text.matchAll(pattern)) {+ yield {body: match[1], start: match.index + match[0].indexOf(match[1])};+ }+}++function markupFlagOffsets(text, fileName) {+ const masked = maskMarkupComments(text);+ const offsets = [];+ for (const block of taggedBlocks(masked, 'style')) {+ offsets.push(+ ...cssFlagOffsets(block.body).map(offset => offset + block.start),+ );+ }+ for (const block of taggedBlocks(masked, 'script')) {+ offsets.push(+ ...scriptFlagOffsets(block.body, `${fileName}.ts`, ts.ScriptKind.TS).map(+ offset => offset + block.start,+ ),+ );+ }+ for (const match of masked.matchAll(+ /\bstyle\s*=\s*("([^"]*)"|'([^']*)')/gi,+ )) {+ const value = match[2] ?? match[3] ?? '';+ const valueStart = match.index + match[0].indexOf(value, 'style'.length);+ offsets.push(+ ...styleAttributeFlagOffsets(value).map(offset => offset + valueStart),+ );+ }+ return offsets;+}++/* ---------------------------------------------------------------------------+ * Entry point+ * ------------------------------------------------------------------------- */++/**+ * The 1-based line numbers of `text` that carry a hardcoded `!important`.+ *+ * A line is reported only when a parser places the flag in an applied CSS+ * declaration, so a comment, a JSDoc block, a prose string, and documentation+ * text are all silent while a real override on the same line is not.+ */+export function importantDeclarationLines(relativePath, text) {+ if (typeof text !== 'string' || text === '') {+ return new Set();+ }+ if (!/important/i.test(text)) {+ return new Set();+ }+ const extension = path.extname(relativePath).toLowerCase();+ let offsets;+ if (CSS_EXTENSIONS.has(extension)) {+ offsets = cssFlagOffsets(text);+ } else if (SCRIPT_KINDS.has(extension)) {+ offsets = scriptFlagOffsets(+ text,+ path.basename(relativePath),+ SCRIPT_KINDS.get(extension),+ );+ } else if (MARKUP_EXTENSIONS.has(extension)) {+ offsets = markupFlagOffsets(text, path.basename(relativePath));+ } else {+ // An extension with no analyzer is judged the fail-closed way rather than+ // waved through.+ offsets = scannedCssFlagOffsets(text);+ }+ const starts = lineStarts(text);+ return new Set(offsets.map(offset => lineAt(starts, offset)));+}diff --git a/internal/vibe-tests/setup-test/setup-important.test.mjs b/internal/vibe-tests/setup-test/setup-important.test.mjsnew file mode 100644index 0000000000..33f736021e--- /dev/null+++ b/internal/vibe-tests/setup-test/setup-important.test.mjs@@ -0,0 +1,265 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {describe, expect, it} from 'vitest';+import {+ cssPropertyVocabulary,+ importantDeclarationLines,+ isCssPropertyName,+} from './setup-important.mjs';++const lines = (file, source) =>+ [...importantDeclarationLines(file, source)].sort(+ (left, right) => left - right,+ );++/**+ * The comment that made a real operator run fail three of its cells.+ *+ * This is the shape a `guest-contained` executor produces when it follows the+ * guidance: it documents the portal tradeoff it accepted and lists the things+ * it deliberately did *not* do, one of which is reaching for `!important`. The+ * lexical check read the word and failed the run for saying it.+ */+const GUEST_CONTAINED_COMMENT = `import {useEffect} from 'react';+import {Theme, neutralTheme} from '@astryxdesign/core';++/**+ * Keep the design system inside this region.+ *+ * A root provider syncs \`data-astryx-theme\` onto the document element, and the+ * theme's \`@scope\` rules key off that attribute, so leaving it in place themes+ * the whole document. There is no supported prop that opts out; removing the+ * attribute and observing for its return is a workaround, not a configuration.+ *+ * TRADEOFF: with the attribute gone, content portaled to \`document.body\` falls+ * outside every scope root and loses its theme tokens. This region renders a+ * button and its tooltip, both of which stay in-subtree, so containment wins+ * here. If it ever needs toasts, wrap it in a layer provider that keeps the+ * viewport in the subtree, or accept an unthemed toast — do not re-add a global+ * attribute under another name, copy theme variables onto \`body\`, or paper over+ * it with \`!important\` overrides.+ */+export function AstryxRegion({mode, children}) {+ useEffect(() => {+ const root = document.documentElement;+ const strip = () => root.removeAttribute('data-astryx-theme');+ strip();+ const observer = new MutationObserver(strip);+ observer.observe(root, {attributes: true, attributeFilter: ['data-astryx-theme']});+ return () => observer.disconnect();+ }, []);+ return (+ <Theme theme={neutralTheme} mode={mode}>+ {children}+ </Theme>+ );+}+`;+describe('CSS property vocabulary', () => {+ it('reads the browser property list rather than a hand-written one', () => {+ const vocabulary = cssPropertyVocabulary();+ expect(vocabulary).not.toBeNull();+ // Large enough to be the real list, and carrying both spellings.+ expect(vocabulary.size).toBeGreaterThan(400);+ expect(vocabulary.has('backgroundColor')).toBe(true);+ expect(vocabulary.has('background-color')).toBe(true);+ // Including the ones a hand-written list would have missed.+ expect(isCssPropertyName('scrollbarGutter')).toBe(true);+ expect(isCssPropertyName('--brand-accent')).toBe(true);+ expect(isCssPropertyName('label')).toBe(false);+ });+});++describe('!important in stylesheets', () => {+ it.each([+ {name: 'a declaration', css: '.host { color: red !important; }', at: [1]},+ {+ name: 'a declaration nested in an at-rule',+ css: '@media (min-width: 40rem) {\n .host {\n gap: 0 !important;\n }\n}',+ at: [3],+ },+ ])('finds $name', ({css, at}) => {+ expect(lines('host.css', css)).toEqual(at);+ });++ it.each([+ {+ name: 'a comment warning against it',+ css: '/* Never use !important in this file. */\n.host { color: red; }',+ },+ {+ name: 'a value string that merely spells it',+ css: '.host::after { content: "!important"; }',+ },+ ])('ignores $name', ({css}) => {+ expect(lines('host.css', css)).toEqual([]);+ });++ it('falls back to a conservative scan when the parser cannot read the file', () => {+ // SCSS line comments defeat the CSS parser; the fallback must still find+ // the declaration and must still skip the comment.+ const scss =+ '// !important is banned\n.host {\n color: red !important;\n}';+ expect(lines('host.scss', scss)).toEqual([3]);+ });++ it('does not exempt a stylesheet because a comment mentions the flag', () => {+ const css = [+ '/* The design system forbids !important; this file predates that. */',+ '.host {',+ ' color: red !important;',+ '}',+ ].join('\n');+ expect(lines('host.css', css)).toEqual([3]);+ });+});++describe('!important in scripts', () => {+ it('does not fire on the comment that failed real runs', () => {+ expect(lines('AstryxRegion.tsx', GUEST_CONTAINED_COMMENT)).toEqual([]);+ });++ it.each([+ {+ name: 'a JSDoc block',+ source:+ '/**\n * Do not paper over it with\n * !important.\n */\nexport const a = 1;',+ },+ {+ name: 'a prose string',+ source: 'export const RULE = "reviewers reject !important overrides";',+ },+ ])('ignores $name', ({source}) => {+ expect(lines('App.tsx', source)).toEqual([]);+ });++ it('finds a declaration assembled across a template interpolation', () => {+ // The parser sees two literal fragments, neither of which carries a whole+ // declaration; the flag is only visible once they are read as one value.+ expect(+ lines('App.tsx', 'const sheet = `.host { color: ${token} !important; }`;'),+ ).toEqual([1]);+ });+});++describe('!important in markup', () => {+ it('finds a style attribute and ignores an HTML comment', () => {+ const html = [+ '<!-- !important is banned in this template -->',+ '<div style="color: red !important">host</div>',+ ].join('\n');+ expect(lines('index.html', html)).toEqual([2]);+ });++ it.each([+ {+ name: 'a style element',+ html: '<style>\n .host { color: red !important; }\n</style>',+ },+ {+ name: 'a script element',+ html: '<script>\n el.style.setProperty("color", "red", "important");\n</script>',+ },+ ])('routes $name to the analyzer that owns it', ({html}) => {+ expect(lines('index.html', html)).toEqual([2]);+ });+});++/**+ * Every extension the detector claims to route, in one table.+ *+ * `.tsx`, `.css` and `.html` above are the shapes the real runs produced; the+ * routing table also claims plain and module JavaScript, JSX, and the two+ * single-file component formats, and an extension that falls through it is+ * scanned lexically instead — which is the false positive this whole file+ * exists to prevent. Each row is the pair that matters: the comment alone says+ * nothing, and the same comment above a real override still reports the+ * override.+ */+describe('the extensions the routing table claims', () => {+ it.each([+ {+ file: 'setup.js',+ comment: '// Do not paper over it with !important.',+ applied: 'const patch = {color: "red !important"};',+ },+ {+ file: 'Region.jsx',+ comment: '// The guidance says never to reach for !important.',+ applied: 'export const Badge = () => <b style={{color: "red !important"}} />;',+ },+ {+ file: 'theme.mjs',+ comment: '// !important is banned in this file.',+ applied: 'root.style.setProperty("color", "red", "important");',+ },+ {+ file: 'theme.cjs',+ comment: '/* Reviewers reject !important overrides. */',+ applied: 'module.exports = `.host { color: red !important; }`;',+ },+ {+ file: 'App.vue',+ comment: '<!-- !important is banned in this template -->',+ applied: '<div style="color: red !important">host</div>',+ },+ {+ file: 'App.svelte',+ comment: '<!-- reviewers reject !important -->',+ applied: '<style>.host { color: red !important; }</style>',+ },+ ])('reads a comment and an override apart in $file', ({file, comment, applied}) => {+ expect(lines(file, comment)).toEqual([]);+ expect(lines(file, `${comment}\n${applied}`)).toEqual([2]);+ });+});++/**+ * Mutations of the real false-positive fixture.+ *+ * Ignoring comments and prose is only safe if a real override cannot hide in+ * one. Each mutation keeps the comment exactly as the executor wrote it and+ * adds a genuine override through one of the three ways a literal counts as+ * applied CSS — a style-object value, a stylesheet string, and the+ * `setProperty` priority argument the old lexical scan could not see at all.+ */+describe('mutations of the real false-positive fixture', () => {+ it.each([+ {+ name: 'a style object below the comment',+ extra: 'const patch = {color: "red !important"};\n',+ },+ {+ name: 'an injected stylesheet',+ extra: 'const sheet = `.host { color: red !important; }`;\n',+ },+ {+ name: 'a runtime setProperty',+ extra: 'root.style.setProperty("color", "red", "important");\n',+ },+ ])('still catches $name', ({extra}) => {+ const found = lines('AstryxRegion.tsx', `${GUEST_CONTAINED_COMMENT}${extra}`);+ expect(found).toHaveLength(1);+ // The finding is on the added code, never on the comment above it.+ expect(found[0]).toBeGreaterThan(+ GUEST_CONTAINED_COMMENT.split('\n').length - 2,+ );+ });++ it.each([+ {+ name: 'directly below a comment that disclaims it',+ source:+ '/** Do not paper over it with !important. */\nconst patch = {color: "red !important"};',+ at: [2],+ },+ {+ name: 'on the same line as a comment that excuses it',+ source:+ 'const patch = {color: "red !important"}; // sanctioned !important',+ at: [1],+ },+ ])('catches an override written $name', ({source, at}) => {+ expect(lines('AstryxRegion.tsx', source)).toEqual(at);+ });+});diff --git a/internal/vibe-tests/setup-test/setup-integrity.mjs b/internal/vibe-tests/setup-test/setup-integrity.mjsindex fbcfeb0ff5..2ea9038ac2 100644--- a/internal/vibe-tests/setup-test/setup-integrity.mjs+++ b/internal/vibe-tests/setup-test/setup-integrity.mjs@@ -21,6 +21,18 @@* removes whitespace between tokens, so it cannot be used to hide a rewrite:* minifying a file onto one line, or stripping the spaces inside its lines,* leaves nothing that matches the baseline and still trips the guard.+ *+ * The `dark-mode-disabled` escape hatch reads `color-scheme` semantically+ * rather than lexically. A single-mode `color-scheme` declaration is exempt+ * only when it is a *paired mode arm* — see `pairedModeArmSpans` — because a+ * mode arm implements the light/dark switch instead of disabling it. Every+ * other form of the declaration, and every non-CSS form of the hatch+ * (`forcedTheme`, `darkMode: false`, a `color-scheme` meta tag), is unchanged.+ *+ * The `hardcoded-important` escape hatch is likewise syntactic rather than+ * lexical — see `setup-important.mjs`. The flag is found by parsing, so a+ * comment, a JSDoc block, or a prose string that merely names `!important`+ * is silent, while a declaration that carries it fails wherever it is written.*/import * as crypto from 'node:crypto';@@ -28,6 +40,7 @@ import {execFileSync} from 'node:child_process';import * as fs from 'node:fs';import * as path from 'node:path';import {fileURLToPath} from 'node:url';+import {importantDeclarationLines} from './setup-important.mjs';export const WHOLESALE_REPLACEMENT_THRESHOLD = Object.freeze({minimumDeletedLines: 20,@@ -51,12 +64,13 @@ const HOST_SOURCE_EXTENSIONS = new Set(['.vue',]);+/**+ * The escape hatches found by matching the added line itself.+ *+ * `hardcoded-important` is deliberately absent: it is found by parsing the+ * file rather than by matching a line, in `syntacticFindings`.+ */const ESCAPE_HATCHES = [- {- kind: 'hardcoded-important',- pattern: /!\s*important\b/i,- message: 'added a hardcoded !important declaration',- },{kind: 'blanket-reset',pattern: /\ball\s*:\s*(?:unset|initial|revert)\b/i,@@ -70,6 +84,11 @@ const ESCAPE_HATCHES = [},];+const HARDCODED_IMPORTANT = Object.freeze({+ kind: 'hardcoded-important',+ message: 'added a hardcoded !important declaration',+});+const compareText = (left, right) => (left < right ? -1 : left > right ? 1 : 0);function git(appDir, args, options = {}) {@@ -247,6 +266,313 @@ function isHostSource(relativePath) {return HOST_SOURCE_EXTENSIONS.has(path.extname(relativePath).toLowerCase());}+/* ---------------------------------------------------------------------------+ * Semantic `color-scheme` analysis+ *+ * `astryx theme build` emits, for any theme with `light-dark()` values:+ *+ * :root { color-scheme: light dark; }+ * html[data-theme="light"] { color-scheme: light; }+ * html[data-theme="dark"] { color-scheme: dark; }+ *+ * Those three rules *implement* mode support — they are what lets a mode+ * attribute resolve `light-dark()` — but a lexical `color-scheme: light` scan+ * reads the second one as disabling dark mode. Established hosts write the same+ * shape by hand (the `enterprise-scoped-synthetic` fixture pairs+ * `.fixture-shell[data-mode='light']` with its dark twin), so this is not a+ * generated-file problem and is not fixed by ignoring generated files.+ *+ * A declaration is exempt only as a *paired mode arm*: its own selector scopes+ * it to exactly one mode, its value is that same mode, and the complementary+ * arm exists at the same scope in the same file. Both halves of the switch have+ * to be present for the pair to mean "this file implements light and dark".+ * ------------------------------------------------------------------------- */++/**+ * Selector and at-rule syntax that scopes a rule to one color mode:+ * a mode-valued attribute (`[data-theme="dark"]`, `[data-mode='light']`,+ * `[data-astryx-media="dark"]`), a `prefers-color-scheme` media condition, or a+ * `.light`/`.dark` mode class. A theme-name attribute such as+ * `[data-astryx-theme="apptheme"]` names no mode and is not one of these.+ */+const MODE_DISCRIMINATOR_PATTERN =+ /\[\s*[A-Za-z_][\w-]*(?:theme|mode|scheme|appearance|media)\s*=\s*["']?(light|dark)["']?\s*\]|\(\s*prefers-color-scheme\s*:\s*(light|dark)\s*\)|\.(light|dark)(?![\w-])/gi;++/** `color-scheme: light`, `color-scheme: only dark`, `color-scheme: dark only`. */+const SINGLE_MODE_VALUE = /^(?:only\s+)?(light|dark)(?:\s+only)?$/i;++/**+ * The mode discriminators in a selector or at-rule prelude, plus the same text+ * with every discriminator's mode replaced by a placeholder. Two arms belong to+ * the same switch when their placeholder text is identical, so+ * `html[data-theme="light"]` pairs with `html[data-theme="dark"]` and not with+ * `.widget[data-theme="dark"]`.+ */+function modeDiscriminators(text) {+ const modes = new Set();+ const skeleton = text.replace(+ MODE_DISCRIMINATOR_PATTERN,+ (match, attribute, media, className) => {+ modes.add((attribute ?? media ?? className).toLowerCase());+ return match+ .replace(/["']/g, '')+ .replace(/\s+/g, '')+ .replace(/(?<![\w-])(?:light|dark)(?![\w-])/i, '<mode>');+ },+ );+ return {modes, skeleton: skeleton.replace(/\s+/g, ' ').trim()};+}++/**+ * Every declaration in a stylesheet, with the selector/at-rule preludes it is+ * nested inside and its absolute character span.+ *+ * Quoted strings and comments are read as opaque text: their braces and+ * semicolons are not structure, so `content: "}"` cannot desynchronize the+ * scan, and a `color-scheme` declaration written inside a JavaScript string+ * literal never becomes a block-scoped declaration that could be exempted.+ */+export function scanStyleDeclarations(text) {+ const declarations = [];+ const stack = [];+ let buffer = '';+ let bufferStart = -1;+ let index = 0;++ const append = (chunk, at) => {+ if (bufferStart === -1 && chunk.trim() !== '') {+ bufferStart = at + (chunk.length - chunk.trimStart().length);+ }+ buffer += chunk;+ };+ const reset = () => {+ buffer = '';+ bufferStart = -1;+ };+ const flushDeclaration = end => {+ const match = /^([A-Za-z-]+)\s*:\s*([\s\S]+)$/.exec(buffer.trim());+ if (match && bufferStart !== -1) {+ declarations.push({+ property: match[1].toLowerCase(),+ value: match[2].trim(),+ context: [...stack],+ start: bufferStart,+ end,+ });+ }+ reset();+ };++ while (index < text.length) {+ const character = text[index];+ if (character === '/' && text[index + 1] === '*') {+ const close = text.indexOf('*/', index + 2);+ index = close === -1 ? text.length : close + 2;+ continue;+ }+ if (character === '"' || character === "'") {+ const start = index;+ index += 1;+ while (index < text.length && text[index] !== '\n') {+ if (text[index] === '\\') {+ index += 2;+ continue;+ }+ if (text[index] === character) {+ index += 1;+ break;+ }+ index += 1;+ }+ append(text.slice(start, index), start);+ continue;+ }+ if (character === '{') {+ stack.push(buffer.trim());+ reset();+ index += 1;+ continue;+ }+ if (character === '}') {+ flushDeclaration(index);+ stack.pop();+ index += 1;+ continue;+ }+ if (character === ';') {+ flushDeclaration(index);+ index += 1;+ continue;+ }+ append(character, index);+ index += 1;+ }+ return declarations;+}++function lineSpans(text, spans) {+ const starts = [0];+ for (let index = 0; index < text.length; index += 1) {+ if (text[index] === '\n') starts.push(index + 1);+ }+ const byLine = new Map();+ const lineOf = offset => {+ let low = 0;+ let high = starts.length - 1;+ while (low < high) {+ const middle = Math.ceil((low + high) / 2);+ if (starts[middle] <= offset) low = middle;+ else high = middle - 1;+ }+ return low;+ };+ for (const span of spans) {+ let line = lineOf(span.start);+ while (line < starts.length && starts[line] < span.end) {+ const lineStart = starts[line];+ const lineEnd =+ line + 1 < starts.length ? starts[line + 1] - 1 : text.length;+ const start = Math.max(span.start, lineStart) - lineStart;+ const end = Math.min(span.end, lineEnd) - lineStart;+ if (end > start) {+ const existing = byLine.get(line + 1) ?? [];+ existing.push({start, end});+ byLine.set(line + 1, existing);+ }+ line += 1;+ }+ }+ return byLine;+}++/**+ * The character spans of every `color-scheme` declaration in `text` that is a+ * paired mode arm, keyed by 1-based line number.+ *+ * An arm qualifies when its enclosing selectors and at-rules name exactly one+ * mode, its value is that same mode, and a complementary arm for the other mode+ * exists at the same scope. An arm whose value contradicts its own selector+ * (`html[data-theme="dark"] { color-scheme: light; }`), an unpaired arm, and any+ * declaration outside a mode-scoped rule (`:root { color-scheme: light; }`) are+ * all absent from the result and stay subject to the escape-hatch scan.+ */+export function pairedModeArmSpans(text) {+ const arms = [];+ for (const declaration of scanStyleDeclarations(text)) {+ if (declaration.property !== 'color-scheme') continue;+ const value = SINGLE_MODE_VALUE.exec(declaration.value);+ if (!value) continue;+ const {modes, skeleton} = modeDiscriminators(declaration.context.join(' '));+ if (modes.size !== 1) continue;+ const [mode] = modes;+ if (mode !== value[1].toLowerCase()) continue;+ arms.push({mode, skeleton, start: declaration.start, end: declaration.end});+ }++ const modesByScope = new Map();+ for (const arm of arms) {+ const seen = modesByScope.get(arm.skeleton) ?? new Set();+ seen.add(arm.mode);+ modesByScope.set(arm.skeleton, seen);+ }+ return lineSpans(+ text,+ arms.filter(arm => modesByScope.get(arm.skeleton).size === 2),+ );+}++/** Text that participates in a light/dark switch, for removal detection. */+function mentionsMode(text) {+ return (+ /\bcolor-scheme\s*:/i.test(text) ||+ new RegExp(MODE_DISCRIMINATOR_PATTERN.source, 'i').test(text)+ );+}++/**+ * True when this change deleted a line that carried part of a mode switch and+ * did not put it back. Deleting one arm of a host's switch and adding a fresh+ * pair elsewhere in the same file would otherwise buy an exemption for the+ * added pair, so an exemption is withheld from a file that lost a mode line.+ */+function droppedModeLine(removedLines, currentSource) {+ if (removedLines.length === 0) return false;+ const remaining = new Set(+ currentSource.split('\n').map(normalizeLine).filter(Boolean),+ );+ return removedLines.some(+ removed =>+ mentionsMode(removed.text) && !remaining.has(normalizeLine(removed.text)),+ );+}++const GENERATED_BANNER = /@generated by `astryx theme build`/;++/**+ * Whether a file's claim to be a generated theme artifact holds up.+ *+ * `astryx theme build <source>` writes its output next to the source file (or+ * where an explicit `--out` in the recorded command says), and stamps a header+ * naming that source. A file carrying the header is checked against it: the+ * declared source must be a relative path inside the sandbox that still exists,+ * and this file must be where that build would have written it. A file with no+ * header makes no claim and is judged on its content alone; a file whose header+ * does not hold up is treated as hostile and gets no exemption, so pasting a+ * generated banner on top of an edited host stylesheet buys nothing.+ *+ * @returns {'unclaimed'|'valid'|'forged'}+ */+function generatedThemeProvenance(appDir, relativePath, text) {+ const header = text.slice(0, 2048);+ if (!GENERATED_BANNER.test(header)) return 'unclaimed';+ const source = /^[\s*/]*Source:\s*(\S.*?)\s*$/m.exec(header)?.[1];+ if (!source) return 'forged';+ if (path.isAbsolute(source)) return 'forged';+ const sourcePath = path.normalize(source);+ if (sourcePath.split(/[\\/]/).includes('..')) return 'forged';+ if (!fs.existsSync(path.join(appDir, sourcePath))) return 'forged';++ const emitted = /^[\s*/]*Command:\s*(\S.*?)\s*$/m.exec(header)?.[1] ?? '';+ const out = /--out(?:=|\s+)(\S+)/.exec(emitted)?.[1];+ const destination = out ? path.normalize(out) : null;+ if (destination !== null) {+ return destination === path.normalize(relativePath) ? 'valid' : 'forged';+ }+ return path.dirname(sourcePath) === path.dirname(path.normalize(relativePath))+ ? 'valid'+ : 'forged';+}++/**+ * The exempt `color-scheme` spans for one file: empty unless the file's own+ * content proves it implements both modes, it did not lose a mode line in this+ * change, and any generated-artifact claim it makes is true.+ */+function modeArmExemptions(appDir, relativePath, currentSource, removedLines) {+ if (!currentSource.includes('color-scheme')) return new Map();+ if (droppedModeLine(removedLines, currentSource)) return new Map();+ if (+ generatedThemeProvenance(appDir, relativePath, currentSource) === 'forged'+ )+ return new Map();+ return pairedModeArmSpans(currentSource);+}++/** The line with its exempt spans blanked out, for escape-hatch matching. */+function maskSpans(text, spans) {+ if (!spans || spans.length === 0) return text;+ let masked = text;+ for (const span of spans) {+ const end = Math.min(span.end, masked.length);+ if (end <= span.start) continue;+ masked =+ masked.slice(0, span.start) ++ ' '.repeat(end - span.start) ++ masked.slice(end);+ }+ return masked;+}+function addedLinesFromPatch(patch) {const lines = [];let newLine = 0;@@ -348,11 +674,30 @@ function evidenceFor(relativePath, lines) {return evidence;}-function findingsFor(relativePath, lines) {+/**+ * Escape hatches on the lines this change added.+ *+ * `importantLines` carries the parser's verdict for the whole file: the line+ * numbers where a `!important` is an applied CSS declaration. Intersecting it+ * with the added lines keeps the rule unchanged — only what this change added+ * is judged — while the judgment itself is now syntactic.+ */+function findingsFor(relativePath, lines, exemptSpans, importantLines) {const findings = [];for (const added of lines) {+ if (importantLines?.has(added.line)) {+ findings.push({+ kind: HARDCODED_IMPORTANT.kind,+ path: relativePath,+ line: added.line,+ message: HARDCODED_IMPORTANT.message,+ });+ }+ const masked = maskSpans(added.text, exemptSpans?.get(added.line));for (const escapeHatch of ESCAPE_HATCHES) {- if (escapeHatch.pattern.test(added.text)) {+ const subject =+ escapeHatch.kind === 'dark-mode-disabled' ? masked : added.text;+ if (escapeHatch.pattern.test(subject)) {findings.push({kind: escapeHatch.kind,path: relativePath,@@ -486,7 +831,22 @@ export function analyzeSetupIntegrity(appDir, attestedDiffSha256) {if (status !== 'deleted' && !file.binary) {const addedLines = trackedAddedLines(resolvedAppDir, file.path);if (isHostSource(file.path)) {- escapeHatches.push(...findingsFor(file.path, addedLines));+ const currentSource = fs.readFileSync(absolutePath, 'utf8');+ escapeHatches.push(+ ...findingsFor(+ file.path,+ addedLines,+ modeArmExemptions(+ resolvedAppDir,+ file.path,+ currentSource,+ existedAtBaseline+ ? trackedRemovedLines(resolvedAppDir, file.path)+ : [],+ ),+ importantDeclarationLines(file.path, currentSource),+ ),+ );}astryxEvidence.push(...evidenceFor(file.path, addedLines));}@@ -504,7 +864,19 @@ export function analyzeSetupIntegrity(appDir, attestedDiffSha256) {});const addedLines = untrackedAddedLines(untrackedByPath.get(file.path));if (isHostSource(file.path)) {- escapeHatches.push(...findingsFor(file.path, addedLines));+ const currentSource = file.binary ? null : file.bytes.toString('utf8');+ escapeHatches.push(+ ...findingsFor(+ file.path,+ addedLines,+ currentSource === null+ ? undefined+ : modeArmExemptions(resolvedAppDir, file.path, currentSource, []),+ currentSource === null+ ? undefined+ : importantDeclarationLines(file.path, currentSource),+ ),+ );}astryxEvidence.push(...evidenceFor(file.path, addedLines));}diff --git a/internal/vibe-tests/setup-test/setup-integrity.test.mjs b/internal/vibe-tests/setup-test/setup-integrity.test.mjsindex b46f3a79fe..ced7add1c0 100644--- a/internal/vibe-tests/setup-test/setup-integrity.test.mjs+++ b/internal/vibe-tests/setup-test/setup-integrity.test.mjs@@ -8,6 +8,7 @@ import {fileURLToPath} from 'node:url';import {afterEach, describe, expect, it} from 'vitest';import {analyzeSetupIntegrity,+ pairedModeArmSpans,substantiveLineDelta,WHOLESALE_REPLACEMENT_THRESHOLD,} from './setup-integrity.mjs';@@ -356,6 +357,365 @@ describe('setup integrity', () => {);});+ describe('color-scheme mode arms', () => {+ /**+ * Real `astryx theme build` output, captured verbatim from a theme that+ * extends `neutralTheme`. Two runs of homogeneous rules — the remaining+ * prose elements and the `--color-data-*` defaults — are elided and marked,+ * and the component block is reduced to one rule; every other byte,+ * including the `@generated` header, the nested `@layer`/`@scope`+ * structure, the three document `color-scheme` rules and the inverted+ * media-surface pair, is exactly what the CLI emits. The emitted shape+ * itself is guarded upstream by+ * `packages/cli/clients/cli/commands/build-theme.color-scheme.test.mjs`.+ */+ const BUILT_THEME_CSS = `/*+ * @generated by \`astryx theme build\` — do not edit manually.+ * Source: src/hostTheme.mjs+ * Command: astryx theme build src/hostTheme.mjs+ * CLI: @astryxdesign/[email protected]+ * Core: @astryxdesign/[email protected]+ */++@layer reset {+@scope ([data-astryx-theme="apptheme"]) to ([data-astryx-theme]) {+ :where(h1, h2, h3, h4, h5, h6) {+ font-family: var(--font-family-heading);+ color: var(--color-text-primary);+ }++ /* elided: the remaining h1-h6, p, small and code/pre prose rules */++ :where(hr) {+ border: none;+ border-top: 1px solid var(--color-border);+ }+}+}++@layer astryx-base {+:root {+ --color-data-categorical-blue: light-dark(#0171E3, #0171E3);+ /* elided: the remaining --color-data-* defaults */+ --color-data-neutral: light-dark(#8494A3, #8C939B);+}+}++@layer astryx-theme {+ :root { color-scheme: light dark; }+ html[data-theme="light"] { color-scheme: light; }+ html[data-theme="dark"] { color-scheme: dark; }++@scope ([data-astryx-theme="apptheme"]) to ([data-astryx-theme]) {+ :scope {+ --color-accent: light-dark(#0B5FFF, #74A8FF);+ }+}+}++@layer astryx-theme {+@scope ([data-astryx-theme="apptheme"]) to ([data-astryx-theme]) {+ [data-astryx-media="dark"] {+ color-scheme: dark;+ --color-text-primary: var(--color-on-dark);+ }++ [data-astryx-media="light"] {+ color-scheme: light;+ --color-text-primary: var(--color-on-light);+ }+}+}+`;++ /** The theme source that artifact names, so its provenance resolves. */+ const BUILT_THEME_SOURCE = `export default {+ name: 'apptheme',+ tokens: {'--color-accent': 'light-dark(#0B5FFF, #74A8FF)'},+};+`;++ /** A host stylesheet that owns its own light/dark switch, by hand. */+ const HOST_MODE_CSS = [+ ":where(.fixture-shell[data-mode='light']) {",+ ' color-scheme: light;',+ ' --background: #f4f6f9;',+ '}',+ '',+ ":where(.fixture-shell[data-mode='dark']) {",+ ' color-scheme: dark;',+ ' --background: #111726;',+ '}',+ '',+ ].join('\n');++ function withBuiltTheme(directory, css = BUILT_THEME_CSS) {+ write(directory, 'src/hostTheme.mjs', BUILT_THEME_SOURCE);+ write(directory, 'src/apptheme.css', css);+ }++ function darkModeFindings(directory) {+ return analyzeSetupIntegrity(directory, attest(directory))+ .escapeHatches.filter(finding => finding.kind === 'dark-mode-disabled')+ .map(finding => `${finding.path}:${finding.line}`);+ }++ /** Where a snippet lands in a file, so expectations track the fixture. */+ function lineOf(text, snippet) {+ const at = text.indexOf(snippet);+ if (at < 0) throw new Error(`snippet not in fixture: ${snippet}`);+ return text.slice(0, at).split('\n').length;+ }++ /** The light-valued declarations in the artifact, both of them arms. */+ const LIGHT_DECLARATIONS = [+ 'html[data-theme="light"]',+ 'color-scheme: light;\n --color-text-primary: var(--color-on-light);',+ ];++ /** Every light declaration flagged, i.e. the whole file unexempted. */+ function everyLightArm(path, css) {+ return LIGHT_DECLARATIONS.map(+ snippet => `${path}:${lineOf(css, snippet)}`,+ );+ }++ it('accepts the paired mode arms a real built theme emits', () => {+ const directory = repository();+ addValidAstryxChange(directory);+ withBuiltTheme(directory);+ const digest = attest(directory);++ const result = analyzeSetupIntegrity(directory, digest);++ expect(result.escapeHatches).toEqual([]);+ expect(result.accepted).toBe(true);+ });++ // MUTATION PROOFS. Each one changes exactly one thing about the artifact+ // above and must be rejected, so the test before this cannot pass by the+ // check having been switched off for built themes.+ it.each([+ {+ name: 'its dark arm rewritten to light',+ css: BUILT_THEME_CSS.replace(+ 'html[data-theme="dark"] { color-scheme: dark; }',+ 'html[data-theme="dark"] { color-scheme: light; }',+ ),+ // Neither arm survives: the pair no longer covers both modes.+ flagged: [+ 'html[data-theme="light"] { color-scheme: light; }',+ 'html[data-theme="dark"] { color-scheme: light; }',+ ],+ },+ {+ name: 'its dark arm deleted',+ css: BUILT_THEME_CSS.replace(+ ' html[data-theme="dark"] { color-scheme: dark; }\n',+ '',+ ),+ flagged: ['html[data-theme="light"] { color-scheme: light; }'],+ },+ {+ name: 'a global light pin added beside the pair',+ css: BUILT_THEME_CSS.replace(+ '@layer astryx-theme {\n',+ '@layer astryx-theme {\n html { color-scheme: light; }\n',+ ),+ flagged: ['html { color-scheme: light; }'],+ },+ {+ name: 'a light pin sharing a line with a real arm',+ css: BUILT_THEME_CSS.replace(+ 'html[data-theme="light"] { color-scheme: light; }',+ 'html[data-theme="light"] { color-scheme: light; } html { color-scheme: light; }',+ ),+ flagged: ['html[data-theme="light"] { color-scheme: light; } html'],+ },+ ])('rejects a built theme with $name', ({css, flagged}) => {+ const directory = repository();+ addValidAstryxChange(directory);+ withBuiltTheme(directory, css);++ expect(darkModeFindings(directory)).toEqual(+ flagged.map(snippet => `src/apptheme.css:${lineOf(css, snippet)}`),+ );+ });++ it.each([+ {+ name: 'a forged generated banner',+ // The banner claims a source that was never written.+ setUp: directory => {+ write(directory, 'src/apptheme.css', BUILT_THEME_CSS);+ return {path: 'src/apptheme.css', css: BUILT_THEME_CSS};+ },+ },+ {+ name: 'an artifact that is not where its source builds it',+ // `astryx theme build src/hostTheme.mjs` writes next to its source, so+ // a copy in another directory is not the artifact its header claims.+ setUp: directory => {+ write(directory, 'src/hostTheme.mjs', BUILT_THEME_SOURCE);+ write(directory, 'vendor/apptheme.css', BUILT_THEME_CSS);+ return {path: 'vendor/apptheme.css', css: BUILT_THEME_CSS};+ },+ },+ {+ name: 'a banner whose source escapes the sandbox',+ setUp: directory => {+ write(directory, 'src/hostTheme.mjs', BUILT_THEME_SOURCE);+ const css = BUILT_THEME_CSS.replace(+ 'Source: src/hostTheme.mjs',+ 'Source: ../../elsewhere/hostTheme.mjs',+ );+ write(directory, 'src/apptheme.css', css);+ return {path: 'src/apptheme.css', css};+ },+ },+ ])('refuses the exemption to $name', ({setUp}) => {+ const directory = repository();+ addValidAstryxChange(directory);+ const {path, css} = setUp(directory);++ expect(darkModeFindings(directory)).toEqual(everyLightArm(path, css));+ });++ it('keeps scanning a genuine built theme for every other escape hatch', () => {+ const directory = repository();+ addValidAstryxChange(directory);+ withBuiltTheme(+ directory,+ BUILT_THEME_CSS.replace(+ ' --color-accent: light-dark(#0B5FFF, #74A8FF);',+ ' --color-accent: light-dark(#0B5FFF, #74A8FF) !important;',+ ),+ );++ expect(+ kinds(analyzeSetupIntegrity(directory, attest(directory))),+ ).toEqual(['hardcoded-important']);+ });++ it("accepts a host stylesheet's own hand-written mode arms", () => {+ const directory = repository();+ addValidAstryxChange(directory);+ write(directory, 'src/host-modes.css', HOST_MODE_CSS);++ expect(darkModeFindings(directory)).toEqual([]);+ });++ it('accepts re-indenting an arm of the host switch', () => {+ const directory = repository();+ write(directory, 'src/index.css', HOST_MODE_CSS);+ git(directory, ['add', 'src/index.css']);+ git(directory, ['commit', '-qm', 'establish host modes']);+ addValidAstryxChange(directory);+ write(+ directory,+ 'src/index.css',+ HOST_MODE_CSS.replace(+ ' color-scheme: light;',+ ' color-scheme: light;',+ ),+ );++ expect(darkModeFindings(directory)).toEqual([]);+ });++ it('rejects dropping one arm of the host switch behind a fresh pair', () => {+ const directory = repository();+ write(directory, 'src/index.css', HOST_MODE_CSS);+ git(directory, ['add', 'src/index.css']);+ git(directory, ['commit', '-qm', 'establish host modes']);+ addValidAstryxChange(directory);+ // The host's dark arm is gone; a fresh, correctly paired switch is added+ // in its place. The pair alone would qualify, but the file lost an arm.+ write(+ directory,+ 'src/index.css',+ [+ ":where(.fixture-shell[data-mode='light']) {",+ ' color-scheme: light;',+ ' --background: #f4f6f9;',+ '}',+ '',+ 'html[data-theme="light"] { color-scheme: light; }',+ 'html[data-theme="dark"] { color-scheme: dark; }',+ '',+ ].join('\n'),+ );++ expect(darkModeFindings(directory)).toEqual([+ // The host's surviving light arm is untouched by this change, so only+ // the added line is scanned — and it no longer earns the exemption.+ 'src/index.css:6',+ ]);+ });++ it('does not exempt a mode arm quoted inside application code', () => {+ const directory = repository();+ addValidAstryxChange(directory);+ write(+ directory,+ 'src/inject.ts',+ [+ 'export const arms = [',+ ' \'html[data-theme="light"] { color-scheme: light; }\',',+ ' \'html[data-theme="dark"] { color-scheme: dark; }\',',+ '];',+ '',+ ].join('\n'),+ );++ expect(darkModeFindings(directory)).toEqual(['src/inject.ts:2']);+ });++ it.each([+ {+ name: 'a prefers-color-scheme pair',+ css: [+ '@media (prefers-color-scheme: light) {',+ ' :root { color-scheme: light; }',+ '}',+ '@media (prefers-color-scheme: dark) {',+ ' :root { color-scheme: dark; }',+ '}',+ '',+ ].join('\n'),+ exempt: [2, 5],+ },+ {+ name: 'arms at different scopes',+ css: 'html[data-theme="light"] { color-scheme: light; }\n.widget[data-theme="dark"] { color-scheme: dark; }\n',+ exempt: [],+ },+ {+ name: 'an arm under an ambiguous selector',+ css: 'html[data-theme="light"] .dark { color-scheme: light; }\nhtml[data-theme="dark"] .dark { color-scheme: dark; }\n',+ exempt: [],+ },+ {+ name: 'a theme-name attribute, which names no mode',+ css: '[data-astryx-theme="apptheme"] { color-scheme: light; }\n[data-astryx-theme="appdark"] { color-scheme: dark; }\n',+ exempt: [],+ },+ {+ name: 'a brace hidden in a string value',+ css: [+ 'html[data-theme="light"]::after { content: "}"; color-scheme: light; }',+ 'html[data-theme="dark"]::after { content: "}"; color-scheme: dark; }',+ '',+ ].join('\n'),+ exempt: [1, 2],+ },+ ])('reads $name correctly', ({css, exempt}) => {+ expect([...pairedModeArmSpans(css).keys()].sort((a, b) => a - b)).toEqual(+ exempt,+ );+ });+ });+it('does not treat prose or lockfile text as a CSS escape hatch', () => {const directory = repository();addValidAstryxChange(directory);@@ -711,3 +1071,102 @@ describe('setup integrity — reformatting versus replacement', () => {expect(kinds(result)).not.toContain('wholesale-replacement');});});++/**+ * `hardcoded-important` at the sandbox level.+ *+ * The unit-level behavior lives in `setup-important.test.mjs`; these cases+ * prove the analyzer is actually wired into the escape-hatch scan, on both+ * tracked and untracked files, and that nothing else about the scan moved.+ */+describe('setup integrity — hardcoded !important is syntactic', () => {+ const GUEST_CONTAINED_REGION = [+ "import {Theme, neutralTheme} from '@astryxdesign/core';",+ '',+ '/**',+ ' * Keep the design system inside this region.',+ ' *',+ ' * TRADEOFF: with the theme attribute removed, body-portaled content loses',+ ' * its tokens. Do not re-add a global attribute under another name, copy',+ ' * theme variables onto `body`, or paper over it with `!important`.',+ ' */',+ 'export function AstryxRegion({mode, children}) {',+ ' return (',+ ' <Theme theme={neutralTheme} mode={mode}>',+ ' {children}',+ ' </Theme>',+ ' );',+ '}',+ '',+ ].join('\n');++ it('does not fail a run for a comment that names the flag', () => {+ const directory = repository();+ addValidAstryxChange(directory);+ write(directory, 'src/AstryxRegion.tsx', GUEST_CONTAINED_REGION);+ const digest = attest(directory);++ const result = analyzeSetupIntegrity(directory, digest);++ expect(kinds(result)).not.toContain('hardcoded-important');+ expect(result.accepted).toBe(true);+ });++ it.each([+ {+ name: 'a CSS-in-JS template',+ file: 'src/sheet.ts',+ source: 'export const sheet = `.host { color: red !important; }`;\n',+ },+ {+ name: 'a generated stylesheet',+ file: 'src/theme.css',+ source: '.host { color: red !important; }\n',+ },+ ])('still fails a run for $name', ({file, source}) => {+ const directory = repository();+ addValidAstryxChange(directory);+ write(directory, file, source);++ const result = analyzeSetupIntegrity(directory, attest(directory));++ expect(kinds(result)).toContain('hardcoded-important');+ expect(result.accepted).toBe(false);+ });++ it('reports the override and not the comment that disclaims it', () => {+ const directory = repository();+ addValidAstryxChange(directory);+ write(+ directory,+ 'src/AstryxRegion.tsx',+ `${GUEST_CONTAINED_REGION}const patch = {color: 'red !important'};\n`,+ );++ const findings = analyzeSetupIntegrity(+ directory,+ attest(directory),+ ).escapeHatches.filter(finding => finding.kind === 'hardcoded-important');++ expect(findings).toHaveLength(1);+ expect(findings[0].path).toBe('src/AstryxRegion.tsx');+ expect(findings[0].line).toBe(GUEST_CONTAINED_REGION.split('\n').length);+ });++ it('judges a modified tracked file by its added lines only', () => {+ const directory = repository();+ write(directory, 'src/legacy.css', '.legacy { color: red !important; }\n');+ git(directory, ['add', 'src/legacy.css']);+ git(directory, ['commit', '-qm', 'pre-existing override']);+ addValidAstryxChange(directory);+ write(+ directory,+ 'src/legacy.css',+ '.legacy { color: red !important; }\n/* untouched by this change */\n',+ );++ expect(+ kinds(analyzeSetupIntegrity(directory, attest(directory))),+ ).not.toContain('hardcoded-important');+ });+});diff --git a/internal/vibe-tests/setup-test/setup-matrix.mjs b/internal/vibe-tests/setup-test/setup-matrix.mjsindex 37875bc199..d023cf9dda 100644--- a/internal/vibe-tests/setup-test/setup-matrix.mjs+++ b/internal/vibe-tests/setup-test/setup-matrix.mjs@@ -3,14 +3,27 @@import {createHash} from 'node:crypto';const SHA256 = /^[a-f0-9]{64}$/;+/**+ * The host-probe fields a task contract may ever exempt.+ *+ * A task that inserts a control into an existing container moves what follows+ * it and makes the container taller, so those consequences can be declared as+ * intended. Nothing else can: no computed style, no width, and no container+ * text. `text` is deliberately absent — a task that adds copy to a container+ * declares `textInsertionOnly`, which permits text the container *gains* and+ * still reports text it loses or rewrites, where a `text` field would exempt+ * the comparison outright and let an executor delete host copy.+ */const ALLOWABLE_HOST_FIELDS = new Set([- 'text','geometry.x','geometry.y','geometry.top','geometry.right','geometry.bottom','geometry.left',+ // Block-axis growth only: an insertion makes a container taller, never wider.+ 'height',+ 'geometry.height',]);const ALLOWABLE_OVERLAY_FIELDS = new Set(['geometry.x',@@ -177,6 +190,14 @@ export function validatePromptContracts(prompts, probeConfig, matrixConfig) {allowed.fields,`prompt ${prompt.id} ${allowed.fixture}:${allowed.probe} fields`,);+ if (+ 'textInsertionOnly' in allowed &&+ typeof allowed.textInsertionOnly !== 'boolean'+ ) {+ throw new Error(+ `prompt ${prompt.id} ${allowed.fixture}:${allowed.probe} textInsertionOnly must be a boolean`,+ );+ }assertUnique(allowed.fields,`prompt ${prompt.id} ${allowed.fixture}:${allowed.probe} fields`,diff --git a/internal/vibe-tests/setup-test/setup-matrix.test.mjs b/internal/vibe-tests/setup-test/setup-matrix.test.mjsindex d5c4b92746..5f55c0776b 100644--- a/internal/vibe-tests/setup-test/setup-matrix.test.mjs+++ b/internal/vibe-tests/setup-test/setup-matrix.test.mjs@@ -75,20 +75,53 @@ describe('setup execution matrix', () => {const allFields = prompts.flatMap(prompt =>prompt.contract.allowedHostChanges.flatMap(allowed => allowed.fields),);- expect(allFields.every(field => field.startsWith('geometry.'))).toBe(true);+ // Position offsets, plus block-axis growth where a task mandates inserting+ // something into a host container. Nothing else is exemptible.+ expect(+ allFields.every(+ field => field.startsWith('geometry.') || field === 'height',+ ),+ ).toBe(true);expect(allFields).not.toContain('geometry.width');+ expect(allFields).not.toContain('width');expect(allFields).not.toContain('color');+ // Container text is never exempted outright, only ever insertion-only.+ expect(allFields).not.toContain('text');- const invalid = structuredClone(prompts);- invalid- .find(prompt => prompt.id === 's1')- .contract.allowedHostChanges.push({- fixture: 'tailwind-v4-control',- probe: 'primary-action',- fields: ['color'],- });- expect(() => validatePromptContracts(invalid, probes, matrix)).toThrow(- /cannot allow protected host field color/,+ // One per protected class: a computed style, an inline-axis dimension,+ // and container text, which is only ever insertion-only.+ for (const field of ['color', 'width', 'text']) {+ const invalid = structuredClone(prompts);+ invalid+ .find(prompt => prompt.id === 's1')+ .contract.allowedHostChanges.push({+ fixture: 'tailwind-v4-control',+ probe: 'primary-action',+ fields: [field],+ });+ expect(() => validatePromptContracts(invalid, probes, matrix)).toThrow(+ new RegExp(`cannot allow protected host field ${field}`),+ );+ }+ });++ it('accepts the s5 insertion allowance and nothing broader', () => {+ const s5 = prompts.find(prompt => prompt.id === 's5');+ expect(s5.contract.allowedHostChanges).toEqual([+ expect.objectContaining({+ fixture: 'enterprise-scoped-synthetic',+ probe: 'host-shell',+ fields: ['height', 'geometry.height', 'geometry.bottom'],+ textInsertionOnly: true,+ }),+ ]);++ const badFlag = structuredClone(prompts);+ badFlag.find(+ prompt => prompt.id === 's5',+ ).contract.allowedHostChanges[0].textInsertionOnly = 'yes';+ expect(() => validatePromptContracts(badFlag, probes, matrix)).toThrow(+ /textInsertionOnly must be a boolean/,);});diff --git a/internal/vibe-tests/setup-test/setup-measure.mjs b/internal/vibe-tests/setup-test/setup-measure.mjsindex 4890b810ff..d876ff9c88 100644--- a/internal/vibe-tests/setup-test/setup-measure.mjs+++ b/internal/vibe-tests/setup-test/setup-measure.mjs@@ -469,6 +469,39 @@ export function readPage(spec) {inTopLayer,portalChild: topLayerElement.parentElement === document.body,},+ /**+ * The host token scopes this surface sits inside, nearest first.+ *+ * Recorded so that "the host's tokens no longer reach this element" is+ * reported as the structural fact it is, rather than only as a list of+ * colours that came out different. The two failures look identical in a+ * style diff and have opposite fixes: restate the colours and the next+ * host token change silently desynchronizes; restore the boundary and the+ * host's own rules resolve as they always did.+ */+ tokenScopes: (spec.hostTokenScopes ?? []).length+ ? (() => {+ const scopes = [];+ for (+ let node = element;+ node instanceof Element;+ node = node.parentElement+ ) {+ for (const selector of spec.hostTokenScopes) {+ let matches = false;+ try {+ matches = node.matches(selector);+ } catch {+ matches = false;+ }+ if (matches && !scopes.includes(selector)) {+ scopes.push(selector);+ }+ }+ }+ return scopes;+ })()+ : [],};};@@ -723,6 +756,7 @@ async function main() {const probeSpec = {properties: probeFile.properties,surfaceProperties,+ hostTokenScopes: fixtureProbes.hostTokenScopes ?? [],probes: fixtureProbes.probes,rootVariables: fixtureProbes.rootVariables,interaction: fixtureProbes.interaction ?? null,