`registry_item_added` fires when a catalog block is installed and
`render_complete` fires when a video is produced, but nothing joined them, so
"did this video use the catalog?" had no answer.
`hyperframes add` now records each installed item in `hyperframes.json`
(installed files are plain composition HTML with no provenance marker, so this
manifest is the only record that a file came from the registry), and
`render_complete` reports both the items the project installed and the blocks
the rendered composition actually reaches. An item installed and then never
mounted was tried and dropped, which no add-time event can express.
The scan answering "which sub-compositions does this file mount" now has one
owner, `collectSubCompositionSrcs` in `@hyperframes/parsers`, shared with
lint's `lintMissingOrEmptySubComposition`. It holds two invariants that were
previously restated per call site and got re-derived wrongly: it is a text scan
rather than a DOM query, because `<template>` content is inert and every
sub-composition except the render entry is wrapped in one; and references
resolve root-relative at every nesting level, matching `parseSubCompositions`.
It walks tag by tag rather than running open-ended spans across the whole file,
so a malformed composition cannot stall the render plan.
Also: `registryItems` is declared in the config schema, which closes with
`additionalProperties: false`, with an ajv-backed test pinning every key the CLI
writes; counts are never truncated by the name cap, and the reported used blocks
stay a subset of the reported installed ones, with `registry_items_truncated`
marking a windowed list; and an unreadable manifest reports itself rather than
posing as a project that never used the catalog.
The runtime absorbed a series of authoring mistakes over time and `runtime/init.ts`
says so in its own comments, but the skills kept teaching the old rules. Four of
them actively cost an agent a failing run: add `crossorigin` (lint rejects it
unconditionally), never build a timeline inside `async` (lint calls that the
documented contract), never `gsap.set` later-scene clips (two fixHints instruct
exactly that), and 12 copyable media snippets with no `id`, which render silent.
Corrected in every place each claim appeared, including `hyperframes-animation`,
three workflow scripts, the scaffolded project instructions, the CLI `docs`
command, and the public docs site: `data-track-index` is a Studio display lane
the render never reads, `class="clip"` is a layout convention rather than a
visibility requirement, timed elements may nest, the visibility window is
half-open, sub-composition host dimensions are backfilled, and the root-fill rule
applies only to the layered-composite path.
Behaviour changes, each backed by a render rather than by reading code:
- `timeline_registry_missing_init` deleted. The runtime creates the registry
before any inline script; a composition without the guard line renders and
animates correctly.
- `video_nested_in_timed_element` kept, message corrected. A rendered repro shows
the nested-with-local-start case really does break, so the rule guards a real
defect, but nothing is "FROZEN": the extractor ignores the wrapper's offset
while visibility uses it, so the clip shows wrong frames and then vanishes.
- `mediaRenderIds` now stamps media whose source is a `<source>` child, closing a
duplicate-id gap the old `[src]`-only selector left open.
- Stale messages fixed on `subcomposition_root_styled_by_class` and
`deprecated_data_layer`.
`coreSkillContent.test.ts` pinned the literal sentence that made root
`data-start` look required, so it is narrowed to structure plus the regression it
genuinely catches.
Not covered, and flagged in the PR: the media global-vs-local start heuristic in
`runtime/init.ts` is the root cause behind the nested-video defect. Removing it
changes the meaning of existing compositions and needs its own deprecation.
Grouped audio shipped and its three canaries were deleted rather than raised.
Solo and the group meter shipped and were removed in the same week, so the
digest says so. Notes that the v0.8.0 minor bump marks two catalog component
removals rather than the week's headline.
Generated with bun run changelog:weekly, then rewritten for publication.
Every sha was machine-verified: 40 chars, prefix-matched, an ancestor of main,
and inside the 2026-08-17..2026-08-25Z window. npx mint validate passes from docs/.
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
* docs(audio): document the audio effects system
The effects feature had no documentation at all — the only mentions anywhere in
docs/ were changelog entries. This adds the three pages the color-grading feature
already has, one per audience, and closes a gap in the existing audio guide.
- prompting/audio-effects — a new Level 5 chapter on asking for a mix in
symptoms rather than in filters, with the voiceover carve as the headline, the
level-before-depth check, groups, and the three requests that have no honest
answer (de-essing, noise removal, tone matching).
- studio/audio-effects — the rack, presets by symptom, the carve module, groups,
the deliberately asymmetric mute/solo, automation lanes, and troubleshooting.
- reference/audio-effects — the contract: all four attributes, every effect and
parameter range, why some parameters cannot be automated, the 19 presets, the
five jobs and five one-knob profiles, carve semantics, the group model, the
render bus, preview/render parity, and the three lint rules.
Also points the existing "duck music under important speech" advice in
guides/voice-and-audio at the carve, which does that properly and was never
named there.
Facts verified against source rather than the shipped skill prose: the panel
section is "Audio FX" (the neighbouring "Effects" section is visual effects, and
an earlier draft of this page named the wrong one), MAX_AUTOMATION_POINTS is 512,
fromPreset carries a preset id rather than a boolean, the leveller targets the
track's own 80th percentile, group mute reaches the render while solo never
leaves Studio, and the CLI carve currently writes clip ids.
No screenshots in this pass, and no placeholders for them either — the pages
carry concrete markup and tables instead. Screenshots of the rack, the carve
module, and a group row would each earn their place later.
mint validate and mint broken-links both pass.
* docs(audio): give audio its own Studio group, split by task
Review feedback: the audio page did not belong in Studio / Edit. That group is
already one task per page — canvas, timeline, animation, captions — and a single
page covering the rack, the carve, groups, and automation lanes was four tasks
bundled together and dropped in beside them.
Studio now has an Audio group holding four task pages:
- Effects and presets — the rack, presets by symptom, adding single effects in a
working order, the one-knob controls, Even Out Levels
- Voiceover carve — its own page, because it is the feature people come for
- Groups, mute, and solo — including why mute reaches the export and solo cannot
- Automation lanes — drawing envelopes, the shape menu, and which parameters
cannot move at all
Not a new top-level tab: the tabs here are audience-scoped (Guides, Studio,
Catalog, Developers), so a feature tab would be the only one of its kind and
would strand the prompting chapter out of its Level 5 sequence and the reference
page out of Developers.
Repointed the deep link in guides/voice-and-audio at the carve's own page.
Lane interactions verified in source before documenting: the right-click menu
offers Ramp up, Ramp down, Swell, Dip, and Simplify (which needs three points).
Deliberately not documented: "clicking a lane label reveals it in the rack",
which is not on main.
mint validate and mint broken-links both pass.
* docs(audio): fix the four review blockers
All four verified in source before fixing; the review was right on every count.
**The registry was incomplete.** `pitchshift` ships at `audioFx.ts:509-535`
(`semitones` −12–12, `mix` 0–1, worklet-backed so neither automatable) and was
missing entirely — sixteen effects, not fifteen. It also joins the worklet list,
so five effects expose no automatable parameters rather than four.
**Three presets were missing.** `chipmunk`, `giant`, and `monster` ship at
`audioFxPresets.ts:336-357`, all built on `pitchshift`. Twenty-two presets, and
Character holds ten. Fixed in both the reference table and the Studio list.
**The copyable markup contradicted the warning above it.** The page said
`carve.mjs` only finds double-quoted attributes and then gave three
single-quoted examples — copying the chain example would make a later carve miss
the existing chain and overwrite it. All three are now double-quoted with
`"`, each followed by its unescaped reading so it stays legible.
**The attribute table over-claimed.** `data-audio-group` is a plain id, not JSON,
and is ignored on `<video>`; the other three also live on `<hf-audio-group>` for
a group. The table now carries shape and valid host per attribute.
**The automation contract was wrong on two axes.** A clip lane's `t` is
clip-relative but a GROUP lane's is composition time, because a group has no
`data-start` (`webAudioTransport.ts:337-342`, `audioMixer.ts:1311-1344`) — both
pages now split the two clocks. And `volume` is not 0–1: the ceiling is
`MAX_AUDIO_GAIN`, +12 dB or about 3.981 (`audioGain.ts:8-9`), so a boosting lane
is valid and documented.
**Current-main drift.** #3416 is merged, so the CLI now records the voices'
shared group when it is safe and falls back to clip ids when that group contains
the bed or a music/SFX member. Documented, including why neither refusal shows
up on the run that writes it, and rebased onto main.
mint validate and mint broken-links both pass.
* docs(audio): name the real add-menu family, and finish propagating pitchshift
Second review round. All three findings were my own incomplete propagation — I
corrected the reference for `pitchshift` last round and left the reader-facing
pages behind it.
**The add-menu family is `Time`, not `Space`.** `propertyPanelFxAddMenu.tsx:22-28`
labels the four groups Filters / Dynamics / Non-linear / Time, and the time group
holds pitchshift, delay, chorus, phaser, and reverb. The Studio page sent readers
looking for a group that does not exist. It is now a table naming the family and
its contents, and the reference's "Time — space and width" heading is retitled,
since that description stopped covering the family the moment pitch shift joined
it.
Also from the same file: the menu offers the named jobs in place of a bare
`peaking`, because picking `peaking` is picking a machine and leaving the real
decision — which range — for afterwards. Worth saying on the task page.
**Pitch shift was missing from both no-automation lists** that a reader actually
follows — `studio/audio-automation` and, unflagged but the same defect, the
prompting chapter. Five worklet effects in all four places now. Called out
explicitly on the Studio page, because a rising pitch is exactly the thing
someone reaches for a lane to do, and the lane will not report that it cannot.
**Narrowed the group-metadata sentence.** "The other three are JSON, and on a
group they live on `<hf-audio-group>`" swept in `data-fx-carve`, contradicting the
table directly above it. Only `data-fx-chain` and `data-automation` are group
metadata.
mint validate and mint broken-links both pass.
* feat(audio): open the audio FX, group and mute features to everyone
The twelve-PR audio stack landed on main with all three of its canaries still
at 0%, so the FX rack, the group rows, mute and solo are in the build and
reachable by nobody. This removes the gates rather than raising the numbers: a
canary that gates nothing is a branch every future reader has to evaluate.
Gone:
- the `audio-fx-rack`, `audio-track-mute` and `audio-groups` registry entries;
- the five studio gates they fed — the Audio FX section in `PropertyPanelFlat`,
the mute label, the muted strike-through and the solo button in
`TimelineTrackPlainHeader`, and the group-row derivation in
`useTimelineTrackDerivations`. Each feature now renders on its own
precondition (an audio track, a grouped track) exactly as it did for an
enrolled user.
The old test pinned `audio-fx-rack` at 0% and asserted it was registered, which
is the opposite of what should hold now. Replaced with a pin that no
`audio-*` canary exists at all: re-registering one silently re-hides a shipped
feature, and nothing else in the tree would say so. Verified it fails when one
is added back.
The equivalent removal on wa-25-review-fixes (#3363) can no longer land — that
branch is 105 commits and 310 files divergent from main now that the stack has
squash-merged past it.
* docs(audio): retire the last references to the audio canaries
Two leftovers the gate removal did not reach.
`TimelineTrackPlainHeader.tsx` still said "Gated: the relabel ships behind the
canary, unlike the preview fix" above the function that picks Mute vs Hide.
Nothing gates it now, so the comment asserted the opposite of the code.
`docs/weekly-updates.mdx` is published, and it told readers the audio work is
"staged behind a canary at zero percent, so none of it is visible by default"
and to "set `HF_CANARY_AUDIO_FX_RACK=on` to use the rack today". That env var
maps to no registry entry any more, so following the instruction does nothing
at all. The week's record stays — it is a dated entry — but it now says the
rollout completed and that the variable is inert.
* fix(studio): name the mute action per track, and pin the newly-live audio rows
Review findings on the canary removal. All three are in code the 0% gate made
unreachable, so this is the first time any of it runs for a user.
*blocker* — `visibilityButtonLabel`'s audio branch returned "Muted" / "Mute":
the current STATE rather than the action, so nothing told a screen-reader user
that activating an already-muted row would unmute it, and it dropped `suffix`,
so every audio row shared one accessible name. Music plus VO is the ordinary
case, which makes that two identical buttons. Now `Unmute track N` /
`Mute track N`, matching the wording `timelineTrackVisibility` already writes
into undo history for the same click. `showAsMute` also picks the icon, so this
is the control's whole identity, not a tooltip.
Tests, for paths that had never executed enabled — a canary at 0% returns
`out_of_cohort` before bucketing, and studio additionally excludes
`navigator.webdriver`, so no suite could reach them:
- `VisibilityButton` — both audio states, two rows staying distinguishable, the
visual branch unchanged, and the callback still taking the real track key
rather than the display row. Fails on the old label.
- `useTimelineTrackDerivations` — an ungrouped project stays in raw ascending
order with no groups, and an interleaved group's members become contiguous
under an anchor at `memberTracks[0] - 0.5` while the ungrouped track between
them keeps its place. Plus label/volume/mute mirroring and the id fallback.
Also pins the three retired canary names individually rather than by prefix:
`audio-fx-rack` coming back is caught either way, but `fx-rack` escaped a
`startsWith("audio-")` check. The family guard stays alongside it.
* fix(studio): record the row the mute button announced, not a second derivation
Review finding: the header's track number and the undo-history label's are
computed from two different orderings, and un-gating `audio-groups` is what
makes them diverge.
The header's row comes from the group-aware list — `groupTimelineTracks` emits a
synthetic anchor row per group and pulls members contiguous. The history's comes
from `timelineTrackOrder`, a plain ascending sort of element-bearing keys with no
anchors. On the fixture in this PR's own derivation test, grouped order
`[-0.5, 0, 2, 1]` against ascending `[0, 1, 2]`: clicking mute on the group's
first member said "Mute track 2" and recorded "Mute track 1". Off-cohort this
could not happen — the old branch returned raw tracks, so both sides sorted the
same way.
`onToggleTrackHidden` now carries the display row the clicked control rendered,
and `toggleTimelineTrackHidden` prefers it over deriving its own. One number
instead of two derivations, which is what `timelineTrackDisplay`'s "one owner of
what track number does the user see" already promised. The callback still acts on
the real fractional key, so nothing muted the wrong row before or now — only the
announced and recorded row was wrong.
Also pins the rest of the newly-live surface: the solo button's presence and
pressed state, its absence on a visual track, and the strike-through for both a
row's own mute and a group mute (with the title that says which). Three existing
call-site assertions now check the threaded row too.
* fix(catalog): reveal Matrix Decode captions with autoAlpha so the docs preview renders
The demo and snippet flipped word spans with zero-duration display sets,
which the seek-driven docs player never applies after its style restore:
the composition played 8s of black. autoAlpha reveals with the scrambles
as same-length absolute overlays follow the keyframes contract (never
tween display) and survive seeks and loop wraps. Scramble text now
matches each word's length so it decodes in place instead of jumping.
* chore(registry): remove the Checkout Flow component
Owner-directed removal of the checkout-flow catalog item: source,
demo, generated docs page and payload, and its entries in the registry
manifest, catalog index, docs nav, and search vectors. The deletions
are allowlisted in check-no-main-deletions.
* feat(cli): add normalize-audio to match one clip's loudness to another
Measures two authored `<audio>` clips with FFmpeg's integrated EBU R128
loudness and writes the target's matching `data-volume`, leaving the
reference untouched.
The measurement is bounded to the window the composition actually plays.
`data-end` bounds a clip's timeline window just as `data-duration` does, and
`-ss`/`-t` belong before `-i`: after it they bound the OUTPUT, and with
`-f null` there is none, so ebur128 keeps integrating past the clip. On a
fixture whose played window is -61.8 LUFS inside a file that measures -27.9
whole, either mistake reports a loudness the composition never plays and
"corrects" an already-matched clip by tens of dB.
Two EBU R128 passes run between reading the composition and writing it, each
bounded only by a two-minute timeout, and the skill docs tell agents to keep
Studio open meanwhile — so the attribute patch is re-applied to a fresh read
and written through a temp file and a rename.
Under `--json` the failures are documents too: an agent doing
`JSON.parse(stdout)` on a bare error line throws. A pair needing more than the
+12 dB ceiling has a source-file problem rather than a mixer one — mixer gain
raises the noise floor with the signal — so the refusal names the remedy.
* fix(cli): validate --tolerance before paying for the measurement
Each EBU R128 pass is bounded at 120s and normalize-audio runs two, so
parsing the argument afterwards made a typo'd --tolerance cost both of them
before failing on something that was wrong from the start.
Not pinned by a test: the ordering is internal to the command and neither it
nor the parser is exported, so covering it would mean restructuring for a spy
rather than asserting the behaviour.
* docs(cli): restore the blank line between the preview and normalize-audio sections
Lost when I resolved the rebase conflict against the background-preview docs
by hand instead of letting the formatter near it. oxfmt --check failed on the
one file, which fails Preflight — and because preview-parity needs Preflight it
skipped, and the preview-regression gate fails closed on a skip, so a missing
newline read as a preview defect.
The quieter half: the same needs chain meant the required Test context was
never created at that head. Not failing — absent, so there was no test signal
at all on the PR.
`--background` was rejected outside the embedded server. It now re-execs the
CLI in foreground, which makes it mode-agnostic by construction: whichever
server the child resolves to serves the config endpoint the readiness probe
looks for. `--foreground` is its counterpart, for a non-interactive shell that
wants to stay attached, and a bare launch keeps the same promise — attached in
an interactive terminal, managed in an agent session.
That generalization exposed an existing hole. Local-studio mode runs Vite with
the studio package as its cwd and needs that package's own Vite config, which
the published tarball does not carry, but resolving the package was treated as
proof the mode was usable. An npm-installed studio therefore took a path that
can never come up — previously a clear error, now a ten-second silent timeout.
The predicate becomes "can this studio actually be served", so a published
install falls back to embedded mode, which works.
Over the 1k line budget at ~1.3k. The overage is one command file and its
tests carrying one invariant, and the seam that would split it further is
inside a single request-handling function — a split there would produce two
PRs neither of which starts a preview on its own.
* fix(catalog): make component previews answer their variables panel
Every control on a component's catalog page did nothing. Asking
caption-camera-follow for a violet accent rendered gold, and so did green
and blue, on 166 of the 168 components that declare variables.
A component ships a snippet, which is what the page hands you to paste and
which carries the declaration plus the script that turns a chosen value
into a CSS custom property, and a demo.html which stages and animates it.
The preview is built from the demo, and the demo was authored as a copy of
the snippet rather than a reference to it. The copies drifted until almost
none of them carried the declaration or the reader, so the payload for that
page never contained the word violet at all.
Components come in two shapes, so the repair does too.
123 ship a snippet that registers its own paused timeline. That snippet is
a whole piece, so their preview is now built from it and carries markup,
variables and motion together.
45 are markup plus a commented recipe, where the demo owns the motion.
Those demos now carry the snippet's declaration, reader and var-driven CSS
in the registry itself, written by scripts/catalog/sync-demo-variables.ts.
Nothing is patched in at build time.
A test runs that tool in dry mode and fails when a demo has drifted again,
naming the command that repairs it. It also asserts it inspected more than
a hundred components, because a check that silently matches nothing is how
this rotted in the first place.
Measured by rendering every payload in a real player rather than by reading
markup: payloads declaring their variables go from 2 of 168 to 168 of 168,
previews that animate go from 166 to 167, and nothing that moved stopped
moving. ascii-render-pass and star-rating-fill render a still frame when
built from their snippet, so they keep the demo path as a recorded
exception and stay in the state they were already in.
* refactor(catalog): give the preview pipeline one lookup and one entrypoint guard
Follow-up on the same branch, no behaviour change: 42 tests still pass and
`sync-demo-variables --check` still reports all 168 components clean.
The payload generator and the demo sync had each grown their own copy of
"given a component directory, find the snippet and the demo". Both now call
`componentFiles`, which is the same duplication-by-copying that broke the
previews in the first place.
Both catalog generators also carried a byte-identical 12-line guard for
"only run main() when this file is the entrypoint". That clone was already
in the tree, but nothing had touched both files at once before, so it had
never surfaced. It is now `runAsCommand`, and the sync script's variant of
the same condition is `isEntrypoint`.
The rest is flattening: the layering guards read as a table of conditions
instead of a chain, the reporting splits by what it reports, and the entry
resolution comes out of `buildPayload` rather than being spliced into it.
Also runs the formatter over the demos this branch rewrote. Whitespace only,
and `notes-typing` is the only component demo that renders pre-formatted
text, which this does not touch.
* fix(docs): load the player from latest, not a pinned minor
The catalog pages pinned the player CDN URL to a minor line, and that pin
sat one line behind after the last release. Every page kept rendering, on
the older build, so nothing surfaced it: the only symptom was that a fix
published to npm never appeared on the docs.
The generator derived its pin from the player's package.json, which is
correct only if every page is regenerated on the release that moves it.
That is the step that did not happen, and it has to happen across 175
generated pages plus three hand-written files for the pin to be true.
A version carried in step across 178 places will be stale, and stale here
is silent. Ask for latest instead and there is nothing to carry.
This costs the ability to hold the docs back from a bad player release.
Paid deliberately: the pin did not buy that either, it only delayed the
good releases too.
A test asserts no pinned version comes back, and fails if it stops finding
the references at all, so it cannot pass by matching nothing.
* refactor(scripts): list tracked files instead of walking the tree
The pin guard hand-rolled a recursive directory walk with its own skip
list and size cap, which the audit flagged: helpers living in a test file
earn no coverage, so their complexity lands straight on the CRAP score.
git already knows which files to read, and ignores node_modules and build
output for us, so one call replaces the walker and both findings go away.
* docs(changelog): weekly digest 2026-08-10–2026-08-17
Rewritten from `git log --no-merges` grouped by type and scope rather than
polished from the generator draft.
The window overlaps last week's digest. 106 non-merge commits land inside
2026-08-10T00:00:00Z..2026-08-18T00:00:00Z, but five were already published
in the Aug 3-10 entry (#3148, #3149, #3150, #3089, #3151, all dated Aug 10).
Those are excluded by set-subtracting the 109 SHAs that entry cites, so this
covers 101 commits and cites 89 PRs. The release range is corrected the same
way: last week claimed v0.7.90 through v0.7.105, and both the v0.7.104 and
v0.7.105 release commits fall inside this window, so this week is v0.7.106
through v0.7.109.
Verified at HEAD rather than from commit bodies:
- The audio FX rack is behind the `audio-fx-rack` canary at percentage 0 in
canaryRegistry.ts, and the gate site is real: PropertyPanelFlat.tsx reads
isCanaryEnabled("audio-fx-rack"). It is described as staged, not shipped.
The flag gates the authoring surface only, so a composition that already
carries data-fx-chain still plays and renders, and that is stated.
- The video primitive moves were added, reverted twenty minutes later
because their previews did not deploy, then relanded with the workflow
fixed. Only the end state is announced.
- The CLI canary route was added and reverted inside the window, so the
revert is what gets reported.
- The preview volume control landed after v0.7.109, so it is called out as
shipping in the next release rather than as available now.
Every SHA is emitted by a script that refuses to write unless it resolves to
40 chars, prefix-matches its abbreviation, is an ancestor of origin/main,
falls inside the window, and was not cited by the previous digest. Six
negative controls confirm each check rejects, and a positive control confirms
valid input still writes. No SHA was hand-typed.
* docs(changelog): embed the weekly video in the Aug 10-17 digest
45.1s square film built from the changelog-video skill. Uploaded to
static.heygen.ai and the CloudFront path invalidated and verified serving.
* feat(engine): stamp rendered files with hidden renderer provenance
* fix(engine,producer): re-assert provenance at every container writer
Review found that a no-audio MOV render still shipped untagged. The concat
step is the last container write on that path (mux is skipped without audio,
and applyFaststart only copies mov/webm), and the concat demuxer does not
carry the chunks' container metadata through.
The same hole applies to no-audio WebM, and to the in-process chunked encode
in chunkEncoder, not just the distributed assemble path. mp4 was masked
throughout because applyFaststart re-runs ffmpeg for that format and re-tagged
the output.
Tags the four remaining writers: the chunked-encode concat, and assemble's
single-chunk remux, concat and cfr re-encode.
Also corrects the trust claim. These are unsigned, freely writable keys, so a
present tag means the file claims to be HyperFrames output, not that
HyperFrames wrote it. Documented as an unauthenticated diagnostic hint rather
than an authenticity or attribution boundary.
Tests assert on the assembled file through the real assemble() path for both
mov and webm; both fail without the concat fix.
* test(engine): pin provenance through the in-process chunked concat
Review noted the distributed writers are mutation-pinned but the
encodeFramesChunkedConcat fix had no real-file regression of its own.
Encodes 70 frames at a 30-frame chunk size so the concat step actually runs,
then asserts the tags on the resulting no-audio mov. Fails without the concat
fix, passes with it.
* feat(registry): add the notification-cascade block and banner-push-in component
A vertical ad-template block: phone notifications land one after another on a
2.000s beat and stack up the screen, each banner pushing the pile down as it
arrives, before the whole stack lifts away into a closing card carrying the
HyperFrames lockup. Every decisive number - the 214px pitch, the 22px entry
rise, the expo.out restack - is measured from reference footage rather than
invented. The backdrop plate is a generated photograph, shipped with the item.
The banner-push-in component carries the reusable arrival move on its own:
one banner fades in and rises into place while everything already on screen
slides up one pitch in lockstep.
Both pass the full browser gate (runtime, layout, motion, WCAG AA contrast)
installed into a scratch project from a served registry.
* feat(registry): add the share-sheet-carousel block and sheet-spring-up component
A share sheet springs up from the bottom of the phone and cycles photographic
previews inside its card on a fast cut rhythm - fourteen cuts over 7.2s -
while the blurred ground swaps behind it on the same beats, ending on an
accept tap. A brand strip with the HyperFrames lockup rides the bottom of the
preview, as the reference's did. The four stills are generated photographs,
shipped with the item.
The sheet-spring-up component carries the arrival on its own: a real spring
sampled frame by frame from reference footage - up from below, 192px
overshoot, 0.72s settle - shipped as the sampled table rather than an ease
that approximates it.
Both pass the full browser gate (WCAG AA) installed from a served registry.
* feat(registry): add the typing-indicator and streaming-text components
Two chat primitives extracted from reference footage of real conversations.
typing-indicator is the three-dot bubble that says someone is writing: it
pops in at the thread's edge on the measured entry (scale 0.6 to 1, alpha
0.4 to 1, 0.10s power2.out), holds, and vanishes when the message lands. An
optional bounded dot wave is included for compositions that want the dots to
breathe.
streaming-text is not a typewriter: words arrive in the uneven bursts of a
streamed AI answer, on a token rhythm measured word-by-word from the
reference, each word landing grey and inking to full colour over 0.27s. The
GAPS table ships in the integration note and cycles for any word count.
Both demos pass the browser gate.
* feat(registry): add the ai-chat-reveal block
A question is typed on a rising keyboard - measured keystroke rhythm, steady
caret - sent, and answered by an AI that streams its reply word by word:
thinking dot on the measured alpha ramp, tokens arriving in uneven bursts,
a bulleted list, then a cut to a branded closing card.
The typing and streaming schedules are generated at load from the measured
gap tables, so every piece of copy is a variable - question, three answer
paragraphs, three bullets, and the whole closing card - while the rhythm
stays the reference's. Kept at the native 750x1624 capture size so the
measured keyboard geometry stays pixel-true.
Passes the full browser gate (145/145 WCAG AA) installed from a served
registry.
* feat(registry): add the message-thread-reveal block
A full text conversation plays out on a phone: bubbles popping in on their
measured entries, typing indicators holding the beat, a shared link card,
an emoji burst, delivered receipts, the composer typing five messages
keystroke by keystroke - and the whole thread scrolling up beat by beat on
the measured y-choreography until a warm closing card lands.
Every message swap keeps the measured keystroke tables intact: the new copy
is length-matched character for character to the reference's typed lines, so
all 97 typed frames land on their original beats. The footage plate is
replaced by a CSS room-and-phone-body, the link card carries a generated
still, and the closing card is rebuilt around the HyperFrames lockup with
its stars, proof line, and feature icons preserved.
Relates to the thread-message-stack work in #3046: that PR ships a
caller-payload message-stack component; this block is the complete
ad-template film around the same subject. Kept as its own commit so either
can move independently.
Passes the full browser gate (65/65 WCAG AA) installed from a served
registry.
* feat(registry): add the notes-reveal block and line-reveal-list component
A personal note is typed character by character in a notes app - the caret
riding every letter on the measured keystroke frames, the page scrolling up
on the measured settle curves as each line lands - then cuts to a paper card
with a marker headline, a circled word, a ticked checklist, and the video
card. New copy is length-matched line by line to the measured reveal table,
so all 176 keystrokes land on their original frames. The two hand-drawn
faces (Permanent Marker, Courier Prime - both OFL) ship with the item; the
reference's proprietary UI face is replaced by the system stack.
The line-reveal-list component carries the paragraph rhythm on its own:
lines land on the measured writing cadence that slows as the thought gets
heavier - 2.20s, 2.03s, 2.97s, 3.10s, 3.33s, 3.63s - and the page makes room
with the measured scroll-settle table instead of a linear glide.
Both pass the browser gate (366/366 WCAG AA for the block) installed from a
served registry.
* docs(catalog): publish the ten new ad-template items
Regenerated pages, payloads, navigation and the flat index for the five
blocks and five components added in the preceding commits. Every existing
page is untouched: the diff is ten new item pages, their payload assets, and
the two regenerated indexes.
* chore(registry): rebuild the on-device search index for the new items
* style(registry): run oxfmt over the new item sources
The repo-wide format gate covers registry HTML; the staged-file hook did
not reach these. Payloads and pages regenerated to match.
* feat(registry): restage the five component demos as device specimens
The first demos dropped each primitive onto a bare canvas, which stripped
the context the moves were measured in - a dark bubble on a black frame, a
sheet floating in empty gradient. Each demo now plays inside a phone on a
studio ground, in the move's native habitat - lock screen, chat thread,
share sheet, assistant answer, notes page - with a specimen caption naming
the component and its measured numbers. Interiors are authored at 1080x1920
and scaled into the screen, so they reuse the blocks' gate-proven geometry.
Timelines are unchanged. All five pass the browser gate.
* refactor(registry): shelve the five ad-template films as showcases
The video-primitive tag pins an item to the Motion Primitives shelf and
overrides every other grouping rule - right for an atomic move, wrong for a
25-second film. The five ad-template blocks move to the Showcases shelf
(Scenes & demos), where complete scenes live; the primitives shelf keeps
only the moves.
* refactor(registry): retire banner-push-in and line-reveal-list
Reviewed against the shelf they would join and cut as duplicates.
banner-push-in was the thinnest cut against the existing notification
family - notification-stack already owns the arrival-plus-lockstep-shift
move, mirrored. line-reveal-list was pinched from both sides: the existing
line-by-line-slide owns generic staggered lines, and the incoming
notes-typing scene carries the measured writing cadence and scroll-settle
at scene level. Their measured tables live on inside the films they were
extracted from.
* feat(registry): add four scene primitives - the moments, mountable
social-proof-card: the app-store close as one scene - wordmark, five stars,
proof line, three feature icons, CTA capsule - in a quiet stagger. Composes
with, not against, star-rating-fill / testimonial-proof-card / cta-lockup,
which stay the atomic owners of their moves.
marker-checklist-card: a hand-lettered paper card - marker headline, an
ellipse that draws itself around one word, checklist rows whose checks draw
on. The paper-and-marker sibling of mk-specs-list.
chat-thread: a conversation as a scene - measured bubble pop-ins, expo
lockstep shifts, typing dots holding the beat, a media placeholder. Message
content is one variable: heights are measured at mount and the choreography
is generated to fit. Relates to #3046's caller-payload stack; kept
independent.
notes-typing: the notes-app confession - lines typed on the measured human
keystroke rhythm, the caret riding every landed character. The scene
counterpart to typed-prompt's bare prompt line.
All four follow notification-stack's mountable-scene pattern: container
units, theme-contract tokens, one paused timeline registered under the
literal id. All demos pass the browser gate.
* docs(catalog): regenerate for the reshelved films and scene primitives
Ten pages become twelve: the five films move to the Showcases shelf, the
two retired components' pages are gone, and the four scene primitives get
pages under Motion Scenes. Every untouched page is byte-identical.
* feat(registry): bring chat-thread to film fidelity, with a per-message type switch
The scene now carries everything the reference conversation carries: status
bar, back badge, avatar and name pill, bubbles with real iMessage tails, a
Delivered receipt under the last sent bubble, large emoji rows, a media
placeholder, and a link card with title, domain and chevron.
Every message picks its type by prefix, the way marker-highlight picks a
style: recv:/sent: text bubbles, emoji: a large row, img a media
placeholder, card:Title~domain a link card. Heights are still measured at
mount and the choreography generated, so any mix of types fits.
* feat(registry): add chat-message - the atom, with its type as an enum
ONE message arrives on the measured entry, growing from its sender's
corner. The type is a proper enum - Received, Sent, Emoji, Image, Link
card - switched on the catalog page the way marker-highlight switches its
style, with the bubble tail and the Delivered receipt as their own
switches. chat-thread remains the conversation-as-scene built from
arrivals like this one; the pipe grammar belongs at that level, the enum
belongs here. Demo cycles all five types, one at a time, with a type chip
naming each.
* fix(registry): neutral composer placeholder, gsap 3.14.2 pin, exact font licences
Review fixes for #3217:
- Rendered composer placeholder "iMessage" -> "Message" in chat-thread,
its demo, and message-thread-reveal (technique comments stay as provenance)
- notes-reveal now loads gsap@3.14.2 like every other item
- Licence wording names each face: Courier Prime OFL 1.1,
Permanent Marker Apache-2.0 (verified against embedded name-table records)
Mirrored catalog payloads and pages regenerated for the four touched items.
* feat(catalog): put the variables panel back, on payloads
The panel drove its preview by loading an .html from docs/public, a type the
host does not publish, so it showed an empty frame in production and was
parked when the catalog was re-landed.
It now mounts the same JSON payload the plain player uses and re-mounts it as
values change, injecting them as window.__hfVariables into the composition head
before any of its scripts run, which is where the runtime reads overrides from.
Doing it in the markup rather than after load is what stops the composition
initialising with the wrong values first.
172 items with variables get the panel back; the playhead carries across a
change so a tweak mid-shot does not jump back to frame zero.
* fix(docs): drop the unused url form and the needless escapes
* fix(docs): the panel cannot reference a binding beside the export
* feat(catalog): make importing an SVG the obvious move
A reader arrives at this control with a shape, not with path data, and the
panel asked for the coordinates first. Import is now the primary action in a
drop target you can see is a drop target, and the raw path sits behind a
disclosure for anyone who wants it.
* feat(cli): let a fruitless catalog search report the gap
An agent that searches by meaning and finds nothing worth installing knows
something we do not: the name of a move the catalog is missing. There was no
way to tell us, so that knowledge was lost at the end of every run.
hyperframes feedback --search-miss "<query>" --wanted "<the move>" records it.
It carries no rating, so it never lands in the rating metric, and it is a
separate deliberate command rather than something catalog --query does on its
own: plain search still sends nothing, which is what the CLI promises.
--rating stops being required at the arg level, since a miss has no rating to
give. The check moved into the run body, where an absent one is now handled
rather than crashing on undefined.
* feat(cli): carry tuned variable values into the install snippet
Someone who tunes a block on its catalog page had no way to keep those values:
the install command was the same one everybody gets, and the tuning stayed on
the page.
hyperframes add <item> --vars '<json>' now prints a mount element carrying
data-variable-values, so the values land where the block is used.
They ride on the host rather than being written into the installed file. That
keeps the composition on disk byte-identical to the registry's, so a later
reinstall can still tell an edit from an update, and it lets two mounts of the
same block carry different values.
* fix(catalog): serve the item's own directory so runtime paths resolve
Some compositions assemble their asset URLs at run time —
"compositions/components/" + texture + ".png" for the texture masks, a font the
compiler pulled into _remote_media — and no scan of the markup can see a string
that does not exist until a script concatenates it. Those items either rendered
black or were dropped to a video that had never been uploaded.
Each item that needs it now has its prepared directory published, and its
payload carries a <base> pointing at it, so any relative path the composition
invents resolves. caption-texture renders its masks again, and
variable-font-flex has a preview at all for the first time: its MP4 and poster
are both 403.
Both layouts are published, because which one a composition asks for differs
per item, and a directory only earns that if it is under 2 MB. The 12 MB
texture sheet keeps the recorded video it already had.
* fix(catalog): let the variables panel actually drive the composition
Every control on the panel was inert. The values reached the composition and
nothing repainted, because the payload had already been compiled: compiling
inlines a mounted component and resolves its variables into the markup and CSS,
so by the time a reader turns a knob there is nothing left to change.
An item that declares variables now ships uncompiled, keeping the mount the
runtime loads at run time, which is the only state where data-variable-values
still means anything. The component travels inline as a data URI rather than a
sibling file, because .html is the one type the docs host will not publish. The
demo's own pinned values come off, so the reader's choices reach the mount
instead of losing to the values the demo picked to show itself off.
Measured on the rendered frame rather than the DOM: green rgb(98,207,144),
blue rgb(6,6,199), violet rgb(177,147,230), and back to green.
docs/public/catalog drops from 48 MB to 35 MB along the way, since an
uncompiled payload carries far less than an inlined one.
* feat(catalog): keep variable changes in the url
A reader who tuned a piece lost it on reload, and had nothing to send anyone.
The values now live in the query string, scoped by composition id so two links
never read each other,and only the ones that differ from the defaults are
written, so changing one knob gives a short URL rather than every variable
spelled out.
replaceState rather than pushState: dragging a slider should not leave a trail
of history entries. An unreadable value is ignored rather than thrown, so a
truncated or hand-edited link opens the piece at its defaults.
* fix(catalog): only rewrite the url when a value actually changed
* refactor(catalog): memoise the declared defaults on their content
* feat(catalog): offer an install command carrying the tuned values
The Install block is generated before anyone touches a knob, so it can only
ever print the plain command. Someone who spent a minute tuning a piece copied
it and got the defaults back.
The panel now carries its own command in the Snippet tab, with --vars holding
exactly the values that differ. An untouched piece still offers the same short
command, so nothing gets noisier for the common case.
* fix(catalog): a piece with nothing to render is a skip, not a failure
caption-blend-difference is a stylesheet and a paragraph of prose — a class you
add to your own captions, with no standalone scene to show. The generator
treated that as a build failure, so every run ended by reporting something
broken when nothing was.
It now reports the shape it is and keeps its recorded video, which is the only
honest preview such an item has. A genuine render failure still throws.
* fix(catalog): restore variables from the url on a cold load
A shared link opened at the defaults. The first render happens on the server,
where there is no window to read the query string from, and React then hydrates
against that markup and never revisits it — so the values only appeared once you
touched a control.
The URL is read again after mount, which is the first moment it exists. The
value is also escaped once now rather than twice: URLSearchParams already
decodes on the way out, and decoding a second time turned an SVG path full of
percent-escapes into something that no longer parsed, besides doubling the
length of every link.
* fix(catalog): mount the preview with the values a link carried
The frame was built from the declared defaults and the shared values were
posted to it afterwards, which is too late for anything the composition reads
once at init: a path arrived after the mark had already been drawn from the
default one, so a link looked right in the panel and wrong on screen.
* feat(catalog): the install command follows the values you tuned
Copying the Install line gave the plain command back, because that block is
generated before anyone touches a knob and had no way to know what changed. The
tuned command only existed in the panel Snippet tab, which is not where anyone
looks for it.
The line now reads the same query string the panel writes, so the two agree
without either component knowing the other exists, and a shared link carries the
right command too. replaceState fires no event, so the panel announces its own
writes.
* fix(catalog): send a text variable to the preview once it is finished
Every other control in the explorer reports a whole value on every event: a
slider at any position is a position, a swatch is a colour. A text field is
not. Typing v3 into a badge posted v first, so the preview remounted and
rendered a composition built from half a word.
The post now waits while a text field has focus and goes out when the edit is
committed, with Enter or by clicking away. The field itself is unchanged and
still tracks every keystroke.
---------
Co-authored-by: Miguel Angel Simon Sierra <miguelangelsi07@gmail.com>
Miguel Ángel