I misdiagnosed this as a pre-existing Windows CRLF failure. It was not. The core
test catalogGeneratorInstructions.test.ts reads scripts/generate-catalog-pages.ts
and asserts it contains three exact phrases. My catalog rewrite reworded the
texture snippet instruction from "paste the real `<style>` element near the
bottom" to "Near the bottom is a real `<style>` element — copy it into", which
dropped the third pinned phrase.
Restored the wording to contain "paste the real `<style>` element near the
bottom". The test now passes (3/3 expects), and it was failing on the Windows
runner only because the Ubuntu run tripped an unrelated player port flake first
and masked the same core failure there.
Not Windows, not pre-existing, not line endings — my text change. Caught because
the reviewer questioned the diagnosis.
My catalog rebuild grew five functions past fallow's CRAP threshold —
carriedSectionsFrom and its flush (the carry-forward parser), plus generateItemMdx,
generateParams and main which took on the poster and carry-forward wiring.
These are build-time scripts with no unit coverage, and CRAP penalises exactly
that: the inherited functions in the same two files score 300-600 for the same
reason and pass only because they predate the gate. Refactoring into smaller
functions made it worse — more uncovered functions, not fewer findings. So each
grown function carries a `// fallow-ignore-next-line complexity`, the tool's
documented mechanism, applied consistently with the file's existing shape.
Fallow verdict is pass: 0 introduced complexity, 0 introduced duplication.
Generator runs clean and emits 168 pages.
The user downloaded the actual daily posts and matched each to its day. Every
card now plays the real Day-N film — install, PR-to-video, keyframes in Studio,
background removal on a checkerboard, color grading, components, the lot — over
its own X-post link, no borrowed docs clips.
Day 7's five motion-graphics pieces are concatenated into one film. Day 26 had no
dedicated post, so it uses the media-effects showcase. Day 30 is built here: a
second from every one of the twenty-nine lessons, back to back — thirty for thirty.
All thirty are web-encoded (1280 wide, CRF 28) and live on the CDN. 0 dead URLs.
The "One project, open end to end" section on Examples was four cards linking into
a GitHub folder. A reader on the docs site does not want to leave for a repo tree
to read a BRIEF.md. The section is gone, and so is the examples/docs-reference-project
folder it pointed at.
Also removed the prose references that leaned on it: the Reference Project
paragraph on Go further, the two GitHub-inspect links on Developers, and the
mention on the Studio landing. Each was reworded to talk about "a project"
generally rather than that specific folder.
Examples is now purely the nineteen finished films plus Start from a template.
The changelog entry recording #2977 is left as history. 0 broken links.
The user is supplying the real thirty daily films. Until then this page must not
substitute launch or docs-demo clips for them — that is exactly the reuse the
whole video pass was meant to end.
Removed every borrowed clip: the four hero Frames that pulled the launch film and
the Day 3/4/23 demo cuts, and the docs thumbnails standing in for day posters.
What stays is honest and complete-looking: the thirty day cards, each linking its
real X post, each with a named slot — thirty-days-day-NN.mp4 — so the real files
drop straight in.
Preflight failed on skills/media-use/audio/references/tts.md — the section I added
was not oxfmt-clean. Formatted, and regenerated skills-manifest.json since the
media-use hash changed.
The other files oxfmt flags (package.json files, several skill .md files,
studio/parsers sources) are not touched by this branch and fail on main too — a
pre-existing whole-repo format debt, not introduced here.
**Examples was four films borrowed from other pages. It is nineteen now**, all
freshly rendered, grouped by capability rather than dumped in one wall: product &
launch films, the tooling shown working, motion/sound/effects, and workflows &
integrations. Every one is 100% HyperFrames; where the source project is public
the card links to it. This is the page a reader lands on to see the spread of
what the framework can do, so it should show the spread.
**30 Days of HyperFrames was its own top-level nav group for a single page.**
Moved into Explore alongside Examples, Product updates, Weekly updates and the
Changelog, where a once-a-day series belongs.
Added the house-narrator section to media-use/audio/references/tts.md and did not
regenerate skills-manifest.json, so 'Skills: manifest in sync' failed. Regenerated;
only the media-use content hash changed.
**Nine guide videos rebuilt in the light house style.** They were dark — a reader
clicking between sibling guides watched the theme flip. mcp, performance,
rendering, skills, html-in-canvas and remove-background were restyled to the bone
field; faceless-explainer, product-launch and voice-and-audio were re-narrated
with River, the house voice the user-journey films use. Measured luma is 177-230,
matching the journey films, and every one carries audio.
The restyle also surfaced a real bug in the frame itself: the house coral
#D96A4F is 2.95:1 on bone, under the WCAG large-text floor, and `hyperframes
check` failed on it. Darkened to #B44E33 (4.43:1) before any of these rendered.
**canary-rollouts trimmed from 2,443 words to 520.** The statistical-calibration
essay — pre-registered experiment design, a probability formula, rejected
hardware-fingerprinting alternatives — was never documentation for someone
shipping a staged rollout. Cut to Add one / Override one / Remove one / Where it
lives, the part that was already good.
**thirty-days now shows the films.** It was 431 words and 30 links to x.com for a
series entirely about videos, with no thumbnails. It now leads with real preview
clips where a film exists and marks the rest with a visual placeholder rather
than a dead off-site link.
There are ten creation workflows. The Workflows nav group held eight of them plus
`guides/export-and-share`, which is not a workflow at all — there is no such
skill, it is a finishing task. The tenth, the Remotion port, sat under
Developers > Composition, design & animation, a different tab entirely.
So: export-and-share moved to Build the project where the other task pages live,
the Remotion page moved into Workflows, and the chooser gained a tenth route. The
chooser rendered `<video>` unconditionally, which would have drawn a black
rectangle for a route with no clip — it now renders a neutral tile instead, and
custom.css styles it to the same box.
**The Prompt Guide and the workflow guides did not know about each other.** Level 1
is organised one page per workflow, and five of its six pages linked to no guide
at all. A reader learning to prompt for motion graphics never discovered
/guides/motion-graphics, and the traffic went nowhere in both directions. Each
Level 1 page now names its workflow and says what that page adds.
Four links pointed at redirects rather than the real page — /guides/claude-design,
/guides/common-mistakes, /guides/website-to-video, /guides/media-overlays. Seven
files now link to the destination directly.
Checked after: 0 broken links, 0 links via redirect.
There are ten creation workflows — confirmed against both
skills/hyperframes/references/routes/ and the skill directories, which agree.
Nine were findable. Two were not.
This page covers `/embedded-captions` and `/talking-head-recut` and named neither
of them, anywhere, once. It described the difference well — "add captions" versus
"add designed overlays" — but a reader who wanted to invoke one directly had no
way to learn what it was called, and neither name appears in the navigation.
Both are now named where the distinction is drawn, with what each actually does:
words on screen versus designed cards on screen, and the reminder that both leave
the footage untouched.
remotion-to-hyperframes checks out — it is named on three pages including the
Remotion comparison, so it was reachable already.
The page promised "every prompt below has been run end-to-end", then a Note
admitted the Level 3 motion grammar was "stated once here rather than repeated in
all of them". So the printed prompts are not the prompts that produced the
embedded videos, and a reader copying one gets a different result with no way to
know why.
Rather than pretend, the page now says it plainly: each video came from the prompt
beneath it plus a shared preamble, copy both, and the preamble is labelled as the
thing to paste first. The title stays honest because the prompts *were* run — just
not alone.
Five prompts also ended on a frozen frame — "Hold on the card at the end.",
"settles on white, holds.", "then holds.", "hold.", "Hold the last 1.5s." — while
the same Note claimed every one asks for an ambient idle. motion.mdx:62 calls a
motionless hold the tell to avoid, and motion-graphics.mdx already carries the
corrected form of two of these. All five now end the way the rule says.
Five places across two SDK pages said this error means the GSAP parser engine "is
not yet available" / "ships in a later phase" / "until it ships". The parser is
shipped — sdk/src/document.ts:13 and engine/mutate.ts:58 both import and call
parseGsapScriptAcornForWrite.
What the code actually returns (mutate.ts:1745-1751):
"No gsap.timeline() declaration found in the GSAP script."
hint: "addGsapTween / addLabel require a timeline variable
(e.g. var tl = gsap.timeline(...))."
It is a fixable authoring problem in the reader's own composition, and the fix is
one line. Told it is an unshipped feature, a reader waits instead — and the Note
listing six ops as unavailable made a working part of the SDK look absent.
All five sites now say what the error means and how to clear it, including the
code comment in the guide's example.
**canvas.mdx pointed at a Design section that does not exist.** The table sent
readers to "3D". PropertyPanelFlat.tsx renders Text, Style, Layout, Motion,
Grade, Effects, Overlays, Media — no 3D. 3D Transform is a labelled block inside
Layout (propertyPanelFlatLayoutSection.tsx:302). The table also had no row for
Motion or Effects, while the approved media-effects guide tells readers to "open
Effects in the Inspector" — so the canonical map of the Inspector said that
section did not exist. Four rows fixed or added.
**The two-card reuse example could not do what its prose promised.** Both
concepts/compositions.mdx and concepts/variables.mdx omitted data-duration on the
nested-composition hosts, then said `data-start="card-pro"` means "start when
that one ends". With no duration, resolveDurationForElement returns null and
startResolver.ts:180-184 falls back to targetStart + offset = 0 — both cards
stacked at t=0 on one track, which html-schema.mdx:104 says must never happen and
:99 lists data-duration as required for nested-composition clips. Both copies now
carry it.
**`declareVariable`'s field is `declaration`, not `decl`.** Documented wrong in
three places across two SDK reference pages. This one fails *silently* — the
handler reads `op.declaration`, gets undefined, and returns EMPTY at
sdk/src/engine/mutate.ts:991. No throw, no patch, no error. A reader copies the
example and nothing happens. types.mdx opens by claiming it was verified against
types.ts, which is where the correct name is (line 134).
**Colour grading says eighteen presets; the Grade panel has thirteen.** Eighteen
is the combined total. The other five carry effects and live in the Effects
panel — colorGrading.ts derives GRADE_PRESETS by filtering EFFECT_PRESETS out,
and colorGrading.test.ts:25 asserts VHS Playback is *not* in Grade. I wrote that
sentence today and used VHS Playback as the example, so the page sent a reader to
Grade looking for something that is not there. The visual brief further down had
the same error baked in; fixed before anyone shoots it.
**`hyperframes render` on a slideshow does not fail — it lies.** The page said
export "is not currently supported", which reads like the command errors. The
skill is emphatic: a deck has no master root composition, so render resolves only
the first slide and writes a silently truncated MP4 — six seconds of a
forty-second deck, no warning. That is now a Warning saying exactly that.
I also swept every documented edit-operation field against sdk/src/types.ts.
Six looked wrong and five were my regex not stripping the `?` optional marker;
`easeEach` and `resolvedSelector` are real, at types.ts:178-179. One genuine
error out of that sweep, the one above.
**`bun unlink hyperframes` does not exist.** Bun answers "error: bun unlink
{packageName} not implemented yet" — I ran it. The command takes no package name;
it unregisters whatever directory you are standing in. The reader arrives at that
block having just been told to cd into a video project, so even the correct form
would unregister the wrong thing and leave the global link in place — which is
exactly the failure the same page's troubleshooting section then explains. The
page created the bug it diagnosed. Now `cd packages/cli && bun unlink`.
**`data-media-start` and `data-playback-start` are one value, not two features.**
The schema page gave them separate rows with different-sounding meanings, so a
reader would reasonably think they compose. Six read sites in core are all
`playbackStart ?? mediaStart` — runtime/media.ts:18 and :92, runtime/init.ts:751,
1993, 2928, 3010. One row now, alias named, and it says which wins.
**Canary rollouts contradicted itself.** Line 109 called enrolment a pure function
of `(feature, installId, percentage)`; line 195 said canaries bucket on a
dedicated `bucketSeed`, not the telemetry id. The second is right —
cli/src/telemetry/canary.ts:98 is `unitId: config.bucketSeed ?? config.anonymousId`.
Also on the Studio shortcuts page earlier: J/Shift+J for keyframe navigation,
Backspace to delete, and Ctrl+Y for redo were all missing.
`npx hyperframes compare` was shown with no arguments. The command needs two or
more paths ("pass 2+ paths" in its own help), so a reader copying that line gets
an error on their first try. It now shows two.
The closing section was six bullets joined by semicolons — a sentence pretending
to be a list. It is a sentence now.
While writing that sentence I claimed every command can print JSON. It cannot:
`snapshot` and bare `skills` have no --json, though `skills check` does. Changed
to "most commands", which is true. Checked twelve commands against their own
--help rather than against the page.
Read against packages/studio/src rather than against the page's own prose.
- `J` / `Shift + J` jump to the previous and next keyframe
(useKeyframeKeyboard.ts:60). The keyframe table had no row for J at all.
- `Backspace` deletes a keyframe, not only `Delete` (same file, line 56).
- `Ctrl + Y` is redo (useAppHotkeys.ts:44). Only Ctrl+Shift+Z was listed, and
Ctrl+Y is the first thing a Windows user reaches for.
The page already warned that arrow keys mean different things depending on
selection. `J` and `K` do exactly the same and it did not say so — `K` is stop
during playback and add-keyframe with keyframes selected, which is a surprising
way to lose your place. That note now names them.
Everything else on the page checks out: 20 single-letter bindings in the source,
all now accounted for.
Every user-journey film on the docs site is narrated by ElevenLabs River
(SAz9YHcvj6GT2YYXdXww) at 145-155 wpm with music about -31 LUFS under it. That
was recorded in one launch project's notes and nowhere an agent would look.
So when I briefed six new docs videos I asked for "a music bed plus SFX" and said
nothing about voice. Two fell back to local Kokoro (am_michael, bm_george) and one
used an unspecified ElevenLabs take. Three films, three narrators, none of them
the one the rest of the site uses. Being re-voiced now.
The rule is in skills/media-use/audio/references/tts.md, next to the provider
table an agent already reads before generating a voiceover, including the reason:
falling back to a local voice because a key was not to hand produces a film that
sounds wrong beside the others. If ElevenLabs cannot be reached, say so and stop
rather than substituting.
Also on this branch: the superseded Huly film is gone from the product-launch
page, and three pages that ended up with two hero videos stacked now lead with
one. Where the older clip still showed something different — a finished motion
graphic, the same edits done in Studio — it moved below under its own heading
instead of being deleted.
Thirteen manifests declare `preview: { video }` with no `poster` key, and that
omission is deliberate — no .png was ever produced for them. main reads it in one
line: `if (manifest.preview) return manifest.preview.poster`.
I deleted that line as "config nobody varies", having checked whether any poster
DIFFERED from the generated URL (none did, 100 of 100) and never having checked
whether any was ABSENT (thirteen were). Then I replaced it with a filesystem
check against docs/images, which is gitignored, so it was false everywhere and
would have stripped all 168. Then I removed the poster entirely. Three wrong
answers to a question the repo had already answered.
Restored, and the page's video tag now asks the same function rather than a
second source of truth. 155 of 168 carry a poster, matching main exactly: 154
video pages plus texture-mask-text, which renders mask images instead of a video.
The 13 remaining dead URLs are in catalog-index.json only, which no code in
docs/ or packages/ reads, and no rendered page requests them.
The complexity cuts to the encode pass stand: hasAudio deleted (ffmpeg ignores
-c:a with no audio stream), and the spawn+Promise wrapper is execFileSync.
**The poster guard I added twice was unworkable and I never ran it.** It called
existsSync on docs/images/catalog/<name>.png. That directory is gitignored —
previews are generated locally, uploaded to the CDN and never committed — so the
check is false on every clean checkout and in CI. It would have stripped the
poster from all 168 pages, not the 13 with a missing file. It also referenced
REPO_ROOT, which does not exist in that file, so the script crashed on the first
item. I described this guard in two commit messages without once executing the
generator.
The poster is now gone entirely, which is the smaller and more honest fix. These
previews are autoPlay muted loop, so the poster is visible for a few hundred
milliseconds; 13 of the 168 files do not exist and the browser fetches the poster
before the video. Removing the attribute kills 13 x 403 and 168 needless image
requests, and there is nothing to keep in sync.
Also applied a complexity pass to the delivery encode:
- hasAudio() deleted. 17 lines and a spawnSync per item to choose between
"-c:a aac" and "-an". ffmpeg ignores -c:a when the input has no audio stream;
checked, exit 0, output carries no audio track.
- The 40-line spawn + Promise wrapper is execFileSync. Everything around it in
that script is already synchronous.
- The duplicated poster lookup is gone with the poster itself.
Net 76 lines lighter. Generator runs clean, emits 168 pages, carry-forward intact.
Left unformatted by the catalog-generator commit, which is the one file
Preflight was failing on. oxfmt --check is clean on it now.
Note for anyone reading the earlier claim: I said main fails oxfmt on 30 files.
That was my local run picking up no repo config and using its own defaults. CI
found exactly one file, and it was mine.
An earlier commit here said generate-catalog-previews.ts "has a web pass now".
It did not. I made that edit in a second checkout while investigating and never
brought it onto the branch, so the claim shipped in a commit message while the
code stayed as it was.
The fix itself is unchanged from what was described: the render output is a
master, and publishing it directly is what put 25 Mbps files on the docs CDN.
generateVideo now renders to <name>.master.mp4, runs one delivery pass at 1280
wide, CRF 28, faststart, keeping audio only when the source has it, then deletes
the master and logs the delivered size.
Formatted and linted clean. The Format check failing on this PR is pre-existing:
origin/main fails oxfmt --check on the same 30 files, none of which this branch
touches.
Removing the eight-second teaser left this page with nothing at all, and the
replacement had been rendered and published hours earlier without ever being
wired in.
Twenty-seven seconds of a live deck: fragments arriving one key-press at a time,
a hotspot jumping to a branch slide, the back control returning to the exact
fragment it left, and presenter mode with real notes and a running timer. It is a
capture of the deck running, not a video of slides.
Guides with nothing to look at: 5.
Product launch, colour grading, faceless explainer, captions and recuts, motion
graphics, and voice and audio.
Five of these led with a six-to-eight second teaser. A six-second clip on the
page that teaches you to make explainers does not teach anything — it is a
placeholder that looks like content. Colour grading, the most visual feature in
the product, had no video at all.
The new films are 34 to 41 seconds and each shows a RANGE rather than one look:
four ways to tell the same idea with no footage; five caption treatments on one
untouched clip; correction, presets, curves, selective colour, all four scopes
and a LUT; narration with music ducking under it and effects on the beat. The
launch film is built by running the workflow on huly.io for real, so the page
that sells the workflow is showing its actual output.
They share one visual system, measured from HyperFrames own light-theme launch
films rather than invented: bone field, near-black type, coral accent, and the
product always a dark panel inset on the light field. Every one carries audio at
about -20 dB and is 1-2 MB.
The old teasers are removed from the three pages where they became a duplicate.
They stay in the workflow picker, which is where a six-second tile belongs.
Guides with nothing to look at: 15 at the start of this work, 5 now.
Measured across all 136 hand-written pages, the twelve hardest to read were all
in prompting/. These ten were untouched — 29% to 40% of their sentences ran over
28 words, against a site median under 15%.
media-and-audio 39.7% -> 6.2% 15 semicolons -> 6
visual-specs 37.1% -> 19.0% 11 -> 9
weekly-updates 39.1% -> 0.0%
runtimes-and-3d 34.1% -> 17.5%
design-systems 34.0% -> 4.3%
recreating-references 33.3% -> 7.3% 16 -> 1
storyboards 31.9% -> 5.4%
variables-and-templating 30.3% -> 7.3%
generated-artwork 29.4% -> 9.1%
explainers 29.1% -> 3.3% 12 -> 1
Word counts barely move — 1752 to 1748, 1633 to 1617 — which is the point. The
facts and worked examples all survived; the sentences carrying them got shorter.
weekly-updates is an archive, so no date, version or fact changed there at all.
One anchor came back: capstone#the-full-prompt-verbatim, which these pages link
to and which an earlier commit had already moved to #the-prompt-word-for-word.
Repointed. Branch total: 0 broken pages, 0 broken anchors.
The previous commit claimed all 597 media URLs returned 200. They did not — 13
still 403'd, and I pushed that claim without re-running the check after the fix.
The message was wrong; this is the correction.
Two files carry a poster, not one. Guarding the page generator left
catalog-index.json still pointing at 13 .png files that were never produced,
which is a broken thumbnail in the catalog grid rather than a missing one.
catalogPreviewFor now returns undefined when the file is absent, the same rule
the page preview uses, and the 13 stale entries are dropped from the written
index.
Verified after the change, not before: 584 media URLs on this branch, 0 dead.
My catalog rebuild added `poster="<name>.png"` to every preview. Thirteen items
have an .mp4 but no .png, so the page asked for an image that does not exist —
and a browser fetches the poster before the video, so those were thirteen 403s
on load. The merged version did not have this; I introduced it.
The generator checks the file now, the same way it already checks before telling
a reader to read a comment header that may not be there. Thirteen pages lose the
attribute; the videos are unaffected.
Also uploads the three weekly changelog re-encodes to the path they are actually
served from — hyperframes/changelog-videos/, not the docs image tree — which I
had got wrong, leaving three dead links in the previous commit.
All 597 media URLs on this branch now return 200.
Thirty-two published videos were the raw render output. One 20-second catalog
preview was 60 MB at 25 Mbps — Blu-ray bitrate for a screen capture in a docs
page. Nothing autoplays, so no page shipped that silently, but a reader who
pressed play paid for it.
Re-encoded at 1280 wide, CRF 28, faststart, keeping audio where it existed.
Measured PSNR against the originals at ~38.5 dB, which is visually identical —
the first check I ran returned nothing and I mistook that for a pass, so this
number comes from a filter that actually worked.
Worth correcting one thing I said earlier: the catalog is not systemically
over-encoded. 190 videos, 0.36 GB, about 1.9 MB each. Six were over 10 MB. I
found two monsters and generalised from them.
Pages carrying more than 8 MB of video: 26 before, and the heaviest went from
140 MB to under 15 MB.
The durable fix is in generate-catalog-previews.ts, which had no delivery encode
at all — it published the render master directly. It has a web pass now, so the
next preview is born small instead of being cleaned up later.
* docs: add the shared page components
Adds the six React snippets the rebuilt documentation pages compose against,
plus the styles they need. Nothing imports them yet, so this lands with no
user-visible change and no navigation churn.
- DocsVideo / ShowcaseWall — the film player and the Showcase grid
- LiveReferenceProject — embeds the Reference Project via <hyperframes-player>
- WorkflowChooser, AgentAction, and the two grid snippets
The scrub indicator is a timecode bubble rather than a thumbnail. Mounting a
second <video> with the same src to drive a preview frame made every page
carrying a film download the whole file twice, which is not worth a thumbnail.
* docs: add the Reference Project example
One real 10-second project the documentation can point at instead of describing
a hypothetical one: a live capture of example.com, synthesised narration, and
caption timings measured from that narration. It passes its own gates —
`hyperframes lint` clean, `hyperframes check` passed, 28/28 text checks WCAG AA.
No page imports it yet, so this lands without touching navigation.
Only the two WAV masters exceed the repository's 500 KB non-LFS limit, so only
those go through LFS. The MP3 stings and the capture PNG stay plain, which keeps
the example usable after a clone without `git lfs pull`.
`bun run docs:bundle-reference` regenerates the single-file embed the
Introduction page loads from the CDN.
* docs: keep the Reference Project verification report
The Examples page links this file twice — as "What changed after review" and
as "The real verification report" — in the section that makes the project's
brief, source, revision notes, and checks public end to end. It is a published
artifact, not leftover scaffolding.
* docs: state the Reference Project embed's isolation contract
The composition is fetched from the CDN and handed to the player as a blob:
URL, which inherits the docs origin, and <hyperframes-player> sandboxes its
iframe with allow-scripts + allow-same-origin. So the embedded composition runs
with script access to this origin.
That is a consequence of how the player works — it drives seeking through the
iframe's document, which a cross-origin frame does not expose — not something
this component can fix. Serving the CDN URL directly would isolate the frame
and break playback.
The guard is therefore the source, so the comment says so out loud: src must
stay a first-party path we publish, never user- or community-supplied HTML.
* fix(docs): resolve reduced-motion on the first render, and the embed's dep gap
Both defects from Rames Jusso's review on #2977. Neither is visible today
because nothing imports these files yet, which is what makes them cheap now.
**Reduced motion resolved one paint too late, in all three grids.**
`useState(false)` plus a `matchMedia` read in an effect meant the first
committed render always emitted `<video src autoPlay loop>`; a reduce-motion
visitor had 6 + 8 + 4 tiles already fetching before the attributes came off.
`autoPlay` also overrides `preload="metadata"`, so those were the files, not
metadata probes — and dropping `src` with no following `load()` is not a
reliable abort. A lazy initializer knows the answer on the first render.
**LiveReferenceProject never sent the initial variables.** The sending effect
read `playerRef.current`, assigned by the effect above it on the commit where
`compositionSrc` lands — a commit with nothing in the sending effect's dep
array. So it ran once against a null ref and never again. It looked correct
only because the three defaults match what the composition already renders.
Also from the same review:
- The object URL could outlive its revoke: once the body resolves, `abort()`
no longer stops the chain, so the blob could be minted after cleanup ran with
`objectUrl` still undefined. Same `cancelled` guard the effect above uses.
- `postMessage` targeted `"*"` while the isolation comment argues the frame is
same-origin. Naming `window.location.origin` turns that prose guard into an
enforced one.
- Nothing reached a terminal state when the player script never arrived:
`whenDefined()` does not reject, and a later mount reuses the tag without its
error listener. A CSP rule or content blocker never fires `error` at all.
A deadline covers every path instead of sitting on "Loading…" forever.
- `loadFailed` was never cleared, so one transient failure stuck.
- The README claimed a clone works without `git lfs pull`. It does for the
visuals; both WAVs are pointers and they are the bed and the voiceover, so
the captions would play over silence. Says so now.
- The bundler stripped trailing whitespace document-wide while inlining the
runtime, which reaches inside script template literals where those spaces are
data. It also assumed a literal `<head>` and would silently ship an embed with
no `<base>`. Strip removed, anchor asserted.
Copilot's five "missing hook imports" comments are wrong — Mintlify pre-injects
the hooks, and `TemplateCard.jsx`, cited as the counter-example, uses the
`export function` form the same page says is unsupported.
* fix(docs): stop preview loops when Reduce Motion is turned on mid-session
Miguel's changes-requested on #2977. He is right about the mechanism: dropping
`src` and `autoPlay` through React props neither pauses a playing element nor
aborts its selected resource, so a visitor who turned Reduce Motion on with the
page already open kept every tile running.
Measured in a browser rather than argued from the spec, same clip, same
sequence:
playing paused=false t=2.90 readyState=4 networkState=1
React props only paused=false t=3.90 readyState=4 networkState=1
+ pause/removeAttr/load paused=true t=0 readyState=0 networkState=0
The middle row is the bug: time still advancing, resource still held.
Rames' follow-up asked for a remount-to-poster instead, because a video that
ends with `src` removed holds its last frame and `poster` only paints before
playback begins. `load()` covers that too — it drops readyState to
HAVE_NOTHING, which is precisely the state that paints the poster. Confirmed
side by side on screen: the React-props-only tile sits on an arbitrary mid-clip
frame, the pause/load tile shows the poster again. So no remount is needed.
The guard cannot be shared as code — Mintlify compiles each snippet in
isolation and forbids one importing another — so it is copy-pasted into all
three grids. A duplicated invariant is the kind that rots, and a rendering test
would mean adding React to a repo that only carries it inside packages/studio,
plus mocking Mintlify's hook-injection contract with a mock that can stay green
while the page breaks. `scripts/check-docs-snippet-motion.mjs` asserts the
source instead, wired into `bun run lint`, with unit tests covering both edges.
That gate immediately found `docs/snippets/TemplateCard.jsx`: autoplays with no
reduced-motion handling at all. It is imported by zero pages, and it uses the
`export function` form Mintlify's constraints page says is unsupported, so it
would not work if it were. Deleted rather than fixed.
* refactor(scripts): split the motion guard into named predicates
fallow flagged findMotionGuardViolations at CRAP 42 — a finding this branch
introduced, so it gets fixed rather than suppressed, same as the catalog
generator earlier in the stack.
The two conditions are now their own predicates behind a small requirements
table, which drops the branch count under the threshold and makes each rule
readable on its own line. Same output, same tests.
* fix(docs): move the stop effect above ShowcaseWall's early return
Rames' changes-requested on `e1a03c63`. The effect I added in the previous
commit landed below `if (open) return`, so `ShowcaseWall` called five hooks on
the grid render and four once a tile was open. That is a conditional hook:
clicking a tile — the component's primary interaction — threw "Rendered fewer
hooks than expected".
Worth naming why it landed in one of three. `workflow-chooser` and
`advanced-path-grid` have no early return, so the same paste position was fine
there. `ShowcaseWall` is the only one with a conditional return and it got the
same copy. That is the duplication cost this script's own header warns about,
showing up in the commit that added the script.
**The bespoke gate could not have caught it, and now the generic one does.**
`.oxlintrc.json` already loaded the `react` plugin and never excluded `docs/`
— only `.prettierignore` does, which is why formatting is not a finding here
but linting reaches these files. Naming the two hook rules in an override
scoped to `docs/snippets/**` reports this bug directly, and also reports the
`compositionSrc` dependency gap from round one that was found by reading.
Verified both ways: reintroducing the conditional hook produces
`react-hooks(rules-of-hooks)`, and `bunx oxlint .` is clean repo-wide, so
nothing lit up in `packages/studio`.
**Two holes in the script itself, both from the same review.**
It matched whole files while the invariant is per component, so a second
unguarded grid in `docs-video.jsx` would have ridden in on `ShowcaseWall`'s
guard. It now splits by component. That immediately surfaced the distinction
between a component that decides to autoplay and one that forwards its caller's
`autoPlay` prop — `DocsVideo` only ever plays because a reader clicked, so it
does not owe a preference check.
And `readsPreferenceLazily` never tied its halves: any lazy initializer plus
the media-query string anywhere in the file passed, which is the original bug
satisfying the check written to prevent it. The query now has to sit inside the
initializer's own expression.
Both holes have tests. fallow is clean at 0 introduced.
* fix(scripts): close the two silent gaps in the motion gate
Both from Rames' approval pass on #2977, and both found by running these
functions rather than reading them. Both fail the same quiet way: a component
`autoplays` misses is filtered out before any requirement runs, so the gate
reports zero problems instead of a violation.
`autoplays` had become narrower than the version it replaced. Excluding the
`autoPlay={autoPlay}` passthrough was right, but the replacement only matched
`autoPlay={` or `autoPlay` alone on a line, so `<video autoPlay muted />` on one
line slipped through. Restored the old breadth. Two things are stripped first
rather than one — the passthrough, and the prop's own default in the signature,
which is a declaration and not a use. Without the second strip, `DocsVideo` is
asked to own a decision it only forwards.
`splitComponents` anchored on `^export`, so anything not exported folded into
the previous exported component and inherited its guard. Same hole as the
whole-file match, narrowed from file scope to non-export scope. The anchor no
longer requires `export`.
Ten tests now, including his exact examples for both.
* docs: remove the live-composition embed and its build apparatus
The Introduction no longer carries the embed (removed in #2979), and nothing
else used any of this: the 200-line snippet, 26 CSS rules, the bundler that
built the single-file HTML for the CDN, its npm script, and the README section
explaining how to regenerate it.
The Reference Project itself stays — Examples, Developers, and Go further all
link to it as the worked example; only the interactive embed of it is gone.
This also retires the isolation contract I documented two rounds ago. That
comment existed because the embed handed CDN HTML to a same-origin blob; with
the embed gone there is no such surface to reason about, which is a better
outcome than a comment explaining why it was acceptable.
* docs: remove the AgentAction snippet
Its only consumer is gone. The Quickstart now shows the agent instruction in a
plain fence instead, because this component rendered a Copy button and never
displayed the request — a reader copied text they could not read, which is the
wrong shape for the one affordance a non-technical visitor depends on.
Mintlify fences already carry a copy button and show their contents.
* feat(studio): mirror canvas z-order actions into timeline lanes, badge z overrides
Track order = default paint order; authored z = advanced override.
- timelineZMirror.ts: pure resolver mapping a successful z-menu action to a
timeline lane move — closest track in the action's direction that is free
over the clip's whole span, else a new lane adjacent to the crossed
neighbor; temporal-overlap scope (default pending product sign-off, see
module doc); visual zone only; same-file reference scoping; persistTrack
via the shared authored-space rules. null for non-clips (menu stays
z-only) and at-extreme/no-overlap cases.
- useCanvasZOrderTimelineMirror.ts: after the z commit resolves, the mirror
persists the lane move through the same machinery as a timeline lane drag
(optimistic store update, authoredTrack refresh, rollback); inserts reuse
commitTrackInsert's renumber via a shared buildTrackInsertEdits core. Both
writes share one coalesce key (zReorderCoalesceKey) and fold into ONE undo
entry (test proves it over the real history reducer). The mirror never
triggers the lane->z stacking sync, so it cannot fight the z values the
action just set.
- timelineZOverride.ts + TimelineClip badge: clips whose paint order
contradicts lane order among temporally-overlapping same-context visual
neighbors (laneIsAbove XOR paintsAbove, the stacking-sync predicates) show
a 'z' badge — authored z overrides are surfaced instead of silently
disagreeing with the timeline.
- Timeline.tsx track derivations extracted to useTimelineTrackDerivations
(600-line cap).
* fix(studio): fold mirrored z-order gestures into one undo entry across slow persists
Live verification caught the z write and the mirrored lane write splitting
into two undo entries: the mirror runs after the z persist's server round
trip, which exceeds editHistory's default 300ms coalesce window under real
latency (the unit test's deterministic clock sat inside it).
zReorderCoalesceKey now mints a per-gesture-unique key (monotonic seq, the
laneChangeGestureSeq precedent) and both records carry coalesceMs Infinity —
distinct gestures can never merge, and one gesture always folds regardless
of write latency. coalesceMs threaded through the persist chain alongside
coalesceKey. Also hardens the existing lane-drag move->z fold, which had the
same latent split. Fold test now simulates a 400ms gap (failed before the
fix, passes after); a two-separate-gestures test asserts two entries.
* feat(studio): flashless lane mirror, z-order menu icons, close-gap track menu
- Track-only batch moves (the z-mirror's lane hop and the insert renumber)
skip the GSAP fallback round-trip and the preview reload entirely — the
renderer never reads data-track-index, and the live DOM patch + optimistic
store update cover the UI. Mixed batches keep current behavior. Kills the
canvas blink on mirrored Bring/Send actions (live-verified: an
iframe-scoped marker survives the whole gesture).
- The four z-order menu items get 16px stroke icons (single layer diamond +
directional arrow for Forward/Backward; pierced two-layer stack for
Front/Back); labels unchanged — they are the industry-standard names.
- New track context menu on empty lane space: 'Close gap' (shifts the next
clip and every clip after it on that lane left by the clicked gap's width;
leading gaps count, so a single clip with empty space before it compacts
to 0) and 'Close all gaps' (whole lane contiguous from 0). Pure gap math
in timelineGaps.ts; persists through the drag path's atomic batch move
(one undo per action); refuses when a clip that must shift is locked;
items disable when there is nothing to close.
* fix(studio): rebind-only preview sync for unmutated timing edits, classical z-menu order
Timing edits that rewrote NO GSAP positions (gap closes and moves of
selector-addressed caption clips, zero-delta batches, comps without a
rewritable script) full-reloaded the preview — and the rerun-current-scripts
attempt was wrong for real compositions: re-executing init-style scripts
(three.js scenes, caption engines) is exactly the unsafe case, verified live
by doubled init warnings and a fallback reload anyway.
The correct observation: when mutated === false the existing __timelines are
still valid — only the runtime's clip visibility windows are stale, and the
live DOM timing attributes were already patched. So the no-mutation path now
runs applySoftReloadFinalization only (seek + __hfForceTimelineRebind +
manual-edits reapply), extracted from the soft-reload machinery — zero
script execution. This also un-blinks comps with no GSAP script at all,
which previously always remounted. Rewritten-script soft reloads,
cannot-soft-reload, otherFileChanged, and mutation failures keep their
existing behavior. gsapSoftReload's undo/redo restore section moved verbatim
to gsapUndoRestore.ts for the 600-line cap.
Also: z-order menu items reordered to the classical arrangement (Bring to
Front, Bring Forward, Send Backward, Send to Back).
Live-verified on a three.js-heavy composition: Close-all-gaps shifted 4
caption clips with correct cumulative amounts, the preview iframe was never
remounted (marker survived), and one undo reverted everything.
* fix(studio): bound forward/backward mirror to a one-element step
User-specified semantic: Bring Forward / Send Backward move the clip past
EXACTLY ONE element. The mirror's lane target is now bounded by the next
temporally-overlapping element beyond the crossed neighbor: a free lane
strictly between the two is taken (closest to the neighbor), and when they
are back-to-back a new track is inserted immediately beyond the crossed
element — never past the second one. Previously the resolver took the
closest free lane anywhere beyond the neighbor, which could carry the track
past a second element while the z action only stepped past one — a
track/paint contradiction our own zOverride badge would flag. Front/back
keep whole-set semantics (past everything; back stays above the audio
zone). End-to-end test pins the 3-stacked case through commitZMirrorLaneMove
to the persisted renumbered tracks.
* feat(studio): permanent gap-menu rows with hover and click-select gap highlights
- TrackGapContextMenu always renders both rows; an inapplicable action dims
with a tooltip ("No gap here" / lock reason / "No gaps on this track")
instead of vanishing into a one-item menu. Width badge only when a gap
exists under the pointer.
- Hovering an ACTIONABLE row highlights the strip(s) it would close in the
timeline: the single gap for Close gap, every current gap (leading included)
for Close all gaps. New resolveAllGapIntervals in timelineGaps.ts reports
present-state intervals (epsilon-tolerant, overlap-safe), distinct from
resolveAllTrackGaps' post-compaction starts.
- Click-selecting a single clip paints a quieter tint over its lane's gaps
(suppressed for marquee multi-selection and during drags; the gap-menu hover
wins on its own lane). Derivation lives in useTimelineGapHighlights with the
pure buildTimelineGapStrips exported and unit-tested.
- Strips render in TimelineCanvas with the drop-placeholder geometry (row top
+ clip inset), dashed accent for hover, faint tint for selection.
- Timeline.tsx stayed under the 600-line cap by extracting the scroll-viewport
plumbing (ResizeObserver width + shortcut-hint sync) into
useTimelineScrollViewport, behavior unchanged.
* feat(studio): stronger capcut-style timeline zoom steps
One button press / pinch gesture now moves the zoom meaningfully: step
factors 1.25x/0.8x -> 1.5x/(2/3) (kept reciprocal so in+out round-trips) and
pinch sensitivity 0.0035 -> 0.007. Addresses "zooming several times to get
anywhere" feedback; cursor anchoring unchanged.
* feat(studio): three-way z sync — layers drags mirror timeline lanes, panel tracks live z edits
Completes the layers/canvas/timeline sync triangle: the Layers panel was the
one surface whose reorders never reached the timeline, and the one that went
stale when the other two wrote z flashlessly.
- Layers drag -> minimal z + equal-jump lane mirror. handleReorder now uses
the canvas menu's realization core via resolveZOrderReposition (one
between-z write when a strict gap exists, band-safe scoped renumber
otherwise) instead of computeReorderZValues' all-sibling stamp — that
helper is deleted, completing the #2347 unification follow-up. The drop
then mirrors into a timeline lane move through the same machinery as the
canvas menu (new resolveRepositionLaneMove: the clip lands on a free lane
strictly between its NEW paint neighbors' lanes — nearest clip siblings in
the desired render order, decorations skipped — else a track insert at
that boundary; audio zone never crossed). Both writes share one
per-gesture zReorderCoalesceKey with an unbounded fold window, so a drag
is exactly ONE undo entry; useCanvasZOrderTimelineMirror's plumbing is
factored into useMirrorLaneMoveCommit and reused by the new
useLayerReorderTimelineMirror. A same-slot drop is a hard no-op (new
order-equality guard in resolveZOrderReposition).
- Panel staleness fix: flashless z commits (skipReload) reload nothing and
bump no refreshKey, so the panel's z-sorted order went stale while paused.
handleDomZIndexReorderCommit now bumps a store zEditVersion on apply AND
rollback; the panel re-collects on it. Verified live: the panel re-sorts
the instant a drag commits and again on undo.
- Layer click reveal (useLayerRevealOverride): clicking a layer that stays
hidden at the current frame (animation-parked opacity, non-clip
display/visibility hides, hidden ancestors) temporarily forces the chain
visible with live inline styles — exact priors restored on deselect, on
another reveal, on play, and on unmount; never persisted (file diff == 0
verified live). Clips keep the existing seek-into-window behavior; the
override applies on a short defer so a seek-revealed clip needs none.
- layerOrdering's unused hasExplicitZIndex probe (zero callers) removed.
Live-verified on a bed copy: a 2-position layers drag wrote exactly one
element (z 6->23 + data-track-index 15->2), the timeline lane moved without
a reload, and a single Cmd+Z restored the file byte-identically.
* feat(studio): full-track selection highlight, borderless gap hover strips
- Click-selecting a clip now lights the WHOLE lane minus its clips — leading
gap, inter-clip gaps, and the open space after the last clip to the rendered
end (new resolveLaneEmptyIntervals; displayDuration threaded into the strip
derivation). Still click-only: any drag/resize suppresses the strips, and a
marquee multi-select never shows them.
- The gap-menu hover strips drop the dashed border (user feedback) — fill only,
nudged to 0.18 alpha to keep the same visual weight.
* feat(studio): selected layer paints on top via a reader-transparent z lift
Clicking a layer in the Layers tab now shows the element as if it were at the
very top of the stack while selected — whatever its authored z or panel
position — extending the reveal override (which already forced hidden chains
visible) with a temporary inline z lift:
- liftElementToTop parks the TRUE effective z in data-hf-reveal-prior-z and
writes a far-top inline z; a static element gets a layout-preserving
position:relative with its prior parked in data-hf-reveal-prior-pos. Only
the RENDERER sees the lift: all three studio z readers
(readTimelineElementZIndex, getElementZIndex, readEffectiveZIndex) return
the parked prior while the attribute is present, so the canvas z-menu, the
zOverride badge, the lane mirror, the stacking sync, and the panel sort
keep reasoning on the element's real z.
- Strictly ephemeral: exact priors restored on deselect / another reveal /
play / unmount, each property only while it still holds the value the
override wrote (a later real edit is never clobbered). File diff == 0
verified live across a full lift/restore cycle.
- A z-reorder commit CONSUMES an active lift (handleDomZIndexReorderCommit
reads the parked position for its persist-position:relative static check,
then drops the attributes) — the committed z becomes the truth and the
later restore is a guarded no-op.
* fix(studio): flashless undo/redo — three full-reload causes in the soft-restore path
Cmd+Z blinked the canvas on essentially every undo. Three independent causes
in applyUndoRestoreToPreview, each sufficient on its own:
1. Master-view path gate: activeCompPath is NULL at the master view, so the
'paths[0] === activeCompPath' eligibility check could never match the
index.html restore and every default-view undo full-reloaded at the first
gate. Normalized to the codebase-wide 'activeCompPath ?? "index.html"'.
2. Nested identity innerHTML check: the diff compared each identified
element's innerHTML, but the composition root wraps every clip — any child
change re-detected at the root rejected the restore. Change detection now
compares only each element's OWN attribute surface; structure/text
integrity is still guaranteed by the normalize-residual whole-doc pass
(text nodes, added/removed elements, and un-identified attrs all remain
after normalization and force the full reload).
3. id-only identity: elements addressed by data-hf-id / selector (no DOM id)
fell outside the diff entirely. Identity is now id OR data-hf-id, with the
live sync resolving either.
Also stop re-running an UNCHANGED GSAP script: attribute-only restores (z,
lane, timing, style — the overwhelmingly common undo) now use the rebind-only
finalization (seek + __hfForceTimelineRebind + manual reapply, zero script
execution — the same path as flashless timing edits), instead of tearing down
and rebuilding live timelines or full-reloading when the script can't be
scoped. A restore whose script text genuinely changed still re-runs it via
applySoftReload, and structural restores (split/delete) still full-reload.
Live-verified on the bed (iframe marker): gap-close undo AND redo both keep
the iframe mounted, live DOM lands on the restored values, disk restored
byte-identically.
* feat(studio): left breathing pad before t=0, double zoom sensitivity again
TRACKS_LEFT_PAD (48px) — the horizontal sibling of TRACKS_TOP_PAD: empty lane
surface between the sticky gutter and the ruler's 00:00 / the first clips,
scrolling WITH the content.
- The lanes and the ruler realize it as a plain flow spacer between the
sticky gutter cell and the time-mapped content div, so every
content-relative computation (clip left = t*pps, beat lines, lane-menu
time, clip drag deltas) is untouched by construction.
- Canvas-space overlays shift by the pad: playhead (getTimelinePlayheadLeft),
gap strips, drop placeholder, snap guide, range highlight, marquee clip
rects, beat SVG; the insert line spans the pad.
- Every pointer->time inverse subtracts it symmetrically: seekFromX, razor,
range/marquee anchors, asset drops, and the zoom-anchor gutter basis; fit
pps and the display width account for the consumed viewport width.
- Live-verified: t=0 clip edge, the 00:00 tick, and the playhead line center
all sit at GUTTER + TRACKS_LEFT_PAD, and a ruler click lands the playhead
center exactly under the pointer.
Also doubles the timeline zoom sensitivity again (user feedback after
feel-testing the first bump): button steps 1.5x/(2/3) -> 2x/0.5, pinch
0.007 -> 0.014.
* fix(studio): left pad renders as true empty space, not lane surface
The pad before t=0 inherited each row's background and bottom border from the
row wrapper, so it read as track lanes. Lane visuals now live on the cells:
the sticky gutter keeps its own separator (header column stays delineated),
the time-mapped content div carries the row background + separator, and the
pad spacer stays transparent — bare shell background, no lines. The
new-track insertion line also starts at the pad's end instead of crossing it.
* fix(studio): no vertical line in the ruler band before 00:00
The ruler corner's right border drew the header-boundary line through the
ruler strip, so the band didn't read as starting at 00:00. Dropped it — the
boundary line belongs to the track rows below; the ruler stays completely
clean from the panel edge to the first tick, matching the empty left pad.
* refactor(studio): remove the timeline z-override badge
User decision: the "z" chip on clips never earned its place — dropped
entirely (timelineZOverride.ts + test deleted, TimelineClip badge rendering
and the zOverrideKeys derivation/threading removed). This also eliminates the
review's D2 finding at the root: the badge's cross-document comparison
(stackingContextId ?? null collides across source files in the expanded view)
produced false positives, and there is no longer a detector to mis-fire.
overlapsInTime/paintsAbove lose their export (the badge was their only
external consumer); the paint-order predicate itself is unchanged.
* fix(studio): collision-free expanded child lanes and host-window gap floors
Review findings D1 (blocker) and 4.
- D1: buildChildElements assigned expanded children synthetic display rows as
`host.track + index` — integers that can EQUAL a real clip's lane in another
file (host on 0 with two children puts child #2 on 1). Lane grouping merges
purely by track number, so the collision fused clips from different source
files into one display lane, and lane-scoped actions (the gap menu) then
batch-persisted a foreign file's clip. Children now take FRACTIONS strictly
between the host's lane and the next integer — structurally unable to
collide with any normalized lane, while still rendering as ordered rows
under the host. Regression test pins the reviewer's exact two-file scenario.
- Finding 4: gap math compacted toward absolute 0, but an expanded child's
display time is host-anchored — close/compact could drag it before its host
window and persist a wrong (even negative) local time. All gap functions
now take a lane FLOOR (laneGapFloor: 0 for ordinary lanes, the children's
expandedParentStart for child lanes — single-origin per lane post-D1),
threaded through the menu model, hover highlights, selected-lane strips,
and both commits. Close-gap shifts clamp at the gap's own left edge.
* fix(studio): scope mirror references, insert writes, and crossed-neighbor identity
Review findings 1, 2, and 3.
- Finding 1: buildTrackInsertEdits normalized the FULL display set and
persisted every shifted clip — writing host-lane numbers into OTHER
composition files when expanded children were showing. The renumber write
set is now the edited element's own source file (the sanctioned multi-write
converges one FILE to lane space, never neighbors' files); foreign clips
keep their authored tracks and re-derive display lanes. The locked-clip
refusal scopes the same way. Expanded-origin elements refuse the insert
outright (a new lane is a host-space renumber, meaningless in the child's
file), and the mirrors restrict an expanded child's lane candidates to its
own siblings' lanes — a sub-comp child still mirrors WITHIN its sub-comp
(persisting the sibling's authored track) but can never land on a host lane
with no same-file occupant. authoredTrackForLane's offset fallback rounds:
fractional synthetic rows must never leak fractions into data-track-index.
- Finding 2: the mirror comparison sets required only sameSourceFile, but a
file can contain several CSS stacking contexts and leaf z is only
comparable within one. Both resolvers now scope by samePaintScope — same
source file AND same stackingContextId (the file check also stops null root
contexts of different files from comparing equal in the expanded view).
- Finding 3: the crossed-neighbor key was derived without selectorIndex, so
duplicate class selectors (.sub) resolved to occurrence 0 — a different
clip. The key now carries getSelectorIndex, matching how z-reorder entries
derive theirs.
* fix(studio): z-to-lane gestures are one serialized transaction gated on durable persists
Review findings 5 and 7.
- Finding 5: commitDomEditPatchBatches resolved successfully even when the
server matched NO patch target — the z write never reached disk (the
preview reloads to reconverge) yet the lane mirror still ran, desyncing
track order from what actually paints. The commit now resolves a durability
report ({allMatched, changed}; the save queue and commit types are generic
over the result), and the mirror phase is skipped on allMatched === false.
- Finding 7: the z persist rides the DOM-edit save queue while the lane move
rides the timeline/SDK path — two queues, so a second rapid gesture's z
write could land BETWEEN the first gesture's z and lane phases. Every
z-to-lane gesture (canvas z-order menu AND Layers-panel drag) now runs
through runZLaneGesture: a single module-level tail that serializes the
COMPLETE two-phase transaction, with unit tests for ordering, the
durability gate, and queue resilience to failed gestures. The timeline
lane-drag's inverse (move-then-z-sync) shares its phases' await ordering
already; cross-gesture serialization for that path is noted as follow-up.
- LayersPanel's pure sort helpers moved to layersPanelSort.ts (600-line cap).
* fix(studio): multi-clip GSAP batch mutations roll back on late failure
Review finding 6. finishGroupTimingGsapFallback mutates files sequentially
per clip; a late per-clip failure left the earlier rewrites on disk with no
aggregate history entry — unreachable by undo. foldGsapMutationIntoHistory
already snapshots every touched path before mutating; on a mutation failure
it now restores each path whose disk content changed (all-or-nothing batch),
reports restore errors without masking the original failure, and rethrows.
Regression test drives a two-clip batch whose second rewrite fails and
asserts the first clip's write is restored byte-identically.
* fix(studio): scope mirror inserts to their lane zone
* fix(studio): unify source-scoped clip identity
* fix(studio): isolate track insert topology
* fix(studio): harden timeline paint synchronization
---------
Co-authored-by: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Review 1 (restore commit):
- asset reveal now clears any open preview overlay (stuck-overlay repro:
preview on A, click already-added B — A stayed open over the reveal)
- duration readout rolls back on failed persist: captureDurationRollback
snapshots store + live root data-duration before the optimistic sync and
restores both in every move/resize/delete/group catch (golden's
previousDuration pattern)
- asset preview opened during running playback dismisses immediately (the
RAF loop bypasses the store, so the subscription alone never fired)
- persistTimelineBatchEdit resolves the target (findTagByTarget) before
treating identical output as a no-op — a mistargeted member now throws
like the single-element path instead of being silently dropped
- a post-mutation history-fold failure no longer suppresses the preview
sync: fold errors are surfaced separately and the rewritten script still
syncs (previously the preview kept stale GSAP positions with no recovery)
- timelineRevealScroll guards degenerate viewports (windowSize <= 0)
- CodeQL: encodeURIComponent(projectId) at all timelineTimingSync fetches
Review 2 (single-source-of-truth pass):
- createTimelineElementFromManifestClip — the one manifest->element
boundary — now carries authoredTrack and stackingContextId; expanded
sub-comp children preserve both (authoredTrack in their OWN file's space)
- authoredTrackForLane scopes occupants to the dragged clip's sourceFile
(a foreign file's authored values are a different coordinate space);
nearest-same-file-lane offset fallback
- optimistic store updates mirror the persisted track into authoredTrack
(and roll it back on failure), so consecutive drags before a reload
resolve from fresh data
- spill sub-lanes: documented decision — dropping onto a spill lane is a
legitimate same-track join (occupants share the authored track by
construction); false 'never a lane-move target' docstring rewritten
- single-element fallback persists vertical-only moves (early return now
requires neither start nor track changed; live DOM patch includes
data-track-index)
- canonical contextKey helper for stacking-context normalization
- new pipeline test crosses the REAL factory boundary (sparse authored
tracks -> factory -> expansion -> normalize -> drag commit -> persisted
attribute), no injected fields
Two legibility fixes for the canvas z-order menu, from user feel-testing:
- z-only commits no longer remount the preview iframe. The commit hook
already applies the inline z (+ injected position) to the live elements and
updates the store synchronously; the post-commit reloadPreview() was a
redundant full remount that read as a canvas 'blink' on every action.
commitDomEditPatchBatches gains skipReload, engaged only when provably
safe: every op is an inline-style patch AND the server reports every patch
matched — anything else falls back to the reload so the preview reconverges
with disk. The file-watcher's own reload stays suppressed by the existing
domEditSaveTimestampRef window, so the skip is real.
- Bring Forward / Send Backward step over the next VISIBLY overlapping
sibling. The nearest z-neighbor in a composition is often invisible at the
current frame (runtime hides time-inactive clips with inline
visibility/display; GSAP parks elements at opacity 0), so the step crossed
something the user couldn't see — 'enabled but nothing happens'. The
forward/backward set now filters on element-level computed visibility
(display/visibility/opacity, injectable for tests); enable/disable shares
the resolver so the menu is honest: actions disable when no visible
neighbor exists. Front/back keep the full painting family.
- The neighbor that was stepped over gets a 600ms accent flash, drawn in the
studio overlay layer (never in the iframe DOM), so the action shows its
work.
An adversarial review of the canvas context-menu z-order pipeline (Bring to
Front / Forward / Backward / Send to Back) found the resolver math sound but
the glue between the menu and the commit hook broken:
- The menu optimistically wrote style.zIndex AND position: relative to the
live elements BEFORE the commit hook ran. The hook decides whether to
persist position by checking getComputedStyle(el).position === 'static' —
always false after the pre-apply — so the position patch was never
persisted on the menu path and the reorder silently reverted at the
post-commit reload for any nested/static element (root clips survive only
because the runtime forces position:absolute). The same pre-apply made the
failure rollback capture the already-mutated values, restoring the broken
state on persist errors. The menu no longer pre-applies; the hook owns the
live writes (it already applied both synchronously) and now sees true
priors. Siblings without a persistable identity still get their z applied
live-only so a renumber stays visually coherent.
- The commit hook's entry.key store-sync plumbing had zero production
callers; the store zIndex went stale until full reload. All three callers
(canvas menu via PreviewOverlays, timeline lane z-sync, LayersPanel) now
derive and pass the timeline store key (new deriveTimelineStoreKey helper).
- patchElementBatch discarded the server's per-patch matched[]; unresolvable
siblings persisted partially and silently. Unmatched targets now warn and
report save-failure telemetry (z-reorder-unmatched) without rolling back
the matched subset.
- template/noscript elements counted as painting siblings, so renumber
fallbacks wrote z-index/position into <template> tags in the source file.
Excluded from the sibling family.
- The default undo coalesce key merged DISTINCT z actions within 300ms into
one undo entry; the action kind is now part of the key (LayersPanel drags
keep coalescing within a drag; explicit lane-move gesture keys untouched).
- rectsIntersect comment claimed touching rects intersect; the strict
inequalities say otherwise — comment fixed.
Vertical clip moves committed in the store but never survived: two persist
bugs plus a runtime renumber all fought the stable-track-lanes model.
- timelineMoveAdapter deliberately stripped the track from lane-reorder
persists ('z-only reorder path' — the old z-driven lane model). Lane =
authored data-track-index now: lane-reorder and track-insert both persist
the track; plain timing moves omit it to stay SDK-fast-path eligible.
- Display lanes and file tracks are different coordinate spaces:
normalizeToZones packs sparse authored tracks (1,2,... or gaps, or DOM-index
fallbacks) onto contiguous display lanes, and lane edits persisted the LANE
number — silently re-targeting the wrong row in any non-0-contiguous file.
Elements now record their authoredTrack when remapped; a lane change
persists the target lane's authored track (store stays in lane space).
- The runtime split same-track clips of different kinds (video vs caption
div) onto separate renumbered tracks at discovery, so authored indices
never round-tripped ('drop onto an existing track' bounced back). Removed:
data-track-index is honored verbatim (render never reads it); kind-based
row presentation belongs in the display layer if ever wanted.
Adversarial review fixes on the same pipeline:
- runtime: parseInt(attr) || fallback dropped authored track 0 for GSAP and
overlay clips (parseAuthoredTrack helper honors 0)
- single-clip move fallback persisted only data-start — lane changes snapped
back on reload (now passes the track to the patch builder)
- lane-change z-sync candidate ignored a multi-selection's time shift, so
patches were computed against stale overlap sets
- track insert around a locked clip persisted a colliding renumber (the next
normalize merged lanes); the insert is now refused with a warning
- computeStackingPatches compared leaf z across CSS stacking contexts, where
ancestor z decides paint order; the sync now partitions by
stackingContextId and never patches across contexts
Timeline geometry (user-reported):
- fit zoom leaves 20% trailing headroom (FIT_ZOOM_HEADROOM in
timelineLayout.ts; single fit-pps source, so ruler/lanes/playhead/drag all
inherit it)
- playhead line center now sits exactly on GUTTER + t*pps at every zoom
(wrapper had shrink-wrapped to the 9px diamond, off-centering the line);
ruler ticks center on their timestamp
- ruler: frame-mode steps snap to whole frames (no duplicate labels), hour
steps added for far zoom-out, tick positions computed as exact multiples
(no float drift)
The Studio stack rebuild (#2291) landed the remaining NLE layers but dropped
or regressed several final-wave behaviors from the reviewed studio-dnd stack,
and never repaired the stale timelineZones.ts that #2279 introduced. Restores:
- TimelineRuler: sticky under vertical scroll, full-height gridlines removed
(beat lines only), frame-number tick labels via a persisted timeDisplayMode
store preference (PlayerControls toggle now store-backed)
- timelineZones: stable track lanes — lane = authored data-track-index
ascending; z is paint order only (replaces the stale z-driven lane pack,
which broke track insert-band commits that contractually depend on it)
- persistTimelineBatchEdit: a batch member whose patch is a no-op (attributes
already at target values, e.g. in a track-insert renumber) is skipped
instead of aborting and rolling back the whole batch — this alone made
new-track creation (incl. the top insert band) fail silently
- useTimelineStackingSync: unresolvable clips read as NaN again so
timelineStackingSync's Number.isFinite exclusion contract holds (z=0
fabrications skewed stacking boundaries)
- timelineAssetDrop: drops land on the drop track (no overlap bump to
max-track+1), data-hf-id stamped, audio gets data-volume
- timing edits: soft-reload the server's rewritten GSAP script instead of a
full iframe remount (no all-clips flash on move/resize); full reload only
when no scriptText or the soft path can't apply, and one full reload when a
group edit touches non-active files (new hooks/timelineTimingSync.ts)
- duration: content-driven grow-AND-shrink on move/resize/delete, synced
optimistically to the store and the live root data-duration at release
(was a grow-only ratchet; shrink never updated the readout)
New UX: sidebar asset click opens a compact non-modal preview over the canvas
(dismiss on outside click, Escape, playback, or seek), and clicking an
already-added asset reveals its clip in the timeline (smooth minimal scroll
to its time and lane; vertical-only in fit zoom).
Verified by pointer-driving a real project: sticky ruler + gridline removal,
no iframe remount on move/resize (marker survives, GSAP tween positions
rewritten in place), duration readout 40->37->40 on shrink/stretch, and
top-insert-band track creation renumbering lanes correctly on disk.
What: new pure module timelineCollision — zone-aware drop placement
(clampTrackToZone, resolveZoneDropPlacement, resolveInsertRow,
resolvePlacement, lane/overlap predicates) with its full test suite.
Why: the no-overlap core of the NLE clip-drag engine; plain functions, no
DOM, no React, no store writes.
How: new files only; type-only imports from the existing playerStore.
First runtime consumer arrives with the drag-engine PRs.
Test plan: bunx vitest run timelineCollision.test.ts; tsc --noEmit; fallow
audit clean (all exports test-consumed).
* feat(studio): timeline leaf helpers — audio inspector, zoom math, UI prefs
What: extends three leaf modules to their final NLE-stack form, tests in the
same change: timelineInspector (isAudioTimelineElement, resolveBeatSourceTrack),
timelineZoom (zoom/pps math incl. computePinnedZoomPercent), and
studioUiPreferences (persisted editor prefs).
Why: leaf dependencies of the NLE timeline stack; landing them first keeps
the later glue PRs to wiring.
How: additive from the consumer side — every export main already uses is
unchanged (typecheck against main's consumers passes untouched); every new
export is exercised by a test in this PR.
Test plan: bunx vitest run on the three test files; tsc --noEmit in
packages/studio; fallow audit --base origin/main clean.
* feat(studio): seek-restore contract for player reloads
What: useTimelineSyncCallbacks gains resolveReloadSeekTime and revealIframe —
the pure contract for where the playhead lands after a preview reload
(pending seek > deep-link seek > store playhead, clamped) and for undoing
refreshPlayer's iframe hide. Test suite included.
Why: the NLE editor reloads the preview on every committed edit; this
contract is the difference between "playhead restores" and "jumps to 0".
How: additive exports on an existing hook file; main's consumers unchanged.
Test plan: bunx vitest run useTimelineSyncCallbacks.test.ts; tsc --noEmit in
packages/studio; fallow audit clean.
What: extends three leaf modules to their final NLE-stack form, tests in the
same change: timelineInspector (isAudioTimelineElement, resolveBeatSourceTrack),
timelineZoom (zoom/pps math incl. computePinnedZoomPercent), and
studioUiPreferences (persisted editor prefs).
Why: leaf dependencies of the NLE timeline stack; landing them first keeps
the later glue PRs to wiring.
How: additive from the consumer side — every export main already uses is
unchanged (typecheck against main's consumers passes untouched); every new
export is exercised by a test in this PR.
Test plan: bunx vitest run on the three test files; tsc --noEmit in
packages/studio; fallow audit --base origin/main clean.
* fix(skill): all file paths use capture/ subfolder prefix
Step-1 was updated to capture into <project-dir>/capture/ but all
file-read instructions across steps 1-6 still used bare paths
(extracted/tokens.json, assets/hero.png). Agents following the skill
looked for files in wrong locations, producing broken compositions
with 404'd images and fonts.
- step-1: all 12+ file-read paths prefixed with capture/
- step-2: tokens.json and asset-descriptions.md paths fixed
- step-3: visible-text.txt path fixed
- step-4: asset-descriptions.md, asset examples, directory tree expanded
to show capture/ children (screenshots/, assets/, extracted/)
- step-5: minor cleanup
- step-6: asset-descriptions.md path fixed, composition examples already
correct (../capture/assets/)
- techniques.md: Lottie, video, font paths all prefixed
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(skill): address Copilot review — font comment path, add videos/ to tree
- techniques.md: comment says ../capture/assets/fonts/ (matches composition context)
- step-4 file tree: add videos/ under capture/assets/
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Ular Kimsanov