mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-14 18:01:20 +08:00
Vance Ingalls
10d2725b54
## Summary First slice of `P0-1` from the player perf proposal: lays the foundation for a player perf gate so later PRs can plug in fps / scrub / drift / parity scenarios without rebuilding infrastructure. Ships one smoke scenario (`03-load`, cold + warm composition load) to prove the gate end-to-end on real numbers. ## Why There was no automated way to catch player perf regressions. Every perf concern in the existing proposal — composition load time, sustained FPS, scrub p95, mirror-clock drift, live-vs-seek parity — needs the same plumbing: a same-origin harness, a Puppeteer runner, a baseline file, a gate that emits structured results, and a CI workflow that runs the right scenarios on the right changes. Building that up-front in one reviewable PR lets every subsequent perf PR (`P0-1b`, `P0-1c`, and beyond) be a 100-line scenario file plus a baseline entry instead of re-litigating the framework. ## What changed ### Harness — `packages/player/tests/perf/server.ts` - `Bun.serve` on a free port, single same-origin host for the player IIFE bundle, hyperframe runtime, GSAP from `node_modules`, and fixture HTML. - Same-origin matters: cross-origin would force every probe through `postMessage`, hiding bugs and inflating numbers in ways production never sees. Tests should measure the path the studio editor actually takes. - Routes: - `/player.js` → built IIFE bundle (rebuilt on demand). - `/vendor/runtime.js`, `/vendor/gsap.min.js` → resolved from `node_modules` so fixtures don't need to ship copies. - `/fixtures/*` → fixture HTML. ### Runner — `packages/player/tests/perf/runner.ts` - `puppeteer-core` thin wrappers (`launchBrowser`, `loadHostPage`). - Uses the system Chrome detected by `setup-chrome` in CI rather than the bundled puppeteer revision — keeps the action smaller, lets us pin Chrome version policy at the workflow level, and matches what users actually run. ### Gate — `packages/player/tests/perf/perf-gate.ts` + `baseline.json` - Loads `baseline.json` (initial budgets: cold/warm comp load, fps, scrub p95 isolated/inline, drift max/p95) with a 10% `allowedRegressionRatio`. - Per-metric direction (`lower-is-better` / `higher-is-better`) so the same evaluator handles latency and throughput. - Returns a structured `GateReport` consumed by both the CLI (table output) and `metrics.json` (CI artifact). - Two modes: `measure` (log only — used during the rollout) and `enforce` (fail the build) — flip per-metric once we trust the signal, without touching the harness. ### CLI orchestrator — `packages/player/tests/perf/index.ts` - Parses `--mode` / `--scenarios` / `--runs` / `--fixture` in both space- and equals-separated form (so `--scenarios fps,scrub` and `--scenarios=fps,scrub` both work — matches what humans type and what GitHub Actions emits). - Runs scenarios, runs the gate, and **always** writes `results/metrics.json` with schema version, git SHA, metrics, and gate rows — so failed runs are still investigable from the artifact alone. ### Fixture + smoke scenario - `fixtures/gsap-heavy/index.html`: 200 stagger-animated tiles, no media. Heavy enough to make load time meaningful, light enough to be deterministic. - `scenarios/03-load.ts`: cold + warm composition load. Measures from navigation start to player `ready` event, reports p95 across runs. ### CI — `.github/workflows/player-perf.yml` - `paths-filter` on `player` / `core` / `runtime` — perf only runs when something that could move the needle actually changed. - Sets up bun + node + chrome, runs perf in `measure` mode on a shard matrix (so future scenarios shard naturally), uploads `metrics.json` artifacts, and a summary job aggregates shard results into a single PR comment. ### Wiring - `packages/player`: `puppeteer-core`, `gsap`, `@types/bun` devDeps; typecheck extended to cover the perf `tsconfig`; new `perf` script. - Root `package.json`: `player:perf` workspace script so `bun run player:perf` runs the whole suite locally with the same flags CI uses. - `.gitignore`: `packages/player/tests/perf/results/`. - Separate `tests/perf/tsconfig.json` so test code doesn't pollute the package `rootDir` while still being typechecked. ## Test plan - [x] Local: `bun run player:perf` passes — cold p95 ≈ 386 ms, warm p95 ≈ 375 ms, both well under the seeded baselines. - [x] Typecheck, lint, format pass on the perf workspace. - [x] Existing player unit tests (71/71) still green. - [ ] First CI run after merge will be the real signal: confirms `setup-chrome` works on hosted runners, the shard matrix wires up, and `metrics.json` artifacts upload. ## Stack Step `P0-1a` of the player perf proposal. The next two slices are content-only — they don't touch the harness: - `P0-1b` (#400): adds `02-fps`, `04-scrub`, `05-drift` scenarios on a 10-video-grid fixture. - `P0-1c` (#401): adds `06-parity` (live playback vs. synchronously-seeked reference, compared via SSIM). Wiring this gate up first means each follow-up is a self-contained scenario file + baseline row + workflow shard.
96 lines
1.7 KiB
Plaintext
96 lines
1.7 KiB
Plaintext
# Dependencies
|
|
node_modules/
|
|
|
|
# Build output
|
|
dist/
|
|
*.tsbuildinfo
|
|
|
|
# Environment
|
|
.env
|
|
.env.local
|
|
.env.*.local
|
|
|
|
# OS
|
|
.DS_Store
|
|
Thumbs.db
|
|
|
|
# Docs media — served from CDN, not committed.
|
|
# Regenerate with scripts/generate-{catalog,template}-previews.ts then upload
|
|
# with `bun run upload:docs-images`. Add explicit negations below for any
|
|
# non-generated assets (logos, svgs) that should stay in the repo.
|
|
docs/images/
|
|
|
|
# IDE
|
|
.vscode/
|
|
.idea/
|
|
*.swp
|
|
*.swo
|
|
|
|
# Test
|
|
coverage/
|
|
.debug/
|
|
|
|
# Producer regression test failures (generated debugging artifacts)
|
|
packages/producer/tests/*/failures/
|
|
|
|
# Player perf test results (generated each run, attached as CI artifact)
|
|
packages/player/tests/perf/results/
|
|
|
|
# Rendered output (not test fixtures — those use git LFS)
|
|
output/
|
|
renders/
|
|
!packages/producer/tests/*/output/
|
|
|
|
# Composition source media (large binaries)
|
|
compositions/**/*.mp4
|
|
compositions/**/*.mov
|
|
compositions/**/*.MOV
|
|
|
|
# npm pack artifacts
|
|
*.tgz
|
|
|
|
# Logs
|
|
*.log
|
|
npm-debug.log*
|
|
|
|
# Temporary
|
|
tmp/
|
|
.tmp/
|
|
|
|
# Generated files
|
|
packages/producer/src/services/fontData.generated.ts
|
|
|
|
# Test artifacts
|
|
my-video/
|
|
examples/
|
|
packages/studio/data/
|
|
.desloppify/
|
|
.worktrees/
|
|
|
|
# Playwright MCP browser cache
|
|
.playwright-mcp/
|
|
|
|
# Installed skills (user-specific)
|
|
.agents/
|
|
.claude/skills/
|
|
skills-lock.json
|
|
|
|
# Skills from other PRs (not managed here)
|
|
skills/hyperframes-animation-map/
|
|
skills/hyperframes-contrast/
|
|
|
|
# Capture outputs
|
|
captures/
|
|
# Legacy test captures at repo root (use captures/ instead)
|
|
*-capture/
|
|
*-demo/
|
|
*-ad/
|
|
*-tour/
|
|
*-brand/
|
|
|
|
# Local regression-test and video project scratch directories.
|
|
# These hold per-site captures, compositions, narration audio, rendered MP4s.
|
|
cursor-tests/
|
|
basecamp-video/
|
|
launch-video*/
|