Skip to content

feat: add templates - #102

Merged
vanceingalls merged 3 commits into
mainfrom
vance/add-templates
Mar 28, 2026
Merged

vanceingalls merged 3 commits into
mainfrom
vance/add-templates

Conversation

@vanceingalls

@vanceingalls vanceingalls commented Mar 27, 2026 •

Copy link
Copy Markdown
Collaborator

What

Adds 4 new composition templates and fixes structural issues across all templates.

New templates

  • decision-tree — animated flowchart with branching paths
  • kinetic-type — bold kinetic typography promo
  • product-promo — multi-scene product showcase with SVG assets (3 scenes)
  • nyt-graph — animated data chart in NYT print editorial style

Fixes across all templates

  • GSAP updated from 3.12.2 → 3.14.2 (all templates, including warm-grain, swiss-grid, vignelli, play-mode)
  • New templates restructured with proper root wrapper div, data-duration, sub-composition refs with data-composition-id / data-width / data-height
  • nyt-chart: replaced ${compId} template literal variables with hardcoded "nyt-chart" string — cheerio's css-what parser crashes on template literals during bundling, causing silent fallback to raw HTML without runtime injection
  • nyt-chart: added DOM readiness retry for dynamically created SVG elements
  • kinetic-type: removed external S3 audio URL
  • All templates: GSAP script loaded in <head> before any scripts reference it

Why

The new templates expand the range of content types available via hyperframes init. The fixes ensure all templates work correctly in the studio preview (bundler inlines sub-compositions and injects the runtime).

Test plan

  • All 4 new templates render in studio preview
  • nyt-graph chart animates bars, line, and labels on playback
  • Existing templates unaffected (GSAP version bump is backwards compatible)
  • hyperframes lint passes on all templates
  • generators.ts updated with new template IDs

- Update GSAP from 3.12.2 to 3.14.2 across all templates
- Fix new template index.html structure: proper root wrapper div
  with data-duration, sub-composition refs with data-composition-id
  and data-width/data-height
- Fix nyt-chart: replace template literal variables with hardcoded
  string in querySelector — cheerio css-what parser crashes on them
- Fix nyt-chart: add DOM readiness check for dynamic SVG elements
- Remove external S3 audio URL from kinetic-type
- Move GSAP script to head before usage in all templates
@vanceingalls
vanceingalls marked this pull request as ready for review March 28, 2026 00:15

@vanceingalls vanceingalls left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review: PR #102 — feat: add templates

Nice set of templates. The GSAP version bump to 3.14.2 across all existing templates is a welcome cleanup, and the new templates show good variety (data viz, kinetic type, product promo, decision tree). A few issues worth addressing:


Critical: composition-id mismatch in product-promo/index.html

The data-composition-id values on the sub-composition refs in index.html do not match the IDs declared inside the actual composition files. The bundler resolves sub-compositions by matching these IDs, so this will break runtime injection.

index.html ref composition file declares
data-composition-id="scene1" data-composition-id="scene1-logo-intro"
data-composition-id="scene2-4" data-composition-id="scene2-4-canvas"
data-composition-id="scene5" data-composition-id="scene5-logo-outro"

The data-composition-id in product-promo/index.html lines 70, 83, and 96 need to match the actual composition files (scene1-logo-intro, scene2-4-canvas, scene5-logo-outro).


Important: unscoped CSS selectors in scene2-4-canvas.html

scene2-4-canvas.html uses bare class selectors like .canvas { ... }, .web-frame { ... }, .cursor { ... } instead of scoping them under [data-composition-id="scene2-4-canvas"]. Every other composition in this PR correctly scopes its styles (decision-tree, nyt-chart, scene1-logo-intro, scene5-logo-outro). When the bundler inlines sub-compositions into the parent document, unscoped selectors will leak and affect elements in other compositions.


Important: null guard missing in decision-tree

In decision_tree.html, the callback at "hold3+=1":

const node = document.querySelector("#node-python");
if (!node.querySelector(".selection-border")) {

If document.querySelector("#node-python") returns null (e.g., template not yet cloned), calling .querySelector on it will throw. The nyt-chart template handles this pattern correctly with a retry guard -- the same approach should be used here, or at minimum add a if (!node) return; guard.


Important: font loading strategy inconsistency in nyt-chart

nyt-chart.html uses display=swap for its Google Fonts link, while all other templates in this PR use display=block. In video rendering, swap can cause a visible flash of unstyled text (FOUT) in the first few frames if the font loads after the first paint. display=block is the correct choice for video compositions since it holds rendering until the font loads.


Minor: decision-tree has "Pythom" as intentional typo

This is clearly intentional (the animation corrects it to "Python"), but it is worth adding an HTML comment near line 83 like <!-- intentional typo: corrected by animation --> so future contributors do not "fix" it.


Minor: SVG assets missing trailing newline

figma-cursors.svg, figma-logo-pieces.svg, and figma-logo-pills.svg are all missing a trailing newline. Minor, but some tools and git diffs get noisy about it.


Observation: kinetic-type references external S3 video

main-graphics.html loads a video from https://gen-os-static.s3.us-east-2.amazonaws.com/.... The PR description says the external audio URL was removed from kinetic-type, but this video URL is still an external dependency. If that S3 bucket gets cleaned up, this template breaks silently. Consider documenting this dependency or bundling a placeholder.


Overall the templates are well-structured, the animation choreography is thoughtful, and the GSAP patterns are clean. The composition-id mismatch in product-promo is the main blocker.

- product-promo: fix composition-id mismatch (scene1 → scene1-logo-intro,
  scene2-4 → scene2-4-canvas, scene5 → scene5-logo-outro)
- decision-tree: add null guards on querySelector calls
- nyt-chart: font display=swap → display=block for deterministic rendering
@vanceingalls
vanceingalls merged commit 476c207 into main Mar 28, 2026
15 checks passed
dahans-msft2 pushed a commit to dahans-msft2/hyperframes that referenced this pull request Aug 6, 2026
## What

Adds 4 new composition templates and fixes structural issues across all templates.

### New templates
- **decision-tree** — animated flowchart with branching paths
- **kinetic-type** — bold kinetic typography promo
- **product-promo** — multi-scene product showcase with SVG assets (3 scenes)
- **nyt-graph** — animated data chart in NYT print editorial style

### Fixes across all templates
- GSAP updated from 3.12.2 → 3.14.2 (all templates, including warm-grain, swiss-grid, vignelli, play-mode)
- New templates restructured with proper root wrapper div, `data-duration`, sub-composition refs with `data-composition-id` / `data-width` / `data-height`
- nyt-chart: replaced `${compId}` template literal variables with hardcoded `"nyt-chart"` string — cheerio's css-what parser crashes on template literals during bundling, causing silent fallback to raw HTML without runtime injection
- nyt-chart: added DOM readiness retry for dynamically created SVG elements
- kinetic-type: removed external S3 audio URL
- All templates: GSAP script loaded in `<head>` before any scripts reference it

## Why

The new templates expand the range of content types available via `hyperframes init`. The fixes ensure all templates work correctly in the studio preview (bundler inlines sub-compositions and injects the runtime).

## Test plan

- [x] All 4 new templates render in studio preview
- [x] nyt-graph chart animates bars, line, and labels on playback
- [x] Existing templates unaffected (GSAP version bump is backwards compatible)
- [x] `hyperframes lint` passes on all templates
- [x] `generators.ts` updated with new template IDs
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants