Architecture

Reference Value
Subject and boundary Test layers, the commands that run them, the CI jobs that gate a pull request, the cross-platform generated-byte contract and how to diagnose a failure. Product acceptance is outside this repository.
Verified source package.json scripts, ci.yml, setup action, Gallery Playwright config, config/playwright, tests/repository at tag v0.40.0. Verified tag v0.40.0, commit 43bba26a73dd0f7aa01cb7c8f37d697734b367ad, checked 2026-11-10, including the merge-queue CI from #200, #201, #203, #204 and #205; ruleset 19092134 read on November 10, 2026. Earlier passes checked 2026-11-09 and November 7, 2026.
Support state Maintained verification configuration at v0.40.0. Gallery uses Kit 3 and the hook-only navigation lifecycle; the optional adapter is covered by package fake-router tests.

Test layers

Layer Location and runner Proves Does not prove
Repository tests/repository/tooling (release, API and token-cascade tools) and tests/repository/contracts (package manifests and exports, config presets, token artifact ownership, licence notices, workflow SHA pinning); Vitest with vitest.repository.config.ts Cross-package and tooling invariants Rendered behavior
Package unit packages/*/src/**/*.test.ts and __tests__; Vitest per package (@yesid/config has none and is covered by repository contracts) Neutral package behavior: parsing, generators, contrast, engines, components, state, actions Integration in an app
Gallery unit apps/gallery/tests, apps/gallery/src/**/*.test.ts Every public UI family and motion action has an example; UI initialization identity; motion token contract; Gallery gate policy Browser behavior
Gallery browser apps/gallery/tests/browser/*.spec.ts; Playwright on Chromium against a production preview Accessibility (axe), keyboard and tap targets, overflow, theme boot, frames, site header, code block, density, runtime Released tarballs, other browsers, product routes
Product Each product's own suites Consumer behavior, locale, accessibility, motion and deployment (outside this repository)

Remembered-section verification

The tag's unit contract tests, boot tests and Gallery browser cases cover preference scope, server readability, initial geometry, pending semantics and startup recovery. Review the scenarios at the exact test ref; these source files are not a fresh test-run receipt.

Product adoption checks cover first visit expanded/neutral Collapse all control/open TOC, stored collapse/expand across routes and visits, individual/jump non-writing behavior, threshold and independent-panel exclusions, malformed/blocked storage, another tab, disabled JavaScript, delayed hydration, app-resource failure and five-second stall recovery. Include responsive charts/media, nested fragments, Back and locale reading-position adapters. The pre-paint scanner limits in template, noscript, iframe, xmp, double-escaped script text and --!> comments require the actual mounted count and product layout checks. Source: remembered-sections.md.

Commands

Need Command
Everything CI's check job runs bun install --frozen-lockfile, bun run check, bun run test, bun run ci:tokens, bun run build
Types and API bun run check: api:check, root tool and repository-test TypeScript, then every workspace check (including svelte-check)
All unit tests bun run test: the test:changed selection tests (node --test), then the repository suite, then every workspace test through Turbo
One package bun run --cwd packages/<name> test and check
Repository suite only bun run test:repository
Generated bytes bun run ci:tokens
Browser suite bun run browser:install once, then bun run test:browser (builds the Gallery, then runs Playwright); bun run test:browser:list lists the matrix without building
Fast local loop bun run test:changed (#204): Vitest --changed against origin/main plus the impacted Playwright specs at one phone and one desktop project. A local accelerator, not a CI gate

Browser matrix

Project Selects Context
phone, tablet, desktop Untagged tests 390x844 touch, 768x1024 touch, 1440x900
reduced-motion Tests tagged @motion Phone, reduced motion
light, dark Tests tagged @theme Desktop, theme seeded through the theme localStorage key

The Gallery run pins Chromium, en-CA, UTC, reduced motion by default, one worker, no retries, blocked service workers and forbidOnly in CI; traces and screenshots are kept on failure. Specs that assert normal motion opt into no-preference explicitly. Assertions are behavioral; there are no pixel snapshots.

CI gate

flowchart LR
  PR["pull_request to main / merge_group / dispatch"] --> CL["classify"]
  CL --> CK["check (ubuntu)"]
  CL --> BS["browser-shards x3 (Playwright container)"]
  BS --> BA["browser-authority"]
  CL --> TW["token-outputs-windows"]
  CK --> TP["token-byte-parity"]
  TW --> TP
  CK --> CI["ci (required)"]
  BA --> CI
  TW --> CI
  TP --> CI
Job Steps
classify Runs tools/ci-policy.ts taken from the PR's base SHA, or the merge queue's base SHA; a later queue entry whose base is not yet on main uses main's trusted policy instead of failing. Selects the browser lane unless the PR changes only the root README.md, CONTRIBUTING.md or DECISIONS.md, and marks release-only PRs by exact title and a byte-for-byte reproduction.
check Always runs. Setup with Turbo and Vitest caches; api:approve --base <PR base SHA>; check; test; ci:tokens; upload the four Ubuntu token outputs; turbo run build; on release-only PRs, release:check and packing all eight packages.
browser-shards Three shards (#203), one worker each (two workers broke the sheet drag test), in the Playwright v1.61.1 container pinned by digest, with Bun bootstrapped without APT (#201); test:browser --shard=N/3; uploads a timing file on every run that is not cancelled, and the Playwright report and test results on failure, each kept 7 days. Skipped for docs-only and release-only PRs.
browser-authority Wrapper that requires all three browser shards to succeed. Skipped with them.
token-outputs-windows Cached Windows setup (#203); api:check on Windows, tokens:build, upload the four Windows outputs. Skipped on release-only PRs.
token-byte-parity Byte comparison (cmp) of DESIGN.md, theme.css, motion tokens.ts and tokens.css from both runners; prints both SHA-256 values on mismatch. Skipped on release-only PRs.
ci Runs policy from the PR's base SHA. Fails when a needed job failed or was cancelled, or was skipped outside the lane classify selected.

The setup action installs Bun from .bun-version and runs bun install --frozen-lockfile with a Bun cache keyed on the OS, .bun-version and bun.lock. Secret scanning and CodeQL run separately (see Security, configuration and supply chain).

Ruleset 19092134 "Protect main" (read 2026-11-10) requires ci and gitleaks (strict up-to-date off) and CodeQL code scanning results, and merges through a merge queue (#200): squash, ALLGREEN, up to 5 entries per group, no wait, 30-minute check timeout, admin bypass always. Org ruleset 26919834 also protects the default branch. Measured 2026-11-10 on #203 (run 42766147239, 3 attempts): execution on the deciding path median 376 to 238 s, slowest browser job 358 to 221 s, Windows job 111.5 to 75 s. Wall time under the throttled runner queue was not proven (attempts took 248 to 2,313 s).

Diagnose a failure

Symptom Investigation and recovery
api:check drift Run bun run api:report and read the diff. Intended: commit the reports with a fragment. Unintended: fix the export or type.
api:approve fails A package's report changed without a new .changes fragment naming it. Add one.
API extraction cannot resolve a config Check the package tsconfig.json and its extends target and that the frozen install contains @yesid/config. The tooling reports the invalid config before emitting declarations.
Token drift or parity mismatch Edit tokens.json or the generator, run bun run tokens:build, inspect every changed output. A parity-only failure points at line endings or platform-dependent generator code.
Frozen install fails First check the pinned Bun version and the manifest/lockfile diff. If Linux CI requires a lockfile change, regenerate with that same Bun on Linux, inspect the diff and rerun. A failure alone is not proof that every lockfile must be generated on Linux.
Browser test fails Download the failure artifact; rerun the spec with its project, theme and motion setting locally.
Gate scan finds zero files Wrong root or extensions; an empty scan is not compliance.
Packages pass but a product regresses Inspect the product's release URLs, lockfile and integration config, then run the product's affected checks.