feat(animation): add weighted playback and authored locomotion evaluation

.github/workflows/integration.yml

@@ -35,7 +35,7 @@ env:
   TN_BASE_SHA: ${{ inputs.base_sha }}
 
 jobs:
-  # The per-lane trigger filters these six files used to carry, as one gate: the pull request's own
+  # The per-lane trigger filters these lane files used to carry, as one gate: the pull request's own
   # changed paths decide which lanes run, and a lane this commit does not touch is skipped rather than
   # spending a runner. Lane-local workflow edits select that lane; shared scheduling edits
   # fail closed to every lane. Source filters remain independent of workflow-only selection.
@@ -48,6 +48,7 @@ jobs:
       contents: read
       actions: read
     outputs:
+      animation: ${{ steps.filter.outputs.animation }}
       candidate_sha: ${{ steps.filter.outputs.candidate_sha }}
       required_jobs: ${{ steps.filter.outputs.required_jobs }}
       exposure: ${{ steps.filter.outputs.exposure }}
@@ -74,6 +75,7 @@ jobs:
           TN_HEAD_SHA: ${{ inputs.candidate_sha }}
           # Exact source filters; workflow-only changes compare each job and filter separately.
           TN_LANE_FILTERS: |
+            animation ^packages/core/src/animation\.ts$|^packages/core/__tests__/animation[^/]*\.spec\.ts$|^examples/abyss-framework/src/render/animation-reversal[^/]*\.ts$|^examples/abyss-framework/src/animation-reversal-main\.ts$|^examples/abyss-framework/animation-reversal\.html$|^examples/abyss-framework/playtests/animation-reversal\.playtest\.json$|^scripts/verify-animation-reversal\.ts$|^packages/core/__tests__/vq-locomotion-blend-spaces\.spec\.ts$|^examples/abyss-framework/src/render/locomotion-[^/]*\.ts$|^examples/abyss-framework/src/render/vq-locomotion-[^/]*\.ts$|^examples/abyss-framework/src/vq-locomotion-main\.ts$|^examples/abyss-framework/playtests/vq-locomotion-blend-spaces\.playtest\.json$|^examples/abyss-framework/assets/mannequin\.glb$|^scripts/verify-vq-locomotion\.ts$
             cold-boot ^packages/create-threenative/(template-assets|templates/[^/]+/src/render)/(autoExposure|exposure|exposureGraph|exposureReadback|worldEnvironment)\.ts$|^packages/create-threenative/__tests__/auto-exposure[^/]*\.spec\.ts$|^packages/create-threenative/__tests__/fixtures/auto-exposure/.*$|^packages/core/src/.*$|^packages/core/patches/.*$|^packages/playtest/.*$|^packages/runtime-native/.*$|^pnpm-lock\.yaml$|^scripts/xvfb\.sh$|^\.github/actions/(workspace-dist|pnpm|playwright-chromium)/.*$
             exposure ^packages/create-threenative/(template-assets|templates/[^/]+/src/render)/(autoExposure|exposure|exposureGraph|exposureReadback|worldEnvironment)\.ts$|^packages/create-threenative/__tests__/auto-exposure[^/]*\.spec\.ts$|^packages/create-threenative/__tests__/fixtures/auto-exposure/.*$|^packages/core/src/.*$|^packages/core/patches/.*$|^packages/playtest/.*$|^packages/runtime-native/.*$|^pnpm-lock\.yaml$|^scripts/xvfb\.sh$|^\.github/actions/(workspace-dist|pnpm|playwright-chromium)/.*$
             csg ^examples/integrations/csg/.*$
@@ -348,6 +350,130 @@ jobs:
           path: ${{ github.workspace }}/artifacts/ci-integration-receipts/${{ github.job }}.json
           if-no-files-found: error
 
