@motion-proto/live-tokens 0.97.0 → 0.98.2

package/src/testing-js/{chunk-NB3NZRBM.js → chunk-7CM5D7PF.js}

@@ -9,6 +9,8 @@ var DEFAULT_COMPONENTS_PATH = "/live-tokens/components";
 var TESTING_CONFIG_FILE = "live-tokens.testing.ts";
 var COMPONENTS_PATH_ENV = "LIVE_TOKENS_COMPONENTS_PATH";
 var COMPONENT_ENV = "LIVE_TOKENS_COMPONENT";
+var A11Y_THEMES_ENV = "LIVE_TOKENS_A11Y_THEMES";
+var UPDATE_ARIA_ENV = "LIVE_TOKENS_UPDATE_ARIA";
 var PAGES_ENV = "LIVE_TOKENS_PAGES";
 var PAGE_VIEWPORTS_ENV = "LIVE_TOKENS_PAGE_VIEWPORTS";
 var DEFAULT_PAGE_VIEWPORTS = [
@@ -54,6 +56,8 @@ export {
   TESTING_CONFIG_FILE,
   COMPONENTS_PATH_ENV,
   COMPONENT_ENV,
+  A11Y_THEMES_ENV,
+  UPDATE_ARIA_ENV,
   PAGES_ENV,
   PAGE_VIEWPORTS_ENV,
   DEFAULT_PAGE_VIEWPORTS,
@@ -61,4 +65,4 @@ export {
   resolveTestingConfig,
   devServerCommand
 };
-//# sourceMappingURL=chunk-NB3NZRBM.js.map
+//# sourceMappingURL=chunk-7CM5D7PF.js.map

package/src/testing-js/chunk-7CM5D7PF.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../testing/config.ts","../editor/core/routing/ownedRoutes.ts"],"sourcesContent":["import fs from 'node:fs';\nimport path from 'node:path';\nimport { DEFAULT_COMPONENTS_PATH } from '../editor/core/routing/ownedRoutes';\n\n/** The file a project puts its shared test settings in, at the project root. */\nexport const TESTING_CONFIG_FILE = 'live-tokens.testing.ts';\n\n/** The components route the run drives, published from the settings so the\n *  suites need no argument. */\nexport const COMPONENTS_PATH_ENV = 'LIVE_TOKENS_COMPONENTS_PATH';\n\n/** Narrows a run to one component. */\nexport const COMPONENT_ENV = 'LIVE_TOKENS_COMPONENT';\n\n/** `all` repeats each component accessibility scan under the eight preset\n *  themes. The repository's own contract run sets it; a consumer run scans\n *  the active theme alone. */\nexport const A11Y_THEMES_ENV = 'LIVE_TOKENS_A11Y_THEMES';\n\n/** Rewrites each component's recorded accessibility tree. */\nexport const UPDATE_ARIA_ENV = 'LIVE_TOKENS_UPDATE_ARIA';\n\n/** The page targets a run opens, as JSON: `[{ source, route }]`. */\nexport const PAGES_ENV = 'LIVE_TOKENS_PAGES';\n\n/** The viewports every page rule runs at, as JSON: `[{ width, height }]`. */\nexport const PAGE_VIEWPORTS_ENV = 'LIVE_TOKENS_PAGE_VIEWPORTS';\n\nexport interface PageViewport {\n  width: number;\n  height: number;\n}\n\n/** The contract project's own desktop size, and the phone the text styles\n *  carry media overrides for. Nothing here is derived from a page. */\nexport const DEFAULT_PAGE_VIEWPORTS: PageViewport[] = [\n  { width: 1280, height: 900 },\n  { width: 390, height: 844 },\n];\n\n/** What `resolveDataDirs` falls back to, restated because that resolver is\n *  plugin-side and the tarball ships the plugin built rather than as source.\n *  `vite-plugin/testingConfig.test.ts` pins the two together. */\nconst DEFAULT_DATA_DIR = 'src/live-tokens/data';\n\nconst DEFAULT_DEV_COMMAND = 'npm run dev -- --host {host} --port {port}';\n\nexport interface LiveTokensTestingConfig {\n  /** Vite config a generated Vitest config merges. Default `vite.config.ts`. */\n  viteConfig?: string;\n  /** Command that starts the dev server. `{host}` and `{port}` are substituted.\n   *  Default `npm run dev -- --host {host} --port {port}`. */\n  devCommand?: string;\n  /** Fixed port for the dev server. Omitted, the run takes a free one. */\n  port?: number;\n  /** The components route, when `editorRoutes` moved it off the owned default. */\n  componentsPath?: string;\n  /** The plugin's data directory. Default: `dataDir` from\n   *  `live-tokens.config.json`, else `src/live-tokens/data`. The run never uses\n   *  it directly; it is the tree the isolated copy is made from. */\n  dataDir?: string;\n  /** Module that registers the project's components without mounting the app.\n   *  The registry contract imports it before it selects entries. */\n  registrySetup?: string;\n  /** Module exporting the `ComponentContract[]` a custom component adds to the\n   *  shipped list (default export or a named `contracts` export). The suite\n   *  files are static Playwright entry points, so an env var naming this path\n   *  plus a dynamic import inside `selectedContracts()` is the only way a\n   *  custom contract reaches them. */\n  contractsModule?: string;\n  /** Page source path to the concrete URL that renders it, for a route the\n   *  `pages` object cannot express: one served by `resolve()`, or one whose\n   *  parameters only the project knows. Page paths are relative to the\n   *  project root. */\n  pageRoutes?: Record<string, string>;\n  /** Replaces the two sizes every page rule runs at. */\n  pageViewports?: PageViewport[];\n}\n\nexport interface ResolvedTestingConfig {\n  root: string;\n  viteConfig: string;\n  devCommand: string;\n  port?: number;\n  componentsPath: string;\n  dataDir: string;\n  registrySetup?: string;\n  contractsModule?: string;\n  pageRoutes: Record<string, string>;\n  pageViewports: PageViewport[];\n}\n\n/** Types the settings file without importing the interface by hand. */\nexport function defineTestingConfig(config: LiveTokensTestingConfig): LiveTokensTestingConfig {\n  return config;\n}\n\n/** `dataDir` as the plugin resolves it, from the same file the plugin reads. */\nfunction configuredDataDir(root: string): string {\n  try {\n    const parsed = JSON.parse(fs.readFileSync(path.join(root, 'live-tokens.config.json'), 'utf-8'));\n    if (parsed && typeof parsed === 'object' && typeof parsed.dataDir === 'string') {\n      return path.resolve(root, parsed.dataDir);\n    }\n  } catch {\n    // Missing or unparseable reads as absent, matching `readLiveTokensConfig`.\n  }\n  return path.resolve(root, DEFAULT_DATA_DIR);\n}\n\nexport function resolveTestingConfig(\n  config: LiveTokensTestingConfig = {},\n  root: string = process.cwd(),\n): ResolvedTestingConfig {\n  const projectRoot = path.resolve(root);\n  return {\n    root: projectRoot,\n    viteConfig: path.resolve(projectRoot, config.viteConfig ?? 'vite.config.ts'),\n    devCommand: config.devCommand ?? DEFAULT_DEV_COMMAND,\n    port: config.port,\n    componentsPath: config.componentsPath ?? DEFAULT_COMPONENTS_PATH,\n    dataDir: config.dataDir ? path.resolve(projectRoot, config.dataDir) : configuredDataDir(projectRoot),\n    registrySetup: config.registrySetup\n      ? path.resolve(projectRoot, config.registrySetup)\n      : undefined,\n    contractsModule: config.contractsModule\n      ? path.resolve(projectRoot, config.contractsModule)\n      : undefined,\n    pageRoutes: config.pageRoutes ?? {},\n    pageViewports: config.pageViewports?.length ? config.pageViewports : DEFAULT_PAGE_VIEWPORTS,\n  };\n}\n\nexport function devServerCommand(command: string, host: string, port: number): string {\n  return command.replaceAll('{host}', host).replaceAll('{port}', String(port));\n}\n","// The package's dev-only editor surfaces live under a reserved `/live-tokens/*`\n// namespace so they can never collide with a consumer's own routes — the\n// consumer owns the rest of the URL space. Keeping the defaults in one place\n// is the guard against the nav rail and the dispatcher drifting onto different\n// paths (the collision/shadow class these constants exist to prevent).\n//\n// A consumer relocates or disables each surface via the `editorRoutes` prop on\n// <LiveTokensRouter>; these are only the defaults.\nexport const DEFAULT_EDITOR_PATH = '/live-tokens/editor';\nexport const DEFAULT_COMPONENTS_PATH = '/live-tokens/components';\nexport const DEFAULT_COLORS_PATH = '/live-tokens/colors';\nexport const DEFAULT_DOCS_PATH = '/live-tokens/docs';\n"],"mappings":";AAAA,OAAO,QAAQ;AACf,OAAO,UAAU;;;ACQV,IAAM,0BAA0B;;;ADJhC,IAAM,sBAAsB;AAI5B,IAAM,sBAAsB;AAG5B,IAAM,gBAAgB;AAKtB,IAAM,kBAAkB;AAGxB,IAAM,kBAAkB;AAGxB,IAAM,YAAY;AAGlB,IAAM,qBAAqB;AAS3B,IAAM,yBAAyC;AAAA,EACpD,EAAE,OAAO,MAAM,QAAQ,IAAI;AAAA,EAC3B,EAAE,OAAO,KAAK,QAAQ,IAAI;AAC5B;AAKA,IAAM,mBAAmB;AAEzB,IAAM,sBAAsB;AAgDrB,SAAS,oBAAoB,QAA0D;AAC5F,SAAO;AACT;AAGA,SAAS,kBAAkB,MAAsB;AAC/C,MAAI;AACF,UAAM,SAAS,KAAK,MAAM,GAAG,aAAa,KAAK,KAAK,MAAM,yBAAyB,GAAG,OAAO,CAAC;AAC9F,QAAI,UAAU,OAAO,WAAW,YAAY,OAAO,OAAO,YAAY,UAAU;AAC9E,aAAO,KAAK,QAAQ,MAAM,OAAO,OAAO;AAAA,IAC1C;AAAA,EACF,QAAQ;AAAA,EAER;AACA,SAAO,KAAK,QAAQ,MAAM,gBAAgB;AAC5C;AAEO,SAAS,qBACd,SAAkC,CAAC,GACnC,OAAe,QAAQ,IAAI,GACJ;AACvB,QAAM,cAAc,KAAK,QAAQ,IAAI;AACrC,SAAO;AAAA,IACL,MAAM;AAAA,IACN,YAAY,KAAK,QAAQ,aAAa,OAAO,cAAc,gBAAgB;AAAA,IAC3E,YAAY,OAAO,cAAc;AAAA,IACjC,MAAM,OAAO;AAAA,IACb,gBAAgB,OAAO,kBAAkB;AAAA,IACzC,SAAS,OAAO,UAAU,KAAK,QAAQ,aAAa,OAAO,OAAO,IAAI,kBAAkB,WAAW;AAAA,IACnG,eAAe,OAAO,gBAClB,KAAK,QAAQ,aAAa,OAAO,aAAa,IAC9C;AAAA,IACJ,iBAAiB,OAAO,kBACpB,KAAK,QAAQ,aAAa,OAAO,eAAe,IAChD;AAAA,IACJ,YAAY,OAAO,cAAc,CAAC;AAAA,IAClC,eAAe,OAAO,eAAe,SAAS,OAAO,gBAAgB;AAAA,EACvE;AACF;AAEO,SAAS,iBAAiB,SAAiB,MAAc,MAAsB;AACpF,SAAO,QAAQ,WAAW,UAAU,IAAI,EAAE,WAAW,UAAU,OAAO,IAAI,CAAC;AAC7E;","names":[]}

package/src/testing-js/chunk-EWSGE27V.js

@@ -0,0 +1,168 @@
+// src/testing/support/a11y.ts
+import { test } from "@playwright/test";
+var A11Y_ANNOTATION = "a11y";
+var AXE_TAGS = ["wcag2a", "wcag2aa", "wcag21aa", "wcag22aa"];
+var SCOPE_ATTR = "data-lt-a11y-scope";
+var EXCLUDE_ATTR = "data-lt-a11y-exclude";
+var HTML_LIMIT = 300;
+var EngineMissing = class extends Error {
+};
+async function importEngine(packageName, load) {
+  try {
+    return await load();
+  } catch (error) {
+    if (error.code === "ERR_MODULE_NOT_FOUND") throw new EngineMissing(`${packageName} is not installed`);
+    throw error;
+  }
+}
+var axeModules = null;
+async function importAxe() {
+  await importEngine("axe-core", () => import("axe-core"));
+  const { AxeBuilder } = await importEngine("@axe-core/playwright", () => import("@axe-core/playwright"));
+  return { AxeBuilder };
+}
+var loadAxe = () => axeModules ??= importAxe();
+var alfaModules = null;
+async function importAlfa() {
+  const { Audit, Outcome } = await importEngine("@siteimprove/alfa-act", () => import("@siteimprove/alfa-act"));
+  const { Rules } = await importEngine("@siteimprove/alfa-rules", () => import("@siteimprove/alfa-rules"));
+  const { Node } = await importEngine("@siteimprove/alfa-dom", () => import("@siteimprove/alfa-dom"));
+  const { Native: DomNative } = await importEngine("@siteimprove/alfa-dom", () => import("@siteimprove/alfa-dom/native"));
+  const { Device } = await importEngine("@siteimprove/alfa-device", () => import("@siteimprove/alfa-device"));
+  const { Native: DeviceNative } = await importEngine("@siteimprove/alfa-device", () => import("@siteimprove/alfa-device/native"));
+  const { Page: AlfaPage } = await importEngine("@siteimprove/alfa-web", () => import("@siteimprove/alfa-web"));
+  const http = await importEngine("@siteimprove/alfa-http", () => import("@siteimprove/alfa-http"));
+  const { URL } = await importEngine("@siteimprove/alfa-url", () => import("@siteimprove/alfa-url"));
+  return {
+    Audit,
+    Outcome,
+    R65: Rules.get("R65").getUnsafe(),
+    Node,
+    DomNative,
+    Device,
+    DeviceNative,
+    AlfaPage,
+    http,
+    URL
+  };
+}
+var loadAlfa = () => alfaModules ??= importAlfa();
+async function missingEngine(engines) {
+  try {
+    for (const name of engines) await (name === "axe" ? loadAxe() : loadAlfa());
+    return null;
+  } catch (error) {
+    if (error instanceof EngineMissing) return error.message;
+    throw error;
+  }
+}
+function axeResults(rule, results, withReasons) {
+  return results.flatMap(
+    (result) => result.nodes.map((node) => {
+      const reasons = withReasons ? [...new Set([...node.any, ...node.all, ...node.none].map((check) => check.message).filter(Boolean))] : [];
+      return {
+        rule,
+        engineRule: result.id,
+        impact: node.impact ?? result.impact ?? null,
+        target: node.target.map((part) => Array.isArray(part) ? part.join(" >>> ") : String(part)).join(" | "),
+        html: node.html.slice(0, HTML_LIMIT),
+        help: [result.help, ...reasons].join(". "),
+        helpUrl: result.helpUrl
+      };
+    })
+  );
+}
+async function scanAxe(page, scope, exclude, rule, only) {
+  const { AxeBuilder } = await loadAxe();
+  let builder = new AxeBuilder({ page }).include(scope);
+  builder = only ? builder.withRules(only) : builder.withTags(AXE_TAGS);
+  for (const selector of exclude) builder = builder.exclude(selector);
+  if (rule === "a11y-page") builder = builder.disableRules(["color-contrast"]);
+  const result = await builder.analyze();
+  return [
+    ...axeResults(rule, result.violations, false),
+    ...axeResults("a11y-review", result.incomplete, true)
+  ];
+}
+function pruneToScope(node) {
+  if (node.type === "element" && node.attributes?.some((a) => a.name === SCOPE_ATTR)) return true;
+  if (!node.children) return false;
+  if (node.type === "element" && node.name === "head") return true;
+  node.children = node.children.filter((child) => child.type === "type" || pruneToScope(child));
+  return node.type === "document" || node.children.some((child) => child.type === "element");
+}
+var FOCUS_HELP = {
+  failed: "Focusing the element changes nothing visible",
+  cantTell: "Focusing the element changes no style on it, its descendants, or its ancestors"
+};
+async function scanFocusVisible(page, scope, exclude) {
+  const alfa = await loadAlfa();
+  await page.evaluate(({ scope: scope2, exclude: exclude2, scopeAttr, excludeAttr }) => {
+    for (const element of document.querySelectorAll(scope2)) element.setAttribute(scopeAttr, "");
+    for (const selector of exclude2) {
+      for (const element of document.querySelectorAll(selector)) element.setAttribute(excludeAttr, "");
+    }
+  }, { scope, exclude, scopeAttr: SCOPE_ATTR, excludeAttr: EXCLUDE_ATTR });
+  let json;
+  try {
+    const handle = await page.evaluateHandle(() => document);
+    json = await handle.evaluate(alfa.DomNative.fromNode);
+    await handle.dispose();
+  } finally {
+    await page.evaluate((attrs) => {
+      for (const attr of attrs) for (const element of document.querySelectorAll(`[${attr}]`)) element.removeAttribute(attr);
+    }, [SCOPE_ATTR, EXCLUDE_ATTR]);
+  }
+  pruneToScope(json);
+  const fromWindow = alfa.DeviceNative.fromWindow;
+  const device = alfa.Device.from(await page.evaluate(fromWindow));
+  const url = alfa.URL.parse(page.url()).getUnsafe();
+  const { Request, Response, Headers, Header } = alfa.http;
+  const alfaPage = alfa.AlfaPage.of(
+    Request.of("GET", url),
+    Response.of(url, 200, Headers.of([Header.of("Content-Type", "text/html")])),
+    alfa.Node.from(json, device),
+    device
+  );
+  const results = [];
+  for (const outcome of await alfa.Audit.of(alfaPage, [alfa.R65]).evaluate()) {
+    const kind = alfa.Outcome.isFailed(outcome) ? "failed" : alfa.Outcome.isCantTell(outcome) ? "cantTell" : null;
+    if (!kind) continue;
+    const target = outcome.target;
+    if (!inScope(target)) continue;
+    results.push({
+      rule: "a11y-focus-visible",
+      engineRule: "SIA-R65",
+      impact: null,
+      target: elementLabel(target),
+      html: target.toString().replace(/\s+/g, " ").slice(0, HTML_LIMIT),
+      help: FOCUS_HELP[kind],
+      helpUrl: alfa.R65.uri
+    });
+  }
+  return results;
+}
+function inScope(target) {
+  for (const node of target.inclusiveAncestors()) {
+    if (typeof node.attribute !== "function") continue;
+    if (node.attribute(EXCLUDE_ATTR).isSome()) return false;
+    if (node.attribute(SCOPE_ATTR).isSome()) return true;
+  }
+  return false;
+}
+function elementLabel(target) {
+  const id = target.id.isSome() ? `#${target.id.get()}` : "";
+  return `${target.name}${id}${[...target.classes].map((name) => `.${name}`).join("")}`;
+}
+function recordA11y(results) {
+  if (results.length === 0) return;
+  test.info().annotations.push({ type: A11Y_ANNOTATION, description: JSON.stringify(results) });
+}
+
+export {
+  missingEngine,
+  scanAxe,
+  scanFocusVisible,
+  recordA11y
+};
+//# sourceMappingURL=chunk-EWSGE27V.js.map

package/src/testing-js/chunk-EWSGE27V.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../testing/support/a11y.ts"],"sourcesContent":["import { test, type Page } from '@playwright/test';\n\nexport type A11yRule =\n  | 'a11y-component'\n  | 'a11y-page'\n  | 'a11y-review'\n  | 'a11y-focus-visible'\n  | 'a11y-text-spacing'\n  | 'a11y-reduced-motion'\n  | 'a11y-keyboard';\n\n/** One element one engine flagged. `line` is the page file line, which only\n *  the page suite can resolve; a component finding anchors on its runtime.\n *  `view` names the variants, states, and themes the element failed in.\n *  `variables` names the component properties the result traced to. */\nexport interface A11yResult {\n  rule: A11yRule;\n  engineRule: string;\n  impact: string | null;\n  target: string;\n  html: string;\n  help: string;\n  helpUrl: string;\n  line?: number;\n  view?: string;\n  variables?: string[];\n}\n\nconst A11Y_ANNOTATION = 'a11y';\n\nexport type A11yEngine = 'axe' | 'alfa';\n\nconst AXE_TAGS = ['wcag2a', 'wcag2aa', 'wcag21aa', 'wcag22aa'];\nconst SCOPE_ATTR = 'data-lt-a11y-scope';\nconst EXCLUDE_ATTR = 'data-lt-a11y-exclude';\nconst HTML_LIMIT = 300;\n\nclass EngineMissing extends Error {}\n\nexport async function importEngine<T>(packageName: string, load: () => Promise<T>): Promise<T> {\n  try {\n    return await load();\n  } catch (error) {\n    if ((error as { code?: string }).code === 'ERR_MODULE_NOT_FOUND') throw new EngineMissing(`${packageName} is not installed`);\n    throw error;\n  }\n}\n\nlet axeModules: ReturnType<typeof importAxe> | null = null;\nasync function importAxe() {\n  await importEngine('axe-core', () => import('axe-core'));\n  const { AxeBuilder } = await importEngine('@axe-core/playwright', () => import('@axe-core/playwright'));\n  return { AxeBuilder };\n}\nconst loadAxe = () => (axeModules ??= importAxe());\n\nlet alfaModules: ReturnType<typeof importAlfa> | null = null;\nasync function importAlfa() {\n  const { Audit, Outcome } = await importEngine('@siteimprove/alfa-act', () => import('@siteimprove/alfa-act'));\n  const { Rules } = await importEngine('@siteimprove/alfa-rules', () => import('@siteimprove/alfa-rules'));\n  const { Node } = await importEngine('@siteimprove/alfa-dom', () => import('@siteimprove/alfa-dom'));\n  const { Native: DomNative } = await importEngine('@siteimprove/alfa-dom', () => import('@siteimprove/alfa-dom/native'));\n  const { Device } = await importEngine('@siteimprove/alfa-device', () => import('@siteimprove/alfa-device'));\n  const { Native: DeviceNative } = await importEngine('@siteimprove/alfa-device', () => import('@siteimprove/alfa-device/native'));\n  const { Page: AlfaPage } = await importEngine('@siteimprove/alfa-web', () => import('@siteimprove/alfa-web'));\n  const http = await importEngine('@siteimprove/alfa-http', () => import('@siteimprove/alfa-http'));\n  const { URL } = await importEngine('@siteimprove/alfa-url', () => import('@siteimprove/alfa-url'));\n  return {\n    Audit, Outcome, R65: Rules.get('R65').getUnsafe(), Node, DomNative, Device, DeviceNative, AlfaPage, http, URL,\n  };\n}\nconst loadAlfa = () => (alfaModules ??= importAlfa());\n\n/** The reason to annotate a test `inapplicable` with when one of `engines`\n *  cannot load, or null when all of them load. */\nexport async function missingEngine(engines: A11yEngine[]): Promise<string | null> {\n  try {\n    for (const name of engines) await (name === 'axe' ? loadAxe() : loadAlfa());\n    return null;\n  } catch (error) {\n    if (error instanceof EngineMissing) return error.message;\n    throw error;\n  }\n}\n\ninterface AxeNode {\n  target: unknown[];\n  html: string;\n  impact?: string | null;\n  any: { message: string }[];\n  all: { message: string }[];\n  none: { message: string }[];\n}\n\ninterface AxeRuleResult {\n  id: string;\n  impact?: string | null;\n  help: string;\n  helpUrl: string;\n  nodes: AxeNode[];\n}\n\nfunction axeResults(rule: A11yRule, results: AxeRuleResult[], withReasons: boolean): A11yResult[] {\n  return results.flatMap((result) =>\n    result.nodes.map((node) => {\n      const reasons = withReasons\n        ? [...new Set([...node.any, ...node.all, ...node.none].map((check) => check.message).filter(Boolean))]\n        : [];\n      return {\n        rule,\n        engineRule: result.id,\n        impact: node.impact ?? result.impact ?? null,\n        target: node.target.map((part) => (Array.isArray(part) ? part.join(' >>> ') : String(part))).join(' | '),\n        html: node.html.slice(0, HTML_LIMIT),\n        help: [result.help, ...reasons].join('. '),\n        helpUrl: result.helpUrl,\n      };\n    }),\n  );\n}\n\n/** axe over `scope` (a selector), minus `exclude`. Violations report under\n *  `rule`, and the results axe cannot decide under `a11y-review`. A page scan\n *  leaves contrast to `page-contrast` (decision 8). `only` narrows the scan\n *  from the WCAG tags to the axe rules it names. */\nexport async function scanAxe(\n  page: Page,\n  scope: string,\n  exclude: string[],\n  rule: 'a11y-component' | 'a11y-page',\n  only?: string[],\n): Promise<A11yResult[]> {\n  const { AxeBuilder } = await loadAxe();\n  let builder = new AxeBuilder({ page }).include(scope);\n  builder = only ? builder.withRules(only) : builder.withTags(AXE_TAGS);\n  for (const selector of exclude) builder = builder.exclude(selector);\n  if (rule === 'a11y-page') builder = builder.disableRules(['color-contrast']);\n  const result = await builder.analyze();\n  return [\n    ...axeResults(rule, result.violations as AxeRuleResult[], false),\n    ...axeResults('a11y-review', result.incomplete as AxeRuleResult[], true),\n  ];\n}\n\ninterface SerialNode {\n  type: string;\n  name?: string;\n  attributes?: { name: string }[];\n  children?: SerialNode[];\n}\n\n/** Keeps the head, every scope's ancestor chain, and each scope's subtree\n *  whole. The style sheets travel on the document node, so the cascade stays\n *  intact, and SIA-R65 skips the editor's own controls: 0.3 to 0.8 s a scan\n *  against 2.5 s for the whole document, with the same outcomes. */\nfunction pruneToScope(node: SerialNode): boolean {\n  if (node.type === 'element' && node.attributes?.some((a) => a.name === SCOPE_ATTR)) return true;\n  if (!node.children) return false;\n  if (node.type === 'element' && node.name === 'head') return true;\n  node.children = node.children.filter((child) => child.type === 'type' || pruneToScope(child));\n  return node.type === 'document' || node.children.some((child) => child.type === 'element');\n}\n\nconst FOCUS_HELP = {\n  failed: 'Focusing the element changes nothing visible',\n  cantTell: 'Focusing the element changes no style on it, its descendants, or its ancestors',\n};\n\n/** Alfa's SIA-R65 over `scope` (a selector), minus `exclude`. A cantTell\n *  outcome means Alfa found no focus style at all, so it reports beside a\n *  failure under `a11y-focus-visible`. */\nexport async function scanFocusVisible(page: Page, scope: string, exclude: string[]): Promise<A11yResult[]> {\n  const alfa = await loadAlfa();\n  await page.evaluate(({ scope, exclude, scopeAttr, excludeAttr }) => {\n    for (const element of document.querySelectorAll(scope)) element.setAttribute(scopeAttr, '');\n    for (const selector of exclude) {\n      for (const element of document.querySelectorAll(selector)) element.setAttribute(excludeAttr, '');\n    }\n  }, { scope, exclude, scopeAttr: SCOPE_ATTR, excludeAttr: EXCLUDE_ATTR });\n  let json: SerialNode;\n  try {\n    const handle = await page.evaluateHandle(() => document);\n    json = (await handle.evaluate(alfa.DomNative.fromNode as (node: Document) => Promise<unknown>)) as SerialNode;\n    await handle.dispose();\n  } finally {\n    await page.evaluate((attrs) => {\n      for (const attr of attrs) for (const element of document.querySelectorAll(`[${attr}]`)) element.removeAttribute(attr);\n    }, [SCOPE_ATTR, EXCLUDE_ATTR]);\n  }\n  pruneToScope(json);\n\n  const fromWindow = alfa.DeviceNative.fromWindow as () => ReturnType<typeof alfa.DeviceNative.fromWindow>;\n  const device = alfa.Device.from(await page.evaluate(fromWindow));\n  const url = alfa.URL.parse(page.url()).getUnsafe();\n  const { Request, Response, Headers, Header } = alfa.http;\n  const alfaPage = alfa.AlfaPage.of(\n    Request.of('GET', url),\n    Response.of(url, 200, Headers.of([Header.of('Content-Type', 'text/html')])),\n    alfa.Node.from(json as Parameters<typeof alfa.Node.from>[0], device) as Parameters<typeof alfa.AlfaPage.of>[2],\n    device,\n  );\n\n  const results: A11yResult[] = [];\n  for (const outcome of await alfa.Audit.of(alfaPage, [alfa.R65]).evaluate()) {\n    const kind = alfa.Outcome.isFailed(outcome) ? 'failed' : alfa.Outcome.isCantTell(outcome) ? 'cantTell' : null;\n    if (!kind) continue;\n    const target = outcome.target as unknown as AlfaElement;\n    if (!inScope(target)) continue;\n    results.push({\n      rule: 'a11y-focus-visible',\n      engineRule: 'SIA-R65',\n      impact: null,\n      target: elementLabel(target),\n      html: target.toString().replace(/\\s+/g, ' ').slice(0, HTML_LIMIT),\n      help: FOCUS_HELP[kind],\n      helpUrl: alfa.R65.uri,\n    });\n  }\n  return results;\n}\n\ninterface AlfaElement {\n  name: string;\n  classes: Iterable<string>;\n  id: { isSome(): boolean; get(): string };\n  attribute?: (name: string) => { isSome(): boolean };\n  inclusiveAncestors(): Iterable<AlfaElement>;\n  toString(): string;\n}\n\nfunction inScope(target: AlfaElement): boolean {\n  for (const node of target.inclusiveAncestors()) {\n    if (typeof node.attribute !== 'function') continue;\n    if (node.attribute(EXCLUDE_ATTR).isSome()) return false;\n    if (node.attribute(SCOPE_ATTR).isSome()) return true;\n  }\n  return false;\n}\n\nfunction elementLabel(target: AlfaElement): string {\n  const id = target.id.isSome() ? `#${target.id.get()}` : '';\n  return `${target.name}${id}${[...target.classes].map((name) => `.${name}`).join('')}`;\n}\n\n/** Records `results` on the running test as the annotation the runner turns\n *  into findings (decision 3). The test itself passes. */\nexport function recordA11y(results: A11yResult[]): void {\n  if (results.length === 0) return;\n  test.info().annotations.push({ type: A11Y_ANNOTATION, description: JSON.stringify(results) });\n}\n"],"mappings":"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","names":["scope","exclude"]}

package/src/testing-js/{chunk-GKO27NGN.js → chunk-R54I7YL6.js}

@@ -1,6 +1,6 @@
 import {
   CONTRACTS_MODULE_ENV
-} from "./chunk-SHBYZUPD.js";
+} from "./chunk-5HNZHIHG.js";
 
 // src/testing/vitest.ts
 import path from "path";
@@ -54,4 +54,4 @@ function createVitestConfig(viteConfig, options = {}) {
 export {
   createVitestConfig
 };
-//# sourceMappingURL=chunk-GKO27NGN.js.map
+//# sourceMappingURL=chunk-R54I7YL6.js.map

package/src/testing-js/{chunk-X6KHEVIG.js → chunk-RWH46IU5.js}

@@ -1,12 +1,15 @@
 import {
   openComponentsEditor
-} from "./chunk-WIZ6W7UT.js";
+} from "./chunk-3WCLMOM7.js";
+import {
+  recordA11y
+} from "./chunk-EWSGE27V.js";
 import {
   ContractViolation,
   isInapplicable,
   partLocator,
   requiresInteraction
-} from "./chunk-3UKGXCDL.js";
+} from "./chunk-YVVR3GJZ.js";
 
 // src/testing/support/contractHarness.ts
 import fs from "fs";
@@ -14,6 +17,8 @@ import path from "path";
 var STAGE_GROUP = ".variant-group";
 var STAGE_SCOPE = ".sketch-scope";
 var STAGE = `${STAGE_GROUP}:visible ${STAGE_SCOPE}`;
+var THEME_PICKER = '[role="dialog"][aria-label="Theme Picker"]';
+var KEYBOARD_PATTERNS_URL = "https://www.w3.org/WAI/ARIA/apg/patterns/";
 var SERVER_WRITE_TIMEOUT_MS = 3e4;
 var settle = (page) => page.evaluate(async () => {
   const frame = () => new Promise((resolve) => requestAnimationFrame(() => resolve()));
@@ -158,6 +163,19 @@ var ContractHarness = class _ContractHarness {
       this.fail("contract-listed", `rail lists "${entry.label}" under ${group}, contract declares ${this.contract.origin}`);
     }
   }
+  /** Every variable a property row of the component can set: its schema
+   *  tokens and its intrinsics. */
+  async propertyVariables() {
+    const names = await this.page.evaluate((id) => {
+      const entry = window.__liveTokensEditor?.getComponentRegistryEntries().find((e) => e.id === id);
+      if (!entry) throw new Error(`no registry entry for "${id}"`);
+      return [
+        ...entry.schema.map((token) => token.variable),
+        ...(entry.intrinsics ?? []).flatMap((spec) => spec.variants.map((variant) => spec.variable(variant)))
+      ];
+    }, this.contract.id);
+    return new Set(names);
+  }
   // ── 2. Property projection ───────────────────────────────────────────────
   /**
    * Drive one design token to a probe value and require the declared part's
@@ -372,7 +390,7 @@ ${missing.join("\n")}`);
   }
   async performAction(action) {
     if (action.kind === "press") {
-      await this.locator(action.part).focus().catch(() => void 0);
+      if (action.part) await this.locator(action.part).focus().catch(() => void 0);
       await this.page.keyboard.press(action.key);
       return;
     }
@@ -398,49 +416,68 @@ ${missing.join("\n")}`);
   }
   async runInteraction(testCase) {
     await this.selectView(testCase);
+    const gap = await this.interactionGap(testCase);
+    if (gap === null) return;
+    if (testCase.rule !== "a11y-keyboard") this.fail("contract-interaction", `${testCase.name}: ${gap}`);
+    const element = this.locator(testCase.expect.part);
+    const merged = { ...this.contract.view, ...testCase };
+    const view = [merged.variant, merged.state].filter(Boolean).join(" / ");
+    recordA11y([{
+      rule: "a11y-keyboard",
+      engineRule: testCase.name,
+      impact: null,
+      target: testCase.expect.part,
+      html: await element.count() ? await element.evaluate((node) => node.outerHTML.slice(0, 300)) : "",
+      help: gap,
+      helpUrl: KEYBOARD_PATTERNS_URL,
+      ...view ? { view } : {}
+    }]);
+  }
+  /** What the case observed against what it expects, or null when they agree. */
+  async interactionGap(testCase) {
     const outcome = testCase.expect;
     const tracksValue = outcome.kind === "valueMoves" || outcome.kind === "valueBecomes" || outcome.kind === "valueChanges" || outcome.kind === "valueHolds";
     const before = tracksValue ? await this.valueOf(outcome.part) : "";
+    if (outcome.kind === "activated") {
+      await this.locator(outcome.part).evaluate((node) => {
+        const marked = node;
+        marked.__contractActivated = false;
+        node.addEventListener("click", () => {
+          marked.__contractActivated = true;
+        }, { once: true });
+      });
+    }
     await this.performAction(testCase.action);
     await settle(this.page);
     if (outcome.kind === "attribute") {
       const actual = await this.locator(outcome.part).evaluate((node, name) => node.getAttribute(name), outcome.name);
-      if (actual !== outcome.value) {
-        this.fail("contract-interaction", `${testCase.name}: ${outcome.part}[${outcome.name}] is "${actual}", expected "${outcome.value}"`);
-      }
-      return;
+      return actual === outcome.value ? null : `${outcome.part}[${outcome.name}] is "${actual}", expected "${outcome.value}"`;
     }
     if (outcome.kind === "focused") {
       const focused = await this.isFocused(outcome.part);
-      if (focused !== outcome.value) {
-        this.fail("contract-interaction", `${testCase.name}: ${outcome.part} is ${focused ? "" : "not "}focused, expected ${outcome.value ? "" : "not "}focused`);
-      }
-      return;
+      return focused === outcome.value ? null : `${outcome.part} is ${focused ? "" : "not "}focused, expected ${outcome.value ? "" : "not "}focused`;
+    }
+    if (outcome.kind === "activated") {
+      const activated = await this.locator(outcome.part).evaluate((node) => node.__contractActivated === true);
+      return activated ? null : `${outcome.part} received no click, expected the key to activate it`;
+    }
+    if (outcome.kind === "present") {
+      const present = await this.locator(outcome.part).count() > 0;
+      return present === outcome.value ? null : `${outcome.part} is ${present ? "still" : "not"} in the document, expected it ${outcome.value ? "present" : "gone"}`;
     }
     const after = await this.valueOf(outcome.part);
     if (outcome.kind === "valueHolds") {
-      if (after !== before) {
-        this.fail("contract-interaction", `${testCase.name}: value moved from ${before} to ${after}`);
-      }
-      return;
+      return after === before ? null : `value moved from ${before} to ${after}`;
     }
     if (outcome.kind === "valueChanges") {
-      if (after === before) {
-        this.fail("contract-interaction", `${testCase.name}: value held at ${before}`);
-      }
-      return;
+      return after === before ? `value held at ${before}` : null;
     }
     if (outcome.kind === "valueBecomes") {
-      if (after !== outcome.value) {
-        this.fail("contract-interaction", `${testCase.name}: value is ${after}, expected ${outcome.value}`);
-      }
-      return;
+      return after === outcome.value ? null : `value is ${after}, expected ${outcome.value}`;
     }
     const moved = Number(after) - Number(before);
     const wanted = outcome.direction === "up" ? moved > 0 : moved < 0;
-    if (!wanted) {
-      this.fail("contract-interaction", `${testCase.name}: value went ${before} -> ${after}, expected to move ${outcome.direction}`);
-    }
+    return wanted ? null : `value went ${before} -> ${after}, expected to move ${outcome.direction}`;
   }
   // ── 5. Persistence and reset ─────────────────────────────────────────────
   /** Every alias and config value the component holds, for restoring the buffer. */
@@ -646,7 +683,7 @@ ${missing.join("\n")}`);
    *  follows lands after the repaint. */
   async previewTheme(slug, settleOn) {
     await this.page.locator(".theme-name-trigger").click();
-    await this.page.locator('[role="dialog"][aria-label="Theme Picker"]').waitFor();
+    await this.page.locator(THEME_PICKER).waitFor();
     const row = this.page.locator(`.load-item[data-file-name="theme:${slug}"] .load-name-btn`);
     if (await row.count() === 0) this.fail("contract-theme", `the Theme Picker has no theme "${slug}"`);
     await Promise.all([
@@ -660,12 +697,43 @@ ${missing.join("\n")}`);
     if (settleOn) await this.awaitRootChange(settleOn.variable, settleOn.from);
   }
   async cancelThemePreview(settleOn) {
-    const dialog = this.page.locator('[role="dialog"][aria-label="Theme Picker"]');
+    const dialog = this.page.locator(THEME_PICKER);
     await dialog.getByRole("button", { name: "Cancel", exact: true }).click();
     await dialog.waitFor({ state: "detached" });
     await settle(this.page);
     if (settleOn) await this.awaitRootChange(settleOn.variable, settleOn.from);
   }
+  /** A theme preview that leaves the stage in view, for a check that reads the
+   *  stage's own paint: the Theme Picker's backdrop covers it while the
+   *  preview lasts. Each click is dispatched on its element, because a
+   *  portaled overlay such as ImageLightbox's sits over the picker trigger. */
+  async previewThemeUncovered(slug) {
+    await this.page.locator(".theme-name-trigger").dispatchEvent("click");
+    await this.page.locator(THEME_PICKER).waitFor();
+    const row = this.page.locator(`.load-item[data-file-name="theme:${slug}"] .load-name-btn`);
+    if (await row.count() === 0) this.fail("contract-theme", `the Theme Picker has no theme "${slug}"`);
+    await Promise.all([
+      this.page.waitForResponse(
+        (response) => response.url().includes("/themes/") && response.ok(),
+        { timeout: SERVER_WRITE_TIMEOUT_MS }
+      ),
+      row.dispatchEvent("click")
+    ]);
+    await settle(this.page);
+    await this.showThemePicker(false);
+  }
+  async cancelUncoveredPreview() {
+    await this.showThemePicker(true);
+    const dialog = this.page.locator(THEME_PICKER);
+    await dialog.getByRole("button", { name: "Cancel", exact: true }).dispatchEvent("click");
+    await dialog.waitFor({ state: "detached" });
+    await settle(this.page);
+  }
+  async showThemePicker(shown) {
+    await this.page.locator(THEME_PICKER).evaluate((dialog, visible) => {
+      dialog.closest(".ui-dialog-backdrop").style.visibility = visible ? "" : "hidden";
+    }, shown);
+  }
   async rootValues(names) {
     return this.page.evaluate((variables) => {
       const style = getComputedStyle(document.documentElement);
@@ -804,4 +872,4 @@ function probeValueFor(css) {
 export {
   ContractHarness
 };
-//# sourceMappingURL=chunk-X6KHEVIG.js.map
+//# sourceMappingURL=chunk-RWH46IU5.js.map