ci.yml

# Copyright (c) Meta Platforms, Inc. and affiliates.

# PR CI: test, build, analyze, a11y audit, and comment
# Everything runs in parallel where possible
#
# Merge queue: test + build also run on merge_group events so the
# merge queue can gate on them before landing a PR.
name: CI
# Main's nightly full interaction run and the weekly full WebKit run name
# their commit, so the main heavy lanes tell them from a release-check. A
# cut-evidence release-check names its commit too, so people reading Actions
# tell it from a monitoring release-check. Every other run keeps its default
# name.
run-name: "${{ github.event_name == 'workflow_dispatch' && inputs.operation == 'interaction-full' && format('Interaction proofs of {0}', github.sha) || github.event_name == 'workflow_dispatch' && inputs.operation == 'webkit-weekly' && format('WebKit weekly of {0}', github.sha) || github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check' && inputs.evidence && format('Release evidence of {0}', github.sha) || '' }}"

on:
  pull_request:
    # A draft runs nothing until it is ready; an outside contributor's pull
    # request runs once a maintainer labels it ci:run and pushes or reopens
    # (spec:AST-030 FR17).
    types: [opened, synchronize, reopened, ready_for_review]
    branches: ['main', 'release/**']
  merge_group:
  # Explicit release checks and baseline capture share the canonical owners.
  # Reviewed captures are committed through a normal pull request.
  workflow_dispatch:
    inputs:
      operation:
        description: 'Run the canonical check on exact main or a marked release branch, capture a main baseline candidate, run every Chromium interaction proof on main, or run the full WebKit interaction suite on main (webkit-weekly)'
        type: choice
        options: [capture, release-check, interaction-full, webkit-weekly]
        default: capture
        required: true
      release-branch:
        description: 'Exact branch to check: main before a cut, or marked release/vX.Y.Z after the bump'
        type: string
        required: false
      release-version:
        description: 'Exact X.Y.Z version recorded by the active marker; required only for a marked release branch'
        type: string
        required: false
      expected-head:
        description: 'Exact full main or release branch SHA; required for release-check'
        type: string
        required: false
      plan-digest:
        description: 'Exact SHA-256 digest recorded by the active marker; required only for a marked release branch'
        type: string
        required: false
      recheck:
        description: 'Release re-check, sent by the release re-check workflow: takes the main check lane at once'
        type: boolean
        default: false
      evidence:
        description: 'Cut evidence, sent by the pre-cut release-check and the release re-check: the run is named Release evidence of <sha>'
        type: boolean
        default: false

permissions: {}

# PR CI's budget is 15 minutes. Every job in this workflow that does work on a
# pull request carries `timeout-minutes: 15` (release and maintenance
# dispatches keep longer limits; macOS-only `test-native-swift` keeps 30). Split
# a job that nears the limit (shard, scope, cache); do not raise it.
#
# There is no scope job. Each job that owns tests decides its own scope in its
# first steps (.github/actions/test-scope: the PR's file list against the
# base's trusted classifier) and skips its work, reporting success, when
# nothing in its scope changed; anything undecidable runs everything.
#
# Visual, accessibility and RTL owners (pr-a11y*, visual-scout, pr-visual,
# pr-rtl*) do not run on pull request updates (a shared primitive's dependent
# audits are the one exception, below): they run for release-check,
# which the Main heavy lanes workflow (main-heavy-lanes.yml) dispatches for
# main's tip every three hours and before each weekday cut, and the release
# gate dispatches before a cut. A pull request
# opts into one suite with its label, `ci:run-visual`, `ci:run-a11y` or
# `ci:run-rtl`, applied by someone with write access (add the label, then push
# or close and reopen); run-labels decides. A main failure is fixed forward
# (spec:AST-030 FR12, FR17, DEC-7).
#
# Runners: every job uses GitHub's standard hosted runners, except the release
# path's long jobs, which take a paid larger-runner pool so pull request load
# cannot starve them: release-bump, release-merge-back on a merge-back branch
# (chore/merge-v*), and the build and audit jobs of a release-check a person or
# the release tooling dispatches (one dispatched by github-actions[bot] stays
# on standard runners, a cut-evidence run included). The release-check's short gating and join jobs
# (release-authority, pr-a11y, a11y-contracts, pr-rtl, release-check) stay on ubuntu-slim. Arm jobs stay arm and x64 stay x64 on
# both pools, so visual baselines and native builds see the same architecture.
#
# One group per pull request (a fork's branch name can repeat across forks),
# so a new push cancels the superseded run. Merge-queue entries and dispatches
# get their own groups and are never cancelled by a pull request. Main's
# nightly full interaction run has a group of its own, so it never replaces a
# waiting release-check. The
# release-checks main-heavy-lanes.yml and the release re-check dispatch (as
# github-actions[bot]) share one group: one runs and the newest waits. The
# weekly full WebKit run (webkit-weekly.yml) has a group of its own, so a
# release-check never replaces it while it waits. Only a
# release re-check cancels the running check; it checks main's tip in full, so
# the cancelled check's commits stay covered (spec:AST-030 FR23).
#
# A release-check runs its browser owners in wide shards that all start at
# once, so a full check takes minutes; pull requests keep their narrower legs
# (spec:AST-030 FR23, DEC-17).
# A pull request's newer push cancels its older run. A re-run takes a group of
# its own, so re-running an older head never cancels the run for the pull
# request's current head.
concurrency:
  group: "ci-${{ github.event.pull_request.number && (github.run_attempt == '1' && github.event.pull_request.number || format('{0}-rerun-{1}', github.event.pull_request.number, github.run_id)) || github.event.merge_group.head_sha || (github.event_name == 'workflow_dispatch' && inputs.operation == 'interaction-full' && 'interaction-full') || (github.event_name == 'workflow_dispatch' && inputs.operation == 'webkit-weekly' && github.ref == 'refs/heads/main' && 'webkit-weekly') || (github.event_name == 'workflow_dispatch' && github.triggering_actor == 'github-actions[bot]' && 'main-heavy-lanes') || github.run_id }}"
  cancel-in-progress: ${{ github.event_name != 'workflow_dispatch' || (inputs.recheck && github.triggering_actor == 'github-actions[bot]') }}

