mirror of https://github.com/heygen-com/hyperframes.git synced 2026-09-01 19:42:03 +00:00

Files

T

Miguel Ángel b2fc18b2df fix(skills,lint): correct composition-contract claims the code contradicts (#3468 )

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.

2026-08-24 18:04:39 -04:00

2.5 KiB

Raw Permalink Blame History

Minimal Composition

The smallest renderable HyperFrames composition — a standalone (top-level) root with one clip and one tween:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=1920, height=1080" />
    <title>Minimal HyperFrames Composition</title>
    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
    <style>
      body {
        margin: 0;
        background: #0b0f14;
        color: white;
        font-family: Inter, system-ui, sans-serif;
      }
      #root {
        position: relative;
        width: 1920px;
        height: 1080px;
        overflow: hidden;
      }
      .clip {
        position: absolute;
        inset: 0;
        display: grid;
        place-items: center;
      }
      h1 {
        margin: 0;
        font-size: 96px;
      }
    </style>
  </head>
  <body>
    <div
      id="root"
      data-composition-id="main"
      data-start="0"
      data-width="1920"
      data-height="1080"
      data-duration="5"
    >
      <section id="title-card" class="clip" data-start="0" data-duration="5">
        <h1 id="title">Hello HyperFrames</h1>
      </section>
    </div>
    <script>
      const tl = gsap.timeline({ paused: true });
      tl.from("#title", { y: 48, opacity: 0, duration: 0.6, ease: "power3.out" }, 0.2);
      window.__timelines["main"] = tl;
    </script>
  </body>
</html>

What the runtime actually requires:

Root <div> with data-composition-id, data-width, data-height. Root data-start="0" is written above by convention and every shipped block has it, but the runtime stamps it when absent, so it is not required.
A duration source: root data-duration (as above), or a GSAP timeline, or media, or an adapter that can infer one.
Timed elements carry data-start plus a duration. That attribute alone is what makes an element a clip: class="clip" is a layout and tooling convention, and data-track-index is a Studio display lane. Neither is required, and a composition with no clips at all renders fine.
A GSAP timeline created paused and registered on window.__timelines["<composition-id>"].

Everything else in the skeleton is ordinary HTML and CSS: the #root box, .clip positioning, and fonts are yours to choose.

This pattern is standalone (top-level index.html) — no <template> wrapper around the root. For sub-compositions (files loaded by data-composition-src), see sub-compositions.md.

2.5 KiB Raw Permalink Blame History

Minimal Composition

2.5 KiB

Raw Permalink Blame History