Files
WaterrrForeverandClaude Opus 5.5 d4e4b07e3c fix(cli): a wedged render trips its 60 s watchdog, one local render at a time, and fonts the cloud can't resolve are flagged (#7168)
* fix(producer): a wedged effect scan or screenshot-session open trips the 60 s stall watchdog

The sequential streaming watchdog raced only the capture call. Session init
(where the fast-capture effect scan runs) and opening the screenshot session
for effect frames waited on CDP's protocol timeout instead, which scales with
output area up to 30 minutes, so a starved page hung a render for ~25 minutes
before the watchdog saw the next frame. The effect scan now gives up when a
chunk outlasts its 120 s budget, opening the effect-frame session gets its own
no-progress window, and session init gets a 300 s one; each trip retries on a
fresh session like any other stall.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(cli): one local render at a time per machine; a second waits and says for whom

Renders started side by side from different sessions starve each other until
frames stop landing. `hyperframes render` now takes a machine-wide slot (a lock
file in the HyperFrames cache directory, held by pid) after its preflight and
holds it for the render or the whole batch. A second render waits and prints
the pid and project it is waiting behind; `--no-wait` fails at once instead.
A holder whose process is gone is taken over, and HYPERFRAMES_RENDER_LOCK=off
restores side-by-side renders. `--workers` is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(lint): flag fonts a cloud render cannot resolve, including the font shorthand

Lint read only `font-family`, so `font: 500 16px "PingFang SC", sans-serif`
passed while the renderer, which reads the shorthand too, drew the installed
Mac font locally and the cloud refused it. The shorthand now counts for
font_family_without_font_face (its parser moves to @hyperframes/parsers so
core and lint share one), and a new font_face_local_only warning names an
@font-face whose only sources are local(): it renders here and falls back in
the cloud. The rule's hint and the format reference stop recommending local()
for OS fonts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli): a cloud render that refuses a font says which project files use it

The cloud's "fonts that could not be resolved: PingFang SC" named no
composition. For a render submitted from a local project, the failure now
lists each refused family with the project files that name it, and says how
to ship the font so the cloud can use it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(cli): keep comment shares and exports within the gates, and split the single-render notes out of executeHeldRender

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(parsers): read a spaced line-height slash and var() before the size in the font shorthand

`font: 16px / 1.5 Inter` was read as the family `/ 1.5 Inter`, and
`font: var(--weight) 16px Inter` as `16px Inter`, because a var() counted as
the size. The parser now follows the shorthand grammar: optional style,
variant, weight and width keywords (or var()), then a length, percentage,
keyword or calc() size, then a `/ line-height` in any spacing. When no size can
be told apart from a var(), it says so: lint skips that declaration instead of
reporting a missing font, and the renderer keeps its best guess.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli): say the render slot is one per user account, not per machine

The lock lives in the account's HyperFrames cache folder, so renders by two
user accounts never queued behind each other while the messages, flag help and
docs said "this machine". They now say "per user account" and that
HYPERFRAMES_CACHE_DIR set to a shared folder shares the slot across accounts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli): reclaim a render lock or takeover file left half-written

A lock or `.break` file that exists but cannot be parsed (a crash mid-write
where hard links are unavailable) was never reclaimed: a waiting render waited
forever and --no-wait refused forever. Once such a file is older than any real
write (5 s by mtime) it counts as abandoned: the lock goes through the same
`.break` takeover as a dead holder's, and a takeover file is removed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(producer): opening the capture session counts against the setup stall budget

The sequential streaming attempt opened its own capture session (Chrome launch
and new page) before the setup watchdog and outside the attempt's cleanup, so a
wedged launch still waited for the protocol timeout. Opening now shares the
300 s setup window with session initialisation, a trip fails the attempt like
any other sequential stall, and a session that finishes opening after its
attempt gave up is closed instead of leaking a browser.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(parsers): keep the shorthand result type module-private

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli): reclaim an unreadable render lock only when its writer is provably gone