jobs:
  # Admit the whole run under CI's ceiling of about ninety concurrent jobs
  # (spec:AST-030 FR16, DEC-16), in two jobs (slim on a pull request, standard
  # on a dispatch): `room` waits until the
  # Storybook build has room and starts it, and `admission` waits for the rest
  # of the run unless it already fit. Every job here but build-storybook and
  # ci-full needs admission, directly or through the jobs it needs, so a
  # waiting run holds only its one waiting job and a build that found room.
  # Like every other job both skip for a draft or an unlabelled fork, which run
  # no CI (FR17); the required contexts still report through their own status
  # rules. Neither fails, so each job's own condition decides exactly as before,
  # except for a pull-request run CI is full for, which ci-full stops. `peak` is
  # the most jobs a run holds at once: a release-check's from its legs, a pull
  # request's from its measured most plus the suites its labels opt into
  # (ci-admission.test.mjs). A pull request waits at most twelve minutes in all,
  # inside the fifteen-minute job budget.
  room:
    # Finds room for the run's first job, its Storybook build, and records
    # whether the whole run fit on that look. A pull-request run that finds no
    # room waits, up to its longest wait.
    if: (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run')))
    # A dispatch (a main or release check) may wait longer than a slim job's
    # fifteen-minute cap, so it waits on a standard runner (spec:AST-030 DEC-16).
    runs-on: ${{ github.event_name == 'workflow_dispatch' && 'ubuntu-latest' || 'ubuntu-slim' }}
    timeout-minutes: ${{ github.event_name == 'workflow_dispatch' && 130 || 15 }}
    permissions:
      actions: read
      contents: read
    outputs:
      fits: ${{ steps.room.outputs.fits }}
      full: ${{ steps.room.outputs.full }}
      started: ${{ steps.room.outputs.started }}
      looks: ${{ steps.room.outputs.looks }}
      next: ${{ steps.room.outputs.next }}
      attempt: ${{ github.run_attempt }}
    steps:
      - name: Check out the admission action
        uses: actions/checkout@v7
        with:
          sparse-checkout: .github/actions/ci-admission
          path: .ci-admission
          persist-credentials: false

      - name: Wait for room under the CI ceiling
        id: room
        uses: ./.ci-admission/.github/actions/ci-admission
        continue-on-error: true
        timeout-minutes: ${{ github.event_name == 'workflow_dispatch' && 125 || 13 }}
        with:
          phase: room
          peak: ${{ github.event_name == 'workflow_dispatch' && 39 || 17 }}
          main: ${{ github.event_name == 'workflow_dispatch' }}
          max-wait-minutes: ${{ github.event_name == 'workflow_dispatch' && 120 || 12 }}
          max-looks: ${{ github.event_name == 'workflow_dispatch' && 30 || 2 }}
          label-legs: '{"ci:run-visual": 6, "ci:run-rtl": 9, "ci:run-a11y": 5}'

      # A run stopped for no room fails here, so a re-run of its failed jobs
      # waits again from this job, not from this look's result.
      - name: Stop when CI is full
        if: steps.room.outputs.full == 'true'
        run: |
          echo "::error title=CI is full::CI is full: re-run all jobs or push later. The run found no room under the CI ceiling."
          exit 1

  admission:
    needs: [room]
    if: (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run')))
    # A dispatch (a main or release check) may wait longer than a slim job's
    # fifteen-minute cap, so it waits on a standard runner (spec:AST-030 DEC-16).
    runs-on: ${{ github.event_name == 'workflow_dispatch' && 'ubuntu-latest' || 'ubuntu-slim' }}
    timeout-minutes: ${{ github.event_name == 'workflow_dispatch' && 130 || 15 }}
    permissions:
      actions: read
      contents: read
    outputs:
      full: ${{ steps.rest.outputs.full }}
    steps:
      - name: Stop when CI is full
        if: needs.room.outputs.full == 'true'
        run: |
          echo "::error title=CI is full::CI is full: re-run all jobs or push later. The run found no room under the CI ceiling."
          exit 1

      - name: Check out the admission action
        uses: actions/checkout@v7
        with:
          sparse-checkout: .github/actions/ci-admission
          path: .ci-admission
          persist-credentials: false

      - name: Wait for room under the CI ceiling
        id: rest
        uses: ./.ci-admission/.github/actions/ci-admission
        continue-on-error: true
        timeout-minutes: ${{ github.event_name == 'workflow_dispatch' && 125 || 13 }}
        # A re-run of this job alone reuses an earlier attempt's room
        # outputs, whose clock has run out, so it waits for the whole run on
        # its own clock.
        with:
          phase: ${{ needs.room.outputs.attempt == github.run_attempt && 'rest' || 'whole' }}
          fits: ${{ needs.room.outputs.fits }}
          started: ${{ needs.room.outputs.started }}
          looks: ${{ needs.room.outputs.looks }}
          next: ${{ needs.room.outputs.next }}
          peak: ${{ github.event_name == 'workflow_dispatch' && 39 || 17 }}
          main: ${{ github.event_name == 'workflow_dispatch' }}
          max-wait-minutes: ${{ github.event_name == 'workflow_dispatch' && 120 || 12 }}
          max-looks: ${{ github.event_name == 'workflow_dispatch' && 30 || 2 }}
          label-legs: '{"ci:run-visual": 6, "ci:run-rtl": 9, "ci:run-a11y": 5}'

      # A pull-request run that waited its longest while another started at
      # its longest wait is turned away (spec:AST-030 DEC-16): ci-full stops
      # the run, and the jobs behind admission skip.
      - name: Stop when CI is full at the longest wait
        if: steps.rest.outputs.full == 'true'
        run: |
          echo "::error title=CI is full::CI is full: re-run all jobs or push later. The run found no room under the CI ceiling."
          exit 1

  # Stops a pull-request run that CI is full for, with the reason, so it builds
  # nothing: the run waited its longest while another started at its longest
  # wait, or a run that waited longer still waits. It cancels the run when its
  # token can. A fork's read-only token cannot; then
  # admission fails, the jobs behind it skip or stop, and build, test and
  # docsite-test fail with the same reason, never skip or pass.
  ci-full:
    needs: [room, admission]
    if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (github.event_name == 'pull_request' && !cancelled() && (needs.room.outputs.full == 'true' || needs.admission.outputs.full == 'true')) }}
    runs-on: ubuntu-slim
    timeout-minutes: 5
    permissions:
      # actions: write lets the run cancel itself.
      actions: write
    steps:
      - name: Stop, CI is full
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          echo "::error title=CI is full::CI is full: re-run all jobs or push later. The run found no room under the CI ceiling."
          gh run cancel "$GITHUB_RUN_ID" --repo "$GITHUB_REPOSITORY" || true
          exit 1

  maintenance-request:
    needs: [admission]
    if: github.event_name == 'workflow_dispatch' && inputs.operation == 'capture'
    runs-on: ubuntu-slim
    steps:
      - name: Require explicit main-branch maintenance
        run: |
          set -eu
          if [ "$GITHUB_REF" != 'refs/heads/main' ]; then
            echo 'Baseline maintenance must be dispatched from main.'
            exit 1
          fi

  # The weekly full WebKit run (webkit-weekly.yml, spec:AST-030 DEC-24) runs
  # only from main, like baseline maintenance.
  webkit-weekly-request:
    needs: [admission]
    if: github.event_name == 'workflow_dispatch' && inputs.operation == 'webkit-weekly'
    runs-on: ubuntu-slim
    steps:
      - name: Require main
        run: |
          set -eu
          if [ "$GITHUB_REF" != 'refs/heads/main' ]; then
            echo 'The weekly full WebKit run must be dispatched from main.'
            exit 1
          fi

  # The release authority for an explicit release check: the active release
  # marker, or the exact main pre-cut head, that the canonical checks bind to.
  # Pull requests never run it: a release-branch pull request validates its
  # own bump in release-bump, and every test job decides its own scope.
  release-authority:
    needs: [admission]
    if: github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'
    runs-on: ubuntu-slim
    permissions:
      contents: read
    outputs:
      release_branch: ${{ steps.release-authority.outputs.branch || steps.main-authority.outputs.branch }}
      release_head: ${{ steps.release-authority.outputs.head || steps.main-authority.outputs.head }}
      release_plan_digest: ${{ steps.release-authority.outputs.planDigest }}
    steps:
      # Marks a release re-check, so the re-check workflow can tell its runs
      # from main's hourly check of the same commit.
      - name: Mark a release re-check
        if: inputs.recheck
        run: echo 'Release re-check'

      # Full history only where the release-branch validator reads it (tags,
      # the cut commit, release diffs). A main pre-cut check fetches current
      # main on top, so 50 commits are plenty there; the full clone took over
      # a minute.
      - uses: actions/checkout@v7
        with:
          ref: ${{ github.sha }}
          fetch-depth: ${{ inputs['release-branch'] != 'main' && '0' || '50' }}

      - name: Fetch active release refs
        if: inputs['release-branch'] != 'main'
        run: git fetch origin '+refs/heads/release/v*:refs/remotes/origin/release/v*'

      - name: Validate active release authority
        id: release-authority
        if: inputs['release-branch'] != 'main'
        env:
          RELEASE_BRANCH: ${{ github.event_name == 'workflow_dispatch' && inputs['release-branch'] || github.base_ref }}
          RELEASE_VERSION: ${{ github.event_name == 'workflow_dispatch' && inputs['release-version'] || '' }}
          EXPECTED_HEAD: ${{ github.event_name == 'workflow_dispatch' && inputs['expected-head'] || github.event.pull_request.head.sha }}
          PLAN_DIGEST: ${{ github.event_name == 'workflow_dispatch' && inputs['plan-digest'] || '' }}
          RECEIPT_HEAD: ${{ github.event_name == 'workflow_dispatch' && github.sha || github.event.pull_request.head.sha }}
          REF_NAME: ${{ github.event_name == 'workflow_dispatch' && github.ref_name || github.base_ref }}
          MODE: ${{ github.event_name == 'workflow_dispatch' && 'check' || 'pr' }}
        run: |
          set -eu
          TRUSTED_POLICY="$RUNNER_TEMP/release-policy"
          mkdir -p "$TRUSTED_POLICY/scripts/release" "$TRUSTED_POLICY/scripts/lib"
          git show "origin/$RELEASE_BRANCH:scripts/release/active-release.mjs" \
            > "$TRUSTED_POLICY/scripts/release/active-release.mjs"
          git show "origin/$RELEASE_BRANCH:scripts/release/release-paths.mjs" \
            > "$TRUSTED_POLICY/scripts/release/release-paths.mjs"
          git show "origin/$RELEASE_BRANCH:scripts/lib/workspace-globs.mjs" \
            > "$TRUSTED_POLICY/scripts/lib/workspace-globs.mjs"
          VALIDATOR="$TRUSTED_POLICY/scripts/release/active-release.mjs"
          ACTIVE_BRANCHES=$(node "$VALIDATOR" list-active --root "$GITHUB_WORKSPACE")
          ARGS=(
            validate
            --root "$GITHUB_WORKSPACE"
            --mode "$MODE"
            --release-branch "$RELEASE_BRANCH"
            --expected-head "$EXPECTED_HEAD"
            --checkout-sha "$RECEIPT_HEAD"
            --ref-name "$REF_NAME"
            --active-branches "$ACTIVE_BRANCHES"
          )
          if [ "$MODE" = check ]; then
            ARGS+=(--release-version "$RELEASE_VERSION" --plan-digest "$PLAN_DIGEST")
            REMOTE_HEAD=$(git ls-remote origin "refs/heads/$RELEASE_BRANCH" | awk '{print $1}')
            ARGS+=(--remote-head "$REMOTE_HEAD")
          fi
          node "$VALIDATOR" "${ARGS[@]}"

      - name: Validate exact main pre-cut authority
        id: main-authority
        if: >-
          github.event_name == 'workflow_dispatch' &&
          inputs.operation == 'release-check' &&
          inputs['release-branch'] == 'main'
        env:
          EXPECTED_HEAD: ${{ inputs['expected-head'] }}
        run: |
          set -eu
          if [ "$GITHUB_REF" != 'refs/heads/main' ]; then
            echo 'Main pre-cut checks must be dispatched from main.'
            exit 1
          fi
          if ! [[ "$EXPECTED_HEAD" =~ ^[0-9a-f]{40}$ ]]; then
            echo 'Main pre-cut checks require an exact full expected head.'
            exit 1
          fi
          if [ "$GITHUB_SHA" != "$EXPECTED_HEAD" ]; then
            echo 'Checked-out main commit does not match expected head.'
            exit 1
          fi
          REMOTE_HEAD=$(git ls-remote origin refs/heads/main | awk '{print $1}')
          if [ -z "$REMOTE_HEAD" ]; then
            echo 'Current main head is unavailable.'
            exit 1
          fi
          git fetch --no-tags origin "$REMOTE_HEAD"
          if ! git merge-base --is-ancestor "$EXPECTED_HEAD" "$REMOTE_HEAD"; then
            echo 'Checked main commit is not an ancestor of current main.'
            exit 1
          fi
          printf 'branch=main\nhead=%s\n' "$EXPECTED_HEAD" >> "$GITHUB_OUTPUT"

  # Generated-only version PR lane. It validates release bookkeeping in a few
  # minutes; the merged branch head receives one full visual/a11y/RTL projection.
  release-bump:
    needs: [admission]
    if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (github.event_name == 'pull_request' && startsWith(github.base_ref, 'release/v')) }}
    runs-on: 2-core-ubuntu-arm
    timeout-minutes: 15
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v7
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          fetch-depth: 0

      - name: Fetch release refs, base, main, and trusted release policy
        run: |
          git fetch origin '+refs/heads/release/v*:refs/remotes/origin/release/v*'
          git fetch origin "${{ github.base_ref }}" --depth=200
          git fetch origin 'main:refs/remotes/origin/main'
          TRUSTED_POLICY="$RUNNER_TEMP/release-policy"
          mkdir -p "$TRUSTED_POLICY/scripts/release" "$TRUSTED_POLICY/scripts/lib"
          git show "origin/${{ github.base_ref }}:scripts/release/active-release.mjs" \
            > "$TRUSTED_POLICY/scripts/release/active-release.mjs"
          git show "origin/${{ github.base_ref }}:scripts/release/release-paths.mjs" \
            > "$TRUSTED_POLICY/scripts/release/release-paths.mjs"
          git show "origin/${{ github.base_ref }}:scripts/lib/workspace-globs.mjs" \
            > "$TRUSTED_POLICY/scripts/lib/workspace-globs.mjs"

      - name: Setup Node and pnpm
        uses: ./.github/actions/setup

      - name: Require generated release bookkeeping or a proven test repair
        run: |
          node "$RUNNER_TEMP/release-policy/scripts/release/active-release.mjs" validate-diff \
            --root "$GITHUB_WORKSPACE" \
            --base "origin/${{ github.base_ref }}" \
            --head "${{ github.event.pull_request.head.sha }}" \
            --main-ref origin/main

      - name: Validate branch, head, plan, versions, and Changeset consumption
        run: |
          set -eu
          VALIDATOR="$RUNNER_TEMP/release-policy/scripts/release/active-release.mjs"
          ACTIVE_BRANCHES=$(node "$VALIDATOR" list-active --root "$GITHUB_WORKSPACE")
          node "$VALIDATOR" validate \
            --root "$GITHUB_WORKSPACE" \
            --mode pr \
            --release-branch "${{ github.base_ref }}" \
            --expected-head "${{ github.event.pull_request.head.sha }}" \
            --checkout-sha "${{ github.event.pull_request.head.sha }}" \
            --ref-name "${{ github.base_ref }}" \
            --active-branches "$ACTIVE_BRANCHES" \
            | tee release-bump-receipt.json

      - name: Validate generated changelogs and codemods
        run: |
          pnpm check:changesets
          node scripts/format-changelogs.mjs --check
          VERSION=$(node -p "require('./.release/active.json').version")
          pnpm exec vitest run \
            "packages/cli/assets/codemods/transforms/v${VERSION}/__tests__" \
            packages/cli/assets/codemods/__tests__/registry.test.mjs

      - name: Upload exact-head release bump receipt
        uses: actions/upload-artifact@v7
        with:
          name: release-bump-receipt-${{ github.event.pull_request.head.sha }}
          path: release-bump-receipt.json
          retention-days: 30

  release-merge-back:
    name: release-merge-back
    needs: [admission]
    # Only a release merge-back branch has anything for this job to validate,
    # so every other pull request skips it before the full-history checkout
    # below (minutes on a larger runner). The step after the checkout still
    # checks the exact branch contract, and required lint validates merge-back
    # branches with the same trusted policy.
    if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (github.event_name == 'pull_request' && github.base_ref == 'main' && startsWith(github.head_ref, 'chore/merge-v') && endsWith(github.head_ref, '-to-main')) }}
    # Match the stable publisher so byte parity covers the same packed manifest.
    runs-on: ${{ startsWith(github.head_ref, 'chore/merge-v') && '4-core-ubuntu' || 'ubuntu-latest' }}
    timeout-minutes: 15
    permissions:
      contents: read
    steps:
      - name: Checkout merge-back candidate
        uses: actions/checkout@v7
        with:
          fetch-depth: 0

      - name: Detect the release-merge-back branch contract
        id: release-merge-back-scope
        env:
          MERGE_BRANCH: ${{ github.head_ref }}
        run: |
          set -eu
          case "$MERGE_BRANCH" in
            chore/merge-v*-to-main)
              VERSION=${MERGE_BRANCH#chore/merge-v}
              VERSION=${VERSION%-to-main}
              printf '%s' "$VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$'
              echo 'required=true' >> "$GITHUB_OUTPUT"
              ;;
            *)
              echo 'required=false' >> "$GITHUB_OUTPUT"
              ;;
          esac

      - name: Fetch release authority and trusted validator
        if: steps.release-merge-back-scope.outputs.required == 'true'
        run: |
          set -eu
          git fetch origin main 'refs/tags/v*:refs/tags/v*' '+refs/heads/release/v*:refs/remotes/origin/release/v*'
          TRUSTED_POLICY="$RUNNER_TEMP/release-policy"
          mkdir -p "$TRUSTED_POLICY/scripts/release" "$TRUSTED_POLICY/scripts/lib"
          git show origin/main:scripts/release/active-release.mjs \
            > "$TRUSTED_POLICY/scripts/release/active-release.mjs"
          git show origin/main:scripts/release/release-paths.mjs \
            > "$TRUSTED_POLICY/scripts/release/release-paths.mjs"
          git show origin/main:scripts/lib/workspace-globs.mjs \
            > "$TRUSTED_POLICY/scripts/lib/workspace-globs.mjs"

      - name: Validate published bytes and consumed-only Changeset merge-back
        if: steps.release-merge-back-scope.outputs.required == 'true'
        env:
          MERGE_BRANCH: ${{ github.head_ref }}
        run: |
          set -eu
          VERSION=${MERGE_BRANCH#chore/merge-v}
          VERSION=${VERSION%-to-main}
          printf '%s' "$VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$'
          VALIDATOR="$RUNNER_TEMP/release-policy/scripts/release/active-release.mjs"
          ACTIVE_BRANCHES=$(node "$VALIDATOR" list-active --root "$GITHUB_WORKSPACE")
          # The merge commit's first parent: the main commit it was built on.
          # A main that moved since would read its new files as deletions.
          node "$VALIDATOR" validate-merge-back \
            --root "$GITHUB_WORKSPACE" \
            --base HEAD^1 \
            --release-ref "v$VERSION" \
            --active-branches "$ACTIVE_BRANCHES"

      - name: Setup Node and pnpm for published-byte verification
        if: steps.release-merge-back-scope.outputs.required == 'true'
        uses: ./.github/actions/setup
        with:
          install: 'false'

      - name: Verify immutable tag package bytes match npm
        if: steps.release-merge-back-scope.outputs.required == 'true'
        env:
          MERGE_BRANCH: ${{ github.head_ref }}
        run: |
          set -eu
          VERSION=${MERGE_BRANCH#chore/merge-v}
          VERSION=${VERSION%-to-main}
          TAG_ROOT="$RUNNER_TEMP/release-tag"
          git worktree add --detach "$TAG_ROOT" "v$VERSION"
          cd "$TAG_ROOT"
          pnpm install --frozen-lockfile
          pnpm build
          node scripts/release/verify-published.mjs --version "$VERSION"

  # Required docsite owner (historical check name, AST-030 FR7): one job
  # builds the packages and the docsite production build once, then runs the
  # docsite data tests and the browser contracts side by side on that build.
  # The browser contracts matter because the playground preview runs
  # user-authored code in a sandboxed iframe whose only tie to the page is a
  # nonce-attested MessagePort handshake
  # (apps/docsite/src/app/playground/previewChannel.ts): jsdom can drive that
  # state machine but cannot prove the integration (the frame's real `load`
  # event, a replaced document torn down and its successor given the current
  # code and theme, nothing sent to a document the code navigated to), and
  # only the production build has the opaque-origin sandbox at all. The
  # spec-only lane validates spec records here, where it always has.
  # Whether this push defers the heavy suites (spec:AST-030 FR20, DEC-14): a
  # push to a ready agent-lane pull request (the shared agent login), in its
  # first attempt, runs only the fast checks (lint, typecheck). The heavy jobs
  # skip, and the required checks fail with the reason until the pull request
  # is marked ready or reopened, or its run is re-run in full before merge
  # (any later attempt runs everything). A spec-only change is never deferred.
  # Every other run skips this job at once, so it delays nothing; every job
  # below it carries a status check, so the skip never skips them. It needs
  # only room, beside admission, so the Storybook build it gates still starts
  # with room (spec:AST-030 FR16), and like room it holds one slim job.
  heavy-ci:
    needs: [room]
    if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && ((github.event_name == 'pull_request' && github.event.action == 'synchronize' && github.run_attempt == '1' && contains(fromJSON('["cixzhang"]'), github.event.pull_request.user.login) && github.base_ref == 'main' && !startsWith(github.head_ref, 'chore/merge-v')) && needs.room.outputs.full != 'true') }}
    runs-on: ubuntu-slim
    timeout-minutes: 5
    permissions:
      contents: read
      pull-requests: read
    outputs:
      deferred: ${{ steps.decide.outputs.deferred }}
    steps:
      - name: Check out the scope action
        uses: actions/checkout@v7
        with:
          sparse-checkout: .github/actions/test-scope
          path: .test-scope
          persist-credentials: false

      - name: Decide this push's scope
        id: scope
        uses: ./.test-scope/.github/actions/test-scope

      - name: Defer the heavy suites unless the change is spec-only or Lab-only
        id: decide
        env:
          SPEC_ONLY: ${{ steps.scope.outputs.spec_only }}
          LAB_ONLY: ${{ steps.scope.outputs.lab_only }}
        run: |
          # A Lab-only change runs only fast work, so nothing is deferred (FR26).
          if [ "$SPEC_ONLY" = true ] || [ "$LAB_ONLY" = true ]; then
            echo 'deferred=false' >> "$GITHUB_OUTPUT"
            exit 0
          fi
          echo 'deferred=true' >> "$GITHUB_OUTPUT"
          echo "::notice title=Heavy CI deferred::Heavy CI deferred: runs when marked ready and before merge. Mark the pull request ready, reopen it, or re-run all jobs of this run to run everything."
          echo "Heavy CI deferred: runs when marked ready and before merge." >> "$GITHUB_STEP_SUMMARY"

  docsite-build:
    needs: [room, admission, heavy-ci]
    if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (github.event_name != 'workflow_dispatch' && !startsWith(github.base_ref, 'release/v') && !cancelled() && needs.heavy-ci.outputs.deferred != 'true' && needs.room.outputs.full != 'true' && needs.admission.outputs.full != 'true') }}
    # The Next.js production build uses every core it gets.
    runs-on: ubuntu-latest
    timeout-minutes: 15
    permissions:
      contents: read
      pull-requests: read
    # Placeholder docs-prompt origins: the build and its browser contracts
    # exercise the configured prompt. Deployed values live only in the
    # deployment environment, never in this repository.
    env:
      NEXT_PUBLIC_INTERNAL_DOCS_ORIGIN: https://docs.example.test
      NEXT_PUBLIC_DOCS_ACCESS_CHECK_ORIGIN: https://probe.example.test
    outputs:
      lab_only: ${{ steps.scope.outputs.lab_only }}
      # The browser contracts apply: the docsite was built, and the change is
      # shared infrastructure or more than component tests, stories, spec
      # records and changesets.
      browser: ${{ steps.browser.outputs.applies }}
    steps:
      # This job decides its own scope (no separate scope job): the step
      # reads the PR's file list and the base's trusted classifier, and
      # everything is in scope when it cannot decide. `touches` is false only
      # when every changed file outside the docsite app is a test, a story
      # (or Storybook file), a spec record, a changeset, or an a11y-spec or
      # interaction-harness file. The browser contracts still run when the
      # classifier calls the change shared infrastructure (`full_suite`: the
      # harnesses, Storybook config, a shared test), as for every owner
      # (spec:AST-030 FR13).
      - name: Check out the scope action
        uses: actions/checkout@v7
        with:
          sparse-checkout: .github/actions/test-scope
          path: .test-scope
          persist-credentials: false

      - name: Decide this job's scope
        id: scope
        uses: ./.test-scope/.github/actions/test-scope
        with:
          paths: '^(?:apps/docsite/|(?!(?:.*/)?__tests__/|.*\.(?:test|spec)\.[cm]?[jt]sx?$|apps/storybook/|.*\.stories\.[jt]sx?$|docs/specs/|\.changeset/|internal/a11y-spec/|internal/interaction-harness/))'

      - name: 'Lab-only: Lab tests + Storybook build'
        if: steps.scope.outputs.lab_only == 'true'
        run: |
          echo "::notice title=Lab-only::Lab-only: Lab tests + Storybook build. This job's work is not required for a change only to the Lab package (spec:AST-030 FR26)."

      - name: Skip docsite work for Node tooling
        if: steps.scope.outputs.tooling_only == 'true'
        run: echo "Node-tooling PR — docsite generation is not an owned check"

      - uses: actions/checkout@v7
        if: steps.scope.outputs.tooling_only != 'true' && steps.scope.outputs.lab_only != 'true'

      # Spec validation imports the canonical CLI discovery path, so the
      # lightweight docs path needs workspace dependencies too.
      - uses: ./.github/actions/setup
        if: steps.scope.outputs.tooling_only != 'true' && steps.scope.outputs.lab_only != 'true'

      - name: Validate spec records
        if: (steps.scope.outputs.spec_only == 'true' || steps.scope.outputs.decided != 'true')
        run: node scripts/check-knowledge.mjs

      - name: Build docsite workspace dependencies
        if: steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && steps.scope.outputs.lab_only != 'true'
        run: |
          pnpm -F @astryxdesign/core build
          pnpm --workspace-concurrency=4 \
            -F @astryxdesign/lab \
            -F @astryxdesign/charts \
            -F @astryxdesign/richtext \
            -F @astryxdesign/vega \
            -F @astryxdesign/theme-neutral \
            -F @astryxdesign/theme-matcha \
            -F @astryxdesign/theme-stone \
            -F @astryxdesign/theme-gothic \
            -F @astryxdesign/theme-chocolate \
            -F @astryxdesign/theme-y2k \
            -F @astryxdesign/theme-butter \
            build

      # `build` generates the docsite data first, so the data tests below run
      # on the same generated files the production build used.
      - name: Build the docsite
        if: steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && steps.scope.outputs.lab_only != 'true'
        run: pnpm -F @astryxdesign/docsite build

      - name: Decide whether the browser contracts apply
        id: browser
        run: echo "applies=${{ (steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && steps.scope.outputs.lab_only != 'true') && (steps.scope.outputs.touches == 'true' || steps.scope.outputs.full_suite == 'true') }}" >> "$GITHUB_OUTPUT"

      # docsite-browser serves this build, never one of its own. The commit
      # stamp lets it check that the build is of the commit it checked out.
      - name: Stamp the build with its commit
        if: steps.browser.outputs.applies == 'true'
        run: |
          git rev-parse HEAD > apps/docsite/.next/BUILD_COMMIT
          # The sizes behind the upload, largest first, and what it leaves out.
          du -sh apps/docsite/.next/* apps/docsite/.next/server/* apps/docsite/src/generated apps/docsite/public/monaco apps/docsite/public/vendor 2>/dev/null | sort -rh | head -15
          for kind in '*.map' '*.nft.json'; do
            echo "left out, $kind: $(find apps/docsite/.next -path apps/docsite/.next/cache -prune -o -name "$kind" -type f -print0 | du -ch --files0-from=- 2>/dev/null | tail -1)"
          done

      # Everything `next start` reads that the build generated and the
      # repository ignores: the server and static output, the generated data
      # and theme, the ShadCN registry and the playground's vendored assets.
      # Not the compile
      # cache, the build traces, source maps or file traces (*.nft.json, for
      # a standalone deployment), which serving never reads.
      - name: Upload the docsite build
        if: steps.browser.outputs.applies == 'true'
        uses: actions/upload-artifact@v7
        with:
          name: docsite-build
          path: |
            apps/docsite/.next/
            !apps/docsite/.next/cache/
            !apps/docsite/.next/trace
            !apps/docsite/.next/trace-build
            !apps/docsite/.next/diagnostics/
            !apps/docsite/.next/types/
            !apps/docsite/.next/**/*.map
            !apps/docsite/.next/**/*.nft.json
            apps/docsite/src/generated/
            apps/docsite/src/themes/astryx.js
            apps/docsite/src/themes/astryx.css
            apps/docsite/public/playground-types.json
            apps/docsite/public/monaco/
            apps/docsite/public/vendor/
            apps/docsite/public/shadcn/
          include-hidden-files: true
          if-no-files-found: error
          overwrite: true
          retention-days: 1
          # HTML, RSC payloads and JavaScript compress well; the default level
          # takes most of that at a fraction of the highest level's time.
          compression-level: 6

      # The built API surface the data tests read for public-hook coverage.
      # The CLI and build packages, which the dependency build above skips,
      # are listed as not built; the test names them as excluded and fails on
      # any other package missing from the surface.
      - name: Write the docsite's API surface
        if: steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && steps.scope.outputs.lab_only != 'true'
        run: node scripts/api-report/cli.mjs --surface .api-surface-docsite

      - name: test-docsite (data tests)
        if: steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && steps.scope.outputs.lab_only != 'true'
        env:
          # Relative to the repository root.
          ASTRYX_API_SURFACE: .api-surface-docsite
        run: pnpm -F @astryxdesign/docsite test

      # A docsite-only change skips test-node, and the registry generator
      # lives in the docsite.
      - name: Verify the hidden production registry gate
        if: steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && steps.scope.outputs.lab_only != 'true'
        run: node internal/shadcn-registry/verify-production-gate.mjs

  # The docsite browser contracts, against the build docsite-build uploaded:
  # the same commit, never rebuilt. A planner-driven matrix (one leg today;
  # playwright-legs.mjs splits the spec files by recorded time, so a second
  # leg is a one-line change).
  docsite-browser:
    name: docsite-browser (${{ matrix.leg }}/${{ strategy.job-total }})
    needs: [docsite-build]
    if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && needs.docsite-build.result == 'success' && needs.docsite-build.outputs.browser == 'true') }}
    strategy:
      fail-fast: false
      matrix:
        leg: [1]
    runs-on: ubuntu-latest
    timeout-minutes: 15
    permissions:
      contents: read
    env:
      NEXT_PUBLIC_INTERNAL_DOCS_ORIGIN: https://docs.example.test
      NEXT_PUBLIC_DOCS_ACCESS_CHECK_ORIGIN: https://probe.example.test
    steps:
      - uses: actions/checkout@v7

      - uses: ./.github/actions/setup

      - name: Install Playwright
        run: npx playwright install chromium

      - name: Download the docsite build
        uses: actions/download-artifact@v8
        with:
          name: docsite-build
          path: apps/docsite

      - name: Require the build of this commit
        run: |
          built=$(cat apps/docsite/.next/BUILD_COMMIT)
          here=$(git rev-parse HEAD)
          echo "build: $built; checkout: $here"
          test "$built" = "$here"

      - name: Plan this leg's browser contracts
        id: plan
        run: |
          node .github/scripts/playwright-legs.mjs plan \
            --key docsite --config apps/docsite/playwright.config.ts \
            --leg ${{ matrix.leg }} --of ${{ strategy.job-total }} \
            --out "$RUNNER_TEMP/docsite-leg.txt"

      - name: test-docsite-e2e (browser contracts)
        if: steps.plan.outputs.files != '0'
        run: pnpm test:docsite-browser --test-list "$RUNNER_TEMP/docsite-leg.txt"

      # Only a leg whose contracts ran has evidence; one that stopped before
      # them reports that failure alone.
      - name: Upload docsite browser evidence
        if: always() && steps.plan.outcome == 'success' && steps.plan.outputs.files != '0'
        uses: actions/upload-artifact@v7
        with:
          name: docsite-browser-evidence-${{ matrix.leg }}
          path: test-results/docsite/
          if-no-files-found: error
          retention-days: 7

  # The required docsite context (spec:AST-030 FR7): passes only when the
  # build passed and every browser leg passed, or the build's scope found no
  # browser contract to run. A skipped or cancelled leg otherwise fails it.
  docsite-test:
    needs: [room, admission, heavy-ci, docsite-build, docsite-browser]
    if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft) && (github.event_name != 'workflow_dispatch' && !startsWith(github.base_ref, 'release/v') && !cancelled()) }}
    runs-on: ubuntu-slim
    permissions: {}
    steps:
      - name: Require a branch in this repository or the ci:run label
        if: ${{ github.event_name == 'pull_request' && !(github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run')) }}
        run: |
          echo "::error::Waiting for a maintainer's ci:run label: an outside contributor's pull request runs CI once a maintainer adds it (spec:AST-030 FR17)."
          exit 1

      - name: Stop when CI is full
        if: needs.room.outputs.full == 'true' || needs.admission.outputs.full == 'true'
        run: |
          echo "::error title=CI is full::CI is full: re-run all jobs or push later. The run found no room under the CI ceiling."
          exit 1

      # An agent lane's push defers the heavy suites (spec:AST-030 FR20): the
      # required check fails with the reason, never passes as skipped.
      - name: Heavy CI deferred
        if: needs.heavy-ci.outputs.deferred == 'true'
        run: |
          echo "::error::Heavy CI deferred: runs when marked ready and before merge (spec:AST-030 FR20)."
          exit 1

      - name: 'Lab-only: Lab tests + Storybook build'
        if: needs.docsite-build.outputs.lab_only == 'true'
        run: |
          echo "::notice title=Lab-only::Lab-only: Lab tests + Storybook build. This job's work is not required for a change only to the Lab package (spec:AST-030 FR26)."

      - name: Require the docsite build and its browser contracts
        env:
          BUILD_RESULT: ${{ needs.docsite-build.result }}
          BROWSER: ${{ needs.docsite-build.outputs.browser }}
          BROWSER_RESULT: ${{ needs.docsite-browser.result }}
        run: |
          echo "docsite-build: $BUILD_RESULT; browser contracts apply: ${BROWSER:-unknown}; docsite-browser: $BROWSER_RESULT"
          [ "$BUILD_RESULT" = success ] || exit 1
          if [ "$BROWSER" = true ]; then
            [ "$BROWSER_RESULT" = success ] || exit 1
          else
            [ "$BROWSER" = false ] && [ "$BROWSER_RESULT" = skipped ] || exit 1
          fi

  # Tests run as two parallel lanes joined by `test` below.
  #
  # They used to be one `pnpm test` on a 2-core runner, which ran both Vitest
  # projects back to back and was terminated around 20 minutes with no summary
  # — no assertion output, so nothing said which suite was at fault. `main` was
  # already at ~19m15, so the budget, not any one test, was the defect.
  #
  # The projects are independent by construction (see vitest.config.ts: `ui` is
  # jsdom + StyleX, `node` is everything else), so running them as two jobs
  # costs no duplicate execution. They do NOT carry half the work each: on this
  # CI, `ui` is ~5x the heavier lane, so it takes the larger runner.
  #
  # The earlier local figure that put `node` ahead (570s vs 244s) was not a
  # comparable measurement — only the node run was bounded to a small worker
  # pool, and node is the project whose cost is per-assertion CLI subprocesses.
  #
  # The repo-wide guardrail steps ride `test-ui` (~18s of it).
  #
  # `test` remains a job, so the required check of that name still exists and
  # still reports for every PR. This mirrors the `build` join over
  # build-storybook + typecheck below.
  test-ui:
    name: test-ui (${{ matrix.shard }}/${{ strategy.job-total }})
    needs: [admission, heavy-ci]
    if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && needs.heavy-ci.outputs.deferred != 'true' && (needs.admission.result == 'success' && (github.event_name != 'workflow_dispatch'))) }}
    # One runner ran the whole UI project in ~16 minutes and set the PR's wall
    # time. Vitest's --shard gives each leg an equal share of the files; the
    # two slowest files (~3.5 minutes each) bound a leg, so more legs stop
    # paying. `test` joins the legs: the job result is success only when
    # every leg passed.
    strategy:
      fail-fast: false
      # A pull request or merge-queue entry runs at most two legs at a time,
      # so many open pull requests cannot flood the organization's shared
      # runner pool; the legs still all run, in two waves.
      max-parallel: 2
      matrix:
        shard: [1, 2, 3, 4]
    runs-on: ubuntu-latest
    timeout-minutes: 15
    permissions:
      contents: read
      pull-requests: read
    steps:
      # This job decides its own scope (no separate scope job): the step
      # reads the PR's file list and the base's trusted classifier, and
      # everything is in scope when it cannot decide.
      - name: Check out the scope action
        uses: actions/checkout@v7
        with:
          sparse-checkout: .github/actions/test-scope
          path: .test-scope
          persist-credentials: false

      - name: Decide this job's scope
        id: scope
        uses: ./.test-scope/.github/actions/test-scope

      - name: 'Lab-only: Lab tests + Storybook build'
        if: steps.scope.outputs.lab_only == 'true'
        run: |
          echo "::notice title=Lab-only::Lab-only: Lab tests + Storybook build. This job runs the Lab package's tests, the source-reading guard tests and the repository guards (spec:AST-030 FR26)."

      - name: Skip heavy work for a specialized lane
        if: steps.scope.outputs.docsite_only == 'true' || steps.scope.outputs.spec_only == 'true' || steps.scope.outputs.tooling_only == 'true'
        run: echo "Specialized PR lane — skipping unrelated test suite"

      # A spec-only change runs no other test here, so it runs the tests that
      # read a record it changes: a record such a test reads can break it, and
      # the break would otherwise show first on main (spec:AST-030 FR2). One
      # leg runs this project's readers; the lister needs only git and Node,
      # so a change no test here reads sets up nothing.
      - name: Check out the change for the tests that read its records
        if: matrix.shard == 1 && steps.scope.outputs.spec_only == 'true'
        uses: actions/checkout@v7
        with:
          fetch-depth: 2

      - name: List the tests that read a changed record
        id: spec-readers
        if: matrix.shard == 1 && steps.scope.outputs.spec_only == 'true'
        run: |
          node .github/scripts/fs-guard-tests.mjs --spec-readers --project ui --changed HEAD^1 > "$RUNNER_TEMP/spec-readers.txt"
          echo "UI tests that read a changed record:"
          cat "$RUNNER_TEMP/spec-readers.txt"
          if [ -s "$RUNNER_TEMP/spec-readers.txt" ]; then
            echo 'any=true' >> "$GITHUB_OUTPUT"
          else
            echo 'any=false' >> "$GITHUB_OUTPUT"
          fi

      - uses: ./.github/actions/setup
        if: steps.spec-readers.outputs.any == 'true'

      # No --passWithNoTests: the list holds this project's tests only, so a
      # run that finds none is a lister fault.
      - name: Run the UI tests that read a changed record
        if: steps.spec-readers.outputs.any == 'true'
        run: |
          mapfile -t READERS < "$RUNNER_TEMP/spec-readers.txt"
          pnpm test:ui "${READERS[@]}"

      # Two commits: a pull request's merge commit and its base parent, the
      # diff a scoped run follows.
      - uses: actions/checkout@v7
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true'
        with:
          fetch-depth: 2

      - uses: ./.github/actions/setup
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true'

      - name: Check knowledge schema history
        if: >-
          matrix.shard == 1 &&
          github.event_name == 'pull_request' &&
          steps.scope.outputs.docsite_only != 'true' &&
          steps.scope.outputs.spec_only != 'true' &&
          steps.scope.outputs.tooling_only != 'true'
        run: |
          git fetch origin "${{ github.event.pull_request.base.sha }}" --depth=1
          node scripts/check-knowledge.mjs --base "${{ github.event.pull_request.base.sha }}"

      - name: Check copyright headers
        if: matrix.shard == 1 && steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true'
        run: ./scripts/add-copyright.sh --check

      - name: Check package.json exports are in sync
        if: matrix.shard == 1 && steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true'
        run: node scripts/sync-exports.js --check

      - name: Verify the published CLI ./api type surface
        if: matrix.shard == 1 && steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true'
        run: node .github/scripts/cli-api-types-verify.mjs

      - name: Check token docs are in sync
        if: matrix.shard == 1 && steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true'
        run: node scripts/generate-token-docs.mjs --check

      # Fails when the lab readiness manifest claims a check the source tree
      # contradicts — the report is derived, never hand-maintained.
      - name: Check lab readiness manifest is current
        if: matrix.shard == 1 && steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true'
        run: pnpm lab:readiness:check

      # A scoped pull request runs the tests Vitest's module graph relates to
      # its diff against the base (`--changed`): the changed tests, and every
      # test that imports a changed module, however indirectly. That includes
      # shared infrastructure only the module graph reaches (the interaction
      # harness and the lint plugin: `vitest_full_suite`).
      # Anything else runs every test.
      - name: Run this shard of the UI tests
        env:
          SCOPED: ${{ github.event_name == 'pull_request' && steps.scope.outputs.vitest_full_suite == 'false' }}
          LAB_ONLY: ${{ steps.scope.outputs.lab_only }}
        run: |
          if [ "$LAB_ONLY" = true ]; then
            # A change only to the Lab package runs every Lab test across the
            # same legs, and the guards below as any scoped run does
            # (spec:AST-030 FR26).
            .github/scripts/run-named.sh "Lab tests" -- pnpm test:ui --passWithNoTests --shard=${{ matrix.shard }}/${{ strategy.job-total }} packages/lab/
            # The guard run leaves out the tests the run above already ran, so
            # no test runs twice. Every leg splits the same reduced list, so a
            # leg that cannot list them fails rather than split a different one.
            .github/scripts/run-named.sh "List the tests the first run ran" -- pnpm exec vitest list --project ui packages/lab/ --filesOnly --passWithNoTests --json="$RUNNER_TEMP/already-run.json"
            .github/scripts/run-named.sh "List the tests that read source files" --stdout "$RUNNER_TEMP/fs-guards.txt" -- node .github/scripts/fs-guard-tests.mjs --changed HEAD^1 --already-run "$RUNNER_TEMP/already-run.json"
            mapfile -t GUARDS < "$RUNNER_TEMP/fs-guards.txt"
            if [ "${#GUARDS[@]}" -gt 0 ]; then
              .github/scripts/run-named.sh "Tests that read source files" -- pnpm test:ui --passWithNoTests --shard=${{ matrix.shard }}/${{ strategy.job-total }} "${GUARDS[@]}"
            fi
          elif [ "$SCOPED" = true ]; then
            .github/scripts/run-named.sh "Tests the change reaches" -- pnpm test:ui --changed=HEAD^1 --passWithNoTests --shard=${{ matrix.shard }}/${{ strategy.job-total }}
            # Tests no module graph relates to the change run too: guards
            # that read sources, and tests that load a changed package from
            # its build (by name or its dist/).
            # The list goes through a file so a failing lister fails the step.
            # The guard run leaves out the tests the run above already ran, so
            # no test runs twice. Every leg splits the same reduced list, so a
            # leg that cannot list them fails rather than split a different one.
            .github/scripts/run-named.sh "List the tests the first run ran" -- pnpm exec vitest list --project ui --changed=HEAD^1 --filesOnly --passWithNoTests --json="$RUNNER_TEMP/already-run.json"
            .github/scripts/run-named.sh "List the tests that read source files" --stdout "$RUNNER_TEMP/fs-guards.txt" -- node .github/scripts/fs-guard-tests.mjs --changed HEAD^1 --already-run "$RUNNER_TEMP/already-run.json"
            mapfile -t GUARDS < "$RUNNER_TEMP/fs-guards.txt"
            if [ "${#GUARDS[@]}" -gt 0 ]; then
              .github/scripts/run-named.sh "Tests that read source files" -- pnpm test:ui --passWithNoTests --shard=${{ matrix.shard }}/${{ strategy.job-total }} "${GUARDS[@]}"
            fi
          else
            pnpm test:ui --shard=${{ matrix.shard }}/${{ strategy.job-total }}
          fi
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true'

      # A child process isolates engine state, not CPU or memory contention.
      # FR23 must wait until this runner's other UI workers have exited
      # (AST-036); the other shards run on other machines.
      - name: Run the isolated Markdown benchmark
        run: pnpm test:ui:isolated
        if: matrix.shard == 1 && steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && steps.scope.outputs.lab_only != 'true'

  test-node:
    name: test-node (${{ matrix.shard }}/${{ strategy.job-total }})
    needs: [admission, heavy-ci]
    if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && needs.heavy-ci.outputs.deferred != 'true' && (needs.admission.result == 'success' && (github.event_name != 'workflow_dispatch'))) }}
    # One runner ran the Node project in ~12 minutes. Vitest's --shard splits
    # the files across the legs; `test` joins them.
    strategy:
      fail-fast: false
      # A pull request or merge-queue entry runs at most two legs at a time,
      # so many open pull requests cannot flood the organization's shared
      # runner pool; the legs still all run, in two waves.
      max-parallel: 2
      matrix:
        shard: [1, 2, 3, 4]
    # Vitest runs one test file per CPU beyond the first, so the 2-core runner
    # ran this suite one file at a time (~23 min). Four cores give it three.
    runs-on: ubuntu-latest
    timeout-minutes: 15
    permissions:
      contents: read
      pull-requests: read
    steps:
      # This job decides its own scope (no separate scope job): the step
      # reads the PR's file list and the base's trusted classifier, and
      # everything is in scope when it cannot decide.
      - name: Check out the scope action
        uses: actions/checkout@v7
        with:
          sparse-checkout: .github/actions/test-scope
          path: .test-scope
          persist-credentials: false

      - name: Decide this job's scope
        id: scope
        uses: ./.test-scope/.github/actions/test-scope

      - name: Skip heavy work for a specialized lane
        if: steps.scope.outputs.docsite_only == 'true' || steps.scope.outputs.spec_only == 'true'
        run: echo "Specialized PR lane — skipping unrelated test suite"

      # A spec-only change runs no other test here, so it runs the tests that
      # read a record it changes: a record such a test reads can break it, and
      # the break would otherwise show first on main (spec:AST-030 FR2). One
      # leg runs this project's readers; the lister needs only git and Node,
      # so a change no test here reads sets up nothing.
      - name: Check out the change for the tests that read its records
        if: matrix.shard == 1 && steps.scope.outputs.spec_only == 'true'
        uses: actions/checkout@v7
        with:
          fetch-depth: 2

      - name: List the tests that read a changed record
        id: spec-readers
        if: matrix.shard == 1 && steps.scope.outputs.spec_only == 'true'
        run: |
          node .github/scripts/fs-guard-tests.mjs --spec-readers --project node --changed HEAD^1 > "$RUNNER_TEMP/spec-readers.txt"
          echo "Node tests that read a changed record:"
          cat "$RUNNER_TEMP/spec-readers.txt"
          if [ -s "$RUNNER_TEMP/spec-readers.txt" ]; then
            echo 'any=true' >> "$GITHUB_OUTPUT"
          else
            echo 'any=false' >> "$GITHUB_OUTPUT"
          fi

      - uses: ./.github/actions/setup
        if: steps.spec-readers.outputs.any == 'true'

      # No --passWithNoTests: the list holds this project's tests only, so a
      # run that finds none is a lister fault.
      - name: Run the Node tests that read a changed record
        if: steps.spec-readers.outputs.any == 'true'
        run: |
          mapfile -t READERS < "$RUNNER_TEMP/spec-readers.txt"
          pnpm test:node "${READERS[@]}"

      - uses: actions/checkout@v7
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true'
        with:
          fetch-depth: 2

      - uses: ./.github/actions/setup
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true'

      # Before Vitest starts. A scoped run's `--changed` walks the tests'
      # import graphs before the global setup builds Core, and Vite answers an
      # unresolvable Core, an optional peer of the CLI, with a stub it caches
      # for the run: every theme-build test then fails with "Could not resolve
      # "@astryxdesign/core/theme" imported by "@astryxdesign/cli"". The global
      # setup then finds Core built and skips its own build.
      - name: Build core package
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true'
        run: pnpm -F @astryxdesign/core build

      # Scoped like test-ui's run.
      - name: Run this shard of the Node tests
        env:
          SCOPED: ${{ github.event_name == 'pull_request' && steps.scope.outputs.vitest_full_suite == 'false' }}
        run: |
          if [ "$SCOPED" = true ]; then
            .github/scripts/run-named.sh "Tests the change reaches" -- pnpm test:node --changed=HEAD^1 --passWithNoTests --shard=${{ matrix.shard }}/${{ strategy.job-total }}
            # Tests no module graph relates to the change run too: guards
            # that read sources, and tests that load a changed package from
            # its build (by name or its dist/).
            # The list goes through a file so a failing lister fails the step.
            # The guard run leaves out the tests the run above already ran, so
            # no test runs twice. Every leg splits the same reduced list, so a
            # leg that cannot list them fails rather than split a different one.
            .github/scripts/run-named.sh "List the tests the first run ran" -- pnpm exec vitest list --project node --changed=HEAD^1 --filesOnly --passWithNoTests --json="$RUNNER_TEMP/already-run.json"
            .github/scripts/run-named.sh "List the tests that read source files" --stdout "$RUNNER_TEMP/fs-guards.txt" -- node .github/scripts/fs-guard-tests.mjs --changed HEAD^1 --already-run "$RUNNER_TEMP/already-run.json"
            mapfile -t GUARDS < "$RUNNER_TEMP/fs-guards.txt"
            if [ "${#GUARDS[@]}" -gt 0 ]; then
              .github/scripts/run-named.sh "Tests that read source files" -- pnpm test:node --passWithNoTests --shard=${{ matrix.shard }}/${{ strategy.job-total }} "${GUARDS[@]}"
            fi
          else
            pnpm test:node --shard=${{ matrix.shard }}/${{ strategy.job-total }}
          fi
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true'

      # A Lab-only change may carry a Lab component's CLI discovery entry; the
      # committed list must match its generator (spec:AST-030 FR26).
      - name: 'Lab-only: CLI official-packages check'
        if: matrix.shard == 1 && steps.scope.outputs.lab_only == 'true'
        # One Node-project test file: Vitest finds its project from the path.
        run: pnpm exec vitest run scripts/check-cli-official-packages.test.mjs --maxWorkers=1

      # Theme-family compilation is owned by `theme-build`, not Build. Until
      # that surface has an admitted dedicated lane, broad CI keeps its browser
      # contract inside the existing Node test owner rather than `test-build`.
      # One leg runs it.
      - name: Install Playwright for theme-family contract
        if: matrix.shard == 1 && steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true'
        run: npx playwright install chromium

      # The Node tests above run before any browser is installed, so they skip
      # offline-media's real-browser cases. This step runs them once Chromium
      # is in place, under the install's own condition; with
      # ASTRYX_OFFLINE_MEDIA_BROWSER set, a missing browser fails them.
      # ci-browser-gated-tests.test.mjs keeps this step after the install.
      - name: Offline-media browser cases
        if: matrix.shard == 1 && steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true'
        env:
          ASTRYX_OFFLINE_MEDIA_BROWSER: '1'
        # One Node-project test file: Vitest finds its project from the path.
        run: pnpm exec vitest run .github/scripts/lib/offline-media.test.mjs --maxWorkers=1

      - name: Run the theme-family contract
        if: matrix.shard == 1 && steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true'
        run: pnpm test:theme-family

  # The one pre-job left: a runner must be picked before its job starts, so
  # this decides on a free slim runner whether native Swift changed, and
  # test-native-swift runs on macOS only then. It reads the same scope step as
  # every test job; anything undecidable picks macOS.
  native-swift-runner:
    needs: [admission, heavy-ci]
    if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && needs.heavy-ci.outputs.deferred != 'true' && (needs.admission.result == 'success' && (github.event_name != 'workflow_dispatch'))) }}
    runs-on: ubuntu-slim
    timeout-minutes: 5
    permissions:
      contents: read
      pull-requests: read
    outputs:
      applies: ${{ steps.scope.outputs.applies }}
    steps:
      - name: Check out the scope action
        uses: actions/checkout@v7
        with:
          sparse-checkout: .github/actions/test-scope
          path: .test-scope
          persist-credentials: false

      - name: Decide whether native Swift changed
        id: scope
        uses: ./.test-scope/.github/actions/test-scope
        with:
          paths: '^packages/native/.*(\.swift|/Package\.swift)$|^\.github/scripts/native-swift\.sh$|^\.github/actions/test-scope/'

  test-native-swift:
    needs: [admission, heavy-ci, native-swift-runner]
    if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && needs.heavy-ci.outputs.deferred != 'true' && (github.event_name != 'workflow_dispatch' && always() && !cancelled())) }}
    runs-on: ${{ needs.native-swift-runner.outputs.applies == 'true' && 'macos-15' || 'ubuntu-slim' }}
    # The slim branch only reports that Swift is out of scope; a slim job
    # stops at fifteen minutes.
    timeout-minutes: ${{ needs.native-swift-runner.outputs.applies == 'true' && 30 || 15 }}
    permissions:
      contents: read
    steps:
      # A run CI admission turned away decides no runner either; say so, so the
      # required check fails with the true reason. Admission skips when the
      # first wait (room) stopped the run.
      - name: Stop when CI admission refused the run
        if: needs.admission.result == 'failure' || needs.admission.result == 'skipped'
        run: |
          echo "::error title=CI is full::CI admission refused this run (CI full); re-run all jobs."
          exit 1

      - name: Require a decided Swift runner
        if: needs.admission.result != 'failure' && needs.admission.result != 'skipped' && needs.native-swift-runner.result != 'success'
        run: |
          echo "The Swift runner could not be decided; refusing to skip required work."
          exit 1

      - name: Skip Swift work outside its scope
        if: needs.native-swift-runner.outputs.applies != 'true'
        run: echo "No native Swift change in this scope."

      - uses: actions/checkout@v7
        if: needs.native-swift-runner.outputs.applies == 'true'

      # The steps live in native-swift.sh, which is in the native Swift scope,
      # so a change to them runs on its own pull request.
      - name: Build and test each native Swift package
        if: needs.native-swift-runner.outputs.applies == 'true'
        run: bash .github/scripts/native-swift.sh

  # The full shadcn registry install, preview and hidden production legs
  # (spec:AST-026 FR10, draft): every item through the pinned client. It runs
  # for an explicit release check until the production registry launches; the
  # network-free production gate runs on every pull request that can change
  # the registry: with the Node unit tests, and in docsite-build for a
  # docsite-only change.
  test-registry-e2e:
    name: test-registry-e2e (${{ matrix.leg }}, ${{ matrix.mode }})
    needs: [admission]
    if: github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'
    # The preview and hidden production registries are generated and verified
    # independently, and each installs and compiles every item twice, as a
    # TypeScript and as a JavaScript consumer. One leg per registry and mode:
    # the preview's two modes in one job took 8-12 minutes on the same 1,036
    # items and passed the 15-minute limit once. release-check joins the legs:
    # the job result is success only when all four passed.
    strategy:
      fail-fast: false
      matrix:
        leg: [preview, production]
        mode: [typescript, javascript]
    runs-on: ubuntu-latest
    timeout-minutes: 15
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v7

      - uses: ./.github/actions/setup

      - name: Build registry package exports
        run: pnpm build

      # The registry-wide checks run once, in the TypeScript leg.
      - name: Verify hidden production registry contract
        if: matrix.leg == 'production' && matrix.mode == 'typescript'
        run: node internal/shadcn-registry/verify-production-gate.mjs

      - name: Generate and validate the complete preview registry
        if: matrix.leg == 'preview'
        env:
          DOCSITE_TARGET: canary
        run: node apps/docsite/scripts/generate-data.mjs

      - name: Install and build every preview registry item
        if: matrix.leg == 'preview'
        run: node internal/shadcn-registry/verify-full-catalog.mjs --mode ${{ matrix.mode }}

      - name: Generate the hidden production registry
        if: matrix.leg == 'production'
        env:
          DOCSITE_TARGET: latest
        run: node apps/docsite/scripts/generate-data.mjs

      - name: Verify hidden production discovery surfaces
        if: matrix.leg == 'production' && matrix.mode == 'typescript'
        env:
          ASTRYX_VERIFY_HIDDEN_PRODUCTION: '1'
          NEXT_PUBLIC_DOCS_TARGET: latest
        run: pnpm -F @astryxdesign/docsite exec vitest run src/__tests__/hidden-shadcn-production.test.ts

      - name: Install and build every hidden production registry item
        if: matrix.leg == 'production'
        env:
          ASTRYX_SHADCN_USE_PUBLISHED_PACKAGES: '1'
        run: node internal/shadcn-registry/verify-full-catalog.mjs --mode ${{ matrix.mode }}

  # Historical required check name. The Vitest lanes, the Build test owner,
  # native Swift and the interaction proofs (Chromium and WebKit) always
  # report (each skips its own work outside its scope), so this join projects
  # their combined result without creating another surface lane.
  test:
    needs:
      [
        room,
        admission,
        heavy-ci,
        release-bump,
        test-ui,
        test-node,
        test-build,
        test-native-swift,
        pr-interaction,
        pr-interaction-webkit,
        pr-component-a11y-contracts,
        pr-a11y-dependent-audits,
      ]
    if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft) && (github.event_name != 'workflow_dispatch' && always() && !cancelled()) }}
    runs-on: ubuntu-slim
    permissions:
      contents: read
      pull-requests: read
    steps:
      - name: Require a branch in this repository or the ci:run label
        if: ${{ github.event_name == 'pull_request' && !(github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run')) }}
        run: |
          echo "::error::Waiting for a maintainer's ci:run label: an outside contributor's pull request runs CI once a maintainer adds it (spec:AST-030 FR17)."
          exit 1
      # This job decides its own scope (no separate scope job): the step
      # reads the PR's file list and the base's trusted classifier, and
      # everything is in scope when it cannot decide.
      - name: Stop when CI is full
        if: needs.room.outputs.full == 'true' || needs.admission.outputs.full == 'true'
        run: |
          echo "::error title=CI is full::CI is full: re-run all jobs or push later. The run found no room under the CI ceiling."
          exit 1

      # The PR report says why the heavy checks did not run. Recorded here,
      # in a job a failed-jobs re-run repeats, so its attempt has the record.
      - name: Record the deferral for the PR report
        if: needs.heavy-ci.outputs.deferred == 'true'
        run: |
          printf '{"headSha":"%s","runId":"%s","runAttempt":"%s"}\n' \
            "${{ github.event.pull_request.head.sha }}" "$GITHUB_RUN_ID" "$GITHUB_RUN_ATTEMPT" > heavy-ci-deferred.json

      - name: Upload the deferral for the PR report
        if: needs.heavy-ci.outputs.deferred == 'true'
        uses: actions/upload-artifact@v7
        with:
          name: heavy-ci-deferred-${{ github.run_attempt }}
          path: heavy-ci-deferred.json
          retention-days: 7

      # An agent lane's push defers the heavy suites (spec:AST-030 FR20): the
      # required check fails with the reason, never passes as skipped.
      - name: Heavy CI deferred
        if: needs.heavy-ci.outputs.deferred == 'true'
        run: |
          echo "::error::Heavy CI deferred: runs when marked ready and before merge (spec:AST-030 FR20)."
          exit 1

      - name: Check out the scope action
        uses: actions/checkout@v7
        with:
          sparse-checkout: .github/actions/test-scope
          path: .test-scope
          persist-credentials: false

      - name: Decide this job's scope
        id: scope
        uses: ./.test-scope/.github/actions/test-scope

      - name: 'Lab-only: Lab tests + Storybook build'
        if: steps.scope.outputs.lab_only == 'true'
        run: |
          echo "::notice title=Lab-only::Lab-only: Lab tests + Storybook build. The test owners ran the Lab package's tests and the source-reading guard tests (spec:AST-030 FR26)."

      # A release-branch pull request is spec-only by classification, but its
      # join still runs: it requires the release bump's own validation.
      - uses: actions/checkout@v7
        if: steps.scope.outputs.spec_only != 'true' || steps.scope.outputs.release_bump == 'true'

      - name: Require expected test-owner outcomes
        if: steps.scope.outputs.spec_only != 'true' || steps.scope.outputs.release_bump == 'true'
        env:
          RELEASE_BUMP: ${{ steps.scope.outputs.release_bump }}
          RELEASE_BUMP_RESULT: ${{ needs.release-bump.result }}
          DOCSITE_ONLY: ${{ steps.scope.outputs.docsite_only }}
          SPEC_ONLY: ${{ steps.scope.outputs.spec_only }}
          TOOLING_ONLY: ${{ steps.scope.outputs.tooling_only }}
          LAB_ONLY: ${{ steps.scope.outputs.lab_only }}
          TEST_UI_RESULT: ${{ needs.test-ui.result }}
          TEST_NODE_RESULT: ${{ needs.test-node.result }}
          TEST_BUILD_RESULT: ${{ needs.test-build.result }}
          TEST_NATIVE_SWIFT_RESULT: ${{ needs.test-native-swift.result }}
          PR_INTERACTION_RESULT: ${{ needs.pr-interaction.result }}
          PR_INTERACTION_WEBKIT_RESULT: ${{ needs.pr-interaction-webkit.result }}
          PR_COMPONENT_A11Y_CONTRACTS_RESULT: ${{ needs.pr-component-a11y-contracts.result }}
          PR_A11Y_DEPENDENT_AUDITS_RESULT: ${{ needs.pr-a11y-dependent-audits.result }}
        run: node .github/scripts/ci-test-join.mjs

  # Build the packages and Storybook, and analyze components (parallel with
  # test). Uploads the storybook preview and analysis artifacts for downstream
  # jobs. Sandbox previews come from the exact-head Vercel deployment, so CI
  # builds no Sandbox of its own.
  # Which heavy suites this pull request opted into: one output per suite,
  # `true` while the pull request carries that suite's `ci:run-<suite>` label
  # and its newest application came from someone with write, maintain or
  # admin access (spec:AST-030 FR12). It reads the event that started the run,
  # so a label takes effect on the next push or reopen (FR17). Outside a pull
  # request every output is `false`; the release check runs every suite on its
  # own terms. The decision script comes from the merge commit's trusted
  # sparse checkout, and a lookup that fails denies the suite.
  run-labels:
    needs: [admission, heavy-ci]
    if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && needs.heavy-ci.outputs.deferred != 'true' && (needs.admission.result == 'success' && (github.event_name != 'workflow_dispatch' || inputs.operation == 'release-check'))) }}
    runs-on: ubuntu-slim
    timeout-minutes: 5
    permissions:
      contents: read
      pull-requests: read
    outputs:
      visual: ${{ steps.decide.outputs.visual }}
      a11y: ${{ steps.decide.outputs.a11y }}
      rtl: ${{ steps.decide.outputs.rtl }}
    steps:
      - name: Check out the decision script
        uses: actions/checkout@v7
        with:
          sparse-checkout: |
            .github/scripts/run-labels.cjs
            .github/scripts/review-signal-decision.cjs
          sparse-checkout-cone-mode: false
          path: .run-labels
          persist-credentials: false

      - name: Decide which suites run
        id: decide
        uses: actions/github-script@v9
        with:
          retries: 3
          script: |
            const {decideRunLabels} = require(
              `${process.env.GITHUB_WORKSPACE}/.run-labels/.github/scripts/run-labels.cjs`,
            );
            await decideRunLabels({github, context, core});

  build-storybook:
    # Starts once there is room for it, beside admission's wait for the rest of
    # the run; every job that uses its build also needs admission, so the heavy
    # legs still wait for room (spec:AST-030 FR16, DEC-16).
    needs: [room, heavy-ci]
    if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && needs.heavy-ci.outputs.deferred != 'true' && ((github.event_name != 'workflow_dispatch' || inputs.operation == 'release-check' || inputs.operation == 'webkit-weekly' && github.ref == 'refs/heads/main' || inputs.operation == 'interaction-full' && github.ref == 'refs/heads/main') && always() && !cancelled() && needs.room.outputs.full != 'true')) }}
    # Every browser lane waits for this job, and the package builds and the
    # Storybook build run side by side (build-packages-and-storybook.mjs).
    runs-on: ${{ (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check' && github.triggering_actor != 'github-actions[bot]') && '4-core-ubuntu' || 'ubuntu-latest' }}
    timeout-minutes: ${{ github.event_name == 'workflow_dispatch' && 360 || 15 }}
    permissions:
      # actions: read finds Main's kept package-size measurement of the merge base.
      actions: read
      contents: read
      pull-requests: read
    outputs:
      short_hash: ${{ steps.release.outputs.short_hash || steps.urls.outputs.short_hash }}
      pr_number: ${{ steps.urls.outputs.pr_number }}
      lab_only: ${{ steps.scope.outputs.lab_only }}
    steps:
      # This job decides its own scope (no separate scope job): the step
      # reads the PR's file list and the base's trusted classifier, and
      # everything is in scope when it cannot decide.
      - name: Check out the scope action
        uses: actions/checkout@v7
        with:
          sparse-checkout: .github/actions/test-scope
          path: .test-scope
          persist-credentials: false

      - name: Decide this job's scope
        id: scope
        uses: ./.test-scope/.github/actions/test-scope
        with:
          # `touches` scopes only the package-size check (a package, the
          # lockfile, the root build inputs, or the check itself; shared
          # infrastructure, `full_suite`, runs it too); the build itself
          # follows the specialized-lane outputs.
          paths: '^(packages/|pnpm-lock\.yaml$|package\.json$|tsconfig\.json$|scripts/|\.github/workflows/ci\.yml$|\.github/scripts/package-size\.mjs$|\.github/scripts/lib/package-size\.js$|\.github/scripts/merge-base\.sh$)'
          # A head cut before the package-size check has no script for it.
          requires-head-file: .github/scripts/package-size.mjs

      - name: Skip heavy work for a specialized lane
        if: steps.scope.outputs.docsite_only == 'true' || steps.scope.outputs.spec_only == 'true' || steps.scope.outputs.tooling_only == 'true'
        run: echo "Specialized PR lane — skipping unrelated build"

      - name: Checkout
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true'
        uses: actions/checkout@v7
        with:
          # Component evidence artifacts are named for and reviewed at the PR
          # head, so build their Storybook bytes from that exact tree rather
          # than GitHub's synthetic merge checkout.
          ref: ${{ github.event.pull_request.head.sha || github.sha }}
          # Depth 50 so analyze-pr.js's three-dot diff
          # can find a merge base — depth 1 breaks it ("no merge base") and
          # the analysis silently reported zero changed components.
          fetch-depth: 50

      - name: Verify Storybook source checkout
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && github.event_name == 'pull_request'
        env:
          EXPECTED_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
        run: test "$(git rev-parse HEAD)" = "$EXPECTED_HEAD_SHA"

      - name: Fetch base branch for PR analysis
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && github.event_name == 'pull_request'
        run: git fetch origin ${{ github.base_ref }} --depth=50

      - name: Setup Node and pnpm
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true'
        uses: ./.github/actions/setup

      # Main keeps each commit's size records and API surface for 14 days
      # (deploy.yml): every public component's sizes, every published
      # package's, and every published package's API report. The merge base is
      # compared from them; it is built here only when Main kept no component
      # record for it. The lookup runs before the Storybook build so that build
      # can run beside it.
      - name: Find the merge base
        id: merge-base
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && github.event_name == 'pull_request'
        env:
          BASE_REF: ${{ github.base_ref }}
        run: echo "sha=$(.github/scripts/merge-base.sh "$BASE_REF" 'the size comparisons' || true)" >> "$GITHUB_OUTPUT"

      - name: Find main's size records for the merge base
        id: size-records
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && steps.merge-base.outputs.sha != ''
        continue-on-error: true
        uses: actions/github-script@v9
        env:
          BASE_SHA: ${{ steps.merge-base.outputs.sha }}
        with:
          retries: 3
          script: |
            const {mainArtifactRunId} = require(`${process.env.GITHUB_WORKSPACE}/.github/scripts/lib/main-artifact.cjs`);
            for (const [output, prefix, missing] of [
              ['component_run_id', 'component-size-main', 'the merge base is built here instead'],
              ['package_run_id', 'package-size-main', 'package sizes are shown without a budget'],
              ['api_run_id', 'api-surface-main', 'the merge base is built here instead when the pull request can change a published package'],
            ]) {
              const name = `${prefix}-${process.env.BASE_SHA}`;
              const runId = await mainArtifactRunId({github, ...context.repo, name, sha: process.env.BASE_SHA});
              core.setOutput(output, runId ?? '');
              core.info(runId ? `Using ${name} from run ${runId}.` : `No ${name}; ${missing}.`);
            }

      - name: Download main's component sizes for the merge base
        id: component-download
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && steps.size-records.outputs.component_run_id != ''
        continue-on-error: true
        uses: actions/download-artifact@v8
        with:
          name: component-size-main-${{ steps.merge-base.outputs.sha }}
          run-id: ${{ steps.size-records.outputs.component_run_id }}
          github-token: ${{ github.token }}
          path: .component-size-base

      - name: Download main's API surface for the merge base
        id: api-download
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && steps.size-records.outputs.api_run_id != ''
        continue-on-error: true
        uses: actions/download-artifact@v8
        with:
          name: api-surface-main-${{ steps.merge-base.outputs.sha }}
          run-id: ${{ steps.size-records.outputs.api_run_id }}
          github-token: ${{ github.token }}
          path: .api-surface-base

      # No component record of this merge base was read (Main kept none, or
      # its download failed): build the base beside the Storybook build and
      # record its sizes with this head's analyzer, so every changed component
      # still has a before size (AST-080 FR8). No API surface of this merge
      # base was read: build the published packages the pull request changes,
      # so the API changes step compares with this base (INV24). Without a
      # surface, no API changes are compared. A pull request that changes no
      # package does not build the base for its API surface alone. It runs in
      # the background; the wait before the analysis collects it.
      - name: Start building the merge base without a record
        id: base-build
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && steps.merge-base.outputs.sha != '' && (steps.component-download.outcome != 'success' || (steps.api-download.outcome != 'success' && (steps.scope.outputs.touches == 'true' || steps.scope.outputs.full_suite != 'false')))
        env:
          BASE_SHA: ${{ steps.merge-base.outputs.sha }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
          NEED_API: ${{ steps.api-download.outcome != 'success' }}
          NEED_SIZES: ${{ steps.component-download.outcome != 'success' }}
        run: |
          git worktree add --detach .size-base "$BASE_SHA"
          mkdir -p .component-size-base
          # The inner script reads BASE_SHA, HEAD_SHA, NEED_API and NEED_SIZES
          # from this step's env.
          # shellcheck disable=SC2016
          nohup bash -c '
            set -e
            cd .size-base
            pnpm install --frozen-lockfile
            # Core and its build tooling always build: the other component
            # packages depend on them. Another package builds only when the
            # pull request changes its source. A published package the base
            # leaves unbuilt is reported from the head build only when none of
            # its report inputs changed (SHARED_INPUTS in the API report CLI);
            # otherwise it is reported as unknown, with no rows.
            pnpm -F @astryxdesign/build build
            pnpm -F @astryxdesign/core build
            for pkg in lab charts richtext vega; do
              git diff --quiet "$BASE_SHA" "$HEAD_SHA" -- "packages/$pkg/src" || pnpm -F "@astryxdesign/$pkg" build
            done
            # Main kept the sizes of this merge base: keep its record.
            if [ "$NEED_SIZES" = true ]; then
              node ../.github/scripts/analyze-pr.js --main-record --output ../.component-size-base/component-size.json
            fi
            if [ "$NEED_API" = true ]; then
              {
                for dir in packages/themes/*/; do
                  git diff --quiet "$BASE_SHA" "$HEAD_SHA" -- "$dir" || pnpm -F "./$dir" build
                done
                # The CLI publishes declarations generated from its JSDoc.
                # The head build always writes them, and the CLI report also
                # reads Core, so the base writes them on every pull request,
                # not only when the CLI changes. Without them the API changes
                # report the CLI as unknown. Keep apostrophes out of these
                # comments: the script is single-quoted.
                pnpm -F @astryxdesign/cli sync:api-types
              } || echo "Building the published packages of the merge base failed; the API changes report those packages as unknown."
            fi
            touch ../base-build.done
          ' > base-build.log 2>&1 || touch base-build.failed &
          echo "started=true" >> "$GITHUB_OUTPUT"

      # The same steps as `pnpm build` and the Storybook build, overlapped: a
      # package builds once its workspace dependencies have, and Storybook once
      # the packages its story index records are built.
      - name: Build packages and Storybook
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true'
        run: node .github/scripts/build-packages-and-storybook.mjs

      # A Lab-only change skips the typecheck job (spec:AST-030 FR26), so the
      # Lab package and the Storybook stories that import it are typechecked
      # here, against the packages this job just built: a type error that
      # landed would fail every later pull request's typecheck.
      - name: 'Lab-only: typecheck Lab and its stories'
        if: steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.lab_only == 'true'
        run: pnpm -F @astryxdesign/lab -F @astryxdesign/storybook typecheck

      # A Lab-only change whose route lock differs from the merge base checks
      # the lock against the registry the docsite builds from these packages
      # (spec:AST-030 FR26). Without a merge base, it checks anyway.
      - name: 'Lab-only: check the ShadCN route lock'
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && steps.scope.outputs.lab_only == 'true'
        env:
          DOCSITE_TARGET: canary
          MERGE_BASE: ${{ steps.merge-base.outputs.sha }}
        run: |
          if [ -n "$MERGE_BASE" ] && git diff --quiet "$MERGE_BASE" HEAD -- internal/shadcn-registry/routes.lock.json 2>/dev/null; then
            echo "The route lock matches the merge base."
            exit 0
          fi
          node apps/docsite/scripts/generate-data.mjs

      - name: Verify package exports
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true'
        run: node scripts/verify-exports.mjs

      # The story-tree check reads the built index and skips without one, so it
      # runs here, where Storybook was just built (apps/storybook/README.md).
      # This job builds the pull request's head, and a head that predates the
      # check carries the earlier test, which also rejects the A11y/ fixture
      # root; such a head skips the check, visibly, until it merges main.
      - name: Check the story tree
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true'
        run: |
          STORY_TREE_TEST=apps/storybook/.storybook/story-tree.test.ts
          if ! grep -q 'FIXTURE_ROOT' "$STORY_TREE_TEST"; then
            echo "::notice title=Head predates the story-tree check::Skipping the story-tree check; merge main to run it."
            exit 0
          fi
          pnpm exec vitest run --project node "$STORY_TREE_TEST"

      - name: Stamp Storybook source revision
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true'
        run: git rev-parse HEAD > apps/storybook/dist/astryx-build-sha.txt

      - name: Compute PR preview path
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && github.event_name == 'pull_request'
        id: urls
        run: |
          PR_NUMBER="${{ github.event.pull_request.number }}"
          COMMIT_HASH="${{ github.event.pull_request.head.sha }}"
          SHORT_HASH="${COMMIT_HASH:0:7}"

          echo "short_hash=${SHORT_HASH}" >> $GITHUB_OUTPUT
          echo "pr_number=${PR_NUMBER}" >> $GITHUB_OUTPUT

      - name: Identify full release audit scope
        if: github.event_name == 'workflow_dispatch' && steps.scope.outputs.tooling_only != 'true'
        id: release
        run: |
          test "$(git rev-parse HEAD)" = "$GITHUB_SHA"
          echo "short_hash=${GITHUB_SHA:0:7}" >> "$GITHUB_OUTPUT"
          printf '{"forceFullComponentAudits":true}\n' > analysis.json

      # The interaction proofs read it on a pull request, in main's nightly
      # full interaction run and in the weekly full WebKit run.
      - name: Upload Storybook artifact
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && (github.event_name == 'pull_request' || inputs.operation == 'release-check' || inputs.operation == 'interaction-full' || inputs.operation == 'webkit-weekly')
        uses: actions/upload-artifact@v7
        with:
          name: storybook-${{ steps.release.outputs.short_hash || steps.urls.outputs.short_hash }}
          path: apps/storybook/dist/
          retention-days: 30

      # pr-visual reads each theme's built source to learn which targets that
      # theme styles — a theme's component map is what defineTheme returns, not
      # a literal in its source. This job has already built them; shipping the
      # artifact keeps that job on a download instead of a second full build.
      #
      # core's dist ships with them because importing a built theme executes
      # `import {defineTheme} from '@astryxdesign/core/theme'`, which pnpm
      # resolves through the workspace link into packages/core/dist.
      #
      # Two paths, so the artifact is rooted at their common ancestor
      # (packages/) — the download below unpacks it there.
      - name: Upload built themes and core
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && (github.event_name == 'pull_request' || inputs.operation == 'release-check')
        uses: actions/upload-artifact@v7
        with:
          name: dists-${{ steps.release.outputs.short_hash || steps.urls.outputs.short_hash }}
          path: |
            packages/themes/*/dist/
            packages/core/dist/
          retention-days: 1

      # The merge base built beside the Storybook build: its record, or a
      # warning that Before and Delta stay empty. The wait is what it adds to
      # this job.
      - name: Wait for the merge base's sizes
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && steps.base-build.outputs.started == 'true'
        env:
          NEED_SIZES: ${{ steps.component-download.outcome != 'success' }}
        run: |
          waited=0
          while [ ! -f base-build.done ] && [ ! -f base-build.failed ] && [ "$waited" -lt 600 ]; do
            sleep 1
            waited=$((waited + 1))
          done
          tail -n 20 base-build.log || true
          if [ -f base-build.done ]; then
            echo "::notice title=Merge base built::Main kept no record of the merge base; it was built beside Storybook (waited ${waited}s after the build)."
          elif [ "$NEED_SIZES" = true ]; then
            rm -f .component-size-base/component-size.json
            echo "::warning title=Merge base not built::Building the merge base failed or timed out; Before and Delta stay empty."
          else
            echo "::warning title=Merge base not built::Building the merge base failed or timed out; the API changes are not compared."
          fi

      - name: Analyze components
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && github.event_name == 'pull_request'
        env:
          FULL_SUITE: ${{ steps.scope.outputs.full_suite }}
        run: |
          # Browser audits follow the changed components and their reverse
          # dependents, unless the change touches shared infrastructure.
          FORCE_FULL=()
          if [ "$FULL_SUITE" != false ]; then FORCE_FULL=(--force-full); fi
          BASE_RECORD=()
          if [ -f .component-size-base/component-size.json ]; then
            BASE_RECORD=(--base-record .component-size-base/component-size.json)
          fi
          node .github/scripts/analyze-pr.js \
            --base origin/${{ github.base_ref }} \
            --head HEAD \
            --output analysis.json \
            "${BASE_RECORD[@]}" \
            "${FORCE_FULL[@]}"

      # Published package size: this head's packages are built above, and Main
      # keeps each main commit's measurement for 14 days, so the merge base is
      # compared without building it. Only a pull request that changes a
      # package or the lockfile runs it.
      - name: Measure published package size
        id: package-size
        # A head cut before the check has no script to run (the workflow comes
        # from the merge ref, the checkout from the head): the scope step notes
        # it, and the check skips until the branch merges main.
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && github.event_name == 'pull_request' && steps.scope.outputs.head_file_present != 'false' && (steps.scope.outputs.touches == 'true' || steps.scope.outputs.full_suite != 'false')
        run: |
          node .github/scripts/package-size.mjs measure --output package-size-head.json
          echo "measured=true" >> "$GITHUB_OUTPUT"

      - name: Download main's package size for the merge base
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && steps.package-size.outputs.measured == 'true' && steps.size-records.outputs.package_run_id != ''
        continue-on-error: true
        uses: actions/download-artifact@v8
        with:
          name: package-size-main-${{ steps.merge-base.outputs.sha }}
          run-id: ${{ steps.size-records.outputs.package_run_id }}
          github-token: ${{ github.token }}
          path: .package-size-base

      # Advisory: a package over its budget is flagged in the job summary and
      # the PR report, and fails nothing.
      - name: Compare published package size
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && steps.scope.outputs.head_file_present != 'false' && steps.package-size.outputs.measured == 'true'
        env:
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
          BASE_SHA: ${{ steps.merge-base.outputs.sha }}
        run: |
          # Without a base, the report names why: no merge base was found, or
          # Main kept (or the lookup read) no measurement for it.
          BASE_REASON=not-kept
          if [ -z "$BASE_SHA" ]; then BASE_REASON=no-merge-base; fi
          node .github/scripts/package-size.mjs compare \
            --head package-size-head.json \
            --base .package-size-base/package-size.json \
            --base-reason "$BASE_REASON" \
            --head-sha "$HEAD_SHA" \
            --base-sha "$BASE_SHA" \
            --output package-size.json \
            --summary "$GITHUB_STEP_SUMMARY"

      - name: Write PR comment metadata
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && github.event_name == 'pull_request'
        run: |
          # PR Comment reads this exact-run analysis. Storybook and Sandbox
          # preview links are the branch's Vercel alias.
          cat > pr-meta.json <<EOF
          {
            "prNumber": "${{ steps.urls.outputs.pr_number }}",
            "shortHash": "${{ steps.urls.outputs.short_hash }}",
            "headSha": "${{ github.event.pull_request.head.sha }}",
            "headRepository": "${{ github.event.pull_request.head.repo.full_name }}",
            "baseRepository": "${{ github.event.pull_request.base.repo.full_name }}",
            "runId": "${{ github.run_id }}",
            "runAttempt": "${{ github.run_attempt }}",
            "runUrl": "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
          }
          EOF

      # Advisory API changes (architecture:public-component-api INV24): each
      # published package's report from this build, compared with the merge
      # base's surface (Main's record of it, else the base built above). A
      # package the surface lists but has no report for is reported as
      # unknown. With neither surface, nothing is compared: baseRecord is null
      # and each published package the pull request changes is unknown. It
      # reads the dists built above and never fails the job;
      # api-changes.json goes into the pr-analysis artifact. With no merge
      # base there is nothing to compare.
      # A head cut before cli.mjs existed cannot run the next step;
      # say so (merging main runs it).
      - name: Note a head that predates cli.mjs
        if: (steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && github.event_name == 'pull_request') && hashFiles('scripts/api-report/cli.mjs') == ''
        run: echo "::notice::This pull request's head has no cli.mjs; merging main runs the API change report."

      - name: Report API changes
        if: (steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && github.event_name == 'pull_request') && hashFiles('scripts/api-report/cli.mjs') != ''
        continue-on-error: true
        timeout-minutes: 2
        env:
          BASE_REF: ${{ github.base_ref }}
        run: |
          BASE_SHA=$(.github/scripts/merge-base.sh "$BASE_REF" 'the API changes' || true)
          [ -n "$BASE_SHA" ] || exit 0
          # Main's surface of the merge base, else the base built above,
          # reported here.
          SURFACE=()
          if grep -q -- "'--base-surface'" scripts/api-report/cli.mjs; then
            if [ -f .api-surface-base/surface.json ]; then
              SURFACE=(--base-surface .api-surface-base --base-record main)
            elif [ -f base-build.done ] && [ -d .size-base ]; then
              node scripts/api-report/cli.mjs --surface .api-surface-build --root .size-base \
                || echo "::notice::The merge base's API surface was not written; no API changes are compared."
              if [ -f .api-surface-build/surface.json ]; then
                SURFACE=(--base-surface .api-surface-build --base-record build)
              fi
            fi
          fi
          node scripts/api-report/cli.mjs --changes --base "$BASE_SHA" "${SURFACE[@]}"

      - name: Upload analysis artifact
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && (github.event_name == 'pull_request' || inputs.operation == 'release-check')
        uses: actions/upload-artifact@v7
        with:
          name: pr-analysis
          path: |
            analysis.json
            pr-meta.json
            package-size.json
            api-changes.json
            api-changes.md
          # merge-guard reads this run's api-changes.json up to a day after the
          # run, so the artifact outlives that.
          retention-days: 3

  # Typechecks run beside build-storybook instead of before its Storybook
  # build, so the browser checks that wait on the Storybook artifact start
  # ~1.5 minutes sooner. The build and release-check joins require this job,
  # so a type error still fails both.
  typecheck:
    needs: [room, admission]
    if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && ((github.event_name != 'workflow_dispatch' || inputs.operation == 'release-check') && always() && !cancelled() && needs.room.outputs.full != 'true' && needs.admission.outputs.full != 'true') }}
    runs-on: ${{ (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check' && github.triggering_actor != 'github-actions[bot]') && '2-core-ubuntu-arm' || 'ubuntu-24.04-arm' }}
    timeout-minutes: ${{ github.event_name == 'workflow_dispatch' && 360 || 15 }}
    permissions:
      contents: read
      pull-requests: read
    steps:
      # This job decides its own scope (no separate scope job): the step
      # reads the PR's file list and the base's trusted classifier, and
      # everything is in scope when it cannot decide.
      - name: Check out the scope action
        uses: actions/checkout@v7
        with:
          sparse-checkout: .github/actions/test-scope
          path: .test-scope
          persist-credentials: false

      - name: Decide this job's scope
        id: scope
        uses: ./.test-scope/.github/actions/test-scope

      - name: 'Lab-only: Lab tests + Storybook build'
        if: steps.scope.outputs.lab_only == 'true'
        run: |
          echo "::notice title=Lab-only::Lab-only: Lab tests + Storybook build. This job's work is not required for a change only to the Lab package (spec:AST-030 FR26)."

      - name: Skip typechecks for a specialized lane
        if: steps.scope.outputs.docsite_only == 'true' || steps.scope.outputs.spec_only == 'true' || steps.scope.outputs.tooling_only == 'true'
        run: echo "Specialized PR lane — skipping typechecks"

      - name: Checkout
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && steps.scope.outputs.lab_only != 'true'
        uses: actions/checkout@v7
        with:
          ref: ${{ github.event.pull_request.head.sha || github.sha }}

      - name: Setup Node and pnpm
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && steps.scope.outputs.lab_only != 'true'
        uses: ./.github/actions/setup

      # The doc, template and CLI typechecks resolve the built package types.
      - name: Build packages
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && steps.scope.outputs.lab_only != 'true'
        run: pnpm build

      # Every workspace package's own `typecheck` script: its sources and
      # tests, its doc examples, and any declarations it emits. A new package
      # or tsconfig joins by defining or extending that script, not this job.
      # A PR head cut before `pnpm typecheck` existed runs the previous list,
      # loaded from the merge commit these steps come from.
      - name: Typecheck every package
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && steps.scope.outputs.lab_only != 'true'
        env:
          WORKFLOW_SHA: ${{ github.sha }}
        run: |
          if node -e "process.exit(require('./package.json').scripts?.typecheck ? 0 : 1)"; then
            pnpm typecheck
          else
            echo "::notice title=Head predates pnpm typecheck::Running the previous typecheck list; merge main to use pnpm typecheck."
            legacy="$RUNNER_TEMP/typecheck-predating-head.sh"
            git fetch --quiet --no-tags --depth=1 origin "$WORKFLOW_SHA"
            git show "$WORKFLOW_SHA:.github/scripts/typecheck-predating-head.sh" > "$legacy"
            bash "$legacy"
          fi

  # Join gate that keeps the historical `build` check name: anything keyed on
  # "build" being green (branch protection, tooling, habit) keeps working, and
  # it fails when build-storybook or typecheck fails. On a pull request
  # outside its scope, build-storybook skips its own work and passes, so this
  # gate passes. A skipped build-storybook job (a draft) skips this gate too;
  # a fork pull request without `ci:run` still reports here.
  build:
    needs: [room, admission, heavy-ci, build-storybook, typecheck]
    if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft) && (github.event_name != 'workflow_dispatch' && !cancelled() && (needs.build-storybook.result != 'skipped' || needs.room.outputs.full == 'true' || needs.heavy-ci.outputs.deferred == 'true' || github.event_name == 'pull_request' && !(github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run')))) }}
    runs-on: ubuntu-slim
    permissions: {}
    steps:
      - name: Require a branch in this repository or the ci:run label
        if: ${{ github.event_name == 'pull_request' && !(github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run')) }}
        run: |
          echo "::error::Waiting for a maintainer's ci:run label: an outside contributor's pull request runs CI once a maintainer adds it (spec:AST-030 FR17)."
          exit 1
      - name: Stop when CI is full
        if: needs.room.outputs.full == 'true' || needs.admission.outputs.full == 'true'
        run: |
          echo "::error title=CI is full::CI is full: re-run all jobs or push later. The run found no room under the CI ceiling."
          exit 1

      # An agent lane's push defers the heavy suites (spec:AST-030 FR20): the
      # required check fails with the reason, never passes as skipped.
      - name: Heavy CI deferred
        if: needs.heavy-ci.outputs.deferred == 'true'
        run: |
          echo "::error::Heavy CI deferred: runs when marked ready and before merge (spec:AST-030 FR20)."
          exit 1

      - name: 'Lab-only: Lab tests + Storybook build'
        if: needs.build-storybook.outputs.lab_only == 'true'
        run: |
          echo "::notice title=Lab-only::Lab-only: Lab tests + Storybook build. The Storybook build job built the packages and typechecked Lab and its stories (spec:AST-030 FR26)."

      - name: Assert parallel builds succeeded
        run: |
          echo "build-storybook: ${{ needs.build-storybook.result }}"
          echo "typecheck:       ${{ needs.typecheck.result }}"
          [ "${{ needs.build-storybook.result }}" = "success" ] || exit 1
          [ "${{ needs.typecheck.result }}" = "success" ] || exit 1

  # CI keeps Storybook's static artifact for visual, accessibility, and RTL
  # checks. Vercel independently hosts both human Storybook and Sandbox
  # previews; the PR report links them through the branch's alias.

  # Accessibility audit
  # Skipped when no components changed. Depends only on build-storybook, so it
  # starts as soon as the storybook artifact is up (~2min).
  # The release check's full axe roster is scanned by six shard jobs and
  # joined, with the baseline gate, in pr-a11y-audit, while pr-a11y runs the
  # browser guards beside them. Pull requests audit only their scoped owners in
  # pr-a11y itself, so neither runs there.
  pr-a11y-shard:
    name: pr-a11y (${{ matrix.shard }}/${{ strategy.job-total }})
    needs: [admission, build-storybook]
    # A status check: heavy-ci, which skips on every run but an agent push,
    # is an ancestor (spec:AST-030 FR20); its skip must not skip this job.
    if: (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check') && !cancelled() && needs.admission.result == 'success' && needs.build-storybook.result == 'success'
    strategy:
      fail-fast: false
      matrix:
        shard: [1, 2, 3, 4, 5, 6]
    # Four pages on four cores. At three legs each leg's scan took ~10 minutes;
    # six take about five (spec:AST-030 FR23).
    runs-on: ${{ (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check' && github.triggering_actor != 'github-actions[bot]') && '4-core-ubuntu' || 'ubuntu-latest' }}
    timeout-minutes: 15
    permissions:
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@v7
        with:
          ref: ${{ github.event.pull_request.head.sha || github.sha }}

      - name: Setup Node and pnpm
        uses: ./.github/actions/setup
        with:
          install: 'false'

      - name: Download Storybook artifact
        uses: actions/download-artifact@v8
        with:
          name: storybook-${{ needs.build-storybook.outputs.short_hash }}
          path: apps/storybook/dist

      - name: Install Playwright
        run: pnpm install --frozen-lockfile && npx playwright install chromium

      - name: Run accessibility audit shard
        run: |
          node .github/scripts/accessibility-audit.js \
            --storybook-dir apps/storybook/dist \
            --concurrency 4 \
            --shard "${{ matrix.shard }}/${{ strategy.job-total }}" \
            --shard-output "a11y-shard-${{ matrix.shard }}.json"

      - name: Upload accessibility audit shard
        uses: actions/upload-artifact@v7
        with:
          name: a11y-shard-${{ needs.build-storybook.outputs.short_hash }}-${{ matrix.shard }}
          path: a11y-shard-${{ matrix.shard }}.json
          retention-days: 1
          if-no-files-found: error

  pr-a11y-audit:
    name: pr-a11y (full audit)
    needs: [build-storybook, pr-a11y-shard]
    if: ${{ always() && github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check' }}
    runs-on: ${{ (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check' && github.triggering_actor != 'github-actions[bot]') && '2-core-ubuntu-arm' || 'ubuntu-24.04-arm' }}
    permissions:
      contents: read
    steps:
      - name: Require every audit shard
        env:
          SHARD_RESULT: ${{ needs.pr-a11y-shard.result }}
        run: |
          if [ "$SHARD_RESULT" != success ]; then
            echo "Accessibility audit shards did not all succeed: $SHARD_RESULT"
            exit 1
          fi

      - name: Checkout
        uses: actions/checkout@v7
        with:
          ref: ${{ github.event.pull_request.head.sha || github.sha }}

      - name: Setup Node and pnpm
        uses: ./.github/actions/setup

      - name: Download Storybook artifact
        uses: actions/download-artifact@v8
        with:
          name: storybook-${{ needs.build-storybook.outputs.short_hash }}
          path: apps/storybook/dist

      - name: Download accessibility audit shards
        uses: actions/download-artifact@v8
        with:
          pattern: a11y-shard-${{ needs.build-storybook.outputs.short_hash }}-*
          path: a11y-shards
          merge-multiple: true

      # Builds the report a single full run would write from the complete
      # shard set (or fails), then applies the checked-in baseline.
      - name: Run accessibility audit
        run: |
          node .github/scripts/accessibility-audit.js \
            --storybook-dir apps/storybook/dist \
            --output a11y-report.json \
            --merge-shards a11y-shards \
            --baseline .github/a11y-baseline.json \
            --fail-on-new

      - name: Upload a11y artifact
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: a11y-report
          path: a11y-report.json
          retention-days: 1

  pr-a11y-guards:
    name: pr-a11y (audit and guards)
    needs: [build-storybook, run-labels]
    # A status check: heavy-ci, which skips on every run but an agent push,
    # is an ancestor (spec:AST-030 FR20); its skip must not skip this job.
    if: (((github.event_name == 'pull_request' && needs.run-labels.outputs.a11y == 'true') || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'))) && !cancelled() && needs.build-storybook.result == 'success' && needs.run-labels.result == 'success'
    runs-on: ${{ (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check' && github.triggering_actor != 'github-actions[bot]') && '2-core-ubuntu-arm' || 'ubuntu-24.04-arm' }}
    timeout-minutes: ${{ github.event_name == 'workflow_dispatch' && 360 || 15 }}
    permissions:
      contents: read
      pull-requests: read
    steps:
      # This job decides its own component scope (no separate scope job):
      # the step reads the PR's file list and the base's trusted classifiers.
      # Outside a pull request every audit applies in full.
      - name: Check out the scope action
        uses: actions/checkout@v7
        with:
          sparse-checkout: .github/actions/test-scope
          path: .test-scope
          persist-credentials: false

      - name: Decide this job's component scope
        id: scope
        uses: ./.test-scope/.github/actions/test-scope
        with:
          component-audit: 'true'

      - name: Checkout
        uses: actions/checkout@v7
        with:
          ref: ${{ github.event.pull_request.head.sha || github.sha }}

      - name: Verify evidence checkout
        if: (github.event_name == 'pull_request') && steps.scope.outputs.has_components == 'true'
        env:
          EXPECTED_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
        run: test "$(git rev-parse HEAD)" = "$EXPECTED_HEAD_SHA"

      # Dependencies are installed later, together with the Playwright browser,
      # because the analysis artifact has to be downloaded first.
      - name: Setup Node and pnpm
        if: steps.scope.outputs.has_components == 'true'
        uses: ./.github/actions/setup
        with:
          install: 'false'

      - name: Download analysis artifact
        if: steps.scope.outputs.has_components == 'true'
        uses: actions/download-artifact@v8
        with:
          name: pr-analysis

      - name: Download Storybook artifact
        if: steps.scope.outputs.has_components == 'true'
        uses: actions/download-artifact@v8
        with:
          name: storybook-${{ needs.build-storybook.outputs.short_hash }}
          path: apps/storybook/dist

      - name: Install Playwright
        if: steps.scope.outputs.has_components == 'true'
        run: pnpm install --frozen-lockfile && npx playwright install chromium

      # Fails on axe violations not present in the checked-in baseline
      # (.github/a11y-baseline.json). See CONTRIBUTING.md "Accessibility
      # audits" for the baseline workflow.
      # Release checks scan the full roster in pr-a11y-shard and gate it in
      # pr-a11y-audit; this job keeps the scoped PR audit and the guards.
      - name: Run accessibility audit
        if: (github.event_name == 'pull_request') && steps.scope.outputs.has_components == 'true'
        run: |
          SCOPE_ARGS=()
          if [ "${{ github.event_name }}" = 'pull_request' ]; then
            COMPONENTS=$(node .github/scripts/a11y-pr-scope.mjs analysis.json)
            # An explicit empty filter means no changed components, never all
            # stories. Shared-surface full sweeps belong to release-check.
            SCOPE_ARGS=(--components "$COMPONENTS")
            echo "PR accessibility scope: ${COMPONENTS:-no changed components; fast browser guards still run}"
          fi
          node .github/scripts/accessibility-audit.js \
            --storybook-dir apps/storybook/dist \
            --output a11y-report.json \
            --concurrency 4 \
            "${SCOPE_ARGS[@]}" \
            --baseline .github/a11y-baseline.json \
            --fail-on-new

      # if: always() so the report artifact (and the PR comment built from it)
      # still exists when the gate above fails.
      - name: Upload a11y artifact
        if: (always() && github.event_name == 'pull_request') && steps.scope.outputs.has_components == 'true'
        uses: actions/upload-artifact@v7
        with:
          name: a11y-report
          path: a11y-report.json
          retention-days: 1

      # A modal <dialog> hidden before close() blocks the whole page in Safari
      # 26.1 and leaves no trace (#4290). The ordering is produced by a CSS
      # transition, which jsdom does not run — so the unit suite cannot see it
      # and this Chromium probe is the guard. Runs after the upload above so an
      # a11y failure still publishes its report.
      - name: Run modal close visibility guard
        if: steps.scope.outputs.has_components == 'true'
        run: node .github/scripts/modal-close-visibility.js --storybook-dir apps/storybook/dist

      # A public component var can be documented, read, and emitted into the
      # theme CSS and still be unreachable — an inline write or an unlayered
      # declaration outranks `@layer astryx-theme` (#4530). jsdom resolves no
      # cascade, so the unit suites assert on the generated CSS text, which
      # proves emission and not effect. Chromium is where the promise is
      # checkable. The source-side wiring half lives in
      # packages/cli/foundation/discovery/theming-targets.test.mjs.
      - name: Run theme var reachability guard
        if: steps.scope.outputs.has_components == 'true'
        run: node .github/scripts/theme-var-reachability.js --storybook-dir apps/storybook/dist

      # A story play function is where geometry assertions live (they need
      # getBoundingClientRect, so jsdom is out), but nothing else observes the
      # result: Vitest never collects stories, and pr-visual loads stories
      # without awaiting `play` — and is soft while it earns trust. This guard
      # loads each listed story in Chromium and fails when its play assertions
      # throw. Hosted here with the sibling Chromium guards because pr-a11y is
      # the blocking job that runs whenever components change.
      - name: Run story play guard
        if: steps.scope.outputs.has_components == 'true'
        run: node .github/scripts/story-play-guard.js --storybook-dir apps/storybook/dist

  # Browser accessibility specs get their own budget. The scoped axe sweep and
  # the always-on Chromium guards consume most of a pull request's 15-minute
  # job budget before these specs start; running beside them keeps both owners
  # inside the budget without weakening the stable pr-a11y join.
  pr-a11y-specs:
    name: pr-a11y (browser specs ${{ matrix.leg }}/${{ strategy.job-total }})
    needs: [build-storybook, run-labels]
    # A status check: heavy-ci, which skips on every run but an agent push,
    # is an ancestor (spec:AST-030 FR20); its skip must not skip this job.
    if: (((github.event_name == 'pull_request' && needs.run-labels.outputs.a11y == 'true') || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'))) && !cancelled() && needs.build-storybook.result == 'success' && needs.run-labels.result == 'success'
    runs-on: ${{ (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check' && github.triggering_actor != 'github-actions[bot]') && '2-core-ubuntu-arm' || 'ubuntu-24.04-arm' }}
    timeout-minutes: ${{ github.event_name == 'workflow_dispatch' && 360 || 15 }}
    # A pull request's selection splits into up to three legs by recorded
    # time, each about ten minutes or less on one worker; a leg the selection
    # does not need stops after its count step. A release check runs every
    # spec in one job.
    strategy:
      fail-fast: false
      matrix:
        leg: ${{ fromJSON(github.event_name == 'workflow_dispatch' && '[1]' || '[1, 2, 3]') }}
    permissions:
      contents: read
      pull-requests: read
    steps:
      # This job decides its own component scope (no separate scope job):
      # the step reads the PR's file list and the base's trusted classifiers.
      # Outside a pull request every audit applies in full.
      - name: Check out the scope action
        uses: actions/checkout@v7
        with:
          sparse-checkout: .github/actions/test-scope
          path: .test-scope
          persist-credentials: false

      - name: Decide this job's component scope
        id: scope
        uses: ./.test-scope/.github/actions/test-scope
        with:
          component-audit: 'true'

      - name: Checkout
        uses: actions/checkout@v7
        with:
          ref: ${{ github.event.pull_request.head.sha || github.sha }}

      - name: Verify evidence checkout
        if: (github.event_name == 'pull_request') && steps.scope.outputs.has_components == 'true'
        env:
          EXPECTED_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
        run: test "$(git rev-parse HEAD)" = "$EXPECTED_HEAD_SHA"

      - name: Setup Node and pnpm
        if: steps.scope.outputs.has_components == 'true'
        uses: ./.github/actions/setup
        with:
          install: 'false'

      - name: Download analysis artifact
        if: steps.scope.outputs.has_components == 'true'
        uses: actions/download-artifact@v8
        with:
          name: pr-analysis

      # Before the count: a pull request that changes a multi-component folder
      # (Chat, Layer, Chart and the like) resolves its components through the
      # built Storybook's story index.
      - name: Download Storybook artifact
        if: steps.scope.outputs.has_components == 'true'
        uses: actions/download-artifact@v8
        with:
          name: storybook-${{ needs.build-storybook.outputs.short_hash }}
          path: apps/storybook/dist

      # How many legs the selection needs, from the specs' recorded times, and
      # this leg's share, which the run step reads. It runs before the
      # Chromium install; listing the specs installs the workspace's
      # dependencies. The runner, its routing lines and the
      # times come from the merge commit. The merge commit's first parent is
      # the base branch tip that it merges into.
      - name: Count this run's accessibility legs
        id: legs
        if: steps.scope.outputs.has_components == 'true'
        env:
          ASTRYX_HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
          PR_TITLE: ${{ github.event.pull_request.title }}
          WORKFLOW_SHA: ${{ github.sha }}
        run: |
          runner="$RUNNER_TEMP/a11y/.github/scripts/a11y-pr-contracts.mjs"
          mkdir -p "$RUNNER_TEMP/a11y/.github/scripts" "$RUNNER_TEMP/a11y/scripts/lib"
          git fetch --quiet --no-tags --depth=2 origin "$WORKFLOW_SHA"
          git show "$WORKFLOW_SHA:.github/scripts/a11y-pr-contracts.mjs" > "$runner"
          git show "$WORKFLOW_SHA:scripts/lib/duration-split.mjs" > "$RUNNER_TEMP/a11y/scripts/lib/duration-split.mjs"
          BASE_SHA=$(git rev-parse "$WORKFLOW_SHA^1")
          export BASE_SHA
          node "$runner" --count-legs ${{ strategy.job-total }} --leg ${{ matrix.leg }} --share-out "$RUNNER_TEMP/a11y-leg-share.json"

      - name: Leave the specs to the legs that have a share
        if: steps.scope.outputs.has_components == 'true' && steps.legs.outputs.runs != 'true'
        run: echo "This leg runs no accessibility specs (${{ steps.legs.outputs.count }} leg(s) planned for this selection)."

      - name: Install Playwright
        if: steps.scope.outputs.has_components == 'true' && steps.legs.outputs.runs == 'true'
        run: pnpm install --frozen-lockfile && npx playwright install chromium

      # The runner runs every spec playwright.config.ts matches whose own
      # `@pr-a11y` routing lines select it for this pull request. The runner and
      # routing lines come from the merge commit these steps come from, so an
      # older PR head is routed by current policy while specs run at that head.
      - name: Run browser accessibility specs
        if: (!cancelled()) && steps.scope.outputs.has_components == 'true' && steps.legs.outputs.runs == 'true'
        env:
          ASTRYX_HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
          PR_TITLE: ${{ github.event.pull_request.title }}
          WORKFLOW_SHA: ${{ github.sha }}
        # This leg runs exactly the share its count step planned, with the
        # merge commit's runner, which the count step fetched.
        run: |
          runner="$RUNNER_TEMP/a11y/.github/scripts/a11y-pr-contracts.mjs"
          git show "$WORKFLOW_SHA:.github/scripts/a11y-pr-contracts.mjs" > "$runner"
          node "$runner" --share "$RUNNER_TEMP/a11y-leg-share.json" --leg ${{ steps.legs.outputs.leg }} --of ${{ steps.legs.outputs.count }}

      - name: Upload browser accessibility evidence
        if: (!cancelled()) && steps.scope.outputs.has_components == 'true' && steps.legs.outputs.runs == 'true'
        uses: actions/upload-artifact@v7
        with:
          name: pr-a11y-evidence-${{ needs.build-storybook.outputs.short_hash }}-${{ matrix.leg }}
          path: |
            pr-a11y-evidence/
            pr-a11y-output/
            test-results/
            *-audit-evidence/
          retention-days: 30
          if-no-files-found: ignore

  # Stable required context joining the scoped audit/guards and browser specs.
  pr-a11y:
    needs: [pr-a11y-guards, pr-a11y-specs, run-labels]
    if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (always() && ((github.event_name == 'pull_request' && needs.run-labels.outputs.a11y == 'true') || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'))) }}
    runs-on: ubuntu-slim
    timeout-minutes: 5
    permissions:
      contents: read
    steps:
      - name: Require every accessibility owner
        env:
          GUARDS_RESULT: ${{ needs.pr-a11y-guards.result }}
          SPECS_RESULT: ${{ needs.pr-a11y-specs.result }}
        run: |
          if [ "$GUARDS_RESULT" != success ] || [ "$SPECS_RESULT" != success ]; then
            echo "Accessibility owners did not all succeed: guards=$GUARDS_RESULT specs=$SPECS_RESULT"
            exit 1
          fi

  # Release-only accessibility contracts run beside pr-a11y instead of after
  # its full axe sweep, so the release check waits for the longer of the two
  # rather than their sum. release-check requires this job as it requires
  # pr-a11y.
  a11y-contracts-shard:
    name: Accessibility spec-test contracts (${{ matrix.shard }}/${{ strategy.job-total }})
    needs: [admission, build-storybook]
    # A status check: heavy-ci, which skips on every run but an agent push,
    # is an ancestor (spec:AST-030 FR20); its skip must not skip this job.
    if: (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check') && !cancelled() && needs.admission.result == 'success' && needs.build-storybook.result == 'success'
    # Six legs: at three, the slowest leg took ~20 minutes, held by its longest
    # spec file; files longer than a leg's share are now cut across legs
    # (spec:AST-030 FR23).
    strategy:
      fail-fast: false
      matrix:
        shard: [1, 2, 3, 4, 5, 6]
    # One core per worker: on two cores, four workers starved the CPU-bound
    # "every expectation" specs past their timeouts.
    runs-on: ${{ (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check' && github.triggering_actor != 'github-actions[bot]') && '4-core-ubuntu' || 'ubuntu-latest' }}
    timeout-minutes: 15
    permissions:
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@v7
        with:
          ref: ${{ github.event.pull_request.head.sha || github.sha }}

      - name: Setup Node and pnpm
        uses: ./.github/actions/setup
        with:
          install: 'false'

      - name: Download Storybook artifact
        uses: actions/download-artifact@v8
        with:
          name: storybook-${{ needs.build-storybook.outputs.short_hash }}
          path: apps/storybook/dist

      - name: Install Playwright
        run: pnpm install --frozen-lockfile && npx playwright install chromium

      # The exhaustive contract/fixture matrix. PRs retain scoped axe
      # validation and the fast interaction guards in pr-a11y; they must not
      # pay for every component's browser bindings on every change.
      - name: Run accessibility spec-test contracts
        if: github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'
        env:
          ASTRYX_HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
          A11Y_CONTRACT_WORKERS: 4
          # The Table release proof's timing budgets hold on 4-core-ubuntu only;
          # on the bot's ubuntu-latest checks, cut-evidence runs included, its
          # receipt reports timing (spec:AST-030 DEC-17). Moving cut-evidence
          # runs to the release runner adds `inputs.evidence` to this one
          # condition, which runs-on shares (ci-table-timing-gate.test.mjs).
          ASTRYX_TABLE_TIMING_GATE: ${{ (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check' && github.triggering_actor != 'github-actions[bot]') && '1' || '0' }}
        # Tests are split by recorded duration (a11y-contract-shard.mjs), not
        # Playwright's count-based --shard; every listed test runs in one leg.
        run: |
          set -euo pipefail
          node .github/scripts/a11y-contract-shard.mjs --shard "${{ matrix.shard }}/${{ strategy.job-total }}" > contract-tests.txt
          pnpm exec playwright test --test-list contract-tests.txt --config playwright.config.ts --project chromium

      - name: Upload pressed-state pixel evidence
        if: always() && github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'
        uses: actions/upload-artifact@v7
        with:
          name: pressed-state-evidence-${{ needs.build-storybook.outputs.short_hash }}-${{ matrix.shard }}
          path: test-results/pressed-state-evidence/
          # A failing run keeps its evidence here (the join merges only after
          # every leg passed, then deletes these copies).
          retention-days: 30
          # Only the shard that ran the spec has frames; the join requires them.
          if-no-files-found: ignore

      # Component-audit browser evidence. A whole-component audit has to show
      # the states it graded, and the audit node cannot always run a browser —
      # so the frames and their sensor receipts are produced here, bound to the
      # same exact head as every other check in this job.
      - name: Upload component-audit browser evidence
        if: always() && github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'
        uses: actions/upload-artifact@v7
        with:
          name: component-audit-evidence-${{ needs.build-storybook.outputs.short_hash }}-${{ matrix.shard }}
          path: test-results/chat-layout-audit-evidence/
          retention-days: 30
          if-no-files-found: ignore

  # Joins the contract shards for release-check: every shard must pass, and
  # each evidence set is rebuilt under its usual artifact name. A set no shard
  # produced fails the merge, as the single job's upload used to fail.
  a11y-contracts:
    name: Accessibility spec-test contracts
    needs: [build-storybook, a11y-contracts-shard]
    if: ${{ always() && github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check' }}
    runs-on: ubuntu-slim
    permissions: {}
    steps:
      - name: Require every contract shard
        env:
          SHARD_RESULT: ${{ needs.a11y-contracts-shard.result }}
        run: |
          if [ "$SHARD_RESULT" != success ]; then
            echo "Accessibility contract shards did not all succeed: $SHARD_RESULT"
            exit 1
          fi

      - name: Join pressed-state pixel evidence
        uses: actions/upload-artifact/merge@v7
        with:
          name: pressed-state-evidence-${{ needs.build-storybook.outputs.short_hash }}
          pattern: pressed-state-evidence-${{ needs.build-storybook.outputs.short_hash }}-*
          retention-days: 30
          delete-merged: true

      - name: Join component-audit browser evidence
        uses: actions/upload-artifact/merge@v7
        with:
          name: component-audit-evidence-${{ needs.build-storybook.outputs.short_hash }}
          pattern: component-audit-evidence-${{ needs.build-storybook.outputs.short_hash }}-*
          retention-days: 30
          delete-merged: true

  # How many legs each interaction lane starts. It counts each lane the way
  # its legs do (same scope, planner and recorded times, at most ten legs),
  # so a lane starts only the legs that have a share. A leg fails when its
  # own count needs more legs than started.
  interaction-legs:
    name: interaction-legs
    needs: [room, admission, heavy-ci, webkit-weekly-request]
    if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && needs.heavy-ci.outputs.deferred != 'true' && ((github.event_name != 'workflow_dispatch' || inputs.operation == 'interaction-full' && github.ref == 'refs/heads/main' || inputs.operation == 'webkit-weekly' && needs.webkit-weekly-request.result == 'success') && always() && !cancelled() && needs.room.outputs.full != 'true' && needs.admission.outputs.full != 'true')) }}
    runs-on: ubuntu-latest
    timeout-minutes: 5
    permissions:
      # The release check reads the weekly WebKit verdicts.
      actions: read
      contents: read
      pull-requests: read
    env:
      # The code where WebKit and Chromium differ on touch, and the lane's
      # shared setup. A change to it runs WEBKIT_SPEC_PATHS.
      WEBKIT_SHARED_PATHS: '^(packages/core/src/gestures/|packages/core/src/motion/|packages/core/src/internal/touch|packages/core/src/utils/(press|touch|primaryClick|isApplePlatform|flatTree|inputStream|clickGuard|selectionLock|coarsePointer|sharedResizeObserver|scrollView|nodeType|inputAge)|packages/core/src/privateAttributes/(hapticSwitch|reducedMotion)\.stylex\.ts$|packages/core/src/theme/tokenReferences\.ts$|packages/core/src/Layer/(inputHold|modalOutlet)\.ts$|packages/core/src/hooks/(useMenuPress|menuPress|useLongPress|usePressFeedback|isRtlElement|useIsomorphicLayoutEffect|useAttachment|usePager|__tests__/(usePager|pagerBundle))|internal/interaction-harness/|internal/a11y-spec/|playwright\.interaction\.config\.ts$|packages/themes/[^/]+/src/|apps/storybook/|\.github/workflows/ci\.yml$|package\.json$|pnpm-lock\.yaml$|\.github/scripts/(playwright-legs|a11y-pr-contracts|lane-environment)\.mjs$|\.github/scripts/(stale-head-hint|merge-base)\.sh$|scripts/lib/duration-split\.mjs$|\.github/(playwright-leg-durations|lane-environments)\.json$|\.github/actions/test-scope/|.*\.interaction\.browser\.spec\.ts$)'
      # The release interaction check's throwaway pull request: an
      # interaction-check/ branch in this repository, opened by the account
      # the release tooling uses. It runs the full WebKit suite when the last
      # full weekly run failed or is more than seven days old, and at a minor
      # release; otherwise the subset below, as a pull request does
      # ("Decide the WebKit scope", spec:AST-030 DEC-24).
      WEBKIT_RELEASE_CHECK: ${{ startsWith(github.head_ref, 'interaction-check/') && github.event.pull_request.user.login == 'cixzhang' && github.event.pull_request.head.repo.full_name == github.repository }}
      # The weekly full WebKit run on main (webkit-weekly.yml).
      WEBKIT_WEEKLY: ${{ github.event_name == 'workflow_dispatch' && inputs.operation == 'webkit-weekly' }}
      # The specs a shared-code change runs. Besides them, a change runs each
      # interaction spec it edits, and every interaction spec in a component
      # folder whose code it changes (`playwright-legs.mjs select`).
      WEBKIT_SPEC_PATHS: >-
        packages/core/src/gestures/
        packages/core/src/motion/__tests__/animatedLayout.interaction
        packages/core/src/motion/__tests__/animator.interaction
        packages/core/src/hooks/__tests__/usePager.interaction
        internal/interaction-harness/
    outputs:
      chromium: ${{ steps.matrix.outputs.chromium }}
      webkit: ${{ steps.matrix.outputs.webkit }}
      chromium_specs: ${{ steps.select-chromium.outputs.specs }}
    steps:
      - name: Check out the scope action
        uses: actions/checkout@v7
        with:
          sparse-checkout: |
            .github/actions/test-scope
            .github/scripts
            scripts/lib
          path: .test-scope
          persist-credentials: false

      - name: Decide the Chromium proofs' scope
        id: scope-chromium
        uses: ./.test-scope/.github/actions/test-scope
        with:
          # Unit tests, docs, records and accessibility specs in a component
          # folder (packages/<component package>/src/<Component>/) put nothing
          # on a page these proofs load, so they stay out of scope. Shared
          # folders, src roots, theme sources and every other package are
          # shared code and stay in.
          paths: '^(internal/interaction-harness/|internal/a11y-spec/|playwright\.interaction\.config\.ts$|packages/(?!(?:core|lab|charts|richtext|vega)/)[^/]+/src/|packages/(?:core|lab|charts|richtext|vega)/src/(?![A-Z][^/]*/)|packages/(?:core|lab|charts|richtext|vega)/src/[A-Z][^/]*/(?!.*(?:\.test\.[^/]+|\.doc\.mjs|\.md|\.a11y\.[^/]+\.spec\.ts)$)|packages/themes/[^/]+/src/|packages/[^/]+/src/theme/|apps/storybook/|\.github/workflows/ci\.yml$|package\.json$|pnpm-lock\.yaml$|\.github/scripts/(playwright-legs|a11y-pr-contracts|lane-environment)\.mjs$|\.github/scripts/(stale-head-hint|merge-base)\.sh$|scripts/lib/duration-split\.mjs$|\.github/(playwright-leg-durations|lane-environments)\.json$|\.github/actions/test-scope/|.*\.interaction\.browser\.spec\.ts$)'
          # Main's nightly full run plans every spec; a merge-group entry plans
          # none.
          outside-pull-request: ${{ inputs.operation == 'interaction-full' && 'run' || 'skip' }}
          requires-head-file: playwright.interaction.config.ts
          # A Lab-only change still runs each interaction spec it edits.
          lab-only-specs: '\.interaction\.browser\.spec\.ts$'
          # Lists the changed files, so the Chromium selection reads them.
          component-audit: 'true'

      - name: Decide the WebKit proofs' scope
        id: scope-webkit
        uses: ./.test-scope/.github/actions/test-scope
        with:
          # Unit tests, docs, records and accessibility specs in a component
          # folder (packages/<component package>/src/<Component>/) put nothing
          # on a page these proofs load, so they stay out of scope. Shared
          # folders, src roots, theme sources and every other package are
          # shared code and stay in.
          paths: '^(packages/(?!(?:core|lab|charts|richtext|vega)/)[^/]+/src/[^/]+/|packages/(?:core|lab|charts|richtext|vega)/src/(?![A-Z])[^/]+/|packages/(?:core|lab|charts|richtext|vega)/src/[A-Z][^/]*/(?!.*(?:\.test\.[^/]+|\.doc\.mjs|\.md|\.a11y\.[^/]+\.spec\.ts)$)|internal/interaction-harness/|internal/a11y-spec/|playwright\.interaction\.config\.ts$|packages/themes/[^/]+/src/|packages/[^/]+/src/theme/|apps/storybook/|\.github/workflows/ci\.yml$|package\.json$|pnpm-lock\.yaml$|\.github/scripts/(playwright-legs|a11y-pr-contracts|lane-environment)\.mjs$|scripts/lib/duration-split\.mjs$|\.github/(playwright-leg-durations|lane-environments)\.json$|\.github/actions/test-scope/|.*\.interaction\.browser\.spec\.ts$|\.github/scripts/(stale-head-hint|merge-base)\.sh$)'
          outside-pull-request: ${{ inputs.operation == 'webkit-weekly' && 'run' || 'skip' }}
          requires-head-file: playwright.interaction.config.ts
          # A Lab-only change still runs each interaction spec it edits.
          lab-only-specs: '\.interaction\.browser\.spec\.ts$'
          # Lists the changed files, so the planner adds a changed spec.
          component-audit: 'true'

      - name: Keep the leg planner from the workflow's commit
        if: steps.scope-chromium.outputs.applies == 'true' || steps.scope-webkit.outputs.applies == 'true'
        run: |
          mkdir -p "$RUNNER_TEMP/interaction-legs/.github/scripts" "$RUNNER_TEMP/interaction-legs/scripts/lib"
          cp .test-scope/.github/scripts/playwright-legs.mjs "$RUNNER_TEMP/interaction-legs/.github/scripts/"
          cp .test-scope/scripts/lib/duration-split.mjs "$RUNNER_TEMP/interaction-legs/scripts/lib/"
          cp .test-scope/.github/scripts/a11y-pr-contracts.mjs "$RUNNER_TEMP/interaction-legs/.github/scripts/"
          cp .test-scope/.github/playwright-leg-durations.json "$RUNNER_TEMP/interaction-legs/.github/"
          cp .test-scope/.github/scripts/lane-environment.mjs "$RUNNER_TEMP/interaction-legs/.github/scripts/"
          cp .test-scope/.github/scripts/stale-head-hint.sh "$RUNNER_TEMP/interaction-legs/.github/scripts/"
          cp .test-scope/.github/scripts/merge-base.sh "$RUNNER_TEMP/interaction-legs/.github/scripts/"
          cp .test-scope/.github/lane-environments.json "$RUNNER_TEMP/interaction-legs/.github/"

      # The Chromium selection (spec:AST-030 FR31): the specs a pull request
      # reaches, or `full`. Its import graphs read the merge commit's package,
      # harness and Storybook sources. The leg count and every leg read its
      # output; an empty output (a failed or skipped step) runs the full
      # suite. The artifact feeds the escape log.
      - name: Select the Chromium proofs
        id: select-chromium
        if: github.event_name == 'pull_request' && steps.scope-chromium.outputs.applies == 'true' && steps.scope-chromium.outputs.lab_specs_path == ''
        continue-on-error: true
        # A slow sparse fetch must not time out the whole job.
        timeout-minutes: 2
        env:
          CHANGED_FILES: ${{ steps.scope-chromium.outputs.changed_files_path }}
          FULL_SUITE: ${{ steps.scope-chromium.outputs.full_suite }}
          SCOPE_PATHS: '^(internal/interaction-harness/|internal/a11y-spec/|playwright\.interaction\.config\.ts$|packages/(?!(?:core|lab|charts|richtext|vega)/)[^/]+/src/|packages/(?:core|lab|charts|richtext|vega)/src/(?![A-Z][^/]*/)|packages/(?:core|lab|charts|richtext|vega)/src/[A-Z][^/]*/(?!.*(?:\.test\.[^/]+|\.doc\.mjs|\.md|\.a11y\.[^/]+\.spec\.ts)$)|packages/themes/[^/]+/src/|packages/[^/]+/src/theme/|apps/storybook/|\.github/workflows/ci\.yml$|package\.json$|pnpm-lock\.yaml$|\.github/scripts/(playwright-legs|a11y-pr-contracts|lane-environment)\.mjs$|\.github/scripts/(stale-head-hint|merge-base)\.sh$|scripts/lib/duration-split\.mjs$|\.github/(playwright-leg-durations|lane-environments)\.json$|\.github/actions/test-scope/|.*\.interaction\.browser\.spec\.ts$)'
        run: |
          set -o pipefail
          listed="$RUNNER_TEMP/interaction-legs/listed.txt"
          git -C .test-scope ls-tree -r --name-only HEAD > "$listed"
          mapfile -t SOURCES < <(grep -oE '^packages/[^/]+/src/' "$listed" | sort -u)
          git -C .test-scope sparse-checkout add "${SOURCES[@]}" internal/interaction-harness apps/storybook/stories apps/storybook/.storybook
          node "$RUNNER_TEMP/interaction-legs/.github/scripts/playwright-legs.mjs" select-chromium \
            --listed "$listed" --changed "${CHANGED_FILES:-}" \
            --scope "$SCOPE_PATHS" --full-suite "${FULL_SUITE:-true}" \
            --every-spec "${WEBKIT_RELEASE_CHECK:-false}" --root .test-scope \
            --selection .test-scope/.github/interaction-selection.json \
            --primitives .test-scope/.github/a11y-shared-primitives.json \
            --out "$RUNNER_TEMP/interaction-legs/chromium-selection.json" | tee -a "$GITHUB_STEP_SUMMARY"
          node -e 'const r = JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8")); console.log(`specs=${r.full ? "full" : JSON.stringify(r.specs)}`)' \
            "$RUNNER_TEMP/interaction-legs/chromium-selection.json" >> "$GITHUB_OUTPUT"

      - name: Keep the Chromium selection
        if: steps.select-chromium.outcome == 'success'
        uses: actions/upload-artifact@v7
        with:
          name: interaction-selection-${{ github.run_attempt }}
          path: ${{ runner.temp }}/interaction-legs/chromium-selection.json
          retention-days: 90

      - name: Count the Chromium legs
        id: count-chromium
        if: steps.scope-chromium.outputs.applies == 'true'
        continue-on-error: true
        env:
          LAB_SPECS: ${{ steps.scope-chromium.outputs.lab_specs_path }}
          CHROMIUM_SPECS: ${{ steps.select-chromium.outputs.specs }}
        run: |
          # A Lab-only change runs only the interaction specs it edits; any
          # other pull request runs the Chromium selection, and `full` or no
          # selection runs every spec.
          FILTERS=()
          if [ -n "${LAB_SPECS:-}" ]; then mapfile -t LAB < "$LAB_SPECS"; FILTERS=(-- "${LAB[@]}")
          elif [ -n "${CHROMIUM_SPECS:-}" ] && [ "$CHROMIUM_SPECS" != full ]; then
            # A selection that does not parse runs every spec.
            if ! PICKED_LINES=$(node -e 'for (const file of JSON.parse(process.env.CHROMIUM_SPECS)) console.log(file)'); then
              echo "::warning::The Chromium selection does not parse, so every spec runs."
            elif [ -z "$PICKED_LINES" ]; then
              echo "No Chromium interaction proof covers this change: it touches no proof, no component folder that holds one or renders one, and no shared code."
              printf 'count=0\nruns=false\nleg=1\n' >> "$GITHUB_OUTPUT"
              exit 0
            else
              mapfile -t PICKED <<< "$PICKED_LINES"
              FILTERS=(-- "${PICKED[@]}")
            fi
          fi
          git -C .test-scope ls-tree -r --name-only HEAD > "$RUNNER_TEMP/interaction-legs/listed.txt"
          node "$RUNNER_TEMP/interaction-legs/.github/scripts/playwright-legs.mjs" legs \
            --listed "$RUNNER_TEMP/interaction-legs/listed.txt" --source .test-scope \
            --tests-out "$RUNNER_TEMP/interaction-legs/tests.json" \
            --key interaction-chromium --fallback-key interaction-webkit \
            --durations "$RUNNER_TEMP/interaction-legs/.github/playwright-leg-durations.json" \
            --setup-seconds 90 --max-seconds 600 \
            --leg 1 --max-legs 10 \
            "${FILTERS[@]}"

      # The full WebKit suite on the weekly run; for a release check, the
      # last full weekly run's verdict and the release version decide; every
      # other run keeps the subset (spec:AST-030 DEC-24).
      - name: Decide the WebKit scope
        if: steps.scope-webkit.outputs.applies == 'true'
        env:
          GITHUB_TOKEN: ${{ github.token }}
          RELEASE_TITLE: ${{ github.event.pull_request.title }}
        run: |
          if [ "${WEBKIT_WEEKLY:-}" = true ]; then
            echo "The weekly run: every WebKit interaction spec."
            echo "WEBKIT_ALL_SPECS=true" >> "$GITHUB_ENV"
          elif [ "${WEBKIT_RELEASE_CHECK:-}" = true ]; then
            node .test-scope/.github/scripts/webkit-release-scope.mjs >> "$GITHUB_ENV"
          else
            echo "WEBKIT_ALL_SPECS=false" >> "$GITHUB_ENV"
          fi

      - name: Count the WebKit legs
        id: count-webkit
        if: steps.scope-webkit.outputs.applies == 'true'
        continue-on-error: true
        env:
          CHANGED_FILES: ${{ steps.scope-webkit.outputs.changed_files_path }}
          LAB_SPECS: ${{ steps.scope-webkit.outputs.lab_specs_path }}
        run: |
          if [ "${WEBKIT_ALL_SPECS:-}" = true ]; then SPEC_PATHS=(packages/ internal/); else read -ra SPEC_PATHS <<< "$WEBKIT_SPEC_PATHS"; fi
          # With every spec planned, the changed files add nothing. Leave them
          # out, so a missing list cannot make each leg run the whole suite.
          CHANGED=(--changed "${CHANGED_FILES:-}")
          if [ "${WEBKIT_ALL_SPECS:-}" = true ]; then CHANGED=(); fi
          git -C .test-scope ls-tree -r --name-only HEAD > "$RUNNER_TEMP/interaction-legs/listed.txt"
          selected="$RUNNER_TEMP/interaction-legs/selected.txt"
          # A Lab-only change runs only the interaction specs it edits.
          if [ -n "${LAB_SPECS:-}" ]; then
            cp "$LAB_SPECS" "$selected"
          else
            node "$RUNNER_TEMP/interaction-legs/.github/scripts/playwright-legs.mjs" select \
              --listed "$RUNNER_TEMP/interaction-legs/listed.txt" \
              "${CHANGED[@]}" \
              --shared "$WEBKIT_SHARED_PATHS" \
              -- "${SPEC_PATHS[@]}" > "$selected"
          fi
          if [ ! -s "$selected" ]; then
            echo "No WebKit interaction proof covers this change: it touches no shared touch code, no interaction spec, and no component folder that holds one."
            printf 'count=0\nruns=false\nleg=%s\n' "1" >> "$GITHUB_OUTPUT"
            exit 0
          fi
          echo "WebKit proofs for this change:"; sed 's/^/  /' "$selected"
          mapfile -t SELECTED < "$selected"
          node "$RUNNER_TEMP/interaction-legs/.github/scripts/playwright-legs.mjs" legs \
            --listed "$RUNNER_TEMP/interaction-legs/listed.txt" --source .test-scope \
            --tests-out "$RUNNER_TEMP/interaction-legs/tests.json" \
            --key interaction-webkit --fallback-key interaction-chromium \
            --durations "$RUNNER_TEMP/interaction-legs/.github/playwright-leg-durations.json" \
            "${CHANGED[@]}" \
            --setup-seconds 90 --max-seconds 600 \
            --leg 1 --max-legs 10 \
            -- "${SELECTED[@]}"

      # The matrix each lane starts: its counted legs, one leg (which skips)
      # outside its scope or with nothing to run, and all ten when its count
      # failed, so each leg decides for itself as before.
      - name: Name each lane's legs
        id: matrix
        env:
          CHROMIUM_OUTCOME: ${{ steps.count-chromium.outcome }}
          CHROMIUM_COUNT: ${{ steps.count-chromium.outputs.count }}
          WEBKIT_OUTCOME: ${{ steps.count-webkit.outcome }}
          WEBKIT_COUNT: ${{ steps.count-webkit.outputs.count }}
        run: |
          legs() {
            local outcome="$1" count="$2"
            case "$outcome" in
              success) [ "${count:-0}" -ge 1 ] 2>/dev/null || count=1 ;;
              skipped) count=1 ;;
              *) count=10 ;;
            esac
            [ "$count" -le 10 ] || count=10
            local list=1 leg
            for ((leg = 2; leg <= count; leg++)); do list="$list, $leg"; done
            printf '[%s]' "$list"
          }
          echo "chromium=$(legs "$CHROMIUM_OUTCOME" "$CHROMIUM_COUNT")" >> "$GITHUB_OUTPUT"
          echo "webkit=$(legs "$WEBKIT_OUTCOME" "$WEBKIT_COUNT")" >> "$GITHUB_OUTPUT"
          for lane in "Chromium:$CHROMIUM_OUTCOME" "WebKit:$WEBKIT_OUTCOME"; do
            case "${lane#*:}" in
              success | skipped) ;;
              *) echo "::warning title=Leg count fell back to ten::The ${lane%%:*} leg count failed, so its lane starts ten legs that each decide for themselves." ;;
            esac
          done
          cat "$GITHUB_OUTPUT"

  pr-interaction:
    name: pr-interaction (${{ matrix.leg }}/${{ strategy.job-total }})
    needs: [room, admission, heavy-ci, build-storybook, interaction-legs]
    if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && needs.heavy-ci.outputs.deferred != 'true' && ((github.event_name != 'workflow_dispatch' || inputs.operation == 'interaction-full' && github.ref == 'refs/heads/main') && always() && !cancelled() && needs.room.outputs.full != 'true' && needs.admission.outputs.full != 'true')) }}
    # Frame evidence measures timing: four cores, one Playwright worker.
    # The legs share the spec files by their recorded times
    # (playwright-legs.mjs), as few legs as keep each leg's setup and proofs
    # within ten minutes, which leaves a third of the job's fifteen for a slow
    # runner or checkout; interaction-legs starts only those legs, at most
    # ten. `test` reads the job's result, which is success only when every
    # leg passed.
    strategy:
      fail-fast: false
      matrix:
        leg: ${{ fromJSON(needs.interaction-legs.outputs.chromium || '[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]') }}
    runs-on: ubuntu-latest
    timeout-minutes: 15
    permissions:
      # The heavy-suite caps read the author's pull requests and runs.
      actions: read
      contents: read
      pull-requests: read
    steps:
      # This job decides its own scope (no separate scope job): the step
      # reads the PR's file list and the base's trusted classifier, and
      # everything is in scope when it cannot decide.
      # The workflow's own commit: the scope action, and the leg planner with
      # the shared splitter it imports and the recorded times (in .github, a
      # parent of the action, so the checkout's cone holds it).
      - name: Check out the scope action
        uses: actions/checkout@v7
        with:
          sparse-checkout: |
            .github/actions/test-scope
            .github/scripts
            scripts/lib
          path: .test-scope
          persist-credentials: false

      - name: Decide this job's scope
        id: scope
        uses: ./.test-scope/.github/actions/test-scope
        with:
          # Unit tests, docs, records and accessibility specs in a component
          # folder (packages/<component package>/src/<Component>/) put nothing
          # on a page these proofs load, so they stay out of scope. Shared
          # folders, src roots, theme sources and every other package are
          # shared code and stay in.
          paths: '^(internal/interaction-harness/|internal/a11y-spec/|playwright\.interaction\.config\.ts$|packages/(?!(?:core|lab|charts|richtext|vega)/)[^/]+/src/|packages/(?:core|lab|charts|richtext|vega)/src/(?![A-Z][^/]*/)|packages/(?:core|lab|charts|richtext|vega)/src/[A-Z][^/]*/(?!.*(?:\.test\.[^/]+|\.doc\.mjs|\.md|\.a11y\.[^/]+\.spec\.ts)$)|packages/themes/[^/]+/src/|packages/[^/]+/src/theme/|apps/storybook/|\.github/workflows/ci\.yml$|package\.json$|pnpm-lock\.yaml$|\.github/scripts/(playwright-legs|a11y-pr-contracts|lane-environment)\.mjs$|\.github/scripts/(stale-head-hint|merge-base)\.sh$|scripts/lib/duration-split\.mjs$|\.github/(playwright-leg-durations|lane-environments)\.json$|\.github/actions/test-scope/|.*\.interaction\.browser\.spec\.ts$)'
          outside-pull-request: ${{ inputs.operation == 'interaction-full' && 'run' || 'skip' }}
          requires-head-file: playwright.interaction.config.ts
          # A Lab-only change still runs each interaction spec it edits.
          lab-only-specs: '\.interaction\.browser\.spec\.ts$'
          # Lists the changed files, so the Chromium selection reads them.
          component-audit: 'true'

      - name: Require this pull request's Storybook build
        if: steps.scope.outputs.applies == 'true' && needs.build-storybook.result != 'success'
        run: |
          echo "The proofs read this pull request's Storybook build, which did not succeed."
          exit 1

      - name: Skip the proofs outside their scope
        if: steps.scope.outputs.applies != 'true'
        run: echo "No interaction proofs for this change."

      # The head checkout below replaces the workspace, scope checkout
      # included, so the leg planner, the modules it imports (the shared
      # splitter and the Playwright list reader) and the recorded times move
      # to the runner's temporary directory first.
      - name: Keep the leg planner from the workflow's commit
        if: steps.scope.outputs.applies == 'true'
        run: |
          mkdir -p "$RUNNER_TEMP/interaction-legs/.github/scripts" "$RUNNER_TEMP/interaction-legs/scripts/lib"
          cp .test-scope/.github/scripts/playwright-legs.mjs "$RUNNER_TEMP/interaction-legs/.github/scripts/"
          cp .test-scope/scripts/lib/duration-split.mjs "$RUNNER_TEMP/interaction-legs/scripts/lib/"
          cp .test-scope/.github/scripts/a11y-pr-contracts.mjs "$RUNNER_TEMP/interaction-legs/.github/scripts/"
          cp .test-scope/.github/playwright-leg-durations.json "$RUNNER_TEMP/interaction-legs/.github/"
          cp .test-scope/.github/scripts/lane-environment.mjs "$RUNNER_TEMP/interaction-legs/.github/scripts/"
          cp .test-scope/.github/scripts/stale-head-hint.sh "$RUNNER_TEMP/interaction-legs/.github/scripts/"
          cp .test-scope/.github/scripts/merge-base.sh "$RUNNER_TEMP/interaction-legs/.github/scripts/"
          cp .test-scope/.github/lane-environments.json "$RUNNER_TEMP/interaction-legs/.github/"

      # The legs this run needs: every spec file in the merge commit, which the
      # scope checkout fetched whole, at its recorded time (a WebKit time, or
      # its test count times the mean time a test, for one with none), plus
      # 90 s of setup a leg, within ten minutes a leg. Each leg decides the
      # same way before its own setup.
      - name: Count this run's legs
        id: legs
        if: steps.scope.outputs.applies == 'true'
        env:
          LAB_SPECS: ${{ steps.scope.outputs.lab_specs_path }}
          CHROMIUM_SPECS: ${{ needs.interaction-legs.outputs.chromium_specs }}
        run: |
          # A Lab-only change runs only the interaction specs it edits; any
          # other pull request runs the Chromium selection, and `full` or no
          # selection runs every spec.
          FILTERS=()
          if [ -n "${LAB_SPECS:-}" ]; then mapfile -t LAB < "$LAB_SPECS"; FILTERS=(-- "${LAB[@]}")
          elif [ -n "${CHROMIUM_SPECS:-}" ] && [ "$CHROMIUM_SPECS" != full ]; then
            # A selection that does not parse runs every spec.
            if ! PICKED_LINES=$(node -e 'for (const file of JSON.parse(process.env.CHROMIUM_SPECS)) console.log(file)'); then
              echo "::warning::The Chromium selection does not parse, so every spec runs."
            elif [ -z "$PICKED_LINES" ]; then
              echo "No Chromium interaction proof covers this change: it touches no proof, no component folder that holds one or renders one, and no shared code."
              printf 'count=0\nruns=false\nleg=1\n' >> "$GITHUB_OUTPUT"
              exit 0
            else
              mapfile -t PICKED <<< "$PICKED_LINES"
              FILTERS=(-- "${PICKED[@]}")
            fi
          fi
          git -C .test-scope ls-tree -r --name-only HEAD > "$RUNNER_TEMP/interaction-legs/listed.txt"
          node "$RUNNER_TEMP/interaction-legs/.github/scripts/playwright-legs.mjs" legs \
            --listed "$RUNNER_TEMP/interaction-legs/listed.txt" --source .test-scope \
            --tests-out "$RUNNER_TEMP/interaction-legs/tests.json" \
            --key interaction-chromium --fallback-key interaction-webkit \
            --durations "$RUNNER_TEMP/interaction-legs/.github/playwright-leg-durations.json" \
            --setup-seconds 90 --max-seconds 600 \
            --leg ${{ matrix.leg }} --max-legs 10 \
            "${FILTERS[@]}"

      - name: Require a leg for every share
        if: steps.scope.outputs.applies == 'true' && fromJSON(steps.legs.outputs.count || '0') > strategy.job-total
        run: |
          echo "::error::This run's proofs need ${{ steps.legs.outputs.count }} legs, but only ${{ strategy.job-total }} started, so a share would run nowhere. Re-run all jobs."
          exit 1

      - name: Leave the proofs to the other legs
        if: steps.scope.outputs.applies == 'true' && steps.legs.outputs.runs != 'true'
        run: echo "This run's interaction proofs fit ${{ steps.legs.outputs.count }} legs, so this leg runs none."

      # The caps step comes from the merge commit, not the pull request's
      # head: a head that predates the step does not have it. The head
      # checkout below replaces this directory.
      - name: Check out the heavy-suite caps
        if: steps.scope.outputs.applies == 'true' && steps.legs.outputs.runs == 'true'
        uses: actions/checkout@v7
        with:
          path: .heavy-caps
          sparse-checkout: .github/actions/heavy-caps
          persist-credentials: false

      - name: Per-author heavy-suite caps
        if: steps.scope.outputs.applies == 'true' && steps.legs.outputs.runs == 'true'
        uses: ./.heavy-caps/.github/actions/heavy-caps

      # The daily heavy-run cap counts this step (spec:AST-030 FR16).
      - name: Heavy suite runs
        if: steps.scope.outputs.applies == 'true' && steps.legs.outputs.runs == 'true'
        run: 'true'

      # The pull request's head, or the main commit a nightly run checks.
      - name: Checkout
        if: steps.scope.outputs.applies == 'true' && steps.legs.outputs.runs == 'true'
        uses: actions/checkout@v7
        with:
          ref: ${{ github.event.pull_request.head.sha || github.sha }}

      - name: Verify evidence checkout
        if: steps.scope.outputs.applies == 'true' && steps.legs.outputs.runs == 'true'
        env:
          EXPECTED_HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
        run: test "$(git rev-parse HEAD)" = "$EXPECTED_HEAD_SHA"

      # The head's specs run in this lane's environment, which comes from the
      # merge commit. A head older than that environment stops here.
      - name: Require this lane's environment in the branch
        if: steps.scope.outputs.applies == 'true' && steps.legs.outputs.runs == 'true'
        run: >-
          node "$RUNNER_TEMP/interaction-legs/.github/scripts/lane-environment.mjs" check --lane interaction-chromium
          --workflow "$RUNNER_TEMP/interaction-legs/.github/lane-environments.json"
          --head .github/lane-environments.json

      - name: Setup Node and pnpm
        if: steps.scope.outputs.applies == 'true' && steps.legs.outputs.runs == 'true'
        uses: ./.github/actions/setup
        with:
          install: 'false'

      - name: Download Storybook artifact
        if: steps.scope.outputs.applies == 'true' && steps.legs.outputs.runs == 'true'
        uses: actions/download-artifact@v8
        with:
          name: storybook-${{ needs.build-storybook.outputs.short_hash }}
          path: apps/storybook/dist

      - name: Install Playwright
        if: steps.scope.outputs.applies == 'true' && steps.legs.outputs.runs == 'true'
        run: pnpm install --frozen-lockfile && npx playwright install chromium

      # This leg's share of the spec files, by their recorded times. Every
      # spec file is in exactly one leg; one with no recorded time counts the
      # test count the leg count read, times the mean time a test. The planner, the shared splitter it imports and the times come
      # from the scope checkout, the workflow's own commit (kept above): a
      # head cut before them has none.
      - name: Plan this leg's interaction proofs
        id: plan
        if: steps.scope.outputs.applies == 'true' && steps.legs.outputs.runs == 'true'
        env:
          LAB_SPECS: ${{ steps.scope.outputs.lab_specs_path }}
          CHROMIUM_SPECS: ${{ needs.interaction-legs.outputs.chromium_specs }}
        run: |
          # A Lab-only change runs only the interaction specs it edits; any
          # other pull request runs the Chromium selection, and `full` or no
          # selection runs every spec.
          FILTERS=()
          if [ -n "${LAB_SPECS:-}" ]; then mapfile -t LAB < "$LAB_SPECS"; FILTERS=(-- "${LAB[@]}")
          elif [ -n "${CHROMIUM_SPECS:-}" ] && [ "$CHROMIUM_SPECS" != full ]; then
            # A selection that does not parse runs every spec.
            if ! PICKED_LINES=$(node -e 'for (const file of JSON.parse(process.env.CHROMIUM_SPECS)) console.log(file)'); then
              echo "::warning::The Chromium selection does not parse, so every spec runs."
            elif [ -z "$PICKED_LINES" ]; then
              echo "No Chromium interaction proof covers this change: it touches no proof, no component folder that holds one or renders one, and no shared code."
              printf 'count=0\nruns=false\nleg=1\n' >> "$GITHUB_OUTPUT"
              exit 0
            else
              mapfile -t PICKED <<< "$PICKED_LINES"
              FILTERS=(-- "${PICKED[@]}")
            fi
          fi
          node "$RUNNER_TEMP/interaction-legs/.github/scripts/playwright-legs.mjs" plan \
            --key interaction-chromium --fallback-key interaction-webkit --tests "$RUNNER_TEMP/interaction-legs/tests.json" \
            --config playwright.interaction.config.ts --project chromium \
            --leg ${{ steps.legs.outputs.leg }} --of ${{ steps.legs.outputs.count }} \
            --durations "$RUNNER_TEMP/interaction-legs/.github/playwright-leg-durations.json" \
            --out "$RUNNER_TEMP/interaction-leg.txt" \
            "${FILTERS[@]}"

      - name: Run interaction proofs
        if: steps.scope.outputs.applies == 'true' && steps.legs.outputs.runs == 'true' && steps.plan.outputs.files != '0'
        run: |
          pnpm exec playwright test \
            --test-list "$RUNNER_TEMP/interaction-leg.txt" \
            --config playwright.interaction.config.ts \
            --project chromium \
            --output interaction-proof-output

      # A proof that fails on a head older than main may fail for a reason
      # main already fixed. Name each newer main commit that changed a spec
      # this leg ran, or the harness, so the fix is to update the branch and
      # not to retry or debug it. It runs only after this leg's plan
      # succeeded: a failed plan leaves no spec list to read.
      - name: Explain a failure on an older head
        if: failure() && steps.scope.outputs.applies == 'true' && steps.legs.outputs.runs == 'true' && steps.plan.outcome == 'success' && steps.plan.outputs.files != '0'
        continue-on-error: true
        env:
          BASE_REF: ${{ github.event.pull_request.base.ref }}
        run: bash "$RUNNER_TEMP/interaction-legs/.github/scripts/stale-head-hint.sh" "$BASE_REF" "$RUNNER_TEMP/interaction-leg.txt"

      # Storyboards (PNG contact sheets) and curve traces, for review.
      - name: Upload interaction evidence
        if: always() && steps.scope.outputs.applies == 'true' && steps.legs.outputs.runs == 'true'
        uses: actions/upload-artifact@v7
        with:
          name: interaction-evidence-${{ matrix.leg }}
          path: test-results/interaction-evidence
          if-no-files-found: ignore
          retention-days: 7

  # The gesture, motion and harness interaction proofs in WebKit, the engine
  # of every iOS browser, for the code where WebKit and Chromium differ on
  # touch: the gesture host and recognizers, the motion runtime, the touch and
  # press helpers, the menu press model and the pager, plus the harness and the
  # shared setup that runs them (spec:AST-030 FR13). A pull request runs the
  # specs whose bundles reach only that same code, the interaction specs it
  # changes, and the specs in the folder of any component code it changes, so
  # a WebKit break elsewhere never turns an unrelated pull request red; the
  # motion adopters spec renders Storybook components and stays with the
  # Chromium proofs. A release interaction check (an `interaction-check/`
  # branch from the release tooling) runs the same subset. It runs every spec
  # only after a failed or stale weekly full run and at a minor release. The
  # weekly run on main runs every spec.
  # Out of scope every step after the scope step skips and the job reports
  # success, so the `test` join reads it without a new required context. Specs that need Chromium-only evidence skip themselves
  # in WebKit.
  pr-interaction-webkit:
    name: pr-interaction-webkit (${{ matrix.leg }}/${{ strategy.job-total }})
    needs:
      [
        room,
        admission,
        heavy-ci,
        build-storybook,
        interaction-legs,
        webkit-weekly-request,
      ]
    if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && needs.heavy-ci.outputs.deferred != 'true' && ((github.event_name != 'workflow_dispatch' || inputs.operation == 'webkit-weekly' && needs.webkit-weekly-request.result == 'success') && always() && !cancelled() && needs.room.outputs.full != 'true' && needs.admission.outputs.full != 'true')) }}
    # Frame evidence measures timing: four cores, one Playwright worker.
    # The leg count plans as many legs as keep each one's setup and proofs
    # within ten minutes, as the Chromium proofs' count does, at most ten;
    # interaction-legs starts only those legs.
    strategy:
      fail-fast: false
      matrix:
        leg: ${{ fromJSON(needs.interaction-legs.outputs.webkit || '[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]') }}
    runs-on: ubuntu-latest
    timeout-minutes: 15
    # Playwright's own image for the version the lockfile resolves, with
    # WebKit and its system libraries already installed. Installing those on
    # the runner took up to fifteen minutes when the package mirror was slow,
    # which cancelled the leg before a proof ran. A guard test keeps the tag
    # equal to the lockfile's Playwright version.
    container:
      image: mcr.microsoft.com/playwright:v1.61.1-noble
      options: --ipc=host
    # A container's steps default to `sh`; keep the runner's bash.
    defaults:
      run:
        shell: bash
    env:
      # The code where WebKit and Chromium differ on touch, and the lane's
      # shared setup. A change to it runs WEBKIT_SPEC_PATHS.
      WEBKIT_SHARED_PATHS: '^(packages/core/src/gestures/|packages/core/src/motion/|packages/core/src/internal/touch|packages/core/src/utils/(press|touch|primaryClick|isApplePlatform|flatTree|inputStream|clickGuard|selectionLock|coarsePointer|sharedResizeObserver|scrollView|nodeType|inputAge)|packages/core/src/privateAttributes/(hapticSwitch|reducedMotion)\.stylex\.ts$|packages/core/src/theme/tokenReferences\.ts$|packages/core/src/Layer/(inputHold|modalOutlet)\.ts$|packages/core/src/hooks/(useMenuPress|menuPress|useLongPress|usePressFeedback|isRtlElement|useIsomorphicLayoutEffect|useAttachment|usePager|__tests__/(usePager|pagerBundle))|internal/interaction-harness/|internal/a11y-spec/|playwright\.interaction\.config\.ts$|packages/themes/[^/]+/src/|apps/storybook/|\.github/workflows/ci\.yml$|package\.json$|pnpm-lock\.yaml$|\.github/scripts/(playwright-legs|a11y-pr-contracts|lane-environment)\.mjs$|\.github/scripts/(stale-head-hint|merge-base)\.sh$|scripts/lib/duration-split\.mjs$|\.github/(playwright-leg-durations|lane-environments)\.json$|\.github/actions/test-scope/|.*\.interaction\.browser\.spec\.ts$)'
      # The release interaction check's throwaway pull request: an
      # interaction-check/ branch in this repository, opened by the account
      # the release tooling uses. It runs the full WebKit suite when the last
      # full weekly run failed or is more than seven days old, and at a minor
      # release; otherwise the subset below, as a pull request does
      # ("Decide the WebKit scope", spec:AST-030 DEC-24).
      WEBKIT_RELEASE_CHECK: ${{ startsWith(github.head_ref, 'interaction-check/') && github.event.pull_request.user.login == 'cixzhang' && github.event.pull_request.head.repo.full_name == github.repository }}
      # The weekly full WebKit run on main (webkit-weekly.yml).
      WEBKIT_WEEKLY: ${{ github.event_name == 'workflow_dispatch' && inputs.operation == 'webkit-weekly' }}
      # The specs a shared-code change runs. Besides them, a change runs each
      # interaction spec it edits, and every interaction spec in a component
      # folder whose code it changes (`playwright-legs.mjs select`).
      WEBKIT_SPEC_PATHS: >-
        packages/core/src/gestures/
        packages/core/src/motion/__tests__/animatedLayout.interaction
        packages/core/src/motion/__tests__/animator.interaction
        packages/core/src/hooks/__tests__/usePager.interaction
        internal/interaction-harness/
    permissions:
      # The heavy-suite caps read the author's pull requests and runs.
      actions: read
      contents: read
      pull-requests: read
    steps:
      # This job decides its own scope (no separate scope job): the step
      # reads the PR's file list and the base's trusted classifier, and
      # everything is in scope when it cannot decide.
      # The workflow's own commit: the scope action, and the leg planner with
      # the shared splitter it imports and the recorded times (in .github, a
      # parent of the action, so the checkout's cone holds it).
      - name: Check out the scope action
        uses: actions/checkout@v7
        with:
          sparse-checkout: |
            .github/actions/test-scope
            .github/scripts
            scripts/lib
          path: .test-scope
          persist-credentials: false

      - name: Decide this job's scope
        id: scope
        uses: ./.test-scope/.github/actions/test-scope
        with:
          # Unit tests, docs, records and accessibility specs in a component
          # folder (packages/<component package>/src/<Component>/) put nothing
          # on a page these proofs load, so they stay out of scope. Shared
          # folders, src roots, theme sources and every other package are
          # shared code and stay in.
          paths: '^(packages/(?!(?:core|lab|charts|richtext|vega)/)[^/]+/src/[^/]+/|packages/(?:core|lab|charts|richtext|vega)/src/(?![A-Z])[^/]+/|packages/(?:core|lab|charts|richtext|vega)/src/[A-Z][^/]*/(?!.*(?:\.test\.[^/]+|\.doc\.mjs|\.md|\.a11y\.[^/]+\.spec\.ts)$)|internal/interaction-harness/|internal/a11y-spec/|playwright\.interaction\.config\.ts$|packages/themes/[^/]+/src/|packages/[^/]+/src/theme/|apps/storybook/|\.github/workflows/ci\.yml$|package\.json$|pnpm-lock\.yaml$|\.github/scripts/(playwright-legs|a11y-pr-contracts|lane-environment)\.mjs$|scripts/lib/duration-split\.mjs$|\.github/(playwright-leg-durations|lane-environments)\.json$|\.github/actions/test-scope/|.*\.interaction\.browser\.spec\.ts$|\.github/scripts/(stale-head-hint|merge-base)\.sh$)'
          outside-pull-request: ${{ inputs.operation == 'webkit-weekly' && 'run' || 'skip' }}
          requires-head-file: playwright.interaction.config.ts
          # A Lab-only change still runs each interaction spec it edits.
          lab-only-specs: '\.interaction\.browser\.spec\.ts$'
          # Lists the changed files, so the planner adds a changed spec.
          component-audit: 'true'

      - name: Require this pull request's Storybook build
        if: steps.scope.outputs.applies == 'true' && needs.build-storybook.result != 'success'
        run: |
          echo "The proofs read this pull request's Storybook build, which did not succeed."
          exit 1

      - name: Skip the WebKit proofs outside their scope
        if: steps.scope.outputs.applies != 'true'
        run: echo "No WebKit interaction proofs for this change (it touches no gesture, motion, touch or press code, no interaction spec, and none of their shared setup)."

      # The full WebKit suite on the weekly run; for a release check, the
      # last full weekly run's verdict and the release version decide; every
      # other run keeps the subset (spec:AST-030 DEC-24).
      - name: Decide the WebKit scope
        if: steps.scope.outputs.applies == 'true'
        env:
          GITHUB_TOKEN: ${{ github.token }}
          RELEASE_TITLE: ${{ github.event.pull_request.title }}
        run: |
          if [ "${WEBKIT_WEEKLY:-}" = true ]; then
            echo "The weekly run: every WebKit interaction spec."
            echo "WEBKIT_ALL_SPECS=true" >> "$GITHUB_ENV"
          elif [ "${WEBKIT_RELEASE_CHECK:-}" = true ]; then
            node .test-scope/.github/scripts/webkit-release-scope.mjs >> "$GITHUB_ENV"
          else
            echo "WEBKIT_ALL_SPECS=false" >> "$GITHUB_ENV"
          fi

      # The head checkout below replaces the workspace, scope checkout
      # included, so the leg planner, the modules it imports (the shared
      # splitter and the Playwright list reader) and the recorded times move
      # to the runner's temporary directory first.
      - name: Keep the leg planner from the workflow's commit
        if: steps.scope.outputs.applies == 'true'
        run: |
          mkdir -p "$RUNNER_TEMP/interaction-legs/.github/scripts" "$RUNNER_TEMP/interaction-legs/scripts/lib"
          cp .test-scope/.github/scripts/playwright-legs.mjs "$RUNNER_TEMP/interaction-legs/.github/scripts/"
          cp .test-scope/scripts/lib/duration-split.mjs "$RUNNER_TEMP/interaction-legs/scripts/lib/"
          cp .test-scope/.github/scripts/a11y-pr-contracts.mjs "$RUNNER_TEMP/interaction-legs/.github/scripts/"
          cp .test-scope/.github/playwright-leg-durations.json "$RUNNER_TEMP/interaction-legs/.github/"
          cp .test-scope/.github/scripts/lane-environment.mjs "$RUNNER_TEMP/interaction-legs/.github/scripts/"
          cp .test-scope/.github/scripts/stale-head-hint.sh "$RUNNER_TEMP/interaction-legs/.github/scripts/"
          cp .test-scope/.github/scripts/merge-base.sh "$RUNNER_TEMP/interaction-legs/.github/scripts/"
          cp .test-scope/.github/lane-environments.json "$RUNNER_TEMP/interaction-legs/.github/"

      # One leg runs every proof while its setup and the recorded times fit
      # ten minutes, which leaves a third of the job's limit for a slow
      # runner. Past that the planner adds legs, up to the ten-leg ceiling, so a
      # growing suite or a wide change does not reach the limit. Each leg decides the same way, before its
      # own setup, from the workflow's times and the changed files. The spec
      # files come from the merge commit's tree, which the scope checkout
      # fetched whole, so a spec with no recorded time still counts.
      - name: Count this run's WebKit legs
        id: legs
        if: steps.scope.outputs.applies == 'true'
        env:
          CHANGED_FILES: ${{ steps.scope.outputs.changed_files_path }}
          LAB_SPECS: ${{ steps.scope.outputs.lab_specs_path }}
        run: |
          if [ "${WEBKIT_ALL_SPECS:-}" = true ]; then SPEC_PATHS=(packages/ internal/); else read -ra SPEC_PATHS <<< "$WEBKIT_SPEC_PATHS"; fi
          # With every spec planned, the changed files add nothing. Leave them
          # out, so a missing list cannot make each leg run the whole suite.
          CHANGED=(--changed "${CHANGED_FILES:-}")
          if [ "${WEBKIT_ALL_SPECS:-}" = true ]; then CHANGED=(); fi
          git -C .test-scope ls-tree -r --name-only HEAD > "$RUNNER_TEMP/interaction-legs/listed.txt"
          selected="$RUNNER_TEMP/interaction-legs/selected.txt"
          # A Lab-only change runs only the interaction specs it edits.
          if [ -n "${LAB_SPECS:-}" ]; then
            cp "$LAB_SPECS" "$selected"
          else
            node "$RUNNER_TEMP/interaction-legs/.github/scripts/playwright-legs.mjs" select \
              --listed "$RUNNER_TEMP/interaction-legs/listed.txt" \
              "${CHANGED[@]}" \
              --shared "$WEBKIT_SHARED_PATHS" \
              -- "${SPEC_PATHS[@]}" > "$selected"
          fi
          if [ ! -s "$selected" ]; then
            echo "No WebKit interaction proof covers this change: it touches no shared touch code, no interaction spec, and no component folder that holds one."
            printf 'count=0\nruns=false\nleg=%s\n' "${{ matrix.leg }}" >> "$GITHUB_OUTPUT"
            exit 0
          fi
          echo "WebKit proofs for this change:"; sed 's/^/  /' "$selected"
          mapfile -t SELECTED < "$selected"
          node "$RUNNER_TEMP/interaction-legs/.github/scripts/playwright-legs.mjs" legs \
            --listed "$RUNNER_TEMP/interaction-legs/listed.txt" --source .test-scope \
            --tests-out "$RUNNER_TEMP/interaction-legs/tests.json" \
            --key interaction-webkit --fallback-key interaction-chromium \
            --durations "$RUNNER_TEMP/interaction-legs/.github/playwright-leg-durations.json" \
            "${CHANGED[@]}" \
            --setup-seconds 90 --max-seconds 600 \
            --leg ${{ matrix.leg }} --max-legs 10 \
            -- "${SELECTED[@]}"

      - name: Require a leg for every share
        if: steps.scope.outputs.applies == 'true' && fromJSON(steps.legs.outputs.count || '0') > strategy.job-total
        run: |
          echo "::error::This run's proofs need ${{ steps.legs.outputs.count }} legs, but only ${{ strategy.job-total }} started, so a share would run nowhere. Re-run all jobs."
          exit 1

      - name: Leave the proofs to the other legs
        if: steps.scope.outputs.applies == 'true' && steps.legs.outputs.runs != 'true'
        run: echo "This leg runs no WebKit proofs (${{ steps.legs.outputs.count }} leg(s) planned for this change)."

      # The caps step comes from the merge commit, not the pull request's
      # head: a head that predates the step does not have it. The head
      # checkout below replaces this directory.
      - name: Check out the heavy-suite caps
        if: steps.scope.outputs.applies == 'true' && steps.legs.outputs.runs == 'true'
        uses: actions/checkout@v7
        with:
          path: .heavy-caps
          sparse-checkout: .github/actions/heavy-caps
          persist-credentials: false

      - name: Per-author heavy-suite caps
        if: steps.scope.outputs.applies == 'true' && steps.legs.outputs.runs == 'true'
        uses: ./.heavy-caps/.github/actions/heavy-caps

      # The daily heavy-run cap counts this step (spec:AST-030 FR16).
      - name: Heavy suite runs
        if: steps.scope.outputs.applies == 'true' && steps.legs.outputs.runs == 'true'
        run: 'true'

      - name: Checkout
        if: steps.scope.outputs.applies == 'true' && steps.legs.outputs.runs == 'true'
        uses: actions/checkout@v7
        with:
          ref: ${{ github.event.pull_request.head.sha || github.sha }}

      # The container runs as root over a workspace the runner owns, and git
      # refuses a repository another user owns unless it is marked safe.
      - name: Trust the checkout in the container
        if: steps.scope.outputs.applies == 'true' && steps.legs.outputs.runs == 'true'
        run: git config --global --add safe.directory "$GITHUB_WORKSPACE"

      - name: Verify evidence checkout
        if: steps.scope.outputs.applies == 'true' && steps.legs.outputs.runs == 'true'
        env:
          EXPECTED_HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
        run: test "$(git rev-parse HEAD)" = "$EXPECTED_HEAD_SHA"

      # The head's specs run in this lane's environment, which comes from the
      # merge commit. A head older than that environment stops here.
      - name: Require this lane's environment in the branch
        if: steps.scope.outputs.applies == 'true' && steps.legs.outputs.runs == 'true'
        run: >-
          node "$RUNNER_TEMP/interaction-legs/.github/scripts/lane-environment.mjs" check --lane interaction-webkit
          --workflow "$RUNNER_TEMP/interaction-legs/.github/lane-environments.json"
          --head .github/lane-environments.json

      - name: Setup Node and pnpm
        if: steps.scope.outputs.applies == 'true' && steps.legs.outputs.runs == 'true'
        uses: ./.github/actions/setup
        with:
          install: 'false'

      - name: Download Storybook artifact
        if: steps.scope.outputs.applies == 'true' && steps.legs.outputs.runs == 'true'
        uses: actions/download-artifact@v8
        with:
          name: storybook-${{ needs.build-storybook.outputs.short_hash }}
          path: apps/storybook/dist

      # The image carries WebKit, Chromium's headless shell and their system
      # libraries; `install` finds them in place and downloads nothing. A spec
      # that decodes a WebKit recording does so in the headless shell.
      - name: Install Playwright WebKit
        if: steps.scope.outputs.applies == 'true' && steps.legs.outputs.runs == 'true'
        run: pnpm install --frozen-lockfile && npx playwright install webkit chromium-headless-shell

      # This leg's share of the WebKit spec files the legs step selected, by
      # their recorded times. The planner and the times come from the scope
      # checkout, as for the Chromium legs. A selected spec file that the head
      # does not have (one the pull request deletes) is left out.
      - name: Plan this leg's WebKit interaction proofs
        id: plan
        if: steps.scope.outputs.applies == 'true' && steps.legs.outputs.runs == 'true'
        run: |
          PLANNED=()
          while IFS= read -r entry; do
            case "$entry" in
              *.spec.ts) [ -f "$entry" ] && PLANNED+=("$entry") ;;
              *) PLANNED+=("$entry") ;;
            esac
          done < "$RUNNER_TEMP/interaction-legs/selected.txt"
          if [ "${#PLANNED[@]}" -eq 0 ]; then
            echo "The head has none of the selected WebKit spec files."
            echo "files=0" >> "$GITHUB_OUTPUT"
            exit 0
          fi
          node "$RUNNER_TEMP/interaction-legs/.github/scripts/playwright-legs.mjs" plan \
            --key interaction-webkit --fallback-key interaction-chromium --tests "$RUNNER_TEMP/interaction-legs/tests.json" \
            --config playwright.interaction.config.ts --project webkit \
            --leg ${{ steps.legs.outputs.leg }} --of ${{ steps.legs.outputs.count }} \
            --durations "$RUNNER_TEMP/interaction-legs/.github/playwright-leg-durations.json" \
            --out "$RUNNER_TEMP/interaction-leg.txt" -- \
            "${PLANNED[@]}"

      # WebKit renders through Mesa's llvmpipe, which sizes its thread pool
      # from the CPUs the process may run on. A container's CPU quota is not
      # that mask, so a runner that shows the host's CPUs oversubscribes the
      # job's share. Cap llvmpipe's threads at the cgroup quota when one is
      # set (the job's share, rounded up); without a quota the count stays
      # nproc, llvmpipe's own default.
      - name: Run WebKit interaction proofs
        if: steps.scope.outputs.applies == 'true' && steps.legs.outputs.runs == 'true' && steps.plan.outputs.files != '0'
        run: |
          LP_NUM_THREADS="$(nproc)"
          if [ -r /sys/fs/cgroup/cpu.max ]; then
            read -r quota period < /sys/fs/cgroup/cpu.max
            if [ "$quota" != max ]; then
              share=$(( (quota + period - 1) / period ))
              if [ "$share" -lt "$LP_NUM_THREADS" ]; then
                LP_NUM_THREADS="$share"
              fi
            fi
          fi
          export LP_NUM_THREADS
          echo "llvmpipe threads: $LP_NUM_THREADS"
          # Which Mesa software rasterizer the frames go through.
          echo "Mesa DRI drivers: $(ls /usr/lib/x86_64-linux-gnu/dri 2>/dev/null | tr '\n' ' ')"
          pnpm exec playwright test \
            --test-list "$RUNNER_TEMP/interaction-leg.txt" \
            --config playwright.interaction.config.ts \
            --project webkit \
            --output interaction-proof-output-webkit

      # A proof that fails on a head older than main may fail for a reason
      # main already fixed. Name each newer main commit that changed a spec
      # this leg ran, or the harness, so the fix is to update the branch and
      # not to retry or debug it. It runs only after this leg's plan
      # succeeded: a failed plan leaves no spec list to read.
      - name: Explain a failure on an older head
        if: failure() && steps.scope.outputs.applies == 'true' && steps.legs.outputs.runs == 'true' && steps.plan.outcome == 'success' && steps.plan.outputs.files != '0'
        continue-on-error: true
        env:
          BASE_REF: ${{ github.event.pull_request.base.ref }}
        run: bash "$RUNNER_TEMP/interaction-legs/.github/scripts/stale-head-hint.sh" "$BASE_REF" "$RUNNER_TEMP/interaction-leg.txt"

      - name: Upload WebKit interaction evidence
        if: always() && steps.scope.outputs.applies == 'true' && steps.legs.outputs.runs == 'true'
        uses: actions/upload-artifact@v7
        with:
          name: interaction-evidence-webkit-${{ matrix.leg }}
          path: test-results/interaction-evidence
          if-no-files-found: ignore
          retention-days: 7

  # The weekly full WebKit run's verdict, as an artifact named for it. The
  # release check reads the newest one: green and at most seven days old keeps
  # a release on the subset; failed, older or missing runs the full suite
  # (spec:AST-030 DEC-24). The artifacts list every weekly result.
  webkit-weekly-verdict:
    needs: [webkit-weekly-request, pr-interaction-webkit]
    if: ${{ always() && github.event_name == 'workflow_dispatch' && inputs.operation == 'webkit-weekly' && needs.webkit-weekly-request.result == 'success' }}
    runs-on: ubuntu-slim
    permissions: {}
    steps:
      - name: Write the verdict
        env:
          RESULT: ${{ needs.pr-interaction-webkit.result }}
        run: |
          printf '{"sha":"%s","result":"%s","run":"%s"}\n' "$GITHUB_SHA" "$RESULT" "$GITHUB_RUN_ID" > "$RUNNER_TEMP/webkit-weekly-verdict.json"
          cat "$RUNNER_TEMP/webkit-weekly-verdict.json"
      - name: Record the verdict
        uses: actions/upload-artifact@v7
        with:
          name: ${{ needs.pr-interaction-webkit.result == 'success' && 'webkit-weekly-green' || 'webkit-weekly-failed' }}
          path: ${{ runner.temp }}/webkit-weekly-verdict.json
          retention-days: 90

  # Build package test owner. The plugin's production CSS partition is a Build
  # integration contract: source inspection cannot prove which declaration
  # paints after Vite emits the final bundle. The `test-build` name makes that
  # package ownership explicit; the historical `test` join above projects its
  # result. Until runtime:build has a specialized route, broad CI dispatches it.
  test-build:
    needs: [admission, heavy-ci]
    if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && needs.heavy-ci.outputs.deferred != 'true' && (needs.admission.result == 'success' && (github.event_name != 'workflow_dispatch'))) }}
    runs-on: ubuntu-24.04-arm
    timeout-minutes: 15
    permissions:
      # The heavy-suite caps read the author's pull requests and runs.
      actions: read
      contents: read
      pull-requests: read
    steps:
      # This job decides its own scope (no separate scope job): the step
      # reads the PR's file list and the base's trusted classifier, and
      # everything is in scope when it cannot decide.
      - name: Check out the scope action
        uses: actions/checkout@v7
        with:
          sparse-checkout: .github/actions/test-scope
          path: .test-scope
          persist-credentials: false

      - name: Decide this job's scope
        id: scope
        uses: ./.test-scope/.github/actions/test-scope

      - name: 'Lab-only: Lab tests + Storybook build'
        if: steps.scope.outputs.lab_only == 'true'
        run: |
          echo "::notice title=Lab-only::Lab-only: Lab tests + Storybook build. This job's work is not required for a change only to the Lab package (spec:AST-030 FR26)."

      - uses: actions/checkout@v7
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && steps.scope.outputs.lab_only != 'true'

      - name: Per-author heavy-suite caps
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && steps.scope.outputs.lab_only != 'true'
        uses: ./.github/actions/heavy-caps

      # The daily heavy-run cap counts this step (spec:AST-030 FR16).
      - name: Heavy suite runs
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && steps.scope.outputs.lab_only != 'true'
        run: 'true'

      - uses: ./.github/actions/setup
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && steps.scope.outputs.lab_only != 'true'
      - name: Install Playwright
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && steps.scope.outputs.lab_only != 'true'
        run: npx playwright install chromium

      # The Build package's contracts: the packed consumer's dependencies, the
      # production CSS-layer cascade, and cross-package StyleX markers in a
      # real browser. `pnpm test:build` owns the list.
      - name: Run Build package contracts
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && steps.scope.outputs.lab_only != 'true'
        run: pnpm test:build

      # The vibe-tests fixtures share this Playwright-equipped runner: the
      # canonical setup compositions and the guest fixture contrast need a
      # production browser render.
      - name: Verify canonical setup compositions
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && steps.scope.outputs.lab_only != 'true'
        env:
          ASTRYX_CANONICAL_SETUP_BROWSER: '1'
        run: pnpm vitest run internal/vibe-tests/setup-test/setup-canonical.test.ts --project node --maxWorkers=1

      - name: Verify guest fixture contrast
        if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true' && steps.scope.outputs.lab_only != 'true'
        run: pnpm -F @astryxdesign/vibe-tests fixtures:contrast

  # The full visual plan first loads every Core story to learn which theming
  # targets it renders, and that scout is most of the job's time. It runs here
  # as parallel shards over exactly the release plan's story list; pr-visual
  # joins them only when every shard succeeded, and otherwise scouts inline.
  visual-scout:
    name: Stable visual scout (${{ matrix.shard }}/${{ strategy.job-total }})
    needs: [build-storybook, run-labels]
    if: >-
      (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() &&
      needs.build-storybook.result == 'success' &&
      ((github.event_name == 'pull_request' && needs.run-labels.outputs.visual == 'true') ||
       (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check')))
    # A pull request scouts in five legs (at three, each took ~4.5 minutes and
    # the visual regression waited for the slowest one); a release-check, in
    # eight (spec:AST-030 FR23).
    strategy:
      fail-fast: false
      matrix:
        shard: ${{ fromJSON(github.event_name == 'workflow_dispatch' && '[1, 2, 3, 4, 5, 6, 7, 8]' || '[1, 2, 3, 4, 5]') }}
    # Four pages on four cores: the scout is page-load bound, and on the rig
    # this cut a shard's scout by a quarter against two pages on two cores.
    runs-on: ${{ (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check' && github.triggering_actor != 'github-actions[bot]') && '4-core-ubuntu' || 'ubuntu-latest' }}
    timeout-minutes: 15
    permissions:
      contents: read
      pull-requests: read
    steps:
      # This job decides its own component scope (no separate scope job):
      # the step reads the PR's file list and the base's trusted classifiers.
      # Outside a pull request every audit applies in full.
      - name: Check out the scope action
        uses: actions/checkout@v7
        with:
          sparse-checkout: .github/actions/test-scope
          path: .test-scope
          persist-credentials: false

      - name: Decide this job's component scope
        id: scope
        uses: ./.test-scope/.github/actions/test-scope
        with:
          component-audit: 'true'

      - name: Checkout
        uses: actions/checkout@v7

      # Stable visual scope: Core and the non-private shipped themes take
      # part; canaryOnly packages do not. A change to the gate's probe fixture
      # runs the whole plan, whose probe tier shoots it. A pull request the
      # import graph can scope audits the changed components and their
      # reverse dependents (spec:AST-030 FR13).
      - name: Decide stable visual scope
        id: visual-scope
        env:
          FILES_PATH: ${{ steps.scope.outputs.changed_files_path }}
          SCOPED: ${{ github.event_name == 'pull_request' && steps.scope.outputs.full_suite == 'false' }}
          SPECIALIZED: ${{ steps.scope.outputs.spec_only == 'true' || steps.scope.outputs.docsite_only == 'true' || steps.scope.outputs.tooling_only == 'true' }}
        run: |
          if [ "$SPECIALIZED" = true ]; then
            printf 'has_stable_visual=false\nbroad_stable_visual=false\n' >> "$GITHUB_OUTPUT"
            exit 0
          fi
          if [ "${{ github.event_name }}" != pull_request ] || [ ! -s "$FILES_PATH" ]; then
            printf 'has_stable_visual=true\nbroad_stable_visual=true\n' >> "$GITHUB_OUTPUT"
            exit 0
          fi
          VISUAL_ARGS=()
          if [ "$SCOPED" = true ]; then VISUAL_ARGS=(--scoped); fi
          node .github/scripts/visual-scope.mjs --github-output "$GITHUB_OUTPUT" "${VISUAL_ARGS[@]}" < "$FILES_PATH"

      # The baseline is read from the head, which built the Storybook this job
      # compares: a branch behind a main baseline refresh would otherwise show
      # main's accepted pixel changes as its own.
      - name: Check out the head's visual baseline
        if: steps.visual-scope.outputs.has_stable_visual == 'true' && steps.visual-scope.outputs.broad_stable_visual == 'true'
        uses: actions/checkout@v7
        with:
          ref: ${{ github.event.pull_request.head.sha || github.sha }}
          path: .head-visual-baseline
          sparse-checkout: .github/visual-baseline
          persist-credentials: false

      - name: Setup Node and pnpm
        if: steps.visual-scope.outputs.has_stable_visual == 'true' && steps.visual-scope.outputs.broad_stable_visual == 'true'
        uses: ./.github/actions/setup
        with:
          install: 'false'

      - name: Download Storybook artifact
        if: steps.visual-scope.outputs.has_stable_visual == 'true' && steps.visual-scope.outputs.broad_stable_visual == 'true'
        uses: actions/download-artifact@v8
        with:
          name: storybook-${{ needs.build-storybook.outputs.short_hash }}
          path: apps/storybook/dist

      # The artifact carries the themes and the Core dist they import, built
      # at this commit. If it is missing, the gate builds Core and the themes.
      - name: Download built themes and core
        if: steps.visual-scope.outputs.has_stable_visual == 'true' && steps.visual-scope.outputs.broad_stable_visual == 'true'
        continue-on-error: true
        uses: actions/download-artifact@v8
        with:
          name: dists-${{ needs.build-storybook.outputs.short_hash }}
          path: packages

      - name: Install Playwright
        if: steps.visual-scope.outputs.has_stable_visual == 'true' && steps.visual-scope.outputs.broad_stable_visual == 'true'
        run: pnpm install --frozen-lockfile && npx playwright install chromium

      - name: Scout this shard of the release plan
        if: steps.visual-scope.outputs.has_stable_visual == 'true' && steps.visual-scope.outputs.broad_stable_visual == 'true'
        run: |
          node .github/scripts/visual-gate/gate.mjs scout \
            --storybook-dir apps/storybook/dist \
            --baseline .head-visual-baseline/.github/visual-baseline \
            --shard "${{ matrix.shard }}/${{ strategy.job-total }}" \
            --concurrency 4 \
            --observations-out ".visual-scout/observations-${{ matrix.shard }}.json"

      - name: Upload scout shard
        if: steps.visual-scope.outputs.has_stable_visual == 'true' && steps.visual-scope.outputs.broad_stable_visual == 'true'
        uses: actions/upload-artifact@v7
        with:
          name: visual-scout-${{ needs.build-storybook.outputs.short_hash }}-${{ matrix.shard }}
          path: .visual-scout/observations-${{ matrix.shard }}.json
          retention-days: 1
          if-no-files-found: error

  # Stable-package visual regression and explicit baseline capture share this
  # owner. Focused PRs compare the checked-in baseline; broad PRs use the full
  # canonical plan. Maintenance captures candidates on the same runner, and a
  # normal reviewed pull request updates the versioned baseline.
  # Audit and interaction fixtures stay with their existing browser checks.
  pr-visual:
    name: Stable visual regression
    needs:
      [
        admission,
        build-storybook,
        maintenance-request,
        visual-scout,
        run-labels,
      ]
    if: >-
      (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() &&
      ((github.event_name == 'pull_request' &&
        needs.build-storybook.result == 'success' &&
        needs.admission.outputs.full != 'true') ||
       (github.event_name == 'workflow_dispatch' &&
        ((inputs.operation == 'release-check' &&
          needs.build-storybook.result == 'success') ||
         (needs.maintenance-request.result == 'success' && inputs.operation == 'capture')))))
    runs-on: ${{ (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check' && github.triggering_actor != 'github-actions[bot]') && '2-core-ubuntu-arm' || 'ubuntu-24.04-arm' }}
    timeout-minutes: ${{ github.event_name == 'workflow_dispatch' && 360 || 15 }}
    permissions:
      contents: read
      pull-requests: read
    steps:
      # This job decides its own component scope (no separate scope job):
      # the step reads the PR's file list and the base's trusted classifiers.
      # Outside a pull request every audit applies in full.
      - name: Check out the scope action
        uses: actions/checkout@v7
        with:
          sparse-checkout: .github/actions/test-scope
          path: .test-scope
          persist-credentials: false

      - name: Decide this job's component scope
        id: scope
        uses: ./.test-scope/.github/actions/test-scope
        with:
          component-audit: 'true'

      - name: Checkout
        uses: actions/checkout@v7

      # Stable visual scope: Core and the non-private shipped themes take
      # part; canaryOnly packages do not. A change to the gate's probe fixture
      # runs the whole plan, whose probe tier shoots it. A pull request the
      # import graph can scope audits the changed components and their
      # reverse dependents (spec:AST-030 FR13).
      - name: Decide stable visual scope
        id: visual-scope
        env:
          FILES_PATH: ${{ steps.scope.outputs.changed_files_path }}
          SCOPED: ${{ github.event_name == 'pull_request' && steps.scope.outputs.full_suite == 'false' }}
          SPECIALIZED: ${{ steps.scope.outputs.spec_only == 'true' || steps.scope.outputs.docsite_only == 'true' || steps.scope.outputs.tooling_only == 'true' }}
        run: |
          if [ "$SPECIALIZED" = true ]; then
            printf 'has_stable_visual=false\nbroad_stable_visual=false\n' >> "$GITHUB_OUTPUT"
            exit 0
          fi
          if [ "${{ github.event_name }}" != pull_request ] || [ ! -s "$FILES_PATH" ]; then
            printf 'has_stable_visual=true\nbroad_stable_visual=true\n' >> "$GITHUB_OUTPUT"
            exit 0
          fi
          VISUAL_ARGS=()
          if [ "$SCOPED" = true ]; then VISUAL_ARGS=(--scoped); fi
          node .github/scripts/visual-scope.mjs --github-output "$GITHUB_OUTPUT" "${VISUAL_ARGS[@]}" < "$FILES_PATH"

      # The baseline is read from the head, which built the Storybook this job
      # compares: a branch behind a main baseline refresh would otherwise show
      # main's accepted pixel changes as its own.
      - name: Check out the head's visual baseline
        if: github.event_name == 'pull_request' && steps.visual-scope.outputs.has_stable_visual == 'true'
        uses: actions/checkout@v7
        with:
          ref: ${{ github.event.pull_request.head.sha || github.sha }}
          path: .head-visual-baseline
          sparse-checkout: .github/visual-baseline
          persist-credentials: false

      - name: Setup Node and pnpm
        if: github.event_name != 'pull_request' || steps.visual-scope.outputs.has_stable_visual == 'true'
        uses: ./.github/actions/setup
        with:
          install: 'false'

      - name: Download analysis artifact
        if: (github.event_name == 'pull_request') && (github.event_name != 'pull_request' || steps.visual-scope.outputs.has_stable_visual == 'true')
        uses: actions/download-artifact@v8
        with:
          name: pr-analysis

      # Without ci:run-visual a pull request gets the default touched check:
      # only the Core components it touches, never their reverse dependents
      # and never the release plan; a wide change skips it (spec:AST-030
      # FR12).
      # A wide change writes a skipped verdict naming ci:run-visual, so the
      # pull-request comment says how to run the full suite.
      - name: Decide the default touched visual check
        id: touched
        if: github.event_name == 'pull_request' && needs.run-labels.outputs.visual != 'true' && steps.visual-scope.outputs.has_stable_visual == 'true'
        env:
          FILES_PATH: ${{ steps.scope.outputs.changed_files_path }}
          ASTRYX_PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
          ASTRYX_PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
        run: |
          node .github/scripts/touched-components.mjs scope \
            --analysis analysis.json \
            --files "$FILES_PATH" \
            --baseline-manifest .head-visual-baseline/.github/visual-baseline/manifest.json \
            --out touched-scope.json \
            --wide-verdict .visual-run/verdict.json

      - name: Download Storybook artifact
        if: (github.event_name == 'pull_request' || inputs.operation == 'release-check') && (github.event_name != 'pull_request' || steps.visual-scope.outputs.has_stable_visual == 'true')
        uses: actions/download-artifact@v8
        with:
          name: storybook-${{ needs.build-storybook.outputs.short_hash }}
          path: apps/storybook/dist

      # The artifact carries the themes and the Core dist they import, built
      # at this commit. If it is missing, the gate builds Core and the themes.
      - name: Download built themes and core
        if: (github.event_name == 'pull_request' || inputs.operation == 'release-check') && (github.event_name != 'pull_request' || steps.visual-scope.outputs.has_stable_visual == 'true')
        continue-on-error: true
        uses: actions/download-artifact@v8
        with:
          name: dists-${{ needs.build-storybook.outputs.short_hash }}
          path: packages

      # Only a complete set: the gate refuses a partial or mismatched one, and
      # without any it scouts inline as before.
      - name: Download scout shards
        if: ((github.event_name == 'pull_request' || inputs.operation == 'release-check') && needs.visual-scout.result == 'success') && (github.event_name != 'pull_request' || steps.visual-scope.outputs.has_stable_visual == 'true')
        uses: actions/download-artifact@v8
        with:
          pattern: visual-scout-${{ needs.build-storybook.outputs.short_hash }}-*
          path: .visual-scout
          merge-multiple: true

      - name: Install Playwright
        if: github.event_name != 'pull_request' || steps.visual-scope.outputs.has_stable_visual == 'true'
        run: pnpm install --frozen-lockfile && npx playwright install chromium

      - name: Build canonical maintenance Storybook
        if: github.event_name == 'workflow_dispatch' && inputs.operation == 'capture'
        run: pnpm build && pnpm -F @astryxdesign/storybook build

      # The reviewed baseline is versioned with the code so CI never depends on
      # mutable website storage. Baseline refreshes remain separate reviewable PRs.

      - name: Run the visual gate for the touched components
        id: visual
        if: (github.event_name == 'pull_request' && needs.run-labels.outputs.visual == 'true') && steps.visual-scope.outputs.has_stable_visual == 'true'
        env:
          BROAD_STABLE_VISUAL: ${{ steps.visual-scope.outputs.broad_stable_visual }}
          ASTRYX_PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
          ASTRYX_PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
        run: |
          set -eu
          # Component names are not globally unique; use their package identity.
          TOUCHED=$(jq -r '. as $root | [(.newComponents + .modifiedComponents)[] | select($root.componentStats[.].package == "@astryxdesign/core")] | unique | join(",")' analysis.json)
          # Reverse dependents by folder: the folders of the components RTL
          # audits (spec:AST-030 FR13).
          DEPENDENTS=$(jq -r '[(.dependentComponentFolders // [])[] | select(startswith("core/")) | ltrimstr("core/")] | unique | join(",")' analysis.json)
          COMPONENTS="$TOUCHED"
          DEPENDENT_ARGS=()
          if [ -n "$DEPENDENTS" ]; then DEPENDENT_ARGS=(--dependents "$DEPENDENTS"); fi
          THEMES=$(jq -r '(.changedStableThemes // []) | join(",")' analysis.json)
          COMMAND=check
          # Sources no build decided, or a full-suite change, audit the whole
          # plan (spec:AST-030 FR13).
          FORCE_FULL_AUDITS=$(jq -r '.forceFullComponentAudits == true' analysis.json)
          if [ "$BROAD_STABLE_VISUAL" = 'true' ] || [ "$FORCE_FULL_AUDITS" = 'true' ]; then
            COMMAND=release
            SCOPE_ARGS=()
          elif [ -n "$COMPONENTS$DEPENDENTS" ] && [ -n "$THEMES" ]; then
            SCOPE_ARGS=(--tiers 'component,theme-matrix' --components "$COMPONENTS" ${DEPENDENT_ARGS[@]+"${DEPENDENT_ARGS[@]}"} --themes "$THEMES")
          elif [ -n "$COMPONENTS$DEPENDENTS" ]; then
            SCOPE_ARGS=(--tiers component --components "$COMPONENTS" ${DEPENDENT_ARGS[@]+"${DEPENDENT_ARGS[@]}"} --no-scout)
          elif [ -n "$THEMES" ]; then
            SCOPE_ARGS=(--tiers theme-matrix --themes "$THEMES")
          else
            # Broad changes stay with this owner: the canonical full plan has
            # no focused-component review ceiling and no deferred backup gate.
            COMMAND=release
            SCOPE_ARGS=()
          fi

          echo "Stable Core components: ${COMPONENTS:-none}"
          echo "Stable Core reverse dependents: ${DEPENDENTS:-none}"
          echo "Stable themes: ${THEMES:-none}"
          OBS_ARGS=()
          if [ -d .visual-scout ]; then OBS_ARGS=(--observation-shards .visual-scout); fi
          run_gate() {
            node .github/scripts/visual-gate/gate.mjs "$COMMAND" \
              --storybook-dir apps/storybook/dist \
              --baseline .head-visual-baseline/.github/visual-baseline \
              --out .visual-run \
              ${SCOPE_ARGS[@]+"${SCOPE_ARGS[@]}"} \
              ${OBS_ARGS[@]+"${OBS_ARGS[@]}"} \
              --summary-output visual-summary.md
          }
          set +e
          run_gate
          code=$?
          if [ "$code" = 3 ]; then
            # Nothing the scope reaches has a stable story: the whole plan
            # runs instead (spec:AST-030 FR13). An over-budget focused plan
            # writes the skipped verdict, answered below the same way.
            COMMAND=release
            SCOPE_ARGS=()
            run_gate
            code=$?
          fi
          set -e
          # Exit 2 is a visual change for review; every other nonzero exit is
          # an infrastructure failure, not a successful evidence receipt.
          case "$code" in 0|2) ;; *) exit "$code" ;; esac
          STATUS=$(jq -er '.status' .visual-run/verdict.json)
          if [ "$STATUS" = 'skipped' ]; then
            # The focused budget refused before capture. The same owner now
            # captures its bounded canonical full plan rather than leaving a gap.
            set +e
            node .github/scripts/visual-gate/gate.mjs release \
              --storybook-dir apps/storybook/dist \
              --baseline .head-visual-baseline/.github/visual-baseline \
              --out .visual-run \
              ${OBS_ARGS[@]+"${OBS_ARGS[@]}"} \
              --summary-output visual-summary.md
            code=$?
            set -e
            case "$code" in 0|2) ;; *) exit "$code" ;; esac
            STATUS=$(jq -er '.status' .visual-run/verdict.json)
          fi
          [ -f visual-summary.md ] && cat visual-summary.md >> "$GITHUB_STEP_SUMMARY"
          case "$STATUS" in
            pass|changed) ;;
            *) echo "Visual evidence is incomplete: $STATUS"; exit 1 ;;
          esac

      # Only touched components with an accepted baseline shot are compared
      # (one a pull request adds has nothing to compare yet). Exit 0 is clean
      # and 2 a change for review. A scope that plans no shot or has no stable
      # story leaves no verdict, which reads as not-run; anything else is an
      # infrastructure failure.
      - name: Visual check for the default touched components
        if: steps.touched.outputs.has_components == 'true' && steps.touched.outputs.visual_components != ''
        env:
          COMPONENTS: ${{ steps.touched.outputs.visual_components }}
          ASTRYX_PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
          ASTRYX_PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
          ASTRYX_VISUAL_SCOPE: touched
        run: |
          set +e
          node .github/scripts/visual-gate/gate.mjs check \
            --storybook-dir apps/storybook/dist \
            --baseline .head-visual-baseline/.github/visual-baseline \
            --out .visual-run \
            --tiers component \
            --components "$COMPONENTS" \
            --no-scout \
            --summary-output visual-summary.md 2> >(tee visual-gate.err >&2)
          code=$?
          set -e
          case "$code" in
            0|2) ;;
            1)
              if grep -qE 'planned no shots|no stable visual representative' visual-gate.err; then
                rm -f .visual-run/verdict.json
              else
                exit 1
              fi
              ;;
            3) rm -f .visual-run/verdict.json ;;
            *) exit "$code" ;;
          esac
          if [ -f visual-summary.md ]; then cat visual-summary.md >> "$GITHUB_STEP_SUMMARY"; fi

      - name: Upload visual verdict and report
        if: (always() && github.event_name == 'pull_request') && steps.visual-scope.outputs.has_stable_visual == 'true'
        uses: actions/upload-artifact@v7
        with:
          name: visual-pr-report
          path: |
            .visual-run/verdict.json
            .visual-run/manifest.json
            .visual-run/shots/
            .visual-run/report/
          retention-days: 30
          if-no-files-found: ignore

      - name: Run full release visual check
        if: github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'
        run: |
          set -eu
          OBS_ARGS=()
          if [ -d .visual-scout ]; then OBS_ARGS=(--observation-shards .visual-scout); fi
          set +e
          node .github/scripts/visual-gate/gate.mjs release \
            --storybook-dir apps/storybook/dist \
            --baseline .github/visual-baseline \
            --out .visual-run \
            ${OBS_ARGS[@]+"${OBS_ARGS[@]}"} \
            --summary-output visual-summary.md
          code=$?
          set -e
          case "$code" in 0|2) ;; *) exit "$code" ;; esac
          STATUS=$(jq -er '.status' .visual-run/verdict.json)
          case "$STATUS" in
            pass|changed) ;;
            *) echo "Visual evidence is incomplete: $STATUS"; exit 1 ;;
          esac
          cat visual-summary.md >> "$GITHUB_STEP_SUMMARY"

      - name: Upload release visual verdict and report
        if: always() && github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'
        uses: actions/upload-artifact@v7
        with:
          name: visual-release-report
          path: |
            .visual-run/verdict.json
            .visual-run/manifest.json
            .visual-run/shots/
            .visual-run/report/
          retention-days: 14
          if-no-files-found: error

      - name: Capture canonical visual baseline
        id: maintenance-capture
        if: github.event_name == 'workflow_dispatch' && inputs.operation == 'capture'
        # A complete browser-refresh capture can be incomparable with the old
        # baseline. The next step requires full capture, not a clean comparison.
        continue-on-error: true
        run: |
          node .github/scripts/visual-gate/gate.mjs release \
            --storybook-dir apps/storybook/dist \
            --baseline .github/visual-baseline \
            --out .visual-run \
            --summary-output visual-summary.md

      - name: Validate canonical baseline capture
        id: maintenance-validation
        if: >-
          always() && github.event_name == 'workflow_dispatch' && inputs.operation == 'capture' &&
          steps.maintenance-capture.outcome != 'skipped'
        env:
          CAPTURE_SHA: ${{ github.sha }}
          CAPTURE_RUN_ID: ${{ github.run_id }}
          CAPTURE_RUN_ATTEMPT: ${{ github.run_attempt }}
        run: |
          node --input-type=module - <<'NODE'
          import fs from 'node:fs';
          import {validateVisualMaintenanceCapture} from './.github/scripts/visual-maintenance-source.mjs';
          validateVisualMaintenanceCapture({
            manifest: JSON.parse(fs.readFileSync('.visual-run/manifest.json', 'utf8')),
            verdict: JSON.parse(fs.readFileSync('.visual-run/verdict.json', 'utf8')),
            sha: process.env.CAPTURE_SHA,
            runId: process.env.CAPTURE_RUN_ID,
            runAttempt: process.env.CAPTURE_RUN_ATTEMPT,
          });
          NODE
          cat visual-summary.md >> "$GITHUB_STEP_SUMMARY"

      - name: Upload canonical baseline candidate
        if: always() && steps.maintenance-validation.outcome == 'success'
        uses: actions/upload-artifact@v7
        with:
          name: visual-baseline-capture-${{ github.run_id }}-${{ github.run_attempt }}
          path: |
            .visual-run/shots/
            .visual-run/manifest.json
            .visual-run/verdict.json
            .visual-run/report/
          retention-days: 14
          if-no-files-found: error

  # RTL semantic audit. Sibling to pr-a11y: same build-storybook artifact, same
  # analysis.json scoping, so ordinary PRs only pay for the components they
  # touched. A harness-only PR runs the fixed Chart/ChartLegend smoke scope so
  # routing and target changes prove themselves instead of skipping their own
  # check. A policy-sensitive full run spans ~2,000 stories and exceeded the
  # single-job budget, so CI partitions it by canonical package; each shard runs
  # eight browser pages on its four cores (the audit waits on page loads), and
  # the stable pr-rtl join requires all five scope manifests plus a report from
  # every applicable package.
  # The full-roster sweep is the release-check run on main every three hours.
  #
  # Three auto dimensions: D1 icon-mirror, D5 positional-mirror, and D6
  # contextual directional decorations. Curated D2/D3/D4/D7/D8/D9 add
  # behavior and geometry that need selectors. The applicability rollup treats unexplained all-N/A as a
  # coverage gap for both new and existing components.
  #
  # Audit findings remain SOFT while the stability window is observed: the audit
  # step may fail after writing a report. Missing/canceled/incomplete shards are
  # HARD failures, and the pr-rtl join cannot pass without every package scope
  # manifest and every applicable report.
  # To promote findings too, remove the audit step's continue-on-error.
  pr-rtl-shard:
    name: pr-rtl (${{ matrix.package }}${{ matrix.parts > 1 && format(' {0}/{1}', matrix.part, matrix.parts) || '' }})
    needs: [build-storybook, run-labels]
    # A status check: heavy-ci, which skips on every run but an agent push,
    # is an ancestor (spec:AST-030 FR20); its skip must not skip this job.
    if: >-
      ((github.event_name == 'pull_request' && needs.run-labels.outputs.rtl == 'true') ||
       (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check')) &&
      !cancelled() && needs.build-storybook.result == 'success' && needs.run-labels.result == 'success'
    # Core is the largest package, so its audit is split (`--shard`) and joined
    # by pr-rtl-merge: three ways on a pull request, six on a release-check,
    # where three legs took ~10 minutes (spec:AST-030 FR23). Every other
    # package runs whole. pr-rtl-merge expects the same count.
    strategy:
      fail-fast: false
      matrix:
        include: ${{ fromJSON(github.event_name == 'workflow_dispatch' && '[{"package":"core","part":1,"parts":6},{"package":"core","part":2,"parts":6},{"package":"core","part":3,"parts":6},{"package":"core","part":4,"parts":6},{"package":"core","part":5,"parts":6},{"package":"core","part":6,"parts":6},{"package":"lab","part":1,"parts":1},{"package":"charts","part":1,"parts":1},{"package":"richtext","part":1,"parts":1},{"package":"vega","part":1,"parts":1}]' || '[{"package":"core","part":1,"parts":3},{"package":"core","part":2,"parts":3},{"package":"core","part":3,"parts":3},{"package":"lab","part":1,"parts":1},{"package":"charts","part":1,"parts":1},{"package":"richtext","part":1,"parts":1},{"package":"vega","part":1,"parts":1}]') }}
    runs-on: ${{ (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check' && github.triggering_actor != 'github-actions[bot]') && '4-core-ubuntu' || 'ubuntu-latest' }}
    timeout-minutes: 15
    permissions:
      contents: read
      pull-requests: read
    steps:
      # This job decides its own component scope (no separate scope job):
      # the step reads the PR's file list and the base's trusted classifiers.
      # Outside a pull request every audit applies in full.
      - name: Check out the scope action
        uses: actions/checkout@v7
        with:
          sparse-checkout: .github/actions/test-scope
          path: .test-scope
          persist-credentials: false

      - name: Decide this job's component scope
        id: scope
        uses: ./.test-scope/.github/actions/test-scope
        with:
          component-audit: 'true'

      - name: Checkout
        uses: actions/checkout@v7
        with:
          ref: ${{ github.event.pull_request.head.sha || github.sha }}

      - name: Verify RTL checkout
        if: (github.event_name == 'pull_request') && (steps.scope.outputs.has_rtl_components == 'true' || steps.scope.outputs.has_rtl_harness == 'true' || steps.scope.outputs.force_full_component_audits == 'true')
        env:
          EXPECTED_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
        run: test "$(git rev-parse HEAD)" = "$EXPECTED_HEAD_SHA"

      - name: Setup Node and pnpm
        if: (steps.scope.outputs.has_rtl_components == 'true' || steps.scope.outputs.has_rtl_harness == 'true' || steps.scope.outputs.force_full_component_audits == 'true')
        uses: ./.github/actions/setup
        with:
          install: 'false'

      - name: Download analysis artifact
        if: (steps.scope.outputs.has_rtl_components == 'true' || steps.scope.outputs.has_rtl_harness == 'true' || steps.scope.outputs.force_full_component_audits == 'true')
        uses: actions/download-artifact@v8
        with:
          name: pr-analysis

      - name: Download Storybook artifact
        if: (steps.scope.outputs.has_rtl_components == 'true' || steps.scope.outputs.has_rtl_harness == 'true' || steps.scope.outputs.force_full_component_audits == 'true')
        uses: actions/download-artifact@v8
        with:
          name: storybook-${{ needs.build-storybook.outputs.short_hash }}
          path: apps/storybook/dist

      - name: Install Playwright
        if: (steps.scope.outputs.has_rtl_components == 'true' || steps.scope.outputs.has_rtl_harness == 'true' || steps.scope.outputs.force_full_component_audits == 'true')
        run: pnpm install --frozen-lockfile && npx playwright install chromium

      # The D7 native-size regression test lives on the PR head. A head cut
      # before it has no native-size enforcement for the test to check (its
      # audit still checks D7's centering and hit-testing), so the step says
      # so and passes; a head that has the file always runs it, and a failure
      # fails. ci-rtl-d7.test.mjs keeps the path pointing at a real file.
      - name: Verify D7 native target regression
        if: (matrix.package == 'core' && matrix.part == 1) && (steps.scope.outputs.has_rtl_components == 'true' || steps.scope.outputs.has_rtl_harness == 'true' || steps.scope.outputs.force_full_component_audits == 'true')
        env:
          ASTRYX_RTL_BROWSER: '1'
        run: |
          D7_TEST=.github/scripts/rtl-audit-coarse-hit.browser.test.mjs
          if [ ! -f "$D7_TEST" ]; then
            echo '::notice title=D7 regression skipped::skipped: head predates D7 native-size enforcement; its D7 results cover centering and hit-testing only'
            exit 0
          fi
          pnpm exec vitest run --project node "$D7_TEST" --maxWorkers=1

      # A registry/classifier mutation runs the full audit from the PR checkout,
      # while eligibility itself came from trusted base policy. Scope resolution
      # is strict: malformed or missing analysis fails before the soft findings
      # step can run. An ordinary harness-only change uses the bounded routing
      # smoke scope.
      - name: Resolve RTL shard scope
        if: (steps.scope.outputs.has_rtl_components == 'true' || steps.scope.outputs.has_rtl_harness == 'true' || steps.scope.outputs.force_full_component_audits == 'true')
        id: rtl-scope
        run: |
          node .github/scripts/rtl-shard-scope.mjs \
            --analysis analysis.json \
            --package "${{ matrix.package }}" \
            --force-full "${{ steps.scope.outputs.force_full_component_audits }}" \
            --has-components "${{ steps.scope.outputs.has_rtl_components }}" \
            --has-harness "${{ steps.scope.outputs.has_rtl_harness }}" \
            --manifest rtl-shard-scope.json \
            --github-output "$GITHUB_OUTPUT"

      - name: Run RTL audit
        id: rtl
        if: (steps.rtl-scope.outputs.should_run == 'true') && (steps.scope.outputs.has_rtl_components == 'true' || steps.scope.outputs.has_rtl_harness == 'true' || steps.scope.outputs.force_full_component_audits == 'true')
        continue-on-error: true
        env:
          PARTS: ${{ matrix.parts }}
        run: |
          PACKAGE=${{ matrix.package }}
          COMPONENTS="${{ steps.rtl-scope.outputs.components }}"
          FILTER="${{ steps.rtl-scope.outputs.filter }}"
          FILTER_ARGS=()
          if [ -n "$FILTER" ]; then
            FILTER_ARGS=(--filter "$FILTER")
          fi
          SHARD_ARGS=()
          if [ "$PARTS" -gt 1 ]; then
            SHARD_ARGS=(--shard "${{ matrix.part }}/${{ matrix.parts }}" --shard-output "rtl-shard-${{ matrix.part }}.json")
          fi
          echo "Auditing $PACKAGE components: $COMPONENTS"
          node apps/storybook/rtl-audit/rtl-audit.mjs \
            --storybook-dir apps/storybook/dist \
            --output rtl-audit-report.json \
            --packages "$PACKAGE" \
            "${SHARD_ARGS[@]}" \
            --concurrency 8 \
            "${FILTER_ARGS[@]}"

      - name: Require completed RTL shard report
        if: always() && (steps.scope.outputs.has_rtl_components == 'true' || steps.scope.outputs.has_rtl_harness == 'true' || steps.scope.outputs.force_full_component_audits == 'true')
        env:
          PARTS: ${{ matrix.parts }}
        run: |
          SCOPE_OUTCOME="${{ steps.rtl-scope.outcome }}"
          SHOULD_RUN="${{ steps.rtl-scope.outputs.should_run }}"
          AUDIT_OUTCOME="${{ steps.rtl.outcome }}"
          if [ "$SCOPE_OUTCOME" != "success" ]; then
            echo "RTL shard scope did not resolve successfully: $SCOPE_OUTCOME"
            exit 1
          fi
          if [ "$SHOULD_RUN" = "true" ]; then
            if [ "$AUDIT_OUTCOME" != "success" ] && [ "$AUDIT_OUTCOME" != "failure" ]; then
              echo "Applicable RTL audit did not run: $AUDIT_OUTCOME"
              exit 1
            fi
            if [ "$PARTS" -gt 1 ]; then
              # A part writes cards only; pr-rtl-merge checks the joined report.
              test -s "rtl-shard-${{ matrix.part }}.json"
            else
              node .github/scripts/rtl-report-completion.mjs \
                --report rtl-audit-report.json \
                --package "${{ matrix.package }}" \
                --filter "${{ steps.rtl-scope.outputs.filter }}"
            fi
          elif [ "$SHOULD_RUN" = "false" ]; then
            if [ "$AUDIT_OUTCOME" != "skipped" ]; then
              echo "Out-of-scope RTL audit unexpectedly ran: $AUDIT_OUTCOME"
              exit 1
            fi
          else
            echo "RTL shard scope produced no explicit should_run decision."
            exit 1
          fi

      # A head cut before rtl-scorecard-summary.mjs existed cannot run the next step;
      # say so (merging main runs it).
      - name: Note a head that predates rtl-scorecard-summary.mjs
        if: ((always() && steps.rtl-scope.outputs.should_run == 'true' && matrix.parts == 1) && (steps.scope.outputs.has_rtl_components == 'true' || steps.scope.outputs.has_rtl_harness == 'true' || steps.scope.outputs.force_full_component_audits == 'true')) && hashFiles('.github/scripts/rtl-scorecard-summary.mjs') == ''
        run: echo "::notice::This pull request's head has no rtl-scorecard-summary.mjs; merging main runs the RTL scorecard summary."

      - name: Write scorecard summary
        if: ((always() && steps.rtl-scope.outputs.should_run == 'true' && matrix.parts == 1) && (steps.scope.outputs.has_rtl_components == 'true' || steps.scope.outputs.has_rtl_harness == 'true' || steps.scope.outputs.force_full_component_audits == 'true')) && hashFiles('.github/scripts/rtl-scorecard-summary.mjs') != ''
        run: |
          node .github/scripts/rtl-scorecard-summary.mjs \
            --report rtl-audit-report.json \
            --scope "${{ steps.rtl-scope.outputs.components }}" >> "$GITHUB_STEP_SUMMARY"

      - name: Upload RTL shard evidence
        if: (always() && matrix.parts == 1) && (steps.scope.outputs.has_rtl_components == 'true' || steps.scope.outputs.has_rtl_harness == 'true' || steps.scope.outputs.force_full_component_audits == 'true')
        uses: actions/upload-artifact@v7
        with:
          name: rtl-audit-report-${{ matrix.package }}
          path: |
            rtl-shard-scope.json
            rtl-audit-report.json
          if-no-files-found: error
          retention-days: 1

      - name: Upload RTL part
        if: (always() && matrix.parts > 1) && (steps.scope.outputs.has_rtl_components == 'true' || steps.scope.outputs.has_rtl_harness == 'true' || steps.scope.outputs.force_full_component_audits == 'true')
        uses: actions/upload-artifact@v7
        with:
          name: rtl-audit-part-${{ matrix.package }}-${{ matrix.part }}
          path: |
            rtl-shard-scope.json
            rtl-shard-${{ matrix.part }}.json
          if-no-files-found: error
          retention-days: 1

  # Joins the Core parts into the one report a whole Core leg would have
  # written (the same scope manifest, report and completion check), uploaded
  # under the same artifact name for the pr-rtl join. A missing or mismatched
  # part fails here.
  pr-rtl-merge:
    name: pr-rtl (core)
    needs: [build-storybook, pr-rtl-shard, run-labels]
    if: >-
      (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (always() && !cancelled() &&
      ((github.event_name == 'pull_request' && needs.run-labels.outputs.rtl == 'true') ||
       (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check')))
    runs-on: ${{ (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check' && github.triggering_actor != 'github-actions[bot]') && '2-core-ubuntu-arm' || 'ubuntu-24.04-arm' }}
    timeout-minutes: 15
    permissions:
      contents: read
      pull-requests: read
    steps:
      # This job decides its own component scope (no separate scope job):
      # the step reads the PR's file list and the base's trusted classifiers.
      # Outside a pull request every audit applies in full.
      - name: Check out the scope action
        uses: actions/checkout@v7
        with:
          sparse-checkout: .github/actions/test-scope
          path: .test-scope
          persist-credentials: false

      - name: Decide this job's component scope
        id: scope
        uses: ./.test-scope/.github/actions/test-scope
        with:
          component-audit: 'true'

      - name: Checkout
        uses: actions/checkout@v7
        with:
          ref: ${{ github.event.pull_request.head.sha || github.sha }}

      - name: Setup Node and pnpm
        if: (steps.scope.outputs.has_rtl_components == 'true' || steps.scope.outputs.has_rtl_harness == 'true' || steps.scope.outputs.force_full_component_audits == 'true')
        uses: ./.github/actions/setup

      - name: Download Storybook artifact
        if: (steps.scope.outputs.has_rtl_components == 'true' || steps.scope.outputs.has_rtl_harness == 'true' || steps.scope.outputs.force_full_component_audits == 'true')
        uses: actions/download-artifact@v8
        with:
          name: storybook-${{ needs.build-storybook.outputs.short_hash }}
          path: apps/storybook/dist

      - name: Download Core RTL parts
        if: (steps.scope.outputs.has_rtl_components == 'true' || steps.scope.outputs.has_rtl_harness == 'true' || steps.scope.outputs.force_full_component_audits == 'true')
        uses: actions/download-artifact@v8
        with:
          pattern: rtl-audit-part-core-*
          path: rtl-parts

      - name: Join Core RTL parts
        if: (steps.scope.outputs.has_rtl_components == 'true' || steps.scope.outputs.has_rtl_harness == 'true' || steps.scope.outputs.force_full_component_audits == 'true')
        id: join
        env:
          # The Core part count pr-rtl-shard's matrix gives this event.
          CORE_PARTS: ${{ github.event_name == 'workflow_dispatch' && 6 || 3 }}
        run: |
          set -eu
          manifests=(rtl-parts/*/rtl-shard-scope.json)
          if [ "${#manifests[@]}" -ne "$CORE_PARTS" ]; then
            echo "Expected $CORE_PARTS Core RTL parts, found ${#manifests[@]}."
            exit 1
          fi
          for manifest in "${manifests[@]}"; do
            cmp -s "$manifest" "${manifests[0]}" || { echo "Core RTL parts disagree on scope: $manifest"; exit 1; }
          done
          cp "${manifests[0]}" rtl-shard-scope.json
          FILTER=$(jq -r '.filter' rtl-shard-scope.json)
          echo "components=${FILTER:-full core roster}" >> "$GITHUB_OUTPUT"
          if [ "$(jq -r '.shouldRun' rtl-shard-scope.json)" != true ]; then
            echo "Core RTL audit not applicable."
            exit 0
          fi
          FILTER_ARGS=()
          if [ -n "$FILTER" ]; then FILTER_ARGS=(--filter "$FILTER"); fi
          set +e
          node apps/storybook/rtl-audit/rtl-audit.mjs \
            --storybook-dir apps/storybook/dist \
            --output rtl-audit-report.json \
            --packages core \
            --merge-shards rtl-parts \
            ${FILTER_ARGS[@]+"${FILTER_ARGS[@]}"}
          code=$?
          set -e
          # 1 is the soft findings signal; anything else is a failed join.
          case "$code" in 0|1) ;; *) exit "$code" ;; esac
          node .github/scripts/rtl-report-completion.mjs \
            --report rtl-audit-report.json \
            --package core \
            --filter "$FILTER"

      # A head cut before rtl-scorecard-summary.mjs existed cannot run the next step;
      # say so (merging main runs it).
      - name: Note a head that predates rtl-scorecard-summary.mjs
        if: ((always() && hashFiles('rtl-audit-report.json') != '') && (steps.scope.outputs.has_rtl_components == 'true' || steps.scope.outputs.has_rtl_harness == 'true' || steps.scope.outputs.force_full_component_audits == 'true')) && hashFiles('.github/scripts/rtl-scorecard-summary.mjs') == ''
        run: echo "::notice::This pull request's head has no rtl-scorecard-summary.mjs; merging main runs the RTL scorecard summary."

      - name: Write scorecard summary
        if: ((always() && hashFiles('rtl-audit-report.json') != '') && (steps.scope.outputs.has_rtl_components == 'true' || steps.scope.outputs.has_rtl_harness == 'true' || steps.scope.outputs.force_full_component_audits == 'true')) && hashFiles('.github/scripts/rtl-scorecard-summary.mjs') != ''
        run: |
          node .github/scripts/rtl-scorecard-summary.mjs \
            --report rtl-audit-report.json \
            --scope "${{ steps.join.outputs.components }}" >> "$GITHUB_STEP_SUMMARY"

      - name: Upload RTL shard evidence
        if: always() && (steps.scope.outputs.has_rtl_components == 'true' || steps.scope.outputs.has_rtl_harness == 'true' || steps.scope.outputs.force_full_component_audits == 'true')
        uses: actions/upload-artifact@v7
        with:
          name: rtl-audit-report-core
          path: |
            rtl-shard-scope.json
            rtl-audit-report.json
          if-no-files-found: error
          retention-days: 1

  # Stable required context joining the five package shards above.
  pr-rtl:
    needs: [pr-rtl-shard, pr-rtl-merge, run-labels]
    if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (always() && !cancelled() && ((github.event_name == 'pull_request' && needs.run-labels.outputs.rtl == 'true') || (github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check'))) }}
    runs-on: ubuntu-slim
    timeout-minutes: 5
    permissions:
      contents: read
      pull-requests: read
    steps:
      # This job decides its own component scope (no separate scope job):
      # the step reads the PR's file list and the base's trusted classifiers.
      # Outside a pull request every audit applies in full.
      - name: Check out the scope action
        uses: actions/checkout@v7
        with:
          sparse-checkout: .github/actions/test-scope
          path: .test-scope
          persist-credentials: false

      - name: Decide this job's component scope
        id: scope
        uses: ./.test-scope/.github/actions/test-scope
        with:
          component-audit: 'true'

      - uses: actions/checkout@v7

      - name: Download applicable RTL shard reports
        if: (steps.scope.outputs.has_rtl_components == 'true' || steps.scope.outputs.has_rtl_harness == 'true' || steps.scope.outputs.force_full_component_audits == 'true')
        continue-on-error: true
        uses: actions/download-artifact@v8
        with:
          pattern: rtl-audit-report-*
          path: rtl-shard-reports

      - name: Require every applicable RTL shard
        if: always()
        run: |
          node .github/scripts/rtl-join.mjs \
            --check-components "${{ steps.scope.outcome }}" \
            --shards "${{ needs.pr-rtl-shard.result == needs.pr-rtl-merge.result && needs.pr-rtl-shard.result || format('{0}/{1}', needs.pr-rtl-shard.result, needs.pr-rtl-merge.result) }}" \
            --should-run "${{ steps.scope.outputs.has_rtl_components == 'true' || steps.scope.outputs.has_rtl_harness == 'true' || steps.scope.outputs.force_full_component_audits == 'true' }}" \
            --force-full "${{ steps.scope.outputs.force_full_component_audits }}" \
            --reports-dir rtl-shard-reports

  # The default pull-request check for components: accessibility and RTL for
  # only the components the change touches, on one standard runner, against
  # this pull request's Storybook build, with pr-visual's verdict for the same
  # components folded in (pr-visual stays the one visual owner, spec:AST-030
  # FR12). It never widens to reverse dependents or a full suite: those run
  # behind the ci:run-<suite> labels and in the release check. It writes
  # touched-components.json, one row per component with each suite's
  # pass/fail/changed/not-run result, or the wide flag and count, for the
  # pull-request comment. No required context depends on it.
  pr-touched-components:
    name: Touched components (visual, accessibility, RTL)
    needs: [admission, build-storybook, pr-visual]
    if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && github.event_name == 'pull_request' && needs.build-storybook.result == 'success' && needs.build-storybook.outputs.lab_only != 'true' && needs.admission.outputs.full != 'true') }}
    runs-on: ubuntu-24.04-arm
    timeout-minutes: 15
    permissions:
      contents: read
      pull-requests: read
    outputs:
      wide_change: ${{ steps.touched.outputs.wide_change }}
      component_count: ${{ steps.touched.outputs.component_count }}
    steps:
      # The shared scope action lists the pull request's changed files, which
      # decide a wide change.
      - name: Check out the scope action
        uses: actions/checkout@v7
        with:
          sparse-checkout: .github/actions/test-scope
          path: .test-scope
          persist-credentials: false

      - name: List the changed files
        id: scope
        uses: ./.test-scope/.github/actions/test-scope
        with:
          component-audit: 'true'

      # The tested merge commit, as pr-visual checks out: a branch that
      # predates this check has none of its scripts at its own head.
      - name: Checkout
        uses: actions/checkout@v7
        with:
          persist-credentials: false

      # The accessibility and visual baselines are read from the head, which
      # built the Storybook this job audits: a branch behind a main fix that
      # dropped a baseline entry would otherwise report that entry as new.
      - name: Check out the head's accessibility baseline
        uses: actions/checkout@v7
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          path: .head-baseline
          sparse-checkout: |
            .github/a11y-baseline.json
            .github/visual-baseline/manifest.json
          sparse-checkout-cone-mode: false
          persist-credentials: false

      # A spec-only, docsite-only or tooling-only change has no analysis; it
      # has no component either.
      - name: Download analysis artifact
        if: steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.tooling_only != 'true'
        uses: actions/download-artifact@v8
        with:
          name: pr-analysis

      # More than five touched components, or a change to shared styles
      # (themes, tokens, shared .stylex.ts), is a wide change: this check
      # skips and the comment points to the ci:run-<suite> labels.
      - name: Decide the touched components
        id: touched
        env:
          FILES_PATH: ${{ steps.scope.outputs.changed_files_path }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
        run: |
          node .github/scripts/touched-components.mjs scope \
            --analysis analysis.json \
            --files "$FILES_PATH" \
            --baseline-manifest .head-baseline/.github/visual-baseline/manifest.json \
            --head-sha "$HEAD_SHA" \
            --out touched-components.json

      - name: Skip when no component changed or the change is wide
        if: steps.touched.outputs.has_components != 'true'
        env:
          WIDE: ${{ steps.touched.outputs.wide_change }}
          COUNT: ${{ steps.touched.outputs.component_count }}
          STORIES: ${{ steps.touched.outputs.changed_stories }}
        run: |
          if [ "$WIDE" = true ]; then
            echo "Wide change ($COUNT components): add ci:run-visual, ci:run-a11y or ci:run-rtl to run the full suite."
          else
            echo "No component changed; no component audit."
          fi
          if [ "$STORIES" = true ]; then
            echo "Changed stories no other audit covers are audited below."
          fi

      - name: Setup Node and pnpm
        if: (steps.touched.outputs.has_components == 'true' || steps.touched.outputs.changed_stories == 'true')
        uses: ./.github/actions/setup
        with:
          install: 'false'

      - name: Download Storybook artifact
        if: (steps.touched.outputs.has_components == 'true' || steps.touched.outputs.changed_stories == 'true')
        uses: actions/download-artifact@v8
        with:
          name: storybook-${{ needs.build-storybook.outputs.short_hash }}
          path: apps/storybook/dist

      - name: Install Playwright
        id: playwright
        if: (steps.touched.outputs.has_components == 'true' || steps.touched.outputs.changed_stories == 'true')
        run: pnpm install --frozen-lockfile && npx playwright install chromium

      # The same changed-component filters an opted-in pull request uses.
      - name: Accessibility audit for the touched components
        id: a11y
        if: steps.touched.outputs.has_components == 'true' && steps.touched.outputs.a11y_owners != ''
        run: |
          COMPONENTS=$(node .github/scripts/a11y-pr-scope.mjs analysis.json)
          if [ -z "$COMPONENTS" ]; then
            echo "No touched component has accessibility stories."
            exit 0
          fi
          node .github/scripts/accessibility-audit.js \
            --storybook-dir apps/storybook/dist \
            --output a11y-report.json \
            --concurrency 4 \
            --components "$COMPONENTS"

      # A story the change adds or changes that no other audit covers (one an
      # untouched component owns, or an `a11y/` page no component owns) is
      # audited on its own: new violations against the head's baseline fail
      # the job (spec:AST-030 FR12). The touched components' audit already
      # runs their own stories, so those are left out.
      - name: Accessibility audit for changed stories no other audit covers
        id: story-a11y
        if: always() && steps.playwright.outcome == 'success' && steps.touched.outputs.changed_stories == 'true'
        env:
          FILES_PATH: ${{ steps.scope.outputs.changed_files_path }}
          TOUCHED_AUDIT: ${{ steps.touched.outputs.has_components == 'true' && steps.touched.outputs.a11y_owners != '' }}
        run: |
          COVERED=''
          if [ "$TOUCHED_AUDIT" = true ]; then
            COVERED=$(node .github/scripts/a11y-pr-scope.mjs analysis.json)
          fi
          node .github/scripts/accessibility-audit.js \
            --storybook-dir apps/storybook/dist \
            --output a11y-stories-report.json \
            --concurrency 4 \
            --changed-story-files "$FILES_PATH" \
            --covered-components "$COVERED" \
            --baseline .head-baseline/.github/a11y-baseline.json \
            --fail-on-new

      # A failed accessibility audit must not skip RTL: each suite reports
      # its own result.
      - name: RTL audit for the touched components
        id: rtl
        if: always() && steps.playwright.outcome == 'success' && steps.touched.outputs.has_components == 'true' && steps.touched.outputs.rtl_packages != ''
        env:
          PACKAGES: ${{ steps.touched.outputs.rtl_packages }}
          OWNERS: ${{ steps.touched.outputs.rtl_owners }}
        run: |
          mkdir -p rtl-reports
          IFS=',' read -ra PACKAGE_LIST <<< "$PACKAGES"
          for PACKAGE in "${PACKAGE_LIST[@]}"; do
            FILTER=$(tr ',' '\n' <<< "$OWNERS" | grep "^$PACKAGE/" | paste -sd, -)
            [ -n "$FILTER" ] || continue
            # Findings are the report's to judge, as in pr-rtl-shard: a
            # nonzero exit (a failed check or a coverage gap) still writes the
            # package report.
            node apps/storybook/rtl-audit/rtl-audit.mjs \
              --storybook-dir apps/storybook/dist \
              --output "rtl-reports/$PACKAGE.json" \
              --packages "$PACKAGE" \
              --concurrency 8 \
              --filter "$FILTER" ||
              echo "RTL audit for $PACKAGE exited $?; the per-component report judges it."
            test -s "rtl-reports/$PACKAGE.json"
          done

      # The visual result comes from pr-visual, the one visual owner: its
      # default touched check, or its full check under ci:run-visual.
      - name: Download pr-visual's verdict
        if: always() && steps.touched.outputs.has_components == 'true' && (needs.pr-visual.result == 'success' || needs.pr-visual.result == 'failure')
        continue-on-error: true
        uses: actions/download-artifact@v8
        with:
          name: visual-pr-report
          path: .visual-run

      - name: Report per-component results
        if: always() && steps.touched.outputs.has_components == 'true'
        env:
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
          VISUAL_JOB: ${{ needs.pr-visual.result }}
          A11Y_STEP: ${{ steps.a11y.outcome }}
          RTL_STEP: ${{ steps.rtl.outcome }}
        run: |
          node .github/scripts/touched-components.mjs report \
            --analysis analysis.json \
            --visual .visual-run/verdict.json \
            --visual-manifest .visual-run/manifest.json \
            --visual-job "$VISUAL_JOB" \
            --baseline-manifest .head-baseline/.github/visual-baseline/manifest.json \
            --a11y a11y-report.json \
            --a11y-baseline .head-baseline/.github/a11y-baseline.json \
            --a11y-step "$A11Y_STEP" \
            --rtl-dir rtl-reports \
            --rtl-step "$RTL_STEP" \
            --head-sha "$HEAD_SHA" \
            --out touched-components.json

      - name: Upload touched-components results
        if: always() && (steps.touched.outputs.has_components == 'true' || steps.touched.outputs.wide_change == 'true' || steps.touched.outputs.changed_stories == 'true')
        uses: actions/upload-artifact@v7
        with:
          name: touched-components
          path: |
            touched-components.json
            a11y-report.json
            a11y-stories-report.json
            rtl-reports/
          if-no-files-found: ignore
          retention-days: 7

  # The accessibility contracts of the components a pull request touches: the
  # browser accessibility specs it changes, then each touched component's own
  # scoped and release-only specs, inside an eight-minute budget. The job needs
  # only the Storybook build, so it runs beside the test owners and ends before
  # the slowest of them. The `test` join reads its result: a failing contract
  # blocks the merge with no new required context. Out of scope (no component
  # or browser accessibility spec changed, or a specialized lane), every step
  # after the scope step skips and the job succeeds. A wide change runs only
  # the changed specs. A file that does not fit the budget is reported as not
  # run, and the job still succeeds.
  pr-component-a11y-contracts:
    name: Component accessibility contracts
    needs: [room, admission, heavy-ci, build-storybook]
    if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && needs.heavy-ci.outputs.deferred != 'true' && (github.event_name != 'workflow_dispatch' && always() && !cancelled() && needs.room.outputs.full != 'true' && needs.admission.outputs.full != 'true')) }}
    # One core per Playwright worker, as the release contract legs run.
    runs-on: ubuntu-latest
    timeout-minutes: 15
    permissions:
      contents: read
      pull-requests: read
    steps:
      # The workflow's own commit: the scope action, and this lane's
      # environment marker and its check (in .github, a parent of the scripts,
      # so the checkout's cone holds the marker).
      - name: Check out the scope action
        uses: actions/checkout@v7
        with:
          sparse-checkout: |
            .github/actions/test-scope
            .github/scripts
          path: .test-scope
          persist-credentials: false

      - name: Decide this job's scope
        id: scope
        uses: ./.test-scope/.github/actions/test-scope
        with:
          paths: '^(packages/[^/]+/src/|internal/a11y-spec/)'
          outside-pull-request: skip
          component-audit: 'true'

      - name: Require this pull request's Storybook build
        if: steps.scope.outputs.applies == 'true' && needs.build-storybook.result != 'success'
        run: |
          echo "The contracts read this pull request's Storybook build, which did not succeed."
          exit 1

      - name: Skip the contracts outside their scope
        if: steps.scope.outputs.applies != 'true'
        run: echo "No component or browser accessibility spec changed; no contract to run."

      # The checkouts below replace the workspace, scope checkout included, so
      # the marker of this lane's environment, and its check, move out first.
      - name: Keep this lane's environment marker from the workflow's commit
        if: steps.scope.outputs.applies == 'true'
        run: |
          mkdir -p "$RUNNER_TEMP/lane-environment/.github/scripts"
          cp .test-scope/.github/scripts/lane-environment.mjs "$RUNNER_TEMP/lane-environment/.github/scripts/"
          cp .test-scope/.github/lane-environments.json "$RUNNER_TEMP/lane-environment/.github/"

      # The tested merge commit, as the touched-components job checks out: a
      # head that predates these scripts does not have them. The specs run at
      # the head (see "Check out the head that built the Storybook").
      - name: Check out the selection scripts
        if: steps.scope.outputs.applies == 'true'
        uses: actions/checkout@v7
        with:
          persist-credentials: false

      # When the scope could not be decided (a diff GitHub truncates at 3,000
      # files, say), everything is in scope: every file counts as changed, and
      # the job runs every contract its budget fits and lists the rest.
      - name: List every file when the scope is undecided
        id: everything
        if: steps.scope.outputs.applies == 'true' && steps.scope.outputs.changed_files_path == '' && steps.scope.outputs.decided == 'false'
        run: |
          git ls-files > "$RUNNER_TEMP/every-file.txt"
          echo "path=$RUNNER_TEMP/every-file.txt" >> "$GITHUB_OUTPUT"
          echo "::notice title=Every contract in scope::The scope could not be decided, so every file counts as changed."

      # The changed-spec list and the folder rule both read this list. Without
      # it, a contract would not run and the job would still pass.
      - name: Require the changed-file list
        if: steps.scope.outputs.applies == 'true' && steps.scope.outputs.changed_files_path == '' && steps.scope.outputs.decided != 'false'
        run: |
          echo "::error::The scope step could not list the changed files, so the contracts to run are unknown. Re-run the job."
          exit 1

      - name: Download analysis artifact
        if: steps.scope.outputs.applies == 'true'
        uses: actions/download-artifact@v8
        with:
          name: pr-analysis

      # The same touched components as the touched-components job. Their own
      # specs run even for a wide change (more than five components, or shared
      # styles), and then the specs of the folders that render them, inside
      # this job's budget; what does not fit is reported as not run
      # (spec:AST-030 FR12).
      - name: Decide the touched components
        id: touched
        if: steps.scope.outputs.applies == 'true'
        env:
          FILES_PATH: ${{ steps.scope.outputs.changed_files_path || steps.everything.outputs.path }}
        run: |
          GITHUB_STEP_SUMMARY=/dev/null node .github/scripts/touched-components.mjs scope \
            --analysis analysis.json \
            --files "$FILES_PATH" \
            --out "$RUNNER_TEMP/touched-components.json"

      - name: Find the changed browser accessibility specs
        id: specs
        if: steps.scope.outputs.applies == 'true'
        env:
          FILES_PATH: ${{ steps.scope.outputs.changed_files_path }}
        run: |
          list="$RUNNER_TEMP/changed-a11y-specs.txt"
          : > "$list"
          if [ -n "$FILES_PATH" ] && [ -f "$FILES_PATH" ]; then
            # The same spec globs playwright.config.ts runs.
            node --input-type=module -e '
              import fs from "node:fs";
              import {isA11ySpecFile} from "./.github/scripts/lib/a11y-spec-files.mjs";
              const paths = fs.readFileSync(process.argv[1], "utf8").split("\n");
              for (const file of paths.filter(isA11ySpecFile)) console.log(file);
            ' "$FILES_PATH" > "$list"
          fi
          echo "path=$list" >> "$GITHUB_OUTPUT"
          if [ -s "$list" ]; then
            echo "has_specs=true" >> "$GITHUB_OUTPUT"
            echo "Changed browser accessibility specs:"; cat "$list"
          else
            echo "has_specs=false" >> "$GITHUB_OUTPUT"
          fi

      - name: Skip when no contract applies
        if: steps.scope.outputs.applies == 'true' && steps.touched.outputs.contract_owners == '' && steps.specs.outputs.has_specs != 'true'
        env:
          WIDE: ${{ steps.touched.outputs.wide_change }}
          COUNT: ${{ steps.touched.outputs.component_count }}
        run: |
          if [ "$WIDE" = true ]; then
            echo "Wide change ($COUNT components) with no changed spec: add ci:run-a11y to run the scoped accessibility specs."
          else
            echo "No touched component and no changed spec; no contract to run."
          fi

      # The specs, their helpers and the lockfile come from the same commit as
      # the Storybook build. A merge commit has specs that the head Storybook
      # does not have, and those specs fail. Merge-level interactions are the
      # job of the post-merge and release checks.
      - name: Check out the head that built the Storybook
        if: steps.touched.outputs.contract_owners != '' || steps.specs.outputs.has_specs == 'true'
        uses: actions/checkout@v7
        with:
          ref: ${{ github.event.pull_request.head.sha || github.sha }}
          persist-credentials: false

      # The head's specs run in this lane's environment, which comes from the
      # merge commit. A head older than that environment stops here.
      - name: Require this lane's environment in the branch
        if: steps.touched.outputs.contract_owners != '' || steps.specs.outputs.has_specs == 'true'
        run: >-
          node "$RUNNER_TEMP/lane-environment/.github/scripts/lane-environment.mjs" check --lane a11y-contracts
          --workflow "$RUNNER_TEMP/lane-environment/.github/lane-environments.json"
          --head .github/lane-environments.json

      - name: Setup Node and pnpm
        if: steps.touched.outputs.contract_owners != '' || steps.specs.outputs.has_specs == 'true'
        uses: ./.github/actions/setup
        with:
          install: 'false'

      - name: Download Storybook artifact
        if: steps.touched.outputs.contract_owners != '' || steps.specs.outputs.has_specs == 'true'
        uses: actions/download-artifact@v8
        with:
          name: storybook-${{ needs.build-storybook.outputs.short_hash }}
          path: apps/storybook/dist

      - name: Install Playwright
        if: steps.touched.outputs.contract_owners != '' || steps.specs.outputs.has_specs == 'true'
        run: pnpm install --frozen-lockfile && npx playwright install chromium

      # The runner and the routing lines come from the merge commit, so an
      # older head is routed by current policy. The specs run at the head; a
      # spec that the head does not have is not listed and does not run. A
      # failing or unfinished spec fails the job, and so the test join. A file
      # that does not fit the budget is not run and does not fail the job.
      - name: Run the touched components' accessibility contracts
        id: contracts
        if: steps.touched.outputs.contract_owners != '' || steps.specs.outputs.has_specs == 'true'
        # The runner stops at eight minutes; this bounds a hung browser and
        # the spec listing inside the job's 15 minutes.
        timeout-minutes: 10
        env:
          ASTRYX_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
          WORKFLOW_SHA: ${{ github.sha }}
          SPECS_PATH: ${{ steps.specs.outputs.path }}
          FILES_PATH: ${{ steps.scope.outputs.changed_files_path || steps.everything.outputs.path }}
          OWNERS: ${{ steps.touched.outputs.contract_owners }}
          FOLDERS: ${{ steps.touched.outputs.contract_folders }}
          A11Y_CONTRACT_WORKERS: 4
        run: |
          runner="$RUNNER_TEMP/a11y/.github/scripts/a11y-pr-contracts.mjs"
          mkdir -p "$RUNNER_TEMP/a11y/.github/scripts" "$RUNNER_TEMP/a11y/scripts/lib"
          git cat-file -e "$WORKFLOW_SHA^{commit}" 2>/dev/null || git fetch --quiet --no-tags --depth=1 origin "$WORKFLOW_SHA"
          git show "$WORKFLOW_SHA:.github/scripts/a11y-pr-contracts.mjs" > "$runner"
          git show "$WORKFLOW_SHA:scripts/lib/duration-split.mjs" > "$RUNNER_TEMP/a11y/scripts/lib/duration-split.mjs"
          node "$runner" --changed-only "$SPECS_PATH" --changed-files "$FILES_PATH" --owned-by "$OWNERS" --dependents-of "$FOLDERS"

      - name: Upload contract evidence
        if: always() && (steps.contracts.outcome == 'success' || steps.contracts.outcome == 'failure')
        uses: actions/upload-artifact@v7
        with:
          name: component-a11y-contracts
          path: |
            pr-a11y-evidence/
            pr-a11y-output/
          if-no-files-found: ignore
          retention-days: 7

  # The release specs a pull request runs (spec:AST-030 FR32): each
  # `*.release.*.spec.ts` file or spec tagged `@pr-a11y release-only` that it
  # adds or changes, that imports a module it changes, or that visits a
  # component whose rendered source it changes. A spec visits the component a
  # story id names; `a11y-*` ids and fixture pages name one through
  # .github/release-spec-visits.json, and a spec's `@visits` line adds more. An
  # unresolved visit runs the spec; imports that cannot be followed run every
  # release spec. A Lab-only pull request plans too (FR26). The plan splits
  # the specs into shards of at most twelve minutes by recorded time. It runs
  # on a slim runner, so a pull request that triggers nothing never starts the
  # release check's runner.
  release-specs-plan:
    needs: [room, admission, heavy-ci]
    if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && needs.heavy-ci.outputs.deferred != 'true' && (github.event_name != 'workflow_dispatch' && always() && !cancelled() && needs.room.outputs.full != 'true' && needs.admission.outputs.full != 'true')) }}
    runs-on: ubuntu-slim
    timeout-minutes: 5
    permissions:
      contents: read
      pull-requests: read
    outputs:
      has_specs: ${{ steps.plan.outputs.has_specs }}
      specs: ${{ steps.plan.outputs.specs }}
      shards: ${{ steps.plan.outputs.shards }}
    steps:
      - name: Check out the scope action
        uses: actions/checkout@v7
        with:
          sparse-checkout: |
            .github/actions/test-scope
            .github/scripts
          path: .test-scope
          persist-credentials: false

      - name: Decide this job's scope
        id: scope
        uses: ./.test-scope/.github/actions/test-scope
        with:
          # Package and harness sources a release spec can import, and the
          # release specs themselves.
          paths: '^(packages/[^/]+/src/|internal/)|\.release\.[^/]*\.spec\.ts$'
          outside-pull-request: skip
          # Lists the changed files, so the plan reads them.
          component-audit: 'true'
          # A Lab-only change plans too: every changed file is this job's work,
          # listed in lab_specs_path.
          lab-only-specs: '.'

      # The merge commit's package and harness sources for the import graph,
      # its stories for the visits, and the visit map and recorded times.
      - name: Check out the merge commit's sources
        if: steps.scope.outputs.applies == 'true'
        uses: actions/checkout@v7
        with:
          sparse-checkout: |
            .github
            scripts/lib
            packages
            internal
            apps/storybook/stories
          path: .plan
          persist-credentials: false

      - name: Plan the release specs
        id: plan
        if: steps.scope.outputs.applies == 'true'
        env:
          FILES_PATH: ${{ steps.scope.outputs.changed_files_path || steps.scope.outputs.lab_specs_path }}
          TRUNCATED: ${{ steps.scope.outputs.truncated }}
        run: |
          # A planner failure fails the step, never reads as "nothing to run".
          set -o pipefail
          # A change with no file list (GitHub truncated it, or the scope step
          # could not decide) puts every release spec in scope: uncertainty
          # fails closed (spec:AST-030 FR4). A head over 3,000 files must
          # still be split before merge (FR12).
          if [ -n "$FILES_PATH" ]; then
            changes=(--changed "$FILES_PATH")
          elif [ "$TRUNCATED" = true ]; then
            changes=(--all --truncated)
          else
            changes=(--all)
          fi
          git -C .plan ls-files > "$RUNNER_TEMP/listed.txt"
          node .plan/.github/scripts/release-specs-plan.mjs \
            --listed "$RUNNER_TEMP/listed.txt" "${changes[@]}" \
            --root .plan --out "$RUNNER_TEMP/release-specs-plan.json" | tee -a "$GITHUB_STEP_SUMMARY"

  # Each release spec the plan names runs in full and alone (`--workers=1`),
  # in the one shard the plan gives it, on the runner of the gating release
  # check, with that check's Playwright config and timing gate (spec:AST-030
  # FR32, DEC-29). A shard plans at most twelve minutes of recorded time
  # inside its fifteen-minute limit. There is no automatic retry: a
  # timing-budget miss is a failure. The shards start only when the plan
  # names a spec; `release-specs (changed)` joins them.
  release-specs:
    name: release-specs (shard ${{ matrix.shard }}/${{ matrix.of }})
    needs: [room, admission, heavy-ci, build-storybook, release-specs-plan]
    if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && needs.heavy-ci.outputs.deferred != 'true' && (github.event_name != 'workflow_dispatch' && always() && !cancelled() && needs.room.outputs.full != 'true' && needs.admission.outputs.full != 'true' && needs.release-specs-plan.outputs.has_specs == 'true')) }}
    # The gating release check runs its contracts on four cores; timing
    # budgets hold only on that runner.
    runs-on: 4-core-ubuntu
    timeout-minutes: 15
    strategy:
      fail-fast: false
      matrix:
        include: ${{ fromJSON(needs.release-specs-plan.outputs.shards) }}
    permissions:
      contents: read
    steps:
      - name: Check out the workflow's scripts
        uses: actions/checkout@v7
        with:
          sparse-checkout: .github/scripts
          path: .test-scope
          persist-credentials: false

      - name: Require this pull request's Storybook build
        if: needs.build-storybook.result != 'success'
        run: |
          echo "The release specs read this pull request's Storybook build, which did not succeed."
          exit 1

      # The head checkout below replaces the workspace, so the lane's
      # environment marker and the spec-glob list move out of the workflow's
      # commit first.
      - name: Keep the workflow commit's lane marker and spec globs
        run: |
          mkdir -p "$RUNNER_TEMP/lane-environment/.github/scripts" "$RUNNER_TEMP/release-specs/.github/scripts/lib"
          cp .test-scope/.github/scripts/lane-environment.mjs "$RUNNER_TEMP/lane-environment/.github/scripts/"
          cp .test-scope/.github/lane-environments.json "$RUNNER_TEMP/lane-environment/.github/"
          cp .test-scope/.github/scripts/lib/a11y-spec-files.mjs "$RUNNER_TEMP/release-specs/.github/scripts/lib/"

      # The specs, their helpers and the lockfile come from the head that
      # built the Storybook, as the release check runs them against its own
      # build.
      - name: Check out the head that built the Storybook
        uses: actions/checkout@v7
        with:
          ref: ${{ github.event.pull_request.head.sha || github.sha }}
          persist-credentials: false

      - name: Require this lane's environment in the branch
        run: >-
          node "$RUNNER_TEMP/lane-environment/.github/scripts/lane-environment.mjs" check --lane a11y-contracts
          --workflow "$RUNNER_TEMP/lane-environment/.github/lane-environments.json"
          --head .github/lane-environments.json

      - name: Setup Node and pnpm
        uses: ./.github/actions/setup
        with:
          install: 'false'

      - name: Download Storybook artifact
        uses: actions/download-artifact@v8
        with:
          name: storybook-${{ needs.build-storybook.outputs.short_hash }}
          path: apps/storybook/dist

      - name: Install Playwright
        run: pnpm install --frozen-lockfile && npx playwright install chromium

      # The job never drops a planned spec (spec:AST-030 FR32): one the head
      # lacks, or one outside the config's spec globs, fails here by name.
      - name: Run the planned release specs
        env:
          ASTRYX_HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
          SPECS: ${{ toJSON(matrix.specs) }}
          # The Table release proof reads it: timing budgets gate on the
          # release check's runner, so they gate here too.
          ASTRYX_TABLE_TIMING_GATE: '1'
        run: |
          set -euo pipefail
          mapfile -t PLANNED < <(node -e 'for (const file of JSON.parse(process.env.SPECS)) console.log(file)')
          # The plan reads the merge commit, which holds every planned spec.
          # A planned spec the head lacks was added on main after the branch
          # point; it must run, so the step fails until main is merged in.
          RUN=()
          MISSING=()
          for file in "${PLANNED[@]}"; do
            if [ -f "$file" ]; then RUN+=("$file"); else MISSING+=("$file"); fi
          done
          if [ "${#MISSING[@]}" -gt 0 ]; then
            for file in "${MISSING[@]}"; do
              echo "::error file=$file::$file is a planned release spec that this pull request's head does not have: main added it after the branch point. Merge main into the branch so it runs."
            done
            exit 1
          fi
          SPEC_FILES="$RUNNER_TEMP/release-specs/.github/scripts/lib/a11y-spec-files.mjs" node --input-type=module -e '
            import {pathToFileURL} from "node:url";
            const {isA11ySpecFile} = await import(pathToFileURL(process.env.SPEC_FILES));
            const outside = process.argv.slice(1).filter(file => !isA11ySpecFile(file));
            for (const file of outside) console.log("::error file=" + file + "::" + file + " is a release spec outside playwright.config.ts, so no release check runs it.");
            process.exitCode = outside.length > 0 ? 1 : 0;
          ' "${RUN[@]}"
          # One worker: a release spec judges timing alone, as the release
          # check gives an isolated timing proof a contract leg of its own.
          pnpm exec playwright test "${RUN[@]}" --config playwright.config.ts --project chromium --workers=1

  # The check merge-guard waits for when a pull request triggers it: it
  # passes only when every release-spec shard passed.
  release-specs-changed:
    name: release-specs (changed)
    needs: [room, admission, heavy-ci, release-specs-plan, release-specs]
    if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && needs.heavy-ci.outputs.deferred != 'true' && (github.event_name != 'workflow_dispatch' && always() && !cancelled() && needs.room.outputs.full != 'true' && needs.admission.outputs.full != 'true' && needs.release-specs-plan.outputs.has_specs == 'true')) }}
    runs-on: ubuntu-slim
    timeout-minutes: 5
    permissions: {}
    steps:
      - name: Require every release-spec shard
        env:
          SHARDS: ${{ needs.release-specs.result }}
        run: |
          if [ "$SHARDS" != success ]; then
            echo "The release-spec shards did not all succeed: $SHARDS"
            exit 1
          fi

  # Dependent audits (spec:AST-030 FR12): a change to a component's source runs
  # that component's own `audit` specs, and a change to a shared primitive that
  # .github/a11y-shared-primitives.json lists also runs the `audit` specs of
  # the components that use it. These otherwise run only in their own
  # component-audit pull request and in the release check. The plan job reads
  # the changed files and the import graph at the merge commit and splits the
  # audits into at most three legs of about ten minutes each by recorded time.
  # It waits for the Storybook build, which the legs need anyway.
  a11y-dependent-audits-plan:
    needs: [room, admission, heavy-ci, build-storybook]
    if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && needs.heavy-ci.outputs.deferred != 'true' && (github.event_name != 'workflow_dispatch' && always() && !cancelled() && needs.room.outputs.full != 'true' && needs.admission.outputs.full != 'true')) }}
    runs-on: ubuntu-slim
    timeout-minutes: 5
    permissions:
      contents: read
      pull-requests: read
    # owed, ran, deferred and complete are the record merge-guard reads: a
    # head merges only on a run whose complete is true. The same record is
    # the a11y-dependent-audits-record-<attempt> artifact.
    outputs:
      count: ${{ steps.plan.outputs.count || '0' }}
      legs: ${{ steps.plan.outputs.legs || '[1]' }}
      shares: ${{ steps.plan.outputs.shares || '[]' }}
      owed: ${{ steps.plan.outputs.owed || '[]' }}
      ran: ${{ steps.plan.outputs.ran || '[]' }}
      deferred: ${{ steps.plan.outputs.deferred || '[]' }}
      complete: ${{ steps.plan.outputs.complete || 'true' }}
    steps:
      - name: Check out the scope action
        uses: actions/checkout@v7
        with:
          sparse-checkout: .github/actions/test-scope
          path: .test-scope
          persist-credentials: false

      - name: Decide this job's scope
        id: scope
        uses: ./.test-scope/.github/actions/test-scope
        with:
          paths: '^packages/[^/]+/src/'
          outside-pull-request: skip
          component-audit: 'true'

      # Out of scope the run still writes its record, so merge-guard reads
      # "nothing owed" rather than a missing record.
      - name: Skip the dependent audits outside their scope
        if: steps.scope.outputs.applies != 'true'
        env:
          ASTRYX_HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
          RUN_ATTEMPT: ${{ github.run_attempt }}
        run: |
          echo "No package source changed; no dependent audit to run."
          printf '{"head": "%s", "attempt": %s, "owed": [], "ran": [], "deferred": [], "complete": true}\n' \
            "$ASTRYX_HEAD_SHA" "$RUN_ATTEMPT" > "$RUNNER_TEMP/a11y-dependent-audits.json"

      # The planner, the primitive list, the import graph and the recorded
      # times all come from the merge commit.
      - name: Check out the planner
        if: steps.scope.outputs.applies == 'true'
        uses: actions/checkout@v7
        with:
          persist-credentials: false

      # Without the list a changed primitive would go unseen and its
      # dependents' audits would not run.
      # When the scope could not be decided (a diff GitHub truncates, say),
      # everything is in scope and every audit is owed. A decided scope
      # without its list is an error.
      - name: Require the changed-file list
        if: steps.scope.outputs.applies == 'true' && steps.scope.outputs.changed_files_path == '' && steps.scope.outputs.decided != 'false'
        run: |
          echo "::error::The scope step could not list the changed files, so the dependent audits to run are unknown. Re-run the job."
          exit 1

      # A first run fits what it can into three legs of about ten minutes and
      # names the rest as not yet run; a later run at the same head (a re-run
      # of all jobs) runs every owed audit.
      - name: Plan the dependent audits
        id: plan
        if: steps.scope.outputs.applies == 'true'
        env:
          CHANGED_FILES: ${{ steps.scope.outputs.changed_files_path }}
          ASTRYX_HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
          RUN_ATTEMPT: ${{ github.run_attempt }}
          TRUNCATED: ${{ steps.scope.outputs.truncated }}
        run: |
          if [ -n "$CHANGED_FILES" ]; then
            changes=(--changed "$CHANGED_FILES")
          elif [ "$TRUNCATED" = true ]; then
            changes=(--all --truncated)
          else
            changes=(--all)
          fi
          node .github/scripts/a11y-dependent-audits.mjs "${changes[@]}" --out "$RUNNER_TEMP/a11y-dependent-audits.json" --attempt "$RUN_ATTEMPT"

      # Every run of this job uploads its record. A run that planned audits
      # but wrote no record fails here, not later at the merge.
      - name: Upload the dependent-audit record
        if: always()
        uses: actions/upload-artifact@v7
        with:
          # One record per attempt: merge-guard reads the latest attempt's.
          name: a11y-dependent-audits-record-${{ github.run_attempt }}
          path: ${{ runner.temp }}/a11y-dependent-audits.json
          if-no-files-found: error
          retention-days: 30

  # Each leg runs its share of the plan at the head that built the Storybook.
  # A leg without a share runs on a slim runner and only says so. The `test`
  # join reads the legs' result, so a failing audit blocks the merge.
  pr-a11y-dependent-audits:
    name: Dependent audits (${{ matrix.leg }}/${{ strategy.job-total }})
    needs:
      [room, admission, heavy-ci, a11y-dependent-audits-plan, build-storybook]
    if: ${{ (github.event_name != 'pull_request' || !github.event.pull_request.draft && (github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run'))) && (!cancelled() && needs.heavy-ci.outputs.deferred != 'true' && (github.event_name != 'workflow_dispatch' && always() && !cancelled() && needs.room.outputs.full != 'true' && needs.admission.outputs.full != 'true')) }}
    # An empty count (the plan skipped) compares as 0.
    runs-on: ${{ needs.a11y-dependent-audits-plan.outputs.count >= matrix.leg && 'ubuntu-latest' || 'ubuntu-slim' }}
    timeout-minutes: 15
    # A first run plans at most three legs; a later run at the same head may
    # plan up to six to run every owed audit. The matrix starts only the
    # planned legs; without a plan it starts all six, which then stop.
    strategy:
      fail-fast: false
      matrix:
        leg: ${{ fromJSON(needs.a11y-dependent-audits-plan.outputs.legs || '[1, 2, 3, 4, 5, 6]') }}
    permissions:
      contents: read
    steps:
      - name: Require the dependent-audit plan
        if: needs.a11y-dependent-audits-plan.result != 'success'
        run: |
          echo "The dependent-audit plan did not succeed (${{ needs.a11y-dependent-audits-plan.result }}), so the audits to run are unknown."
          exit 1

      - name: Decide this leg
        id: leg
        env:
          COUNT: ${{ needs.a11y-dependent-audits-plan.outputs.count || '0' }}
          LEG: ${{ matrix.leg }}
        run: |
          if [ "$LEG" -le "$COUNT" ]; then
            echo 'runs=true' >> "$GITHUB_OUTPUT"
          else
            echo 'runs=false' >> "$GITHUB_OUTPUT"
            echo "This leg runs no dependent audit ($COUNT leg(s) planned)."
          fi

      - name: Require this pull request's Storybook build
        if: steps.leg.outputs.runs == 'true' && needs.build-storybook.result != 'success'
        run: |
          echo "The audits read this pull request's Storybook build, which did not succeed."
          exit 1

      # The workflow's own commit: this lane's environment marker and its check
      # (in .github, a parent of the scripts, so the checkout's cone holds the
      # marker). The head checkout below replaces the workspace, so they move
      # out first.
      - name: Check out the scope action
        if: steps.leg.outputs.runs == 'true'
        uses: actions/checkout@v7
        with:
          sparse-checkout: |
            .github/actions/test-scope
            .github/scripts
          path: .test-scope
          persist-credentials: false

      - name: Keep this lane's environment marker from the workflow's commit
        if: steps.leg.outputs.runs == 'true'
        run: |
          mkdir -p "$RUNNER_TEMP/lane-environment/.github/scripts"
          cp .test-scope/.github/scripts/lane-environment.mjs "$RUNNER_TEMP/lane-environment/.github/scripts/"
          cp .test-scope/.github/lane-environments.json "$RUNNER_TEMP/lane-environment/.github/"

      - name: Check out the head that built the Storybook
        if: steps.leg.outputs.runs == 'true'
        uses: actions/checkout@v7
        with:
          ref: ${{ github.event.pull_request.head.sha || github.sha }}
          persist-credentials: false

      # The audits run the same specs and config as the contract job, in its
      # environment. A head older than that environment stops here.
      - name: Require this lane's environment in the branch
        if: steps.leg.outputs.runs == 'true'
        run: >-
          node "$RUNNER_TEMP/lane-environment/.github/scripts/lane-environment.mjs" check --lane a11y-contracts
          --workflow "$RUNNER_TEMP/lane-environment/.github/lane-environments.json"
          --head .github/lane-environments.json

      - name: Setup Node and pnpm
        if: steps.leg.outputs.runs == 'true'
        uses: ./.github/actions/setup
        with:
          install: 'false'

      - name: Download Storybook artifact
        if: steps.leg.outputs.runs == 'true'
        uses: actions/download-artifact@v8
        with:
          name: storybook-${{ needs.build-storybook.outputs.short_hash }}
          path: apps/storybook/dist

      - name: Install Playwright
        if: steps.leg.outputs.runs == 'true'
        run: pnpm install --frozen-lockfile && npx playwright install chromium

      # One worker per leg: the recorded times assume one browser per core. A
      # planned spec file that the head does not have is left out.
      - name: Run this leg's dependent audits
        id: audits
        if: steps.leg.outputs.runs == 'true'
        env:
          SHARES: ${{ needs.a11y-dependent-audits-plan.outputs.shares }}
          LEG: ${{ matrix.leg }}
        run: |
          node -e 'for (const f of JSON.parse(process.env.SHARES)[Number(process.env.LEG) - 1] ?? []) console.log(f)' > "$RUNNER_TEMP/dependent-audits.txt"
          FILES=()
          while IFS= read -r file; do
            [ -f "$file" ] && FILES+=("$file")
          done < "$RUNNER_TEMP/dependent-audits.txt"
          if [ "${#FILES[@]}" -eq 0 ]; then
            echo "The head has none of this leg's audit spec files."
            exit 0
          fi
          printf 'Dependent audits in this leg:\n'; printf '  %s\n' "${FILES[@]}"
          pnpm exec playwright test "${FILES[@]}" --config playwright.config.ts --project chromium --reporter list,github --output pr-a11y-dependent-output

      - name: Upload dependent-audit evidence
        if: always() && (steps.audits.outcome == 'success' || steps.audits.outcome == 'failure')
        uses: actions/upload-artifact@v7
        with:
          name: a11y-dependent-audits-${{ matrix.leg }}
          path: |
            pr-a11y-dependent-output/
            test-results/
            *-audit-evidence/
          if-no-files-found: ignore
          retention-days: 7

  # Release-time projection only: the existing owners above do all measurement.
  # A skipped owner or main drift must never look like passing release evidence.
  release-check:
    needs:
      [
        release-authority,
        test-registry-e2e,
        build-storybook,
        typecheck,
        pr-visual,
        pr-a11y,
        a11y-contracts,
        pr-a11y-audit,
        pr-rtl,
      ]
    if: ${{ always() && github.event_name == 'workflow_dispatch' && inputs.operation == 'release-check' }}
    runs-on: ubuntu-slim
    permissions:
      contents: read
    steps:
      - name: Require complete exact-head canonical checks
        uses: actions/github-script@v9
        env:
          RELEASE_NEEDS: ${{ toJSON(needs) }}
          RELEASE_BRANCH: ${{ inputs['release-branch'] }}
          EXPECTED_HEAD: ${{ inputs['expected-head'] }}
          CHECKED_HEAD: ${{ needs.release-authority.outputs.release_head }}
          PLAN_DIGEST: ${{ needs.release-authority.outputs.release_plan_digest }}
        with:
          script: |
            const needs = JSON.parse(process.env.RELEASE_NEEDS);
            for (const name of ['release-authority', 'test-registry-e2e', 'build-storybook', 'typecheck', 'pr-visual', 'pr-a11y', 'a11y-contracts', 'pr-a11y-audit', 'pr-rtl']) {
              if (needs[name]?.result !== 'success') {
                throw new Error(`Required release job ${name} did not succeed: ${needs[name]?.result}`);
              }
            }
            const branch = process.env.RELEASE_BRANCH;
            const expectedHead = process.env.EXPECTED_HEAD;
            if (context.ref !== `refs/heads/${branch}`) {
              throw new Error('Canonical release checks must run from the requested branch.');
            }
            if (context.sha !== expectedHead) {
              throw new Error('Checked-out commit does not match expected head.');
            }
            const {data} = await github.rest.git.getRef({...context.repo, ref: `heads/${branch}`});
            if (branch === 'main') {
              if (process.env.CHECKED_HEAD !== expectedHead) {
                throw new Error('Main authority check did not bind the expected head.');
              }
              const comparison = await github.rest.repos.compareCommitsWithBasehead({
                ...context.repo,
                basehead: `${expectedHead}...${data.object.sha}`,
              });
              if (!['identical', 'ahead'].includes(comparison.data.status)) {
                throw new Error('Checked main commit is not an ancestor of current main.');
              }
              await core.summary
                .addHeading('Main pre-cut checks complete')
                .addRaw(`Exact head: ${expectedHead}\n\n`)
                .addRaw('Canonical visual, accessibility, and RTL checks completed with full scope. This exact checked commit may be used as the cut SHA while it remains in current main history; later main commits are next-release input.')
                .write();
              return;
            }
            if (data.object.sha !== expectedHead) {
              throw new Error(`${branch} moved during checks; dispatch release-check again for its new head.`);
            }
            if (!branch.startsWith('release/v')) {
              throw new Error('Post-bump release checks require a marked release branch.');
            }
            if (!/^[0-9a-f]{64}$/.test(process.env.PLAN_DIGEST)) {
              throw new Error('Post-bump release checks require the active plan digest.');
            }
            await core.summary
              .addHeading('Release checks complete')
              .addRaw(`Branch: ${branch}\n\n`)
              .addRaw(`Exact head: ${expectedHead}\n\n`)
              .addRaw(`Plan digest: ${process.env.PLAN_DIGEST}\n\n`)
              .addRaw('Canonical visual, accessibility, and RTL checks completed with full scope. Main movement is not release input. This receipt is reusable only for this exact branch, head, and plan digest; any branch revision requires a new run.')
              .write();