Skip to content

Commit 5632356

Browse files
docs: show agents where Studio edits go and how tests build, and let docs skip captures (#4936)
* fix(ci): let markdown-only changes under studio and player skip the captures check * docs: map the Studio edit path, the edit accuracy bench and test setup for agents * docs: name the Studio captures rule and the local comment checks * docs: point the Studio gate notes at the scripts that own the rules * docs: correct the Studio save paths and add the producer stage map * docs: name where producer sizes workers and which captures encode inline
1 parent 70dde41 commit 5632356

6 files changed

Lines changed: 121 additions & 7 deletions

File tree

‎AGENTS.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,22 @@ bun run build # Build all packages
3838
bun run test # Run all tests
3939
```
4040

41+
Packages load each other through their `exports`. Under Node, core, parsers,
42+
lint and studio-server resolve to `dist/`, and player always loads its built
43+
bundle. Run `bun run build` once in a fresh worktree, before any package's
44+
tests or typecheck. After editing a package that another package imports, run
45+
that package's `build` again before the dependent package's tests. Core's
46+
`src/generated/` is git-ignored build output: if you see
47+
`Cannot find module '../generated/runtime-inline'`, run
48+
`bun run build:hyperframes-runtime`.
49+
50+
One file: `bun run --cwd packages/<pkg> test <path>`. Each package's `test`
51+
script picks its runner (vitest in most, `bun test` in aws-lambda and
52+
gcp-cloud-run). Producer is the exception: a file that imports `bun:test` runs
53+
with `bun test <file>`, any other with `bunx vitest run <file>`. Root `scripts/*.test.mjs` run through `bun run test:scripts`,
54+
which is an explicit list in `package.json`. CI's test-reachability check fails
55+
any test file that no runner reaches.
56+
4157
### Linting & Formatting
4258

4359
Uses **oxlint** and **oxfmt** (not eslint, not prettier, not biome).

‎CONTRIBUTING.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,8 @@ Reviewers judge rules 2 to 5 and 8. The `Comments` check (`scripts/check-comment
9797

9898
Only comment blocks holding a line your PR added can fail the citation and block rules, and the TODO and URL rules grade only the lines your PR added. Broken citations elsewhere in a file you touched are printed as warnings, and fixing one while you are there is welcome. To grade files by hand, pass their paths: `node scripts/check-comment-citations.mjs path/to/file.ts`.
9999

100+
Run both checks before pushing: `node scripts/check-comment-citations.mjs` and `node scripts/comment-ratchet.mjs` grade your branch against its merge-base with `origin/main` (set `COMMENT_CHECK_BASE` to compare with another base). The pre-commit hooks run neither.
101+
100102
## Adding Registry Items (Blocks & Components)
101103

102104
The registry at `registry/` contains reusable items installable via `hyperframes add <name>`. Each item lives in its own directory under `registry/blocks/` or `registry/components/`.
@@ -198,14 +200,12 @@ All packages use **fixed versioning** — every release bumps all packages to th
198200
### Stable releases
199201

200202
```bash
201-
bun run release:prepare 0.2.0 # drafts changelog if needed, then creates the release commit/tag after review
202-
git push origin main # push the release commit
203-
git push origin v0.2.0 # push the tag → triggers the publish workflow
203+
git switch -c release/v0.2.0 origin/main
204+
bun run release:prepare 0.2.0 # drafts release notes and stops for review; rerun after editing them
205+
git push origin release/v0.2.0 # push the branch, not the local tag
204206
```
205207

206-
> Push the **specific tag**, not `git push --tags` — the latter pushes every local tag and the whole push is rejected if any one already exists on the remote.
207-
208-
The `release:prepare` script drafts missing release notes on the first run and stops for manual review. After the generated TODO summary is rewritten, rerun the same command; it delegates to `set-version`, which creates a `chore: release v<version>` commit and a `v<version>` git tag. Pushing the tag triggers CI to publish all packages to npm and create a GitHub Release.
208+
Open a PR from `release/v0.2.0` to `main`. When it merges, the publish workflow tags the merge commit, publishes every package to npm and creates the GitHub Release. Pushing a stable tag by hand publishes nothing: the workflow only accepts pre-release tags. The full procedure, including recovery from a failed publish, is in [docs/contributing/changelog-process.mdx](docs/contributing/changelog-process.mdx).
209209

210210
`set-version` also refuses to tag if a **higher** semver tag already exists (a stale higher tag would hijack tag-sorting installers like `npx skills`). Delete the stray tag (`git tag -d <tag> && git push origin :refs/tags/<tag>`) or, only if intentional, pass `--skip-monotonicity-check`.
211211

‎packages/producer/README.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -184,6 +184,26 @@ The activity functions plus their result types are also re-exported from `@hyper
184184
4. **Mix** — extracts `<audio>` elements and mixes them into the final video. For `png-sequence`, audio is written as an `audio.aac` sidecar.
185185
5. **Finalize** — applies faststart for streaming-friendly MP4 (no-op for WebM, MOV, and `png-sequence`). For `hls`, stream-copies the encode into playlists and MPEG-TS segments instead.
186186

187+
### Where each step lives
188+
189+
`executeRenderJob` in `src/services/renderOrchestrator.ts` runs the stages in
190+
`src/services/render/stages/`, in this order:
191+
192+
- `compileStage.ts`, `probeStage.ts`, `extractVideosStage.ts`, `audioStage.ts`
193+
- `src/services/render/captureCost.ts` sizes the worker count
194+
(`runCaptureCalibration`, then `resolveRenderWorkerCount`)
195+
- `createCapturePlan` in `src/services/render/capturePlan.ts` picks the capture
196+
kind: streaming, disk, segmented or HDR layered
197+
- capture: `captureStreamingStage.ts`, `captureSegmentedStage.ts` and
198+
`captureHdrStage.ts` encode as they capture; disk capture (`captureStage.ts`)
199+
encodes afterwards in `encodeStage.ts`
200+
- `assembleStage.ts`, except for PNG sequences and GIF, which are written
201+
directly
202+
203+
The job's `producerConfig` is used when present; otherwise `resolveConfig` in
204+
`packages/engine/src/config.ts` builds it. Capture, encoding and browser
205+
primitives are engine services (see `packages/engine/README.md`).
206+
187207
## Documentation
188208

189209
Full documentation: [hyperframes.heygen.com/packages/producer](https://hyperframes.heygen.com/packages/producer)

‎packages/studio/AGENTS.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,50 @@ Two consequences you will meet immediately:
2121
chrome disagrees with the pixels underneath it, the bug is almost always in
2222
the measurement, in `components/editor/domEditOverlayGeometry.ts`.
2323

24+
## Where a canvas edit goes
25+
26+
Paths are under `src/`; bare file names are in `src/components/editor/`. Each
27+
line names the owner; read it there.
28+
29+
1. **Gesture.** `DomEditSelectionChrome.tsx` starts it, `domEditOverlayStartGesture.ts`
30+
arms it, `useDomEditOverlayGestures.ts` (`onPointerUp`) hands it off. Nudge,
31+
crop and inline text enter through `useDomEditNudge.ts`, `DomEditCropHandles.tsx`
32+
and `useInlineTextEditing.tsx`. `hooks/useDomEditSession.ts` wires the handlers.
33+
2. **GSAP or plain.** The predicates `gsapWritesPosition`, `gsapWritesRotation`
34+
and `gsapWritesBox` live in `hooks/gsapRuntimeKeyframes.ts`. The router is
35+
`hooks/useGsapAwareEditing.ts`. Move and a plain rotation keep the route
36+
chosen at press. A GSAP rotation checks ownership again at commit, and resize
37+
decides at commit through `hooks/gsapResizeIntercept.ts`.
38+
3. **Writers.** Plain edits go through `hooks/elementOffsetStager.ts`,
39+
`hooks/useDomGeometryCommits.ts` and `hooks/plainRotation.ts`, then
40+
`hooks/useDomEditPositionPatchCommit.ts`. GSAP edits: `hooks/gsapRuntimeBridge.ts`
41+
(the drag and rotate intercepts), `hooks/gsapDragCommit.ts`,
42+
`hooks/gsapDragPositionCommit.ts` (keyframe at the playhead) and
43+
`hooks/gsapWholePropertyOffsetCommit.ts`. Styles, text, attributes and groups:
44+
`hooks/domStyleCommit.ts`, `hooks/useDomEditTextCommits.ts`,
45+
`hooks/useDomEditAttributeCommits.ts`, `hooks/useGroupCommits.ts`.
46+
4. **Save.** There are three paths. A single DOM edit goes through
47+
`hooks/useDomEditPersist.ts`. It first offers the edit to the SDK path
48+
(`utils/sdkCutover.ts`, wired in `useDomEditSession.ts`), which writes the
49+
file itself. Otherwise it posts studio-server's `file-mutations/patch-element`.
50+
Atomic DOM batches go through `hooks/useDomEditCommits.ts` to
51+
`patch-element-batches`. Script edits go through `hooks/useGsapScriptCommits.ts`,
52+
to `gsap-mutations` or to the SDK path. The routes are in
53+
`packages/studio-server/src/routes/files.ts`. The own-write token is in
54+
`utils/studioFileVersion.ts`, and `hooks/useExternalFileChangeCoordinator.ts`
55+
drops the echo.
56+
5. **Reload.** Each save path decides its own reload. After a `patch-element`
57+
save, `useDomEditPersist.ts` reloads unless `skipRefresh` is set. For script
58+
edits, `useGsapScriptCommits.ts` (`applyPreviewSync`) picks one of three: an
59+
instant patch, `utils/gsapSoftReload.ts`, or a reload.
60+
A reload bumps `refreshKey`, and `refreshPlayer` in
61+
`player/hooks/useTimelinePlayer.ts` either swaps the scene or runs
62+
`player/hooks/useShadowPreviewReload.ts`, which waits while a gesture or a
63+
save is in flight.
64+
6. **Undo.** `hooks/usePersistentEditHistory.ts` records the edit.
65+
`hooks/useEditHistoryActions.ts` steps through history.
66+
`utils/gsapUndoRestore.ts` repaints the preview.
67+
2468
## Driving Studio for verification
2569

2670
A pixel-precise click inside the preview is not something an automated driver
@@ -74,6 +118,26 @@ properties (`rotate`, `scale`, `translate`) into computed style, and it has no
74118
depends on real layout or real computed style, prove it in a browser and keep
75119
the unit test on the pure function underneath.
76120

121+
## The edit accuracy bench
122+
123+
`tests/e2e/edit-accuracy/` performs real gestures in the built CLI's Studio and
124+
checks the saved file, the reloaded preview, undo and a producer frame. It
125+
needs the built CLI (`packages/cli/dist/cli.js`, from `bun run build`) and
126+
`chrome-headless-shell` (`npx hyperframes browser ensure`):
127+
128+
```bash
129+
bun run --cwd packages/studio test:edit-accuracy -- --grid pr --filter '^resize-' --jobs 1
130+
```
131+
132+
- Case ids come from `grid.mjs`; `--filter` is a regex on them. `--grid pr` is
133+
the smaller slice, `full` is what CI runs.
134+
- Each run writes its results, a table and a candidate baseline to
135+
`tests/e2e/evidence/edit-accuracy/<run>/` (git-ignored; `--out` moves it); a
136+
failing case also gets its screens and saved files under `cases/<id>/`.
137+
- CI runs the full grid in shards and `ratchet.mjs` gates the result against the
138+
base branch's `baseline.json`; its header states the rules. When cases newly
139+
pass, commit the `baseline.json` from the `edit-accuracy-gate` artifact.
140+
77141
## Gates that will fail your PR
78142

79143
- **600 lines per file.** CI checks only non-test files your PR changed. A file
@@ -82,6 +146,10 @@ the unit test on the pure function underneath.
82146
function, duplication, unused exports. Adding branches to an already-complex
83147
function trips it; extract rather than nest.
84148
- **oxlint and oxfmt**, not eslint or prettier.
149+
- **Before and After captures.** A PR that changes code under `packages/studio`
150+
or `packages/player` needs `## Before` and `## After` sections in its
151+
description, each with an image or video. The exemptions (a small change with
152+
no visible effect, Markdown) are defined in `scripts/check-pr-captures.mjs`.
85153

86154
## Traps worth knowing
87155

‎scripts/check-pr-captures.mjs‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
#!/usr/bin/env node
22
// Fail a PR touching packages/studio or packages/player unless its body has Before and After sections with media.
3+
// Markdown under them is docs, not behaviour, so it is not watched.
34
// usage: node scripts/check-pr-captures.mjs --base origin/main --head <sha>; the body arrives in the env (see main).
45

56
import { execFileSync } from "node:child_process";
@@ -131,8 +132,9 @@ function parseRecord(record) {
131132
return { path: rest.join("\t"), lines };
132133
}
133134

135+
const DOC_FILE = /\.mdx?$/i;
134136
const isWatched = (path) =>
135-
path !== "" && WATCHED_PREFIXES.some((prefix) => path.startsWith(prefix));
137+
path !== "" && WATCHED_PREFIXES.some((prefix) => path.startsWith(prefix)) && !DOC_FILE.test(path);
136138

137139
/** Parse `git diff --numstat -z --no-renames`, keeping watched paths. A binary file counts as a full budget. */
138140
export const parseNumstat = (numstat) =>

‎scripts/check-pr-captures.test.mjs‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,14 @@ test("numstat keeps only watched paths and counts added plus deleted", () => {
108108
]);
109109
});
110110

111+
test("markdown under a watched package needs no capture", () => {
112+
const files = parseNumstat(
113+
"60\t4\tpackages/studio/AGENTS.md\0" + "8\t0\tpackages/player/README.md\0",
114+
);
115+
assert.deepEqual(files, []);
116+
assert.equal(evaluate({ body: "", files }).ok, true);
117+
});
118+
111119
test("a binary file spends the whole no-visible-change budget", () => {
112120
const [file] = parseNumstat("-\t-\tpackages/studio/public/logo.png\0");
113121
assert.equal(file.lines, 20);

0 commit comments

Comments
 (0)