@motion-proto/live-tokens 0.78.0 → 0.79.0

package/src/testing-js/index.d.ts

@@ -1,6 +1,6 @@
 import { PlaywrightTestProject, PlaywrightTestConfig } from '@playwright/test';
-import { L as LiveTokensTestingConfig } from './vitest-C-wNWcoA.js';
-export { C as COMPONENTS_PATH_ENV, a as COMPONENT_ENV, D as DEFAULT_PAGE_VIEWPORTS, P as PAGES_ENV, b as PAGE_VIEWPORTS_ENV, c as PageViewport, R as ResolvedTestingConfig, T as TESTING_CONFIG_FILE, V as VitestConfigOptions, d as createVitestConfig, e as defineTestingConfig, f as devServerCommand, r as resolveTestingConfig } from './vitest-C-wNWcoA.js';
+import { L as LiveTokensTestingConfig } from './vitest-BMLIbDs2.js';
+export { C as COMPONENTS_PATH_ENV, a as COMPONENT_ENV, D as DEFAULT_PAGE_VIEWPORTS, P as PAGES_ENV, b as PAGE_VIEWPORTS_ENV, c as PageViewport, R as ResolvedTestingConfig, T as TESTING_CONFIG_FILE, V as VitestConfigOptions, d as createVitestConfig, e as defineTestingConfig, f as devServerCommand, r as resolveTestingConfig } from './vitest-BMLIbDs2.js';
 import 'vite';
 import 'vitest/config';
 
@@ -60,7 +60,7 @@ declare const PORT_ENV = "LIVE_TOKENS_TEST_PORT";
  */
 declare function resolvePort(preferred?: number): number;
 
-type ContractRule = 'contract-listed' | 'contract-render' | 'contract-alias' | 'contract-persist' | 'contract-theme' | 'contract-preview' | 'contract-sketch' | 'contract-missing';
+type ContractRule = 'contract-listed' | 'contract-render' | 'contract-alias' | 'contract-persist' | 'contract-theme' | 'contract-states' | 'contract-interaction' | 'contract-behavior' | 'contract-sketch' | 'contract-missing';
 /**
  * A failed obligation, carrying the rule id the CLI reports it under. A defect
  * fixture names the rule it expects, and `check-component --tests` maps a
@@ -241,6 +241,44 @@ interface InteractionExpectation {
     role: string;
     cases: InteractionCase[];
 }
+/**
+ * One mounted case under happy-dom: props in, a DOM event, one assertion. It
+ * carries what a browser cannot reach, the callback a controlled component
+ * calls instead of moving its own state.
+ */
+interface BehaviorCase {
+    name: string;
+    /** Props the fixture mounts with. A snippet-valued prop is not
+     *  expressible; a component whose behavior needs one records that case
+     *  as inapplicable with the reason. */
+    props?: Record<string, unknown>;
+    action?: {
+        kind: 'click' | 'keydown' | 'input';
+        part: string;
+        key?: string;
+        value?: string;
+    };
+    expect: {
+        kind: 'callback';
+        prop: string;
+        args: unknown[];
+    } | {
+        kind: 'no-callback';
+        prop: string;
+    } | {
+        kind: 'attribute';
+        part: string;
+        name: string;
+        value: string | null;
+    } | {
+        kind: 'text';
+        part: string;
+        value: string;
+    };
+}
+interface BehaviorExpectation {
+    cases: BehaviorCase[];
+}
 interface SketchPartExpectation {
     part: string;
     /** The design token `--sketch-fill` must resolve to on this part. */
@@ -279,6 +317,8 @@ interface ComponentContract {
     persistence: PersistenceExpectation;
     theme: ThemeExpectation;
     interaction: InteractionExpectation | Inapplicable;
+    /** What the component does when it is driven, proven under happy-dom. */
+    behavior: BehaviorExpectation | Inapplicable;
     sketch: SketchExpectation | Inapplicable;
 }
 declare function requiresInteraction(role: string | null): boolean;
@@ -296,4 +336,4 @@ declare function allContracts(contracts?: ComponentContract[]): Promise<Componen
 /** The contracts a run covers, narrowed by `LIVE_TOKENS_COMPONENT`. */
 declare function selectedContracts(contracts?: ComponentContract[]): Promise<ComponentContract[]>;
 
-export { CONTRACTS_MODULE_ENV, type ComponentContract, type ContractRule, ContractViolation, type ControlStep, DATA_DIR_ENV, type Inapplicable, type InteractionAction, type InteractionCase, type InteractionExpectation, type InteractionOutcome, type IsolatedData, LiveTokensTestingConfig, PORT_ENV, type PaintMap, type PartDeclaration, type PartLocator, type PersistenceCase, type PersistenceExpectation, type PersistenceShape, type PlaywrightConfigOptions, type PropertyExpectation, type SetupStep, type SketchExpectation, type SketchPartExpectation, type StateExpectation, TEST_DATA_DIR_ENV, type ThemeExpectation, type View, allContracts, createPlaywrightConfig, isInapplicable, isolateDataDir, partLocator, requiresInteraction, resolvePort, selectedContracts, shippedContracts };
+export { type BehaviorCase, type BehaviorExpectation, CONTRACTS_MODULE_ENV, type ComponentContract, type ContractRule, ContractViolation, type ControlStep, DATA_DIR_ENV, type Inapplicable, type InteractionAction, type InteractionCase, type InteractionExpectation, type InteractionOutcome, type IsolatedData, LiveTokensTestingConfig, PORT_ENV, type PaintMap, type PartDeclaration, type PartLocator, type PersistenceCase, type PersistenceExpectation, type PersistenceShape, type PlaywrightConfigOptions, type PropertyExpectation, type SetupStep, type SketchExpectation, type SketchPartExpectation, type StateExpectation, TEST_DATA_DIR_ENV, type ThemeExpectation, type View, allContracts, createPlaywrightConfig, isInapplicable, isolateDataDir, partLocator, requiresInteraction, resolvePort, selectedContracts, shippedContracts };

package/src/testing-js/index.js

@@ -1,16 +1,12 @@
 import {
-  CONTRACTS_MODULE_ENV,
   ContractViolation,
-  allContracts,
   isInapplicable,
   partLocator,
-  requiresInteraction,
-  selectedContracts,
-  shippedContracts
-} from "./chunk-4JQX6WWL.js";
+  requiresInteraction
+} from "./chunk-3UKGXCDL.js";
 import {
   createVitestConfig
-} from "./chunk-FAFOAWYL.js";
+} from "./chunk-Q3YIAAG3.js";
 import {
   COMPONENTS_PATH_ENV,
   COMPONENT_ENV,
@@ -22,6 +18,12 @@ import {
   devServerCommand,
   resolveTestingConfig
 } from "./chunk-NB3NZRBM.js";
+import {
+  CONTRACTS_MODULE_ENV,
+  allContracts,
+  selectedContracts,
+  shippedContracts
+} from "./chunk-ZMZQZ33J.js";
 
 // src/testing/playwright.ts
 import path2 from "path";
@@ -164,6 +166,10 @@ async function createPlaywrightConfig(options = {}) {
         // `.ts` in this repo, `.js` once tsup compiles the shipped build into
         // `src/testing-js`; matching both here needs no build-time swap.
         testMatch: "**/component-*.contract.{ts,js}",
+        // The behavior suite shares the prefix and runs under Vitest. Left in,
+        // Playwright collects it, meets its Svelte imports and reports the
+        // whole project as collecting nothing.
+        testIgnore: "**/component-behavior.contract.{ts,js}",
         // `.tabs-preview` now caps its sticky band at 50vh, which is enough for
         // image, panel, card and sidenavigation to pass alone at 1280x720. A
         // full parallel run still fails panel's gradient radio there, so the

package/src/testing-js/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../testing/playwright.ts","../testing/isolation.ts","../testing/port.ts"],"sourcesContent":["import path from 'node:path';\nimport { fileURLToPath } from 'node:url';\nimport {\n  defineConfig,\n  devices,\n  type PlaywrightTestConfig,\n  type PlaywrightTestProject,\n} from '@playwright/test';\nimport {\n  COMPONENT_ENV,\n  COMPONENTS_PATH_ENV,\n  PAGE_VIEWPORTS_ENV,\n  devServerCommand,\n  resolveTestingConfig,\n  type LiveTokensTestingConfig,\n} from './config';\nimport { CONTRACTS_MODULE_ENV } from './contracts';\nimport { DATA_DIR_ENV, TEST_DATA_DIR_ENV, isolateDataDir } from './isolation';\nimport { resolvePort } from './port';\n\nconst HOST = '127.0.0.1';\n\n/** The shipped suites, wherever the package is installed. */\nconst CONTRACT_TEST_DIR = path.dirname(fileURLToPath(import.meta.url));\n\nexport interface PlaywrightConfigOptions extends LiveTokensTestingConfig {\n  /** Project root the settings resolve against. Default `process.cwd()`. */\n  root?: string;\n  /** Projects that run beside the contract project. */\n  extraProjects?: PlaywrightTestProject[];\n  /** Where projects that declare no `testDir` of their own look. */\n  testDir?: string;\n  /** Bounds the whole run. Default fifteen minutes, the same bound\n   *  `check-component --tests` and `check-page --tests` hold their spawned\n   *  child to (`LIVE_TOKENS_TESTS_TIMEOUT` in `bin/contractRunner.mjs`), so a\n   *  hung run stops here too, for a caller that invokes this factory\n   *  directly rather than through the CLI. */\n  globalTimeout?: number;\n}\n\n/** Mirrors `bin/contractRunner.mjs`'s own `DEFAULT_TESTS_TIMEOUT_MS`,\n *  duplicated because that file is plain JS and cannot import this module\n *  before `build:testing` compiles it (see `bin/engineLoadsLazily.test.ts`). */\nconst DEFAULT_GLOBAL_TIMEOUT_MS = 15 * 60_000;\n\n/**\n * The contract project, its dev server, and the data isolation the two share.\n *\n * Isolation runs here rather than in a global setup because the config is the\n * first thing every process in the run evaluates: the environment it leaves\n * behind reaches the workers and the dev server, and nothing in the run can\n * observe the state before it.\n */\nexport async function createPlaywrightConfig(\n  options: PlaywrightConfigOptions = {},\n): Promise<PlaywrightTestConfig> {\n  const settings = resolveTestingConfig(options, options.root);\n  const { dataDir } = isolateDataDir(settings.dataDir);\n  const port = resolvePort(settings.port);\n  const baseURL = `http://${HOST}:${port}`;\n\n  process.env[COMPONENTS_PATH_ENV] = settings.componentsPath;\n  process.env[PAGE_VIEWPORTS_ENV] = JSON.stringify(settings.pageViewports);\n  if (settings.contractsModule) process.env[CONTRACTS_MODULE_ENV] = settings.contractsModule;\n\n  return defineConfig({\n    testDir: options.testDir ?? CONTRACT_TEST_DIR,\n    // The component suites carry their serial and parallel intent per file:\n    // `component-editor.contract.ts` runs each component's save and reset\n    // cycles in order against one data tree. Turning this on would interleave\n    // them.\n    fullyParallel: false,\n    // One worker is the safe default: the specs share a dev server and a data\n    // directory. A run that can afford more passes a worker count on the\n    // command line.\n    workers: 1,\n    timeout: 30_000,\n    globalTimeout: options.globalTimeout ?? DEFAULT_GLOBAL_TIMEOUT_MS,\n    expect: { timeout: 5_000 },\n    // A shared-server suite times out under CI load in ways it never does\n    // locally, and without a retry budget one wobble aborts a tagged release.\n    retries: process.env.CI ? 2 : 0,\n    // Absolute and rooted at the consumer project, not the config file's own\n    // directory: `check-component --tests`'s generated config lives in a\n    // temporary directory that gets removed on completion, and a relative\n    // `outputDir` would put every trace and screenshot in there too.\n    outputDir: path.join(settings.root, 'test-results/playwright'),\n    reporter: process.env.CI ? [['line'], ['html', { open: 'never' }]] : 'list',\n    use: {\n      baseURL,\n      // Unset, both of these are unbounded: a locator that never resolves waits\n      // out the whole test timeout and reports nothing about where it stopped.\n      actionTimeout: 10_000,\n      navigationTimeout: 30_000,\n      trace: 'on-first-retry',\n      screenshot: 'only-on-failure',\n      // `retain-on-failure` still records every passing test and throws the\n      // file away, which costs ~28% CPU. Match the trace policy instead.\n      video: 'on-first-retry',\n    },\n    projects: [\n      ...(options.extraProjects ?? []),\n      {\n        name: 'contract',\n        testDir: CONTRACT_TEST_DIR,\n        // `.ts` in this repo, `.js` once tsup compiles the shipped build into\n        // `src/testing-js`; matching both here needs no build-time swap.\n        testMatch: '**/component-*.contract.{ts,js}',\n        // `.tabs-preview` now caps its sticky band at 50vh, which is enough for\n        // image, panel, card and sidenavigation to pass alone at 1280x720. A\n        // full parallel run still fails panel's gradient radio there, so the\n        // band can cover a control at some scroll positions. Until that is\n        // fixed the suite runs taller. See docs/contract-test-defects.md.\n        use: { ...devices['Desktop Chrome'], viewport: { width: 1280, height: 900 } },\n      },\n      {\n        name: 'page',\n        testDir: CONTRACT_TEST_DIR,\n        testMatch: '**/page-*.contract.{ts,js}',\n        // The suite sizes the window itself, once per viewport in\n        // `pageViewports`, so the sizes stay one list rather than a project\n        // per viewport whose name the reporter would have to decode.\n        use: { ...devices['Desktop Chrome'] },\n      },\n    ],\n    webServer: {\n      command: devServerCommand(settings.devCommand, HOST, port),\n      // Otherwise defaults to the config file's own directory. A generated\n      // config that lives outside the consumer root (`check-component\n      // --tests`'s temporary config) would run `npm run dev` from wherever\n      // that happens to be instead.\n      cwd: settings.root,\n      url: baseURL,\n      // A server this run did not start carries none of these variables, so it\n      // would write the project's own data tree.\n      reuseExistingServer: false,\n      timeout: 120_000,\n      env: {\n        ...process.env,\n        [TEST_DATA_DIR_ENV]: dataDir,\n        [DATA_DIR_ENV]: dataDir,\n      },\n    },\n  });\n}\n","import fs from 'node:fs';\nimport os from 'node:os';\nimport path from 'node:path';\n\n/**\n * The plugin reads this name ahead of its own options and\n * `live-tokens.config.json`, so setting it redirects every server-side write —\n * the data tree, `tokens.generated.css`, and `fonts.css` — into the copy.\n */\nexport const TEST_DATA_DIR_ENV = 'LIVE_TOKENS_TEST_DATA_DIR';\n\n/** What the suites and the harness read component configs from in the runner's\n *  own process. It names the same directory and is a separate variable because\n *  it answers a different question: where a reader looks, not where the server\n *  is confined. */\nexport const DATA_DIR_ENV = 'LIVE_TOKENS_DATA_DIR';\n\n/**\n * A developer's current session rather than the document under test. Each one\n * is gitignored or dev-written, so leaving it in the copy would make the run\n * pass or fail on whichever theme the maintainer has open.\n *\n *   _working.json     an unsaved buffer, which reads as a dirty document and\n *                     can raise a destructive confirmation dialog\n *   _active.json      the theme the editor has open. One carrying a sketchstyle\n *                     boots the suite with the sketch layer on, which paints\n *                     every fill onto a pseudo-element and leaves the real\n *                     background transparent\n *   _production.json  the theme baked into tokens.generated.css\n *\n * A missing pointer resolves to \"default\" at runtime, so removing them is the\n * whole reset.\n */\nconst SESSION_FILES = new Set(['_working.json', '_active.json', '_production.json']);\n\nexport interface IsolatedData {\n  dataDir: string;\n  /** True when this process made the copy and owns removing it. */\n  created: boolean;\n}\n\nlet removed = false;\n\nfunction registerCleanup(dataDir: string): void {\n  const remove = () => {\n    if (removed) return;\n    removed = true;\n    fs.rmSync(dataDir, { recursive: true, force: true });\n  };\n  process.once('exit', remove);\n  // Playwright owns the exit path on a signal: it stops the workers and kills\n  // the dev server's process group, then exits, which reaches `exit` above.\n  // These two only make sure the copy is gone before that teardown starts.\n  process.once('SIGINT', remove);\n  process.once('SIGTERM', remove);\n}\n\n/**\n * Copy `sourceDataDir` into a unique temporary directory and point both the\n * server and the runner at it. Idempotent across processes: Playwright loads\n * the config again in every worker, and each inherits the parent's environment,\n * so only the first call copies anything.\n */\nexport function isolateDataDir(sourceDataDir: string): IsolatedData {\n  const existing = process.env[TEST_DATA_DIR_ENV];\n  if (existing) {\n    const dataDir = path.resolve(existing);\n    if (!fs.existsSync(dataDir)) {\n      throw new Error(`${TEST_DATA_DIR_ENV} names ${dataDir}, which does not exist`);\n    }\n    process.env[DATA_DIR_ENV] = dataDir;\n    return { dataDir, created: false };\n  }\n\n  const source = path.resolve(sourceDataDir);\n  if (!fs.existsSync(source)) {\n    throw new Error(\n      `No data directory at ${source}. Set \\`dataDir\\` in live-tokens.testing.ts `\n      + 'when the project keeps its live-tokens data somewhere else.',\n    );\n  }\n\n  // realpath: macOS resolves os.tmpdir() through a symlink, and the plugin\n  // compares resolved paths when it decides whether a write is in scope.\n  const dataDir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'live-tokens-contract-')));\n  fs.cpSync(source, dataDir, { recursive: true });\n  for (const entry of fs.readdirSync(dataDir, { recursive: true }) as string[]) {\n    if (SESSION_FILES.has(path.basename(entry))) {\n      fs.rmSync(path.join(dataDir, entry), { force: true });\n    }\n  }\n\n  process.env[TEST_DATA_DIR_ENV] = dataDir;\n  process.env[DATA_DIR_ENV] = dataDir;\n  registerCleanup(dataDir);\n  return { dataDir, created: true };\n}\n","import { execFileSync } from 'node:child_process';\n\nexport const PORT_ENV = 'LIVE_TOKENS_TEST_PORT';\n\nconst PREFERRED_PORT = 4173;\n\n/** Bind the preferred port, fall back to whatever the OS hands out, print the\n *  answer. A Playwright config is evaluated synchronously, so the check runs in\n *  a child rather than on a listener callback. */\nconst PROBE = `\nconst net = require('net');\nconst listen = (port) => new Promise((resolve, reject) => {\n  const server = net.createServer();\n  server.once('error', reject);\n  server.listen(port, '127.0.0.1', () => {\n    const { port: bound } = server.address();\n    server.close(() => resolve(bound));\n  });\n});\n// process.stdout.write, not console.log: the parent's FORCE_COLOR makes\n// console.log wrap a number in ANSI escapes.\nlisten(Number(process.argv[1])).catch(() => listen(0)).then((port) => process.stdout.write(String(port)));\n`;\n\n/**\n * The port the dev server and `baseURL` share. Cached in the environment so\n * every Playwright worker, which loads the config again in its own process,\n * reads the port the main process settled on.\n */\nexport function resolvePort(preferred?: number): number {\n  const cached = process.env[PORT_ENV];\n  if (cached) return Number(cached);\n\n  const port = preferred\n    ?? Number(execFileSync(process.execPath, ['-e', PROBE, String(PREFERRED_PORT)], {\n      encoding: 'utf-8',\n    }).trim());\n  if (!Number.isInteger(port) || port <= 0) {\n    throw new Error(`Could not settle on a dev-server port (read ${port})`);\n  }\n  process.env[PORT_ENV] = String(port);\n  return port;\n}\n"],"mappings":"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","names":["path","dataDir","path"]}
+{"version":3,"sources":["../testing/playwright.ts","../testing/isolation.ts","../testing/port.ts"],"sourcesContent":["import path from 'node:path';\nimport { fileURLToPath } from 'node:url';\nimport {\n  defineConfig,\n  devices,\n  type PlaywrightTestConfig,\n  type PlaywrightTestProject,\n} from '@playwright/test';\nimport {\n  COMPONENT_ENV,\n  COMPONENTS_PATH_ENV,\n  PAGE_VIEWPORTS_ENV,\n  devServerCommand,\n  resolveTestingConfig,\n  type LiveTokensTestingConfig,\n} from './config';\nimport { CONTRACTS_MODULE_ENV } from './contracts';\nimport { DATA_DIR_ENV, TEST_DATA_DIR_ENV, isolateDataDir } from './isolation';\nimport { resolvePort } from './port';\n\nconst HOST = '127.0.0.1';\n\n/** The shipped suites, wherever the package is installed. */\nconst CONTRACT_TEST_DIR = path.dirname(fileURLToPath(import.meta.url));\n\nexport interface PlaywrightConfigOptions extends LiveTokensTestingConfig {\n  /** Project root the settings resolve against. Default `process.cwd()`. */\n  root?: string;\n  /** Projects that run beside the contract project. */\n  extraProjects?: PlaywrightTestProject[];\n  /** Where projects that declare no `testDir` of their own look. */\n  testDir?: string;\n  /** Bounds the whole run. Default fifteen minutes, the same bound\n   *  `check-component --tests` and `check-page --tests` hold their spawned\n   *  child to (`LIVE_TOKENS_TESTS_TIMEOUT` in `bin/contractRunner.mjs`), so a\n   *  hung run stops here too, for a caller that invokes this factory\n   *  directly rather than through the CLI. */\n  globalTimeout?: number;\n}\n\n/** Mirrors `bin/contractRunner.mjs`'s own `DEFAULT_TESTS_TIMEOUT_MS`,\n *  duplicated because that file is plain JS and cannot import this module\n *  before `build:testing` compiles it (see `bin/engineLoadsLazily.test.ts`). */\nconst DEFAULT_GLOBAL_TIMEOUT_MS = 15 * 60_000;\n\n/**\n * The contract project, its dev server, and the data isolation the two share.\n *\n * Isolation runs here rather than in a global setup because the config is the\n * first thing every process in the run evaluates: the environment it leaves\n * behind reaches the workers and the dev server, and nothing in the run can\n * observe the state before it.\n */\nexport async function createPlaywrightConfig(\n  options: PlaywrightConfigOptions = {},\n): Promise<PlaywrightTestConfig> {\n  const settings = resolveTestingConfig(options, options.root);\n  const { dataDir } = isolateDataDir(settings.dataDir);\n  const port = resolvePort(settings.port);\n  const baseURL = `http://${HOST}:${port}`;\n\n  process.env[COMPONENTS_PATH_ENV] = settings.componentsPath;\n  process.env[PAGE_VIEWPORTS_ENV] = JSON.stringify(settings.pageViewports);\n  if (settings.contractsModule) process.env[CONTRACTS_MODULE_ENV] = settings.contractsModule;\n\n  return defineConfig({\n    testDir: options.testDir ?? CONTRACT_TEST_DIR,\n    // The component suites carry their serial and parallel intent per file:\n    // `component-editor.contract.ts` runs each component's save and reset\n    // cycles in order against one data tree. Turning this on would interleave\n    // them.\n    fullyParallel: false,\n    // One worker is the safe default: the specs share a dev server and a data\n    // directory. A run that can afford more passes a worker count on the\n    // command line.\n    workers: 1,\n    timeout: 30_000,\n    globalTimeout: options.globalTimeout ?? DEFAULT_GLOBAL_TIMEOUT_MS,\n    expect: { timeout: 5_000 },\n    // A shared-server suite times out under CI load in ways it never does\n    // locally, and without a retry budget one wobble aborts a tagged release.\n    retries: process.env.CI ? 2 : 0,\n    // Absolute and rooted at the consumer project, not the config file's own\n    // directory: `check-component --tests`'s generated config lives in a\n    // temporary directory that gets removed on completion, and a relative\n    // `outputDir` would put every trace and screenshot in there too.\n    outputDir: path.join(settings.root, 'test-results/playwright'),\n    reporter: process.env.CI ? [['line'], ['html', { open: 'never' }]] : 'list',\n    use: {\n      baseURL,\n      // Unset, both of these are unbounded: a locator that never resolves waits\n      // out the whole test timeout and reports nothing about where it stopped.\n      actionTimeout: 10_000,\n      navigationTimeout: 30_000,\n      trace: 'on-first-retry',\n      screenshot: 'only-on-failure',\n      // `retain-on-failure` still records every passing test and throws the\n      // file away, which costs ~28% CPU. Match the trace policy instead.\n      video: 'on-first-retry',\n    },\n    projects: [\n      ...(options.extraProjects ?? []),\n      {\n        name: 'contract',\n        testDir: CONTRACT_TEST_DIR,\n        // `.ts` in this repo, `.js` once tsup compiles the shipped build into\n        // `src/testing-js`; matching both here needs no build-time swap.\n        testMatch: '**/component-*.contract.{ts,js}',\n        // The behavior suite shares the prefix and runs under Vitest. Left in,\n        // Playwright collects it, meets its Svelte imports and reports the\n        // whole project as collecting nothing.\n        testIgnore: '**/component-behavior.contract.{ts,js}',\n        // `.tabs-preview` now caps its sticky band at 50vh, which is enough for\n        // image, panel, card and sidenavigation to pass alone at 1280x720. A\n        // full parallel run still fails panel's gradient radio there, so the\n        // band can cover a control at some scroll positions. Until that is\n        // fixed the suite runs taller. See docs/contract-test-defects.md.\n        use: { ...devices['Desktop Chrome'], viewport: { width: 1280, height: 900 } },\n      },\n      {\n        name: 'page',\n        testDir: CONTRACT_TEST_DIR,\n        testMatch: '**/page-*.contract.{ts,js}',\n        // The suite sizes the window itself, once per viewport in\n        // `pageViewports`, so the sizes stay one list rather than a project\n        // per viewport whose name the reporter would have to decode.\n        use: { ...devices['Desktop Chrome'] },\n      },\n    ],\n    webServer: {\n      command: devServerCommand(settings.devCommand, HOST, port),\n      // Otherwise defaults to the config file's own directory. A generated\n      // config that lives outside the consumer root (`check-component\n      // --tests`'s temporary config) would run `npm run dev` from wherever\n      // that happens to be instead.\n      cwd: settings.root,\n      url: baseURL,\n      // A server this run did not start carries none of these variables, so it\n      // would write the project's own data tree.\n      reuseExistingServer: false,\n      timeout: 120_000,\n      env: {\n        ...process.env,\n        [TEST_DATA_DIR_ENV]: dataDir,\n        [DATA_DIR_ENV]: dataDir,\n      },\n    },\n  });\n}\n","import fs from 'node:fs';\nimport os from 'node:os';\nimport path from 'node:path';\n\n/**\n * The plugin reads this name ahead of its own options and\n * `live-tokens.config.json`, so setting it redirects every server-side write —\n * the data tree, `tokens.generated.css`, and `fonts.css` — into the copy.\n */\nexport const TEST_DATA_DIR_ENV = 'LIVE_TOKENS_TEST_DATA_DIR';\n\n/** What the suites and the harness read component configs from in the runner's\n *  own process. It names the same directory and is a separate variable because\n *  it answers a different question: where a reader looks, not where the server\n *  is confined. */\nexport const DATA_DIR_ENV = 'LIVE_TOKENS_DATA_DIR';\n\n/**\n * A developer's current session rather than the document under test. Each one\n * is gitignored or dev-written, so leaving it in the copy would make the run\n * pass or fail on whichever theme the maintainer has open.\n *\n *   _working.json     an unsaved buffer, which reads as a dirty document and\n *                     can raise a destructive confirmation dialog\n *   _active.json      the theme the editor has open. One carrying a sketchstyle\n *                     boots the suite with the sketch layer on, which paints\n *                     every fill onto a pseudo-element and leaves the real\n *                     background transparent\n *   _production.json  the theme baked into tokens.generated.css\n *\n * A missing pointer resolves to \"default\" at runtime, so removing them is the\n * whole reset.\n */\nconst SESSION_FILES = new Set(['_working.json', '_active.json', '_production.json']);\n\nexport interface IsolatedData {\n  dataDir: string;\n  /** True when this process made the copy and owns removing it. */\n  created: boolean;\n}\n\nlet removed = false;\n\nfunction registerCleanup(dataDir: string): void {\n  const remove = () => {\n    if (removed) return;\n    removed = true;\n    fs.rmSync(dataDir, { recursive: true, force: true });\n  };\n  process.once('exit', remove);\n  // Playwright owns the exit path on a signal: it stops the workers and kills\n  // the dev server's process group, then exits, which reaches `exit` above.\n  // These two only make sure the copy is gone before that teardown starts.\n  process.once('SIGINT', remove);\n  process.once('SIGTERM', remove);\n}\n\n/**\n * Copy `sourceDataDir` into a unique temporary directory and point both the\n * server and the runner at it. Idempotent across processes: Playwright loads\n * the config again in every worker, and each inherits the parent's environment,\n * so only the first call copies anything.\n */\nexport function isolateDataDir(sourceDataDir: string): IsolatedData {\n  const existing = process.env[TEST_DATA_DIR_ENV];\n  if (existing) {\n    const dataDir = path.resolve(existing);\n    if (!fs.existsSync(dataDir)) {\n      throw new Error(`${TEST_DATA_DIR_ENV} names ${dataDir}, which does not exist`);\n    }\n    process.env[DATA_DIR_ENV] = dataDir;\n    return { dataDir, created: false };\n  }\n\n  const source = path.resolve(sourceDataDir);\n  if (!fs.existsSync(source)) {\n    throw new Error(\n      `No data directory at ${source}. Set \\`dataDir\\` in live-tokens.testing.ts `\n      + 'when the project keeps its live-tokens data somewhere else.',\n    );\n  }\n\n  // realpath: macOS resolves os.tmpdir() through a symlink, and the plugin\n  // compares resolved paths when it decides whether a write is in scope.\n  const dataDir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'live-tokens-contract-')));\n  fs.cpSync(source, dataDir, { recursive: true });\n  for (const entry of fs.readdirSync(dataDir, { recursive: true }) as string[]) {\n    if (SESSION_FILES.has(path.basename(entry))) {\n      fs.rmSync(path.join(dataDir, entry), { force: true });\n    }\n  }\n\n  process.env[TEST_DATA_DIR_ENV] = dataDir;\n  process.env[DATA_DIR_ENV] = dataDir;\n  registerCleanup(dataDir);\n  return { dataDir, created: true };\n}\n","import { execFileSync } from 'node:child_process';\n\nexport const PORT_ENV = 'LIVE_TOKENS_TEST_PORT';\n\nconst PREFERRED_PORT = 4173;\n\n/** Bind the preferred port, fall back to whatever the OS hands out, print the\n *  answer. A Playwright config is evaluated synchronously, so the check runs in\n *  a child rather than on a listener callback. */\nconst PROBE = `\nconst net = require('net');\nconst listen = (port) => new Promise((resolve, reject) => {\n  const server = net.createServer();\n  server.once('error', reject);\n  server.listen(port, '127.0.0.1', () => {\n    const { port: bound } = server.address();\n    server.close(() => resolve(bound));\n  });\n});\n// process.stdout.write, not console.log: the parent's FORCE_COLOR makes\n// console.log wrap a number in ANSI escapes.\nlisten(Number(process.argv[1])).catch(() => listen(0)).then((port) => process.stdout.write(String(port)));\n`;\n\n/**\n * The port the dev server and `baseURL` share. Cached in the environment so\n * every Playwright worker, which loads the config again in its own process,\n * reads the port the main process settled on.\n */\nexport function resolvePort(preferred?: number): number {\n  const cached = process.env[PORT_ENV];\n  if (cached) return Number(cached);\n\n  const port = preferred\n    ?? Number(execFileSync(process.execPath, ['-e', PROBE, String(PREFERRED_PORT)], {\n      encoding: 'utf-8',\n    }).trim());\n  if (!Number.isInteger(port) || port <= 0) {\n    throw new Error(`Could not settle on a dev-server port (read ${port})`);\n  }\n  process.env[PORT_ENV] = String(port);\n  return port;\n}\n"],"mappings":"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","names":["path","dataDir","path"]}

package/src/testing-js/page-compliance.contract.js

@@ -1,12 +1,14 @@
 import {
-  allContracts,
   isInapplicable
-} from "./chunk-4JQX6WWL.js";
+} from "./chunk-3UKGXCDL.js";
 import {
   DEFAULT_PAGE_VIEWPORTS,
   PAGES_ENV,
   PAGE_VIEWPORTS_ENV
 } from "./chunk-NB3NZRBM.js";
+import {
+  allContracts
+} from "./chunk-ZMZQZ33J.js";
 
 // src/testing/page-compliance.contract.ts
 import { test } from "@playwright/test";
@@ -205,6 +207,8 @@ var TEXT_AXES = ["fontFamily", "fontSize", "fontWeight", "lineHeight", "letterSp
 var BLOCK_DISPLAYS = ["block", "flow-root", "list-item", "flex", "grid", "table-cell", "table-caption"];
 var GRID_TOLERANCE = 1;
 var GRID_VIEWPORT = 768;
+var SETTLE_QUIET_MS = 300;
+var SETTLE_BUDGET_MS = 5e3;
 var LARGE_TEXT_PX = 24;
 var LARGE_BOLD_PX = 18.66;
 var BOLD = 700;
@@ -242,18 +246,52 @@ var PageHarness = class _PageHarness {
     await page.waitForFunction((selectors) => {
       const container = document.querySelector(selectors.container);
       if (!container) return false;
-      const content = [...container.children].some((child) => !child.matches(selectors.chrome));
-      const themed = getComputedStyle(document.documentElement).getPropertyValue("--body-md-font-size").trim().length > 0;
-      return content && themed;
+      return [...container.children].some((child) => !child.matches(selectors.chrome));
     }, { container: PAGE_CONTAINER, chrome: CHROME });
     await page.waitForLoadState("networkidle");
-    await page.evaluate(async () => {
+    await _PageHarness.settle(page);
+    return new _PageHarness(page, target, viewport);
+  }
+  /**
+   * Every rule here measures geometry, and the geometry moves for as long as
+   * the theme's own values, the route's stylesheet, and the fonts are still
+   * arriving. A twelve-column grid inside 32px of padding reaches 384px at a
+   * 390px viewport with the theme's 32px `--columns-gutter`, and 120px with
+   * the 8px gutter `tokens.css` computes there on its own, so the same page
+   * reads as overflowing or not depending on what has landed. Waiting on a single custom property settles nothing:
+   * `--body-md-font-size`, the property this gate used to read, is one
+   * `tokens.css` sets itself, and a trace of the boot has it true 84ms before
+   * the page container exists at all. What a rule needs instead is a page that
+   * has stopped moving. The budget bounds a page that never does.
+   */
+  static async settle(page) {
+    await page.evaluate(async ({ quietMs, budgetMs }) => {
       await document.fonts.ready;
+      const root = document.documentElement;
+      const signature = () => [
+        root.scrollWidth,
+        root.scrollHeight,
+        root.clientWidth,
+        root.clientHeight,
+        root.style.length,
+        document.fonts.size,
+        document.fonts.status
+      ].join("|");
       const frame = () => new Promise((resolve) => requestAnimationFrame(() => resolve()));
-      await frame();
-      await frame();
-    });
-    return new _PageHarness(page, target, viewport);
+      const deadline = performance.now() + budgetMs;
+      let last = signature();
+      let quietSince = performance.now();
+      while (performance.now() < deadline) {
+        await frame();
+        const now = signature();
+        if (now !== last) {
+          last = now;
+          quietSince = performance.now();
+          continue;
+        }
+        if (performance.now() - quietSince >= quietMs) return;
+      }
+    }, { quietMs: SETTLE_QUIET_MS, budgetMs: SETTLE_BUDGET_MS });
   }
   fail(rule, line, message) {
     throw new PageViolation(rule, this.target.source, line, message);