Starter kits: Unreal look, shooter revamp, performance by construction, kit contract and worker mode (PRD-723/746/747/748/749/752)

.agents/skills/native-performance-loop/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: native-performance-loop
-description: Run an autonomous ThreeNative native-performance optimization loop using existing harnesses, quick synthetic load tests, and representative real games. Profile bottlenecks, make focused changes, accept or reject measured experiments, and maintain an HTML benchmark dashboard. Use for sustained native runtime optimization, frame pacing, startup, memory, or thermal efficiency campaigns, including the Tempest (rain) campaign where the web Wasm engine must beat stock three.js with the same image.
+description: Run an autonomous ThreeNative native-performance optimization loop using existing harnesses, quick synthetic load tests, and representative real games. Profile bottlenecks, make focused changes, accept or reject measured experiments, and keep a campaign tab in the one `pnpm dashboard` hub. Use for sustained native runtime optimization, frame pacing, startup, memory, or thermal efficiency campaigns, including the Tempest (rain) campaign where the web Wasm engine must beat stock three.js with the same image.
 ---
 
 # Native performance loop
@@ -28,8 +28,8 @@ the developer to supervise each iteration. Creating or editing this skill does n
    Browser results are comparison or diagnosis, never substitute native evidence. Read the local
    `measure-steady-state-fps` and `probe-android-startup-and-heat` skills when their lanes apply.
 4. Create or resume `<primary>/artifacts/native-performance-loop/<campaign-id>/`. Record the
-   contract and results described in [dashboard.md](references/dashboard.md), and create
-   `index.html` immediately, including an honest empty state. Choose workloads and targets
+   contract and results described in [dashboard.md](references/dashboard.md), and show them in a
+   `pnpm dashboard` tab immediately, including an honest empty state. Choose workloads and targets
    autonomously and state them. Default to a two-hour invocation budget, including setup and
    verification, unless the user supplied another duration or experiment limit. Reserve the last
    20 minutes for confirmation, restoration, and delivery; do not launch work that cannot finish
@@ -139,7 +139,7 @@ hypothesis; reaching a target does not establish a hardware limit. Do not instal
 scheduler or claim work continues after the agent stops.
 
 Before delivery, reproduce the best accepted build, rerun affected repository checks and native
-scenarios, refresh `index.html`, and record unrun platforms honestly. Preserve the dashboard and
+scenarios, update the campaign record, and record unrun platforms honestly. Preserve the record and
 raw artifacts outside a disposable task checkout. Follow the repository's PR and worktree cleanup
 rules within the session's existing authorization; no implicit push, merge or publication. Report
 any retained worktree's exact path, size and cleanup blocker. Finish with the dashboard link,

.agents/skills/native-performance-loop/references/dashboard.md

@@ -1,30 +1,30 @@
-# Campaign state and HTML dashboard
+# Campaign state and the dashboard tab
 
-Generate this on invocation, not when installing the skill. The HTML is the developer's view of
-one machine-readable campaign record, not a second manually maintained evidence report.
+Create this on invocation, not when installing the skill. The developer's view is one tab of the
+single KPI hub, `pnpm dashboard` (`scripts/perf-live.ts`, PRD-751), reading one machine-readable
+campaign record. Do not generate a per-campaign HTML page or a second evidence report.
 
 ## Files and updates
 
 Use `<primary>/artifacts/native-performance-loop/<campaign-id>/` with:
 
 - `results.json`: versioned contract, environment identities, workloads, baselines, incumbent,
   experiment history, status, heartbeat, limits and next hypothesis.
-- `index.html`: an offline, self-contained dashboard generated from `results.json`.
 - `raw/<experiment-id>/`: existing harness output, exit codes, sample data, profiles, screenshots,
   candidate patch/commit reference, build identities and exact reproduction commands.
 
