Skill Tracer
Skills › HyperFrames › hyperframes-registry › wiring-blocks.md

wiring-blocks.md

61 lines · skills/hyperframes-registry/references/wiring-blocks.md at a595755

Open on GitHub
1# Wiring Blocks
2
3Blocks are standalone compositions with their own `data-composition-id`, dimensions, duration, and GSAP timeline. Include them in a host composition using `data-composition-src` on a `<div>`.
4

Wiring Blocks

Blocks are standalone compositions with their own data-composition-id, dimensions, duration, and GSAP timeline. Include them in a host composition using data-composition-src on a <div>.

Raw lines 1 to 4
5## Basic wiring
6
7After `hyperframes add data-chart`, wire it into your `index.html`:
8
9```html
10<div id="stage" data-composition-id="main" data-width="1920" data-height="1080" data-duration="20">
11 <video id="a-roll" src="video.mp4" data-start="0" data-duration="20" data-track-index="0"></video>
13 <!-- Block: appears at 2s, plays for 15s, on layer 1 -->
14 <div
15 data-composition-id="data-chart"
16 data-composition-src="compositions/data-chart.html"
17 data-start="2"
18 data-duration="15"
19 data-track-index="1"
20 data-width="1920"
21 data-height="1080"
22 ></div>
23</div>
24```

Basic wiring

After hyperframes add data-chart, wire it into your index.html:

<div id="stage" data-composition-id="main" data-width="1920" data-height="1080" data-duration="20">
  <video id="a-roll" src="video.mp4" data-start="0" data-duration="20" data-track-index="0"></video>

  <!-- Block: appears at 2s, plays for 15s, on layer 1 -->
  <div
    data-composition-id="data-chart"
    data-composition-src="compositions/data-chart.html"
    data-start="2"
    data-duration="15"
    data-track-index="1"
    data-width="1920"
    data-height="1080"
  ></div>
</div>
Raw lines 5 to 25
26## Required attributes
28| Attribute | Description |
29| ---------------------- | -------------------------------------------------------------------- |
30| `data-composition-src` | Path to the block HTML file (relative to index.html) |
31| `data-composition-id` | Unique ID matching the block's internal composition ID |
32| `data-start` | When the block appears in the host timeline (seconds) |
33| `data-duration` | How long the block plays (seconds, at most the block's own duration) |
34| `data-track-index` | Layer ordering — higher numbers render in front |
35| `data-width` | Block canvas width (match the block's dimensions) |
36| `data-height` | Block canvas height (match the block's dimensions) |

Required attributes

AttributeDescription
data-composition-srcPath to the block HTML file (relative to index.html)
data-composition-idUnique ID matching the block's internal composition ID
data-startWhen the block appears in the host timeline (seconds)
data-durationHow long the block plays (seconds, at most the block's own duration)
data-track-indexLayer ordering — higher numbers render in front
data-widthBlock canvas width (match the block's dimensions)
data-heightBlock canvas height (match the block's dimensions)
Raw lines 26 to 37
38## Timeline coordination
40The block's internal GSAP timeline runs independently from the host timeline. The HyperFrames runtime loads the sub-composition, finds its `window.__timelines` registration, and seeks the block in sync with the host, offset by `data-start`. You do NOT need to reference the block's timeline in your host's GSAP code.

Timeline coordination

The block's internal GSAP timeline runs independently from the host timeline. The HyperFrames runtime loads the sub-composition, finds its window.__timelines registration, and seeks the block in sync with the host, offset by data-start. You do NOT need to reference the block's timeline in your host's GSAP code.

Raw lines 38 to 41
42## Positioning blocks
44To position a block in a specific area of the screen, add CSS:
46```html
47<div
48 data-composition-id="data-chart"
49 data-composition-src="compositions/data-chart.html"
50 data-start="2"
51 data-duration="15"
52 data-track-index="1"
53 data-width="1920"
54 data-height="1080"
55 style="position: absolute; right: 0; top: 0; width: 40%; height: 100%;"
56></div>
57```

Positioning blocks

To position a block in a specific area of the screen, add CSS:

<div
  data-composition-id="data-chart"
  data-composition-src="compositions/data-chart.html"
  data-start="2"
  data-duration="15"
  data-track-index="1"
  data-width="1920"
  data-height="1080"
  style="position: absolute; right: 0; top: 0; width: 40%; height: 100%;"
></div>
Raw lines 42 to 58
59## Multiple blocks
61Add additional `<div data-composition-src="...">` siblings with non-overlapping or overlapping `data-start` values — each block's timeline is independent and seeked in sync by the runtime.

Multiple blocks

Add additional <div data-composition-src="..."> siblings with non-overlapping or overlapping data-start values — each block's timeline is independent and seeked in sync by the runtime.

Raw lines 59 to 61