hyperframes/.github/workflows/ci.yml

name: CI

permissions:
  contents: read
  pull-requests: read

# Suppress hyperframes CLI telemetry from HeyGen's own CI runs.
# External users' CI continues to emit telemetry unless they set this themselves.
env:
  HYPERFRAMES_NO_TELEMETRY: "1"

on:
  pull_request:
    # `edited` is required so the workflow re-fires when a PR's base ref is
    # set back to `main` after a Graphite stack restack momentarily flips
    # the base off of `main`. Without it, `pull_request` triggers are not
    # re-evaluated on `base_ref_changed`, leaving required checks skipped
    # for that head SHA forever.
    types: [opened, synchronize, reopened, edited]
    branches: [main]
  push:
    branches: [main]

concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

jobs:
  changes:
    name: Detect changes
    runs-on: ubuntu-latest
    timeout-minutes: 2
    outputs:
      code: ${{ steps.filter.outputs.code }}
      docs_catalog: ${{ steps.filter.outputs.docs_catalog }}
      cli: ${{ steps.filter.outputs.cli }}
      skills: ${{ steps.filter.outputs.skills }}
      catalog_index: ${{ steps.filter.outputs.catalog_index }}
      codex_plugin: ${{ steps.filter.outputs.codex_plugin }}
      gcp_beginframe: ${{ steps.filter.outputs.gcp_beginframe }}
      studio: ${{ steps.filter.outputs.studio }}
    steps:
      # Force git-based change detection instead of the pull_request REST API.
      # The API path can fail the whole workflow on transient listFiles
      # timeouts before any real CI work starts.
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
        with:
          fetch-depth: 0
      - name: Reject accidental file deletions
        if: github.event_name == 'pull_request'
        run: node scripts/check-no-main-deletions.mjs --base origin/main
      - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4
        id: filter
        with:
          token: ""
          filters: |
            catalog_index:
              - "registry/registry.json"
              - "registry/catalog-artifact/**"
              - "scripts/catalog/check-artifact-coverage.ts"
            docs_catalog:
              - "docs/**"
              - "registry/**"
              - "scripts/*docs-catalog*"
              - "package.json"
              - ".github/workflows/ci.yml"
            code:
              - "packages/**"
              - "scripts/**"
              - "package.json"
              - "bun.lock"
              - "tsconfig*.json"
              - "Dockerfile*"
              - ".github/workflows/**"
            cli:
              - "packages/cli/**"
              - "package.json"
              - "bun.lock"
              - ".github/workflows/ci.yml"
            skills:
              - "skills/**"
              - ".claude/skills/**"
              - ".agents/skills/**"
              - "skills-manifest.json"
              - "scripts/lint-skills.ts"
              - "scripts/check-skill-mirror.mjs"
              - "package.json"
              - ".github/workflows/ci.yml"
            codex_plugin:
              - ".codex-plugin/**"
              - "assets/**"
              - "skills/**"
              - "scripts/package-codex-plugin.mjs"
              - "package.json"
              - ".github/workflows/ci.yml"
            studio:
              - "packages/studio/**"
              - "packages/core/**"
              - "packages/studio-server/**"
              - "bun.lock"
              - ".github/workflows/ci.yml"
            gcp_beginframe:
              - "packages/gcp-cloud-run/Dockerfile"
              - "packages/aws-lambda/scripts/probe-beginframe.ts"
              - "packages/engine/src/services/browserManager.ts"
              - "package.json"
              - "bun.lock"
              - ".github/workflows/ci.yml"

  gcp-beginframe-contract:
    name: GCP BeginFrame image contract
    needs: changes
    if: needs.changes.outputs.gcp_beginframe == 'true'
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
        with:
          lfs: true
      - uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435 # v3
      - uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6
        with:
          context: .
          file: packages/gcp-cloud-run/Dockerfile
          target: beginframe-contract
          push: false
          cache-from: type=gha,scope=gcp-beginframe-contract
          cache-to: type=gha,mode=max,scope=gcp-beginframe-contract

  build:
    name: Build
    needs: changes
    if: needs.changes.outputs.code == 'true'
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
        with:
          lfs: true
      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
        with:
          node-version: 22
      - run: corepack enable
      - run: corepack prepare pnpm@10.17.1 --activate
      - uses: ./.github/actions/prepare-ffmpeg-bin
      - run: bash scripts/ci/install-workspace-dependencies.sh
      - run: bun run build
      - run: bun run verify:packed-manifests

  lint:
    name: Lint
    needs: changes
    if: needs.changes.outputs.code == 'true' || needs.changes.outputs.docs_catalog == 'true'
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
        with:
          lfs: true
          fetch-depth: 0
      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
        with:
          node-version: 22
      - uses: ./.github/actions/prepare-ffmpeg-bin
      - run: bash scripts/ci/install-workspace-dependencies.sh
      - run: bun run lint
      - run: bun run check:docs-catalog

  # `fallow audit` runs dead-code + complexity + duplication analysis scoped to
  # the changed files. The default `--gate new-only` means existing legacy
  # findings don't fail the build — only NEW issues introduced by the PR do.
  # This stops bleeding while letting incremental cleanup land separately.
  #
  # On findings, the job posts (or updates) a sticky comment on the PR so
  # reviewers see the full list inline instead of digging through CI logs.
  fallow:
    name: Fallow audit
    needs: changes
    if: needs.changes.outputs.code == 'true' && github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    timeout-minutes: 5
    # Scope write access to this single job — the rest of `ci.yml` keeps the
    # workflow-level `pull-requests: read` default so build / lint / test
    # tokens can't post or modify PR comments. Job-level permissions override
    # the workflow block.
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
        with:
          # Full history so `--base origin/main` can diff against the merge
          # base on stacked PRs, not just the shallow tip.
          fetch-depth: 0
      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
        with:
          node-version: 22
      - uses: ./.github/actions/prepare-ffmpeg-bin
      - run: bash scripts/ci/install-workspace-dependencies.sh
      - name: Run fallow audit
        id: audit
        # `bun install` above made `bunx fallow` resolve from node_modules, so
        # we don't re-download fallow each run. The script disables `errexit`
        # so the audit's non-zero exit (on findings) doesn't abort before we
        # write the exit code to the step output. The size check guards
        # against fallow crashing before producing markdown (e.g. transient
        # parse failure) — without it we'd post a blank sticky comment.
        run: |
          set +e
          bunx fallow audit --base origin/main --fail-on-issues \
            --format pr-comment-github \
            > /tmp/fallow-comment.md
          echo "exit_code=$?" >> "$GITHUB_OUTPUT"
          if [ ! -s /tmp/fallow-comment.md ]; then
            echo "fallow produced no output — see the job logs above." > /tmp/fallow-comment.md
          fi
      - name: Post sticky comment (findings)
        if: steps.audit.outputs.exit_code != '0'
        # Fork PRs run with a read-only GITHUB_TOKEN regardless of the
        # workflow's `permissions:` block, so the comment post will fail on
        # forks. Don't fail the whole job — the audit gate below still fires.
        continue-on-error: true
        uses: marocchino/sticky-pull-request-comment@773744901bac0e8cbb5a0dc842800d45e9b2b405 # v2.9.4
        with:
          # `header` matches fallow's built-in `<!-- fallow-id: fallow-results -->`
          # sentinel so subsequent runs update the same comment.
          header: fallow-results
          path: /tmp/fallow-comment.md
      - name: Remove stale sticky comment (clean run)
        if: steps.audit.outputs.exit_code == '0'
        continue-on-error: true
        uses: marocchino/sticky-pull-request-comment@773744901bac0e8cbb5a0dc842800d45e9b2b405 # v2.9.4
        with:
          header: fallow-results
          delete: true
      - name: Fail if audit found issues
        if: steps.audit.outputs.exit_code != '0'
        run: |
          echo "::error::Fallow audit found new issues — see the PR comment above for details."
          exit 1

  format:
    name: Format
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
        with:
          lfs: true
      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
        with:
          node-version: 22
      - uses: ./.github/actions/prepare-ffmpeg-bin
      - run: bash scripts/ci/install-workspace-dependencies.sh
      - run: bun run format:check

  typecheck:
    name: Typecheck
    needs: changes
    if: needs.changes.outputs.code == 'true'
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
        with:
          lfs: true
      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
        with:
          node-version: 22
      - uses: ./.github/actions/prepare-ffmpeg-bin
      - run: bash scripts/ci/install-workspace-dependencies.sh
      - run: bun run build
      - run: bun run --filter '*' typecheck
      - run: bun run typecheck:scripts

  test:
    name: Test
    needs: [changes, producer-source-tests]
    # Keep the existing required `Test` context authoritative for producer
    # failures too. The dedicated producer matrix remains parallel and legible,
    # while this job fails closed if either lane fails or is cancelled.
    if: always() && needs.changes.outputs.code == 'true'
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - name: Require producer source tests
        if: needs.producer-source-tests.result != 'success'
        run: |
          echo "::error::Producer unit/integration tests did not succeed."
          exit 1
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
        with:
          lfs: true
      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
        with:
          node-version: 22
      - uses: ./.github/actions/prepare-ffmpeg-bin
      - run: bash scripts/ci/install-workspace-dependencies.sh
      - run: bun run --filter '@hyperframes/{parsers,lint,studio-server}' build
      - run: bun run --cwd packages/core build
      - run: bun run --cwd packages/core build:hyperframes-runtime
      # After the builds: the preview scripts drive the producer, which imports
      # @hyperframes/core from dist, so running these first fails on a missing
      # module rather than on anything the test is actually checking.
      - run: bun run test:scripts
      - run: bun run --filter '!@hyperframes/producer' test

  producer-source-tests:
    name: "Producer: ${{ matrix.lane }} tests"
    needs: changes
    if: needs.changes.outputs.code == 'true'
    runs-on: ubuntu-latest
    timeout-minutes: 20
    strategy:
      fail-fast: false
      matrix:
        lane: [unit, integration]
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
        with:
          lfs: true
      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
        with:
          node-version: 22
      - name: Install FFmpeg for integration tests
        if: matrix.lane == 'integration'
        uses: ./.github/actions/install-ffmpeg-linux
      - uses: ./.github/actions/prepare-ffmpeg-bin
      - run: bash scripts/ci/install-workspace-dependencies.sh
      - run: bun run --filter '@hyperframes/{parsers,lint,studio-server}' build
      - run: bun run --cwd packages/core build
      - run: bun run --filter @hyperframes/engine build
      - run: bun run producer:test:${{ matrix.lane }}

  # Tests under skills/**/*.test.mjs are bare `node --test` files with only
  # `node:` built-in imports. They aren't part of any workspace package, and
  # the main `Test` job's `code` path filter excludes `skills/**`, so without
  # this dedicated job they'd never run in CI. Examples:
  #   * skills/media-use/scripts/resolve.test.mjs
  #   * skills/media-use/scripts/lib/manifest.test.mjs
  # Several of these are regression guards (e.g. shell-injection cases), so
  # the whole point is that they fire on PRs that touch skills/.
  test-skills:
    name: "Test: skills"
    needs: changes
    if: needs.changes.outputs.skills == 'true'
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
        with:
          node-version: 22
      - name: Discover and run skills tests
        # We expand the test list via bash so the job fails loudly when the
        # matcher comes back empty, rather than silently no-op'ing (which
        # would defeat the whole point of this job).
        run: |
          set -euo pipefail
          mapfile -t SKILLS_TESTS < <(find skills -type f -name "*.test.mjs" | sort)
          if [ "${#SKILLS_TESTS[@]}" -eq 0 ]; then
            echo "::error::No skills/**/*.test.mjs files found. Did the layout change?"
            exit 1
          fi
          printf 'Running %d skills test file(s):\n' "${#SKILLS_TESTS[@]}"
          printf '  * %s\n' "${SKILLS_TESTS[@]}"
          node --test "${SKILLS_TESTS[@]}"

  test-skill-bootstrap-windows:
    name: "Test: skill bootstrap (Windows, Node 24)"
    needs: changes
    if: needs.changes.outputs.skills == 'true'
    runs-on: windows-latest
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
        with:
          node-version: 24
      - name: Exercise npm-cli bootstrap command
        run: >-
          node --test
          skills/hyperframes-animation/scripts/package-loader.test.mjs
          skills/hyperframes-creative/scripts/package-loader.test.mjs

  # Guards that skills-manifest.json (the published freshness fingerprint read
  # by `hyperframes skills check`) was regenerated when a skill changed. Runs
  # `gen:skills-manifest --check`, which compares per-skill content hashes; the
  # manifest carries no version/timestamp, so it only fails on real content
  # drift. bun runs the TS script directly, no install needed.
  catalog-index-coverage:
    name: "Catalog: search index covers the registry"
    needs: changes
    if: needs.changes.outputs.catalog_index == 'true'
    runs-on: ubuntu-latest
    timeout-minutes: 3
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
      # Comparing two name lists needs neither the embedding model nor a
      # network call, so this stays a seconds-long gate. Regenerating the
      # vectors does need the model, which is why CI checks rather than fixes.
      - name: Verify every searchable registry item has a vector
        run: bun scripts/catalog/check-artifact-coverage.ts

  skills-manifest:
    name: "Skills: manifest in sync"
    needs: changes
    if: needs.changes.outputs.skills == 'true'
    runs-on: ubuntu-latest
    timeout-minutes: 3
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
      - name: Verify skills-manifest.json matches skills/
        run: bun packages/cli/scripts/gen-skills-manifest.ts --check

  # Repo-native project skills live under .claude/skills/ (Claude Code) and
  # .agents/skills/ (Codex CLI). Runs the skill validator against all three
  # locations (skills/, .claude/skills/, .agents/skills/) and verifies the two
  # project-skill trees stay byte-identical mirrors of each other. Fires on
  # any change to the skill dirs or the two validating scripts.
  project-skills-check:
    name: "Skills: project-native lint + mirror"
    needs: changes
    if: needs.changes.outputs.skills == 'true'
    runs-on: ubuntu-latest
    timeout-minutes: 3
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
      - name: Lint SKILL.md files across skills/, .claude/skills/, .agents/skills/
        run: bun scripts/lint-skills.ts
      - name: Verify .claude/skills/ and .agents/skills/ are byte-identical
        run: node scripts/check-skill-mirror.mjs

  codex-plugin-package:
    name: "Codex plugin package"
    needs: changes
    if: needs.changes.outputs.codex_plugin == 'true'
    runs-on: ubuntu-latest
    timeout-minutes: 3
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
        with:
          node-version: 22
      - name: Build upload-ready Codex plugin
        run: node scripts/package-codex-plugin.mjs

  cli-npx-shim:
    name: "CLI: npx shim (${{ matrix.os }})"
    needs: changes
    if: needs.changes.outputs.cli == 'true'
    runs-on: ${{ matrix.os }}
    timeout-minutes: 10
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
        with:
          node-version: 22
      - name: Install dependencies
        if: runner.os != 'Windows'
        run: bash scripts/ci/install-workspace-dependencies.sh --ignore-scripts
      - name: Install dependencies
        if: runner.os == 'Windows'
        run: bun install --frozen-lockfile --ignore-scripts --linker=hoisted
      - run: bun run --cwd packages/cli test src/utils/npxCommand.test.ts src/commands/skills.test.ts

  sdk-tests:
    name: "SDK: unit + contract + smoke"
    needs: changes
    if: needs.changes.outputs.code == 'true'
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
      - run: bash scripts/ci/install-workspace-dependencies.sh
      # Build workspace deps so the sdk's @hyperframes/parsers + core subpath
      # imports resolve via the "node" export condition (dist) under vitest.
      - run: bun run --filter '@hyperframes/parsers' build
      - run: bun run --cwd packages/core build
      - run: bun run --filter @hyperframes/sdk test

  test-runtime-contract:
    name: "Test: runtime contract"
    needs: changes
    if: needs.changes.outputs.code == 'true'
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
        with:
          lfs: true
      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
        with:
          node-version: 22
      - uses: ./.github/actions/prepare-ffmpeg-bin
      - run: bash scripts/ci/install-workspace-dependencies.sh
      # Runtime coverage now imports core modules that consume workspace
      # subpaths. Build their dist exports before Vitest resolves them.
      - run: bun run --filter '@hyperframes/{parsers,lint,studio-server}' build
      - run: bun run --filter @hyperframes/core test:hyperframe-runtime-ci

  studio-load-smoke:
    name: "Studio: load smoke"
    needs: [changes]
    if: needs.changes.outputs.code == 'true'
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
        with:
          lfs: true
      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
        with:
          node-version: 22
      - uses: ./.github/actions/prepare-ffmpeg-bin
      - run: bash scripts/ci/install-workspace-dependencies.sh
      # Build workspace deps so the studio vite.config.ts (loaded by Node) can
      # resolve @hyperframes/core and @hyperframes/studio-server via the "node"
      # export condition (dist).
      - run: bun run --filter '@hyperframes/{parsers,lint,studio-server}' build
      - run: bun run --cwd packages/core build
      - run: bun run --cwd packages/core build:hyperframes-runtime
      - name: Start studio and check for runtime errors
        run: |
          # Start the studio Vite dev server (fast — no bundle step)
          bun run --filter '@hyperframes/studio' dev -- --port 5199 &
          SERVER_PID=$!

          # Wait for the server to be ready (up to 20s)
          for i in $(seq 1 40); do
            if curl -sf http://localhost:5199/ >/dev/null 2>&1; then break; fi
            sleep 0.5
          done

          if ! curl -sf http://localhost:5199/ >/dev/null 2>&1; then
            echo "FAIL: studio dev server did not start"
            kill $SERVER_PID 2>/dev/null || true
            exit 1
          fi

          # Load the studio in headless Chrome with API mocking to trigger
          # the full splash→main transition (catches hooks-after-early-return bugs)
          node scripts/studio-runtime-smoke.mjs http://localhost:5199/#project=smoke-test

          kill $SERVER_PID 2>/dev/null || true

  studio-timeline-viewport:
    name: "Studio: timeline viewport gate"
    needs: [changes]
    if: needs.changes.outputs.studio == 'true'
    runs-on: ubuntu-latest
    timeout-minutes: 12
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
        with:
          node-version: 22
      - run: bash scripts/ci/install-workspace-dependencies.sh
      # Same reason as studio-load-smoke: vite.config.ts is loaded by Node and
      # resolves the workspace packages through their "node" export condition.
      - run: bun run --filter '@hyperframes/{parsers,lint,studio-server}' build
      - run: bun run --cwd packages/core build
      - run: bun run --cwd packages/core build:hyperframes-runtime
      - name: Install the fixture as a Studio project
        # Studio resolves projects from packages/studio/data/projects, which is
        # gitignored. The fixture composition is tracked under tests/e2e, so
        # copy it into place rather than committing a project directory.
        run: |
          mkdir -p packages/studio/data/projects
          cp -R packages/studio/tests/e2e/fixtures/timeline-virtualization \
            packages/studio/data/projects/timeline-virtualization
      - name: Run both arms of the timeline viewport gate
        run: |
          set -euo pipefail

          SERVER_PID=""
          stop_server() {
            if [[ -n "$SERVER_PID" ]]; then
              kill "$SERVER_PID" 2>/dev/null || true
              wait "$SERVER_PID" 2>/dev/null || true
              SERVER_PID=""
            fi
          }
          wait_for_server() {
            local port="$1"
            for i in $(seq 1 60); do
              if curl -sf "http://localhost:${port}/" >/dev/null 2>&1; then return 0; fi
              sleep 1
            done
            echo "FAIL: studio dev server did not start on port ${port}"
            return 1
          }
          trap stop_server EXIT

          # Run one server at a time so the measured browser never competes with
          # a second Vite module graph on the shared runner. The development
          # server supplies the fixture API; production React matches shipped
          # rendering behavior, and the gate asserts that runtime before timing.
          NODE_ENV=production \
            bun run --cwd packages/studio dev -- --port 5313 --strictPort &
          SERVER_PID=$!
          DEFAULT_STATUS=0
          if wait_for_server 5313; then
            STUDIO_URL="http://localhost:5313/#project/timeline-virtualization" \
              TIMELINE_ROW_VIRTUALIZATION=on \
              TIMELINE_ELEMENT_COUNT=50000 \
              TIMELINE_TIER=ci \
              node packages/studio/tests/e2e/timeline-virtualization.mjs \
              | tee /tmp/timeline-gate-default.json \
              || DEFAULT_STATUS=$?
          else
            DEFAULT_STATUS=1
          fi
          stop_server

          NODE_ENV=production \
            VITE_STUDIO_TIMELINE_ROW_VIRTUALIZATION_ENABLED=0 \
            bun run --cwd packages/studio dev -- --port 5314 --strictPort &
          SERVER_PID=$!
          DISABLED_STATUS=0
          if wait_for_server 5314; then
            STUDIO_URL="http://localhost:5314/#project/timeline-virtualization" \
              TIMELINE_ROW_VIRTUALIZATION=off \
              TIMELINE_ELEMENT_COUNT=1000 \
              TIMELINE_TIER=ci \
              node packages/studio/tests/e2e/timeline-virtualization.mjs \
              | tee /tmp/timeline-gate-disabled.json \
              || DISABLED_STATUS=$?
          else
            DISABLED_STATUS=1
          fi
          stop_server

          {
            echo "### Timeline viewport gate"
            echo "- Default arm exit: ${DEFAULT_STATUS}"
            echo "- Explicitly disabled arm exit: ${DISABLED_STATUS}"
          } >> "$GITHUB_STEP_SUMMARY"

          if (( DEFAULT_STATUS != 0 || DISABLED_STATUS != 0 )); then
            echo "FAIL: default=${DEFAULT_STATUS}, disabled=${DISABLED_STATUS}"
            exit 1
          fi
      - name: Upload gate evidence
        # The gate's whole output is machine-readable evidence, and a red run is
        # exactly when someone needs to read it. Keep it on failure too.
        if: always()
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
        with:
          name: timeline-viewport-gate-evidence
          path: /tmp/timeline-gate-*.json
          if-no-files-found: error

  smoke-global-install:
    name: "Smoke: global install"
    needs: [changes, build]
    if: needs.changes.outputs.code == 'true'
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
        with:
          lfs: true
      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
        with:
          node-version: 22
      - uses: ./.github/actions/prepare-ffmpeg-bin
      - run: bash scripts/ci/install-workspace-dependencies.sh
      - run: bun run build

      # Pack the CLI as a tarball (simulates what `npm publish` produces)
      - name: Pack CLI tarball
        run: cd packages/cli && npm pack

      # Install globally using --prefix to avoid sudo
      - name: Install globally via npm
        run: npm install -g --prefix /tmp/hf-smoke ./packages/cli/hyperframes-cli-*.tgz

      # Scaffold a blank project
      - name: Init blank project
        run: |
          export PATH="/tmp/hf-smoke/bin:$PATH"
          mkdir /tmp/hf-project && cd /tmp/hf-project
          hyperframes init test-project --example blank

      # Start preview, probe the runtime endpoint, assert no esbuild errors
      - name: Smoke-test preview server
        run: |
          export PATH="/tmp/hf-smoke/bin:$PATH"
          cd /tmp/hf-project/test-project

          # Start the preview server in the background; capture stderr
          CI=true hyperframes preview --port 3099 2>/tmp/hf-stderr.log &
          SERVER_PID=$!

          # Wait for the server to be ready (up to 15 s)
          for i in $(seq 1 30); do
            if curl -sf http://localhost:3099/ >/dev/null 2>&1; then
              break
            fi
            sleep 0.5
          done

          # Probe the runtime JS endpoint
          BODY=$(curl -sf http://localhost:3099/api/runtime.js | head -c 200 || true)
          if [ -z "$BODY" ]; then
            echo "FAIL: /api/runtime.js returned empty response"
            kill $SERVER_PID 2>/dev/null || true
            cat /tmp/hf-stderr.log
            exit 1
          fi

          kill $SERVER_PID 2>/dev/null || true
          wait $SERVER_PID 2>/dev/null || true

          # Assert stderr does not contain esbuild / runtime load errors
          if grep -qE '✘ \[ERROR\]|Failed to load runtime' /tmp/hf-stderr.log; then
            echo "FAIL: preview emitted runtime errors:"
            cat /tmp/hf-stderr.log
            exit 1
          fi

          echo "PASS: global install smoke test succeeded"

  cli-smoke-required:
    name: "CLI smoke (required)"
    needs: changes
    if: needs.changes.outputs.code == 'true'
    runs-on: ubuntu-latest
    timeout-minutes: 25
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
        with:
          lfs: true
      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
        with:
          node-version: 22
      - name: Install FFmpeg
        uses: ./.github/actions/install-ffmpeg-linux
      - uses: ./.github/actions/prepare-ffmpeg-bin
      - name: Install dependencies
        run: bash scripts/ci/install-workspace-dependencies.sh
      - name: Build monorepo
        run: bun run build

      - name: Create smoke input video
        run: |
          set -euo pipefail
          ffmpeg -hide_banner -loglevel error \
            -f lavfi -i testsrc2=size=640x360:rate=30 \
            -f lavfi -i sine=frequency=880:sample_rate=48000 \
            -t 3 \
            -c:v libx264 \
            -pix_fmt yuv420p \
            -c:a aac \
            -shortest \
            -y /tmp/hf-cli-input.mp4
          test -s /tmp/hf-cli-input.mp4

      - name: Smoke-test CLI from monorepo source
        # init's --skip-skills flag is neutered (see init.ts); opt out of the
        # GitHub skills check via this env so the smoke test stays offline/fast.
        env:
          HYPERFRAMES_SKIP_SKILLS: "1"
        run: |
          set -euo pipefail
          rm -rf /tmp/hf-cli-inside

          bun run --filter @hyperframes/cli dev -- init /tmp/hf-cli-inside \
            --example warm-grain \
            --video /tmp/hf-cli-input.mp4 \
            --skip-transcribe \
            --non-interactive \
            --skip-skills

          bun run --filter @hyperframes/cli dev -- lint /tmp/hf-cli-inside
          bun run --filter @hyperframes/cli dev -- validate /tmp/hf-cli-inside --timeout 3000
          bun run --filter @hyperframes/cli dev -- render /tmp/hf-cli-inside \
            --quality standard \
            --workers auto \
            --strict \
            --output /tmp/hf-cli-inside/renders/inside.mp4 2>&1 | tee /tmp/hf-cli-render.log

          test -s /tmp/hf-cli-inside/renders/inside.mp4

      # Belongs in this job because it needs the BUILT CLI: `shouldTrack()`
      # short-circuits whenever `isDevMode()` is true, which it is for any `.ts`
      # entry, so under vitest a real event and no event look identical. Sends
      # nothing to PostHog — the script wraps fetch and captures the batch.
      - name: Smoke-test `add` telemetry end to end
        run: node scripts/ci/cli-telemetry-e2e.mjs

      - name: Assert page.goto completes under 5s budget
        run: |
          set -euo pipefail
          # Extract the longest page.goto time from render logs.
          # Format: [initSession:MODE] page.goto complete (NNNms)
          MAX_MS=$(grep -oP 'page\.goto complete \(\K[0-9]+' /tmp/hf-cli-render.log | sort -n | tail -1)
          if [ -z "$MAX_MS" ]; then
            echo "::error::No page.goto timing found in render logs — log format may have changed. Update the grep pattern."
            exit 1
          fi
          echo "Slowest page.goto: ${MAX_MS}ms (budget: 5000ms)"
          if [ "$MAX_MS" -gt 5000 ]; then
            echo "::error::page.goto took ${MAX_MS}ms — exceeds 5s budget. Possible Proxy/stub regression."
            exit 1
          fi

      - name: Pack CLI tarball
        run: |
          set -euo pipefail
          mkdir -p /tmp/hf-cli-pack
          cd packages/cli
          PACKED_TARBALL="$(npm pack --pack-destination /tmp/hf-cli-pack | tail -n 1)"
          test -n "$PACKED_TARBALL"
          test -f "/tmp/hf-cli-pack/$PACKED_TARBALL"
          echo "HF_CLI_TARBALL=/tmp/hf-cli-pack/$PACKED_TARBALL" >> "$GITHUB_ENV"

      - name: Install packed CLI outside monorepo
        run: |
          set -euo pipefail
          npm install -g --prefix /tmp/hf-cli-global "$HF_CLI_TARBALL"

      - name: Smoke-test packed CLI outside monorepo
        # init's --skip-skills flag is neutered (see init.ts); opt out of the
        # GitHub skills check via this env so the smoke test stays offline/fast.
        env:
          HYPERFRAMES_SKIP_SKILLS: "1"
        run: |
          set -euo pipefail
          export PATH="/tmp/hf-cli-global/bin:$PATH"
          rm -rf /tmp/hf-cli-outside

          hyperframes init /tmp/hf-cli-outside \
            --example warm-grain \
            --video /tmp/hf-cli-input.mp4 \
            --skip-transcribe \
            --non-interactive \
            --skip-skills

          hyperframes lint /tmp/hf-cli-outside
          hyperframes validate /tmp/hf-cli-outside --timeout 3000
          hyperframes render /tmp/hf-cli-outside \
            --quality standard \
            --workers auto \
            --strict \
            --output /tmp/hf-cli-outside/renders/outside.mp4

          test -s /tmp/hf-cli-outside/renders/outside.mp4

  filesize:
    name: File size check
    runs-on: ubuntu-latest
    timeout-minutes: 1
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
        with:
          fetch-depth: 0
      - name: Check file sizes (max 600 lines)
        # Scoped to files THIS PR changed under packages/studio. Walking the
        # whole tree blamed every unrelated PR for pre-existing offenders.
        # Falls back to a full scan on push events (no base ref available)
        # so the rule still guards main.
        run: |
          set -e
          if [ -n "${{ github.base_ref }}" ]; then
            mapfile -t files < <(
              git diff --name-only --diff-filter=ACMR \
                "origin/${{ github.base_ref }}...HEAD" -- \
                'packages/studio/**/*.ts' 'packages/studio/**/*.tsx' \
                | grep -vE '\.(test|spec)\.(ts|tsx)$|\.generated\.' || true
            )
          else
            mapfile -t files < <(
              find packages/studio -path '*/node_modules' -prune -o \
                \( -name '*.ts' -o -name '*.tsx' \) -print \
                | grep -vE '\.(test|spec)\.(ts|tsx)$|\.generated\.'
            )
          fi
          EXIT=0
          for f in "${files[@]}"; do
            [ -z "$f" ] && continue
            [ -f "$f" ] || continue  # skip files deleted in this PR
            lines=$(wc -l < "$f")
            if [ "$lines" -gt 600 ]; then
              echo "::error file=$f::$f has $lines lines (max 600)"
              EXIT=1
            fi
          done
          exit $EXIT

  semantic-pr-title:
    name: Semantic PR title
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - uses: amannn/action-semantic-pull-request@e32d7e603df1aa1ba07e981f2a23455dee596825 # v5
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          types: |
            feat
            fix
            docs
            style
            refactor
            perf
            test
            build
            ci
            chore
            revert