-Reuse a suitable existing report renderer if present. Otherwise generate a small HTML file with
-inline CSS, embedded data and minimal browser JavaScript; save the small renderer alongside the
-campaign only if needed to regenerate it reliably. No web framework, backend, CDN or new dependency.
-It must open with `file://` without fetching JSON. Write JSON and HTML via temporary siblings and
-atomic replacement, preserving the last readable snapshot if generation fails.
+Reuse an existing hub tab when its reader fits the record (the Shadows vs Unreal tab reads a
+campaign `results.json`). Otherwise add one: a small reader beside `scripts/shadow-perf/dashboard.ts`
+that reads `results.json`, writes nothing and fails closed (missing = `pending`, malformed =
+`invalid`), plus one `TABS` row and one route in `scripts/perf-live.ts`, with a test in
+`scripts/__tests__/perf-live.spec.ts`. No web framework, CDN or new dependency. Write
+`results.json` via a temporary sibling and atomic replacement, preserving the last readable record.
 
-Create the dashboard before the first benchmark, showing “baseline pending,” never sample wins.
-Refresh after each state transition and decision. During long commands, publish a timestamp and
-heartbeat at least every 60 seconds using the existing gate status where available. The HTML must
-show its snapshot time; when an old snapshot is open, say “reload for current progress” instead of
-pretending it is live. If serving locally is already supported, optional refresh must preserve
-filters. A stale heartbeat is “stale / check process,” never proof the worker is still active.
+Add the tab before the first benchmark, showing “baseline pending,” never sample wins. Update the
+record after each state transition and decision. During long commands, publish a timestamp and
+heartbeat at least every 60 seconds using the existing gate status where available. The tab shows
+the record's update time. A stale heartbeat is “stale / check process,” never proof the worker is
+still active.
 
 Escape benchmark names, descriptions, commands and log content as text. If embedding JSON in an
 HTML script element, escape `<` as `\u003c` so data cannot terminate the script. Use textContent for
@@ -73,14 +73,14 @@ FPS derived from percentiles or average several games into an unqualified perfor
 
 ## Verify and resume
 
-Before handing off an HTML snapshot, open it in a browser when a browser tool is available. Check
-that it opens offline, shows actual recorded values, distinguishes missing/provisional data, and
+Before handing off, open the tab in `pnpm dashboard` in a browser when a browser tool is available.
+Check that it shows actual recorded values, distinguishes missing/provisional data, and
 that filters, keyboard controls and evidence links work. A renderer with non-trivial logic needs
 one small runnable check covering metric direction, missing values and unsafe text. If no browser
 is available, check generated structure and links and mark visual inspection unverified.
 
 On resume, load the contract and history, verify ownership and process state, and reconcile the
 worktree with the recorded incumbent before editing. Check executable/workload/environment hashes;
 if any comparison dimension changed, create a new series and baseline instead of connecting its
-points to the old curve. Preserve all previous decisions. Link to this dashboard in the PRD/PR and
+points to the old curve. Preserve all previous decisions. Link to this tab in the PRD/PR and
 final response rather than copying its experiment log into another report.

.claude/skills/ci-speed-loop/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ci-speed-loop
-description: Run ThreeNative's CI speed loop — measure how long a change takes to merge, name the biggest cost from the first failing jobs and queue wait, change one thing, re-measure the same window, record the iteration and refresh the HTML dashboard. Use when asked to speed up CI or the merge queue, work PRD-550, check progress toward the 30-minute merge goal, or refresh docs/ci-speed/index.html. Not for runtime FPS (perf-loop).
+description: Run ThreeNative's CI speed loop — measure how long a change takes to merge, name the biggest cost from the first failing jobs and queue wait, change one thing, re-measure the same window, record the iteration. Use when asked to speed up CI or the merge queue, work PRD-550, check progress toward the 30-minute merge goal, or read the CI speed tab of `pnpm dashboard`. Not for runtime FPS (perf-loop).
 ---
 
 # CI speed loop
