mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-03 04:38:33 +00:00
Miguel Ángel
04bd56a7ae
## Problem
Studio frame capture could fail for projects mounted outside the repo when the project id came from an encoded hash route. A project like `Notion Showcase` loaded as `#project/Notion%20Showcase`, but the capture URL encoded that already-encoded value again, producing `/api/projects/Notion%2520Showcase/...` and a 404.
While validating the fix by seeking through the preview, capture also diverged from the visible player for nested compositions because the thumbnail route sought raw timelines instead of the same player seek path used by Studio preview.
## What this fixes
- Decodes project ids when reading Studio `#project/...` routes and centralizes project hash/API path construction.
- Keeps API URLs encoded exactly once, including project names with spaces, literal `%`, reserved characters, and unicode.
- Updates Studio thumbnail capture to prefer `window.__player.seek(t)` and only fall back to raw timeline seeking for standalone pages.
- Preserves explicit `t=0` thumbnail requests instead of falling back to `0.5` seconds.
- Adds preview-regression CI coverage for Studio routing, frame capture URL construction, thumbnail seeking, and core thumbnail seek parsing.
## Root cause
Studio treated the hash route segment as the canonical project id even when the browser had already percent-encoded it. `buildFrameCaptureUrl` then encoded that string again, so a decoded project directory name and the capture API path no longer matched.
The preview/capture mismatch was a separate seek-path issue: the visible Studio preview seeks through the HyperFrames player, which maps global time into nested composition time. The capture route bypassed that layer and paused all registered timelines at the same global time.
The zero-second capture case came from parsing `t` with a truthiness fallback, so `parseFloat("0") || 0.5` became `0.5`.
## Verification
### Local checks
- `bun run --cwd packages/studio test -- vite.thumbnail.test.ts src/utils/projectRouting.test.ts src/utils/frameCapture.test.ts`
- `bun run --cwd packages/core test -- src/studio-api/routes/thumbnail.test.ts`
- `bunx oxfmt --check .github/workflows/preview-regression.yml packages/studio/vite.thumbnail.ts packages/studio/vite.thumbnail.test.ts packages/studio/vite.config.ts packages/studio/src/utils/projectRouting.ts packages/studio/src/utils/projectRouting.test.ts packages/studio/src/utils/frameCapture.ts packages/studio/src/App.tsx packages/core/src/studio-api/routes/thumbnail.ts packages/core/src/studio-api/routes/thumbnail.test.ts`
- `bunx oxlint .github/workflows/preview-regression.yml packages/studio/vite.thumbnail.ts packages/studio/vite.thumbnail.test.ts packages/studio/vite.config.ts packages/studio/src/utils/projectRouting.ts packages/studio/src/utils/projectRouting.test.ts packages/studio/src/utils/frameCapture.ts packages/studio/src/App.tsx packages/core/src/studio-api/routes/thumbnail.ts packages/core/src/studio-api/routes/thumbnail.test.ts`
- `bun run --cwd packages/studio typecheck`
- `bun run --cwd packages/core build:hyperframes-runtime`
- `bun run --cwd packages/core typecheck`
- `git diff --check`
Pre-commit also reran lint, format, and typecheck successfully for the committed files.
### Browser verification
Using `agent-browser`, I mounted `/Users/miguel07code/Downloads/Notion Showcase` into Studio's project data and opened:
```text
http://127.0.0.1:5197/#project/Notion%20Showcase
```
Before the fix, Capture requested `/api/projects/Notion%2520Showcase/thumbnail/index.html?...` and Studio showed `Capture failed`.
After the fix, I sought the preview to `0s`, `2s`, `10s`, and `18s`, captured each frame, and compared the visible preview crop against the capture output. The capture URLs all used `Notion%20Showcase`, not `Notion%2520Showcase`, and no failure toast appeared.
Mean pixel diffs for preview vs capture were:
- `0s`: `0.0`
- `2s`: `0.8641`
- `10s`: `0.3496`
- `18s`: `0.2309`
The small non-zero diffs are raster/antialias-level differences after resizing the capture to the preview crop dimensions.
## Notes
- Browser screenshots, comparison sheets, network logs, and the `agent-browser` recording are local-only under `qa-artifacts/capture-button/` and are not committed.
- The local Notion Showcase project mount is an ignored symlink under `packages/studio/data/projects/` and is not committed.
- Thumbnail cache versions were bumped so stale captures generated with the old seek behavior are not reused.
138 lines
4.5 KiB
YAML
138 lines
4.5 KiB
YAML
name: preview-regression
|
|
|
|
on:
|
|
pull_request:
|
|
push:
|
|
branches:
|
|
- main
|
|
|
|
concurrency:
|
|
group: preview-regression-${{ github.ref }}
|
|
cancel-in-progress: true
|
|
|
|
jobs:
|
|
changes:
|
|
name: Detect changes
|
|
runs-on: ubuntu-latest
|
|
timeout-minutes: 2
|
|
outputs:
|
|
preview: ${{ steps.filter.outputs.preview }}
|
|
steps:
|
|
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
|
|
with:
|
|
fetch-depth: 0
|
|
- uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4
|
|
id: filter
|
|
with:
|
|
token: ""
|
|
filters: |
|
|
preview:
|
|
- "packages/core/**"
|
|
- "packages/player/**"
|
|
- "packages/studio/**"
|
|
- "packages/cli/**"
|
|
- "packages/producer/src/parity-harness.ts"
|
|
- "packages/producer/src/parity-fixtures.ts"
|
|
- "packages/producer/tests/parity/**"
|
|
- "package.json"
|
|
- "bun.lock"
|
|
- ".github/workflows/preview-regression.yml"
|
|
|
|
preview-parity:
|
|
name: Preview parity
|
|
needs: changes
|
|
if: needs.changes.outputs.preview == 'true'
|
|
runs-on: ubuntu-latest
|
|
timeout-minutes: 20
|
|
steps:
|
|
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
|
|
|
|
- uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
|
|
|
|
- uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
|
|
with:
|
|
node-version: 22
|
|
|
|
- run: bun install --frozen-lockfile
|
|
|
|
- name: Run Studio preview routing regression
|
|
run: |
|
|
bun run --cwd packages/studio test -- vite.thumbnail.test.ts src/utils/projectRouting.test.ts src/utils/frameCapture.test.ts
|
|
bun run --cwd packages/core test -- src/studio-api/routes/thumbnail.test.ts
|
|
|
|
- name: Build preview runtime
|
|
run: bun run --cwd packages/core build:hyperframes-runtime
|
|
|
|
- name: Prepare parity fixtures
|
|
run: bun run --cwd packages/producer parity:fixtures:ci
|
|
|
|
- name: Install ffmpeg
|
|
uses: FedericoCarboni/setup-ffmpeg@36c6454b5a2348e7794ba2d82a21506605921e3d # v3
|
|
|
|
- name: Set up Chrome
|
|
id: setup-chrome
|
|
uses: browser-actions/setup-chrome@c785b87e244131f27c9f19c1a33e2ead956ab7ce # v1
|
|
with:
|
|
chrome-version: stable
|
|
|
|
- name: Start parity fixture server
|
|
run: |
|
|
cd packages/producer/tests/parity/fixtures
|
|
python3 -m http.server 4173 --bind 127.0.0.1 > /tmp/preview-parity-http.log 2>&1 &
|
|
echo "$!" > /tmp/preview-parity-http.pid
|
|
for _ in $(seq 1 30); do
|
|
if curl -fsS http://127.0.0.1:4173/minimal-wysiwyg.html >/dev/null; then
|
|
exit 0
|
|
fi
|
|
sleep 1
|
|
done
|
|
cat /tmp/preview-parity-http.log
|
|
exit 1
|
|
|
|
- name: Run preview parity check
|
|
working-directory: packages/producer
|
|
env:
|
|
PUPPETEER_EXECUTABLE_PATH: ${{ steps.setup-chrome.outputs.chrome-path }}
|
|
run: bun run parity:check:ci
|
|
|
|
- name: Upload parity artifacts
|
|
if: failure()
|
|
uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
|
|
with:
|
|
name: preview-parity-artifacts
|
|
path: packages/producer/.debug/parity-harness-ci/
|
|
if-no-files-found: ignore
|
|
retention-days: 30
|
|
|
|
preview-regression:
|
|
runs-on: ubuntu-latest
|
|
needs: [changes, preview-parity]
|
|
if: always()
|
|
steps:
|
|
- name: Check results
|
|
env:
|
|
PREVIEW_FILTER_RESULT: ${{ needs.changes.outputs.preview }}
|
|
PREVIEW_PARITY_RESULT: ${{ needs.preview-parity.result }}
|
|
run: |
|
|
{
|
|
echo "## Preview regression gate"
|
|
echo ""
|
|
echo "- paths-filter \`preview\` matched: \`${PREVIEW_FILTER_RESULT}\`"
|
|
echo "- preview-parity result: \`${PREVIEW_PARITY_RESULT}\`"
|
|
echo ""
|
|
} >> "$GITHUB_STEP_SUMMARY"
|
|
|
|
if [ "${PREVIEW_FILTER_RESULT}" != "true" ]; then
|
|
echo "::notice title=Preview regression::SKIPPED — no preview/runtime changes. Auto-pass."
|
|
echo "**Status:** SKIPPED (no preview/runtime changes — auto-pass)" >> "$GITHUB_STEP_SUMMARY"
|
|
exit 0
|
|
fi
|
|
|
|
if [ "${PREVIEW_PARITY_RESULT}" != "success" ]; then
|
|
echo "**Status:** FAILED" >> "$GITHUB_STEP_SUMMARY"
|
|
echo "Preview parity check failed"
|
|
exit 1
|
|
fi
|
|
|
|
echo "**Status:** PASSED" >> "$GITHUB_STEP_SUMMARY"
|