Where hard links are unavailable the lock is created by an exclusive open and
then written, so a contender paused between the two leaves an unreadable lock
while it is still alive. The 5 s mtime grace took such a lock over, and both
processes then held the slot. Each contender now writes an owner marker under
a name only it can take (pid plus random suffix, holding its process identity)
before it creates the lock, keeps it while it holds the slot, and removes it
otherwise. An unreadable lock or `.break` is reclaimed only when no other
contender's marker belongs to a live process; markers of dead processes, or of
a reused pid, are deleted. No reclaim is decided by time alone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* refactor: split acquireRenderLock and the streaming-stage session stub under the complexity gate

acquireRenderLock hands contender setup and a single marked claim to their own
functions, and the test stub for createCaptureSession splits its held-open
cases from the fake session it builds, so neither exceeds Fallow's cognitive
or CRAP thresholds. Behaviour is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(ci): raise the CLI and engine size budgets for the watchdog, lock and font-lint additions

Main's CLI unpacked size was already ~0.99% over its budget; the render lock and
owner markers push it past the 1% tolerance. The CLI unpacked budget takes the same
value as #7169 and #7170 (25,159,107) so the PRs merge cleanly. The engine's packed
size grows by about 4.7 KB for the effect-scan and session-open watchdogs; its packed
budget moves to 5% above the measured 467,097, as the budget file's headroom rule sets it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(parsers): a var() size glued to its line height is the shorthand's size

`font: 700 var(--size)/1.1 "Inter"` read as no family at all: the token was
tested whole against var(), and the slash after it hid that it was the size,
so the renderer injected no face for Inter. A var() followed by `/ line-height`
(glued or spaced) can only be the size, and is now read as one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* refactor(parsers): split the shorthand size search out of parseFontShorthand

Keeps parseFontShorthand under Fallow's cognitive-complexity gate; behaviour is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli): render lock never removes another render's takeover, knows a reused pid, works in a shared folder and on Windows

- A `.break` takeover file is removed only by the render that wrote it. One
  whose writer is gone stops the render with the file to delete, instead of
  being removed on an earlier reading, which could remove a live `.break`
  written since and let two renders hold the slot. The takeover re-reads the
  lock under its own `.break` right before replacing it.
- The lock record keeps its holder's process start time, so a pid that now
  belongs to another process (an OOM-killed render in a container with a
  persisted cache) no longer holds the slot forever.
- The `locks` folder is created writable for every account, so accounts
  sharing HYPERFRAMES_CACHE_DIR take turns instead of the second failing with
  EACCES; a folder this account cannot write in says how to fix it, and
  another account's file that cannot be removed is left, not fatal.
- Windows: no PowerShell start-time lookup per check (pid liveness only), a
  file another handle holds (EPERM/EBUSY/EACCES) reads as held, a lock that
  vanished is retried once instead of in a tight loop, and a wait stops when
  its signal aborts. The tests end every acquire they start before removing
  their folder, and the paused contender writes through its open descriptor.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(ci): raise the lint packed size budget for the font-shorthand rule

With main's audio-attribute rule (#7169) merged in, the font-shorthand and
local()-only font findings take @hyperframes/lint's packed tarball to
181925 bytes, over the 179338 budget. The new budget is that measurement
plus the usual 5% headroom.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 18:41:56 +00:00

13 KiB
Raw Permalink Blame History

Composition format

The detail behind the contract in SKILL.md. Full references: npx hyperframes docs compositions, docs data-attributes, docs troubleshooting.

Shape of a project

<!-- index.html: a normal document; declares variables, mounts scenes -->
<html
  data-composition-variables='[{"id":"headline","type":"string","label":"Headline","default":"…"}]'
>
  <body>
    <div
      id="root"
      data-composition-id="main"
      data-start="0"
      data-duration="12"
      data-width="1920"
      data-height="1080"
    >
      <div
        id="intro"
        data-composition-id="intro"
        data-composition-src="compositions/intro.html"
        data-start="0"
        data-duration="4"
        data-track-index="1"
        data-width="1920"
        data-height="1080"
      ></div>
    </div>
    <script>
      window.__timelines["main"] = gsap.timeline({ paused: true });
    </script>
  </body>
</html>
<!-- compositions/intro.html: everything inside <template> -->
<template>
  <style>
    #root {
      position: absolute;
      inset: 0;
    }
  </style>
  <div id="root" data-composition-id="intro" data-width="1920" data-height="1080">
    <h1 id="headline" class="clip" data-start="0.4" data-duration="3" data-var-text="headline">
      …
    </h1>
  </div>
  <script>
    const tl = gsap.timeline({ paused: true });
    tl.fromTo(
      "#headline",
      { opacity: 0, filter: "blur(8px)" },
      { opacity: 1, filter: "blur(0px)", duration: 0.18, ease: "power4.out" },
      0.4,
    );
    window.__timelines["intro"] = tl;
  </script>
</template>
  • Give the host, the scene root and the timeline key the same id. A host id that differs from its scene's makes each render wait 45 s per scene, then show static frames. Styles and scripts outside <template> are dropped.
  • Size the scene root with inset: 0, never hard-coded pixels; the canvas is data-width × data-height.
  • Keep ids unique across the assembled page (prefix them: #intro-title). A scene's timeline can't reach elements outside its file.
  • Use fromTo, not from, inside a scene: the host re-seeks the scene each time it shows, and from records its start state once, so it drifts on seek-back.
  • Never add() a scene's timeline to the root's; the runtime drives each scene itself, and nesting seeks it twice.

Attributes you'll use most

Attribute Meaning
data-start, data-duration Seconds, local to the file that declares the element
data-track-index Studio lane only; paint order is CSS z-index
data-track-kind graphics or captions on scene hosts (video and audio come from the tag)
data-composition-src, data-variable-values Mount a scene file; per-mount variable values (a JSON object)
data-media-start Offset into the source media (a trim)
data-playback-rate Constant speed, 0.1–10
data-has-audio="true" A <video> keeps its own sound; a timed <video> with neither this nor muted fails lint
data-volume, data-fade-in, data-fade-out Gain (1 = 0 dB, up to 3.98 = +12 dB) and edge fades; envelopes use data-automation (/media-use)
data-link, data-sync-origin A video and audio edited as one (see Linked clips)
data-hidden Hidden in preview and render; reversible
data-no-timeline On the root of a still composition: no timeline to wait for

Variables

  • Declare an array of {id, type, label, default}: the video's own on index.html's <html>, a scene or block file's on that file's <html> (or root element), where they stay inside each mount. Types: string (placeholder, maxLength), number (min, max, step, unit), color, boolean, enum (options: [{value, label}]).
  • Bind without script: data-var-text="id", data-var-src="id" (keep a real fallback src on media with audio), var(--id) in CSS; for logic, window.__hyperframes.getVariables() once at init.
  • Values are an object keyed by id. A host's data-variable-values sets one mount; Studio's Variables panel and batch renders set only the root's variables, so to vary a block, change its host's values. Variables can't change the root's data-duration.

Fonts

  • Bundled, so they resolve by name: Inter, Montserrat, Outfit, Nunito, Oswald, League Gothic, Archivo Black, Space Mono, IBM Plex Mono, JetBrains Mono, EB Garamond, Playfair Display, Source Code Pro, Noto Sans JP, Roboto, Open Sans, Lato, Poppins. Common system fonts (Helvetica, Arial, Times, Menlo and the like) are swapped for the nearest of these.
  • The bundle only has Latin text at a few weights per family (Inter: 400, 700, 900). The compiler still fetches each of these families from Google Fonts for the other weights and scripts, and caches the result in ~/.cache/hyperframes/fonts.
  • Any other family needs @font-face in the file that uses it, or lint fails font_family_without_font_face: src: url('assets/fonts/x.woff2') for a file in the project (a capture's own fonts, or one you download there), A local('Exact Name')-only face draws the font installed on this machine; a cloud render has no copy of it (lint warns font_face_local_only), so ship the file instead when the video may render in the cloud.

Timing and the timeline

  • A clip shows over [start, start + duration): an end state landing exactly on its end is never rendered.
  • Only a composition's root timeline is paused; timelines nested inside it are not. Never tl.play().
  • A scene's clock starts at 0 at its host's data-start; media data-start is local to its composition. <video> / <audio> without data-duration play their full length; an <img> without one lasts 3 s.
  • A host's data-duration is the scene's slot: a shorter scene timeline holds its last frame, and a slot shorter than the video goes blank when it ends.
  • Root children with data-start are laid out full-frame by the runtime; an untimed full-bleed background needs position: absolute; inset: 0 or it collapses to nothing.
  • A fill on the composition root is dropped when the video has shader transitions or HDR media; put it on a full-bleed child.
  • data-start="intro + 0.5" starts after intro ends (spaces required). A typo, a missing id or a cycle silently resolves to 0, so snapshot what you time this way.
  • A clip nested inside another timed element counts its data-start from the composition, not from that element, and shows only while that element shows. timeline lists it under its parent and warns never visible when the windows miss (lint: nested_clip_never_visible).
  • npx hyperframes timeline --json lists every clip by kind with absStart, absEnd, file, src, playbackRate, nested, host and durationSource: read it instead of opening every file. It reads one level of nesting (a deeper scene shows children=unread); laneError means a data-automation or data-fx-chain that doesn't parse.

Adding media

Write what a Studio drop writes, so the clip behaves like one the person dropped:

  • id, class="clip", data-start (the playhead or the requested time, never a silent 0) and data-track-index. Video with sound: playsinline data-has-audio="true"; silent footage: muted playsinline. Audio: data-volume="1".
  • Images and video fill the frame: position: absolute; left: 0; top: 0, width and height equal to the canvas, object-fit: contain.
  • z-index is the number of top-level clips already in that file plus one.
  • Raise the root's data-duration to cover the new clip's end, or it never plays.

Linked clips

Studio's Detach audio writes a muted <video> and an <audio> of the same file sharing data-link and data-sync-origin; Studio moves, trims, splits and deletes them as one.

  • Prefer one <video data-has-audio="true">; link only when the sound needs its own track, volume or effects.
  • Every member keeps the same data-start, data-duration, data-media-start and data-playback-rate; retime them all together.
  • Unlink by removing data-link from every member. Leave data-sync-origin alone while they are still one source.

Layout audit opt-outs

check measures boxes at sampled times; overflow: hidden does not silence a finding. Use the narrowest opt-out:

Attribute Silences
data-layout-allow-overflow Overflow on the element and every descendant, including text-clipping checks: keep it on the smallest decorative wrapper
data-layout-bleed="true" One intentional crop of primary text
data-layout-allow-overlap Deliberate text layering, on that block only (not inherited)
data-layout-allow-occlusion An element meant to cover text
data-layout-allow-caption-zone Intentional copy in the caption band
data-layout-ignore A decorative element never audited

Lint errors you'll meet first

Rule Fix
video_missing_muted A timed <video> gets data-has-audio="true" or muted
gsap_css_transform_conflict Set the start inside the tween (gsap.fromTo) instead of a CSS transform
gsap_animates_clip_element Animate a child of the .clip, or its opacity
video_nested_in_timed_element Time the <video> or its wrapper, not both
media_missing_id, media_crossorigin_breaks_preview Give every <audio> an id; drop crossorigin
gsap_timeline_registered_before_async_build Register the timeline at the end of the async callback
standalone_composition_wrapped_in_template Only scene files use <template>
subcomposition_linked_style_names_root_id A linked sheet cannot style a scene's root by id: use an inline <style>, or select a child
subcomposition_root_styled_by_class Style a scene's root as #root
subcomposition_blanks_before_host Make the scene's slot span the time it should show
clip_ends_past_root_duration Raise the root's data-duration
linked_clips_out_of_sync, linked_clip_orphan Retime every linked member together; unlink from all of them
sweep_static A 3 s+ video with no visible change: spread the motion, or mark a still composition data-no-timeline
missing_data_no_timeline A root or host with no timeline: add data-no-timeline, or every render waits 45 s