@@ -20,11 +20,11 @@ node scripts/ci-merge-latency.mjs --since 2026-10-09          # measure only, pr
 node scripts/ci-speed-loop.mjs record --since 2026-10-09 --label "gating board" --notes "..." [--decision keep]
 node scripts/ci-speed-loop.mjs show                           # the ledger
 node scripts/ci-speed-loop.mjs discard --iteration 3 --reason "queue outage, 2 PRs only"
-node scripts/ci-speed-loop.mjs report                         # regenerate the HTML only
+pnpm dashboard                                               # the CI speed tab renders the ledger
 ```
 
-`docs/ci-speed/ledger.json` is the record. `docs/ci-speed/index.html` is generated from it and opens with
-`file://`. Never edit either by hand. Commit both with the change they measure.
+`docs/ci-speed/ledger.json` is the record; the CI speed tab of `pnpm dashboard` renders it on each load
+(PRD-751). Do not edit it by hand. Commit it with the change it measures.
 
 ## The turn
 

.github/actions/native-engine-wasm/action.yml

@@ -1,7 +1,7 @@
 name: Build the product web Wasm engine, or restore the last build of the same sources
 description: >-
   A game on the default `engine: "native"` runs in the browser on packages/runtime-native/build/web/
-  tn-native-engine-web.{mjs,wasm}. Nothing else builds it, `pnpm pack` drops a missing `files` entry
+  tn-native-engine-web{,-threads}.{mjs,wasm} (the threaded one for cross-origin-isolated pages). Nothing else builds it, `pnpm pack` drops a missing `files` entry
   without an error, and a web build without it stops at TN_WASM_ENGINE_MISSING. Run this after
   `pnpm install` and before anything that builds a web game or packs runtime-native.
 
@@ -29,7 +29,7 @@ runs:
       uses: actions/cache@v4
       with:
         path: ${{ github.workspace }}/packages/runtime-native/build/web
-        key: native-engine-web-wasm-v1-${{ runner.os }}-${{ runner.arch }}-${{ inputs.emsdk-version }}-${{ hashFiles('packages/runtime-native/src/engine/**', 'packages/runtime-native/include/**', 'packages/runtime-native/cmake/**', 'packages/runtime-native/CMakeLists.txt', 'packages/runtime-native/CMakePresets.json', 'packages/runtime-native/native-deps.lock.json', 'packages/runtime-native/scripts/download-deps.mjs', 'packages/runtime-native/scripts/web-engine-stamp.mjs') }}
+        key: native-engine-web-wasm-v2-${{ runner.os }}-${{ runner.arch }}-${{ inputs.emsdk-version }}-${{ hashFiles('packages/runtime-native/src/engine/**', 'packages/runtime-native/include/**', 'packages/runtime-native/cmake/**', 'packages/runtime-native/CMakeLists.txt', 'packages/runtime-native/CMakePresets.json', 'packages/runtime-native/native-deps.lock.json', 'packages/runtime-native/scripts/download-deps.mjs', 'packages/runtime-native/scripts/web-engine-stamp.mjs') }}
     - name: Build the web engine
       if: steps.wasm.outputs.cache-hit != 'true'
       shell: bash
@@ -49,21 +49,26 @@ runs:
           node scripts/download-deps.mjs --only "$dependency"
         done
         source "$GITHUB_WORKSPACE/.cache/emsdk/emsdk_env.sh"
-        cmake --preset wasm
-        cmake --build --preset wasm --parallel "$(nproc)"
+        for preset in wasm wasm-threads; do
+          cmake --preset "$preset"
+          cmake --build --preset "$preset" --parallel "$(nproc)"
+        done
     # Fail closed: a partial cache entry or a build that wrote nothing must not reach a pack.
     - name: Check the web engine exists
       shell: bash
       working-directory: packages/runtime-native
       run: |
         set -euo pipefail
-        for file in build/web/tn-native-engine-web.mjs build/web/tn-native-engine-web.wasm; do
-          test -s "$file" || { echo "TN_WEB_ENGINE_MISSING: $file was not built" >&2; exit 1; }
-        done
-        wasm_bytes=$(stat -c %s build/web/tn-native-engine-web.wasm)
         allowed_bytes=4194304