+  animation:
+    name: animation
+    if: ${{ needs.paths.outputs.animation == 'true' && !github.event.pull_request.draft }}
+    needs: paths
+    runs-on: ${{ (github.event.pull_request.head.repo.fork || !vars.TN_RUNNER) && 'ubuntu-24.04' || vars.TN_RUNNER }}
+    timeout-minutes: 25
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
+        with:
+          persist-credentials: false
+          ref: ${{ inputs.candidate_sha }}
+      - uses: ./.github/actions/pnpm
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
+        with:
+          node-version: '22'
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - uses: ./.github/actions/workspace-dist
+        with:
+          pack-archives: 'false'
+          save-bundles: 'false'
+      - uses: ./.github/actions/playwright-chromium
+      - run: pnpm exec vitest run --maxWorkers=1 packages/core/__tests__/animation.spec.ts packages/core/__tests__/animation-reversal-fixture.spec.ts packages/core/__tests__/animation-weighted.spec.ts packages/core/__tests__/vq-locomotion-blend-spaces.spec.ts
+      - name: Capture real mannequin gait reversals on headed WebGPU
+        run: node --import tsx scripts/verify-animation-reversal.ts
+      - name: Capture the two-rig locomotion blend spaces on headed WebGPU
+        run: node --import tsx scripts/verify-vq-locomotion.ts
+      - uses: actions/upload-artifact@v7
+        if: always()
+        with:
+          name: vq04-animation-${{ github.run_id }}-${{ github.run_attempt }}-${{ inputs.candidate_sha }}
+          path: artifacts/vq04-animation
+          if-no-files-found: error
+      - name: Record exact current-attempt integration receipt
+        if: ${{ always() }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TN_CI_JOB_RESULT: ${{ job.status }}
+        run: node "$GITHUB_WORKSPACE/scripts/ci-integration-receipts.mjs" --write
+      - uses: actions/upload-artifact@v7
+        if: ${{ always() }}
+        with:
+          name: ci-integration-receipt-${{ github.run_id }}-${{ github.run_attempt }}-${{ inputs.candidate_sha }}-${{ github.job }}
+          path: ${{ github.workspace }}/artifacts/ci-integration-receipts/${{ github.job }}.json
+          if-no-files-found: error
+
+  animation-native:
+    name: Linux native locomotion correctness
+    needs: [animation]
+    # The browser capture cannot say what the compiled runtime does with the same blend-space
+    # trace, and a stale host binary answers for the wrong source. Build this candidate's ARM
+    # desktop host and run the authored scenario file unchanged, so the lane's own scenario is
+    # the native proof rather than a second near-copy of it.
+    runs-on: ubuntu-24.04-arm
+    timeout-minutes: 60
+    env:
+      CMAKE_BUILD_PARALLEL_LEVEL: '2'
+      TN_PLAYTEST_ALLOW_SOFTWARE: '1'
+      TN_PLAYTEST_NATIVE_SCREENSHOT_TIMEOUT_MS: '30000'
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
+        with:
+          persist-credentials: false
+          ref: ${{ inputs.candidate_sha }}
+      - uses: ./.github/actions/pnpm
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
+        with:
+          node-version: '22'
+          cache: pnpm
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.12'
+      - run: pnpm install --frozen-lockfile
+      - name: Build this source's public JavaScript packages
+        uses: ./.github/actions/workspace-dist
+        with:
+          save-bundles: 'false'
+          pack-archives: 'false'
+      - name: Restore checksum-provisioned native dependencies
+        uses: actions/cache/restore@v4
+        with:
+          path: packages/runtime-native/third_party
+          key: native-third-party-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('packages/runtime-native/scripts/download-deps.mjs', 'packages/runtime-native/scripts/package-android.mjs') }}
+      - name: Install the existing native lane's system prerequisites
+        run: >-
+          sudo apt-get update && sudo apt-get install -y
+          libasound2-dev libcurl4-openssl-dev libfontconfig1-dev libfreetype6-dev
+          libpulse-dev libudev-dev libx11-dev libxext-dev libxrandr-dev
+          libxcursor-dev libxi-dev libxfixes-dev libxss-dev libxkbcommon-dev
+          libgtk-3-dev libwebkit2gtk-4.1-dev libxcomposite-dev xcompmgr
+          libvulkan1 mesa-vulkan-drivers vulkan-tools xvfb zlib1g-dev
+      - name: Build the ordinary ARM desktop host from this source
+        run: pnpm --filter @threenative/runtime-native native:build
+      - name: Bundle the authored locomotion entry for the native host
+        run: node packages/runtime-native/scripts/bundle.mjs --project examples/abyss-framework --entry src/render/vq-locomotion-game.ts --target desktop --output examples/abyss-framework/dist/vq-locomotion-native.js
+      - name: Record this run's host identity beside its screenshots
+        run: |
+          mkdir -p examples/abyss-framework/artifacts/playtest
+          sha256sum packages/runtime-native/build/tn-linux/mystral > examples/abyss-framework/artifacts/playtest/native-host-identity.txt
+          git rev-parse HEAD >> examples/abyss-framework/artifacts/playtest/native-host-identity.txt
+      - name: Run the authored locomotion trace on the freshly built host
+        # A non-zero CLI status fails the step, so a run that never reached its assertions fails too.
+        run: sh scripts/xvfb.sh node packages/playtest/dist/runner/cli.js playtests/vq-locomotion-blend-spaces.playtest.json --target desktop --executable ${{ github.workspace }}/packages/runtime-native/build/tn-linux/mystral --project examples/abyss-framework --host-arg run --host-arg dist/vq-locomotion-native.js
+      - name: Retain native screenshots, host console and executable identities
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: vq04-locomotion-native-${{ github.run_id }}-${{ github.run_attempt }}-${{ inputs.candidate_sha }}
+          path: examples/abyss-framework/artifacts/playtest
+          retention-days: 30
+          if-no-files-found: warn
+      - name: Record exact current-attempt integration receipt
+        if: ${{ always() }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TN_CI_JOB_RESULT: ${{ job.status }}
+        run: node "$GITHUB_WORKSPACE/scripts/ci-integration-receipts.mjs" --write
+      - uses: actions/upload-artifact@v7
+        if: ${{ always() }}
+        with:
+          name: ci-integration-receipt-${{ github.run_id }}-${{ github.run_attempt }}-${{ inputs.candidate_sha }}-${{ github.job }}
+          path: ${{ github.workspace }}/artifacts/ci-integration-receipts/${{ github.job }}.json
+          if-no-files-found: error
+
   fog:
     name: fog capture
     if: ${{ needs.paths.outputs.fog == 'true' && !github.event.pull_request.draft }}
@@ -827,7 +953,7 @@ jobs:
 
   completion:
     name: Verify required integration receipts
-    needs: [paths, csg, ik, vegetation, decals, decals-native, tone, fog, fog-native, capture, fluid-collision, fluid-collision-native, packaged-quickjs, exposure, cold-boot]
+    needs: [paths, csg, ik, vegetation, decals, decals-native, tone, animation, animation-native, fog, fog-native, capture, fluid-collision, fluid-collision-native, packaged-quickjs, exposure, cold-boot]
     if: ${{ always() }}
     runs-on: ${{ (github.event.pull_request.head.repo.fork || !vars.TN_RUNNER_LIGHT) && 'ubuntu-24.04' || vars.TN_RUNNER_LIGHT }}
     timeout-minutes: 5

biome.json

@@ -45,6 +45,7 @@
       "docs/benchmark/rounds/**",
       "docs/verification/prd-357-c4-duplicate-inventory.json",
       "docs/verification/prd-357-c4-duplicate-inventory-before.json",
+      "docs/verification/vq04/**",
       "docs/verification/visuals/**",
       "benchmark/engine-load-test/godot-lights-meshes/benchmark_box_1000.json"
     ]