-        if [ "$wasm_bytes" -gt "$allowed_bytes" ]; then
-          echo "TN_WEB_ENGINE_OVER_BUDGET: measured $wasm_bytes bytes, allowed $allowed_bytes bytes" >&2
-          exit 1
-        fi
-        echo "web engine ready: $wasm_bytes byte wasm (allowed $allowed_bytes bytes)"
+        # The single-thread engine and the threaded one (PRD-752 phase 4), each under the budget.
+        for name in tn-native-engine-web tn-native-engine-web-threads; do
+          for file in "build/web/$name.mjs" "build/web/$name.wasm"; do
+            test -s "$file" || { echo "TN_WEB_ENGINE_MISSING: $file was not built" >&2; exit 1; }
+          done
+          wasm_bytes=$(stat -c %s "build/web/$name.wasm")
+          if [ "$wasm_bytes" -gt "$allowed_bytes" ]; then
+            echo "TN_WEB_ENGINE_OVER_BUDGET: $name.wasm measured $wasm_bytes bytes, allowed $allowed_bytes bytes" >&2
+            exit 1
+          fi
+          echo "web engine ready: $name.wasm $wasm_bytes bytes (allowed $allowed_bytes bytes)"
+        done

.github/workflows/ci.yml

@@ -608,7 +608,11 @@ jobs:
           # The old 90 s cap sat under the floor and killed a healthy run at exactly 90 s (exit
           # 124). Only this outer watchdog moves: every runtime, assertion, sample and duration
           # budget inside the collector is unchanged, so a hang still dies, just not a slow run.
-          timeout 180s node packages/runtime-native/scripts/profile-production.mjs \
+          # 300 s, not 180 (PR #574): hosted runs took 103 s and 138 s, then two runs of one
+          # unchanged tree were killed at exactly 180 s while their build steps ran no slower; four
+          # local replays on 4 cores took 68-83 s with no stall. The collector now prints a
+          # TN_PROD_PHASE line per phase into collector.log, so a killed run names its phase.
+          timeout 300s node packages/runtime-native/scripts/profile-production.mjs \
             --profile production --target desktop --duration 1 --cold-starts 1 --repetitions 1 --warmup 1 \
             --hosted-software \
             --prebuilt-artifact "$GITHUB_WORKSPACE/packages/runtime-native/build/tn-linux/mystral" \
@@ -925,6 +929,8 @@ jobs:
           # in, or this lane would quietly stop covering 21 scenarios it has always covered.
           extras="$GITHUB_WORKSPACE/packages/create-threenative/template-playtests/${{ matrix.template }}"
           if [ -d "$extras" ]; then cp -r "$extras/." "$target/playtests/"; fi
+          # PRD-748: the engine-cost contract row runs on every PR, for every kit that does not opt out.
+          pnpm exec tsx scripts/kit-contract-row.ts engine-cost "${{ matrix.template }}" "$target/playtests"
           scenario_list=$(node "$GITHUB_WORKSPACE/scripts/non-visual-scenarios.mjs" "$target")
           mapfile -t scenarios <<< "$scenario_list"
           test "${#scenarios[@]}" -gt 0
@@ -1033,7 +1039,7 @@ jobs:
       - uses: ./.github/actions/playwright-chromium
       # `test:browser` is the test-browser job's gate; running it again here bought nothing but
       # a second copy of the slowest step in the workflow.
-      - run: pnpm exec playwright test --config=benchmark.playwright.config.ts
+      - run: sh scripts/xvfb.sh pnpm exec playwright test --config=benchmark.playwright.config.ts
 
   # visuals is NOT a job here any more. It captures frames from a WebGPU canvas, and this runner
   # has no GPU — its first execution in the repository's history failed on
@@ -1376,7 +1382,12 @@ jobs:
     # git history — gitleaks' default git mode — which is strictly stronger than the incremental
     # PR range and immune to force-push SHAs the checkout may not have.
     runs-on: ubuntu-latest
-    timeout-minutes: 10
+    # The full-history scan pays a 3.9 GB clone: on a hosted runner it has taken 5m59s
+    # (merge-group run 40715886891, success) and over 10 minutes (run 40754093470, killed by
+    # this budget with actions/checkout still fetching, which then failed the merge queue's
+    # fail-closed receipt verifier). Two runs, same tree cost, opposite verdicts: the budget
+    # was under the work, so it gets headroom rather than the scan losing its full history.
+    timeout-minutes: 20
     permissions:
       contents: read
     env:
@@ -1386,6 +1397,10 @@ jobs:
         with:
           ref: ${{ needs.scope.outputs.candidate_sha || github.sha }}
           fetch-depth: 0
+          # A PR scans only its own commits, so it fetches commits and trees and then just the blobs
+          # its range reads (below): every blob of the 3.9 GB history outlasted this job's 10 minutes
+          # (PR #574, run 40745026751). Pushes and merge groups scan the full history and keep them.
+          filter: ${{ github.event_name == 'pull_request' && 'blob:none' || '' }}
       - name: Verify the PR commit range is present
         if: github.event_name == 'pull_request'
         env:
@@ -1395,6 +1410,20 @@ jobs:
           set -euo pipefail
           range="$BASE_SHA..$HEAD_SHA"
           test "$(git rev-list --count "$range")" -gt 0
+          # The checkout fetched no blobs. Fetch every blob the range's commits read in one request,
+          # and fail when one is still missing: gitleaks exits 0 after scanning 0 commits when it
+          # cannot read one.
+          blobs="$RUNNER_TEMP/gitleaks-range-blobs"
+          git rev-list --no-merges "$range" | git diff-tree --stdin -r --no-commit-id --raw \
+            | awk '$1 != ":160000" && $2 != "160000" { print $3; print $4 }' | grep -v '^0*$' | sort -u > "$blobs"
+          if [ -s "$blobs" ]; then
+            git -c fetch.negotiationAlgorithm=noop fetch --quiet --no-tags --no-write-fetch-head \
+              --recurse-submodules=no --filter=blob:none --stdin origin < "$blobs"
+          fi
+          if GIT_NO_LAZY_FETCH=1 git cat-file --batch-check < "$blobs" | grep ' missing$'; then
+            echo "::error::the PR range's blobs are missing, so gitleaks would scan nothing"
+            exit 1
+          fi
           echo "TN_GITLEAKS_RANGE=$range" >> "$GITHUB_ENV"
       - name: Scan PR commits for leaked secrets
         if: github.event_name == 'pull_request'
@@ -1475,6 +1504,9 @@ jobs:
       - uses: actions/checkout@v7
         with:
           fetch-depth: 0
+          # As in scope: this job reads commits and a few workflow files (`git show`, fetched on
+          # demand), so it fetches no history blobs and fits its 5 minutes on a loaded runner.
+          filter: blob:none
           ref: ${{ needs.scope.outputs.candidate_sha || github.sha }}
       - name: Reject every unsuccessful or missing selected job
         env:

.github/workflows/integration.yml

@@ -79,6 +79,10 @@ jobs:
         with:
           persist-credentials: false
           fetch-depth: 0
+          # Integration scope reads commits, a name-only diff and two workflow files (`git show`,
+          # fetched on demand from the public repository), so it fetches no history blobs: every
+          # blob of the 3.9 GB history outlasted 5- and 10-minute jobs on PR #574.
+          filter: blob:none
           ref: ${{ inputs.candidate_sha }}
       - id: filter
         env:
@@ -1090,6 +1094,8 @@ jobs:
           persist-credentials: false
           ref: ${{ inputs.candidate_sha }}
           fetch-depth: 0
+          # The receipt collector reads artifacts and the Actions API, never git history blobs.
+          filter: blob:none
       - uses: actions/download-artifact@v7
         if: needs.paths.outputs.required_jobs != '[]'
         with: