Implementation mirror · source-first

Video primitives without a ceiling.

The installed HTML, CSS, and JavaScript are the interface. Structured inputs accelerate creation without limiting it.

Open canonical HeyGenVerse design See the implementation contract

Source of truth: the HeyGenVerse artifact. This repository HTML is a versioned implementation mirror. It must follow that design while translating it into buildable contracts, tests, and release slices.

thread-message-stack.html Live source preview
Launch room20 messages

Source owns the experience.

The contract adds an optional data seam. It does not create a new abstraction layer between creators and the browser.

One HTML file, two ways to customize

Agents can replace structured data quickly, then edit any source line when the desired result exceeds the declared inputs. 

<script type="application/json" data-hf-primitive-data>
{
  "messages": [
    { "side": "out", "text": "Ship the new primitive?" },
    { "side": "in",  "text": "Make it twenty messages." }
  ],
  "timing": { "stagger": 0.42, "hold": 0.8 }
}
</script>

<style>/* Every selector stays editable. */</style>
<div class="thread"></div>
<script>/* Every render and motion rule stays editable. */</script>

The user journey stays short.

Smart discovery can drive HeyGen authentication, then return users to the exact primitive and query they selected.

Mermaid source 
flowchart LR
  A[Describe 20-message thread] --> B[Smart catalog discovery]
  B --> C[HeyGen OAuth when selected]
  C --> D[Install full HTML source]
  D --> E[Materialize JSON data]
  E --> F[Edit HTML, CSS, and JavaScript]
  F --> G[Existing lint, check, preview, render]

Adapt the current 25 primitives.

Keep their authored motion. Replace hardcoded content with data seams only where repetition or external content needs it.

Conversation and ordered lists

Thread Message Stack, Rank List Settle, Pill Row Collapse, State Chip Rail

Hardcoded rows and fixed count→items[] plus authored layout and timing

Repeatable cards and personas

Persona Card Fan, Plan Room Audit

Fixed card markup→cards[] plus an editable card template

Copy-led compositions

Kinetic Type Swap, Version Plate Type, Marker Highlight, Caliper Caption Rail, Caption Camera Follow

Text embedded in markup→Existing scalar variables plus open source

Cards with business data

Receipt Card, Chevron Pill Card Morph, Grade Split Reveal

Fixed fields and labels→fields{}, scalar controls, editable markup

2D visual effects

Echo Trail, Halftone Dissolve, Particle Text Dissolve, Press Ripple, Whiteboard Ink

Authored effect constants→Optional parameters, source remains canonical

Transitions and match cuts

Match Cut

Fixed transition target→Named source and destination slots in HTML

Camera and focus

Depth Rack Focus, Focus Rack, Orbit Ring Camera

Fixed media and camera path→Media references plus editable camera code

Spatial assembly

Glyph Ring Assemble, Z Punch Through

Fixed objects and depth→Object data plus direct scene graph editing

First build: Thread Message Stack.

Prove the source-first contract with one collection primitive before generalizing anything. The shipping artifact remains one copied HTML file.

Implementation slice

  • Keep the current bubble markup, layout, GSAP timing, and visual defaults.
  • Replace the fixed message nodes with one messages[] JSON seam and a small local render loop.
  • Let the installer replace only that JSON block when structured message data is supplied.
  • Copy the whole HTML file into the project so every selector, keyframe, and script remains editable.
  • Use the existing CLI authentication, catalog install, preview, lint, check, and render paths.

Explicit cut line

  • No new component runtime or package dependency.
  • No universal primitive schema or shared slot protocol.
  • No nested array editor in Studio.
  • No migration of the other 24 primitives in this release.
  • No promise that every future primitive uses the same JSON shape.

Thin file contract

<script type="application/json" data-hf-primitive-data>
{
  "messages": [
    { "side": "out", "text": "Message 01" },
    { "side": "in",  "text": "Message 02" }
    // ...up to the requested 20, or any authored count
  ],
  "timing": { "stagger": 0.42, "hold": 0.8 }
}
</script>
Mermaid source 
sequenceDiagram
  participant U as User or agent
  participant C as Smart catalog
  participant I as CLI installer
  participant H as Installed HTML
  U->>C: Find an iMessage primitive for 20 messages
  C-->>U: Select Thread Message Stack
  U->>C: Complete HeyGen OAuth if needed
  C->>I: Resume selection with original query
  I->>H: Copy source and materialize messages[]
  H-->>U: Preview all 20; source stays editable

First-migration acceptance

The same primitive renders 1, 6, and 20 ordered messages without clipping or silent truncation; the installer changes only the embedded data block; existing local source edits remain possible; and the project still passes the current HyperFrames lint, check, preview, and render workflow. Primitive two starts only after this journey is measured.

PostHog is part of the product contract.

The first primitive is not complete unless the acquisition and activation journey is observable from anonymous discovery through authenticated render. Track the funnel without collecting authored content.

Required funnel events

  • primitive_catalog_searched — a catalog query returns results.
  • primitive_catalog_result_selected — a user chooses a primitive and rank is recorded.
  • primitive_auth_started and primitive_auth_completed — OAuth begins and the suspended install resumes.
  • primitive_install_started and primitive_install_completed — source is materialized into the project.
  • primitive_preview_succeeded — the installed primitive first renders locally.
  • primitive_render_succeeded — the first final render completes.
  • Matching *_failed events use a bounded error_code, never raw exception text.

Identity and privacy boundary

  • Create one funnel_id before search and preserve it across OAuth, resume, retries, and install.
  • Use the anonymous CLI installation identity before auth; on OAuth success, identify the HeyGen user and alias the anonymous journey once.
  • Attach primitive_id, catalog_version, result rank, CLI version, duration, auth state, and a deduping event or install id.
  • Never send the raw query, message text, HTML, CSS, JavaScript, asset URLs, credentials, tokens, or rendered media.
  • Honor the existing telemetry opt-out and keep event names and properties versioned and documented.

Activation funnel

catalog searched
  → result selected
  → OAuth completed
  → install completed
  → first preview
  → first render

Measurement acceptance

A test journey that searches anonymously, authenticates, resumes the same selection, installs, previews, and renders must produce one ordered funnel with a stable funnel_id, correctly stitched identities, no duplicate success events, and no user-authored content in any PostHog payload.

Start with one thin seam.

The first implementation proves arbitrary collections without changing the core renderer or building a universal visual schema.

Ship first

  • Convert Thread Message Stack from six hardcoded bubbles to an arbitrary JSON message array.
  • Let catalog install materialize user data into the copied source file.
  • Keep existing scalar variables for common Studio controls.
  • Preserve the current HyperFrames runtime, GSAP contract, lint, check, and render path.
  • Ship and verify the PostHog journey from anonymous catalog search through authenticated first render.

Do not build yet

  • A new universal component runtime.
  • A nested object and array editor in Studio.
  • A no-code scene graph that models every HTML and CSS capability.
  • A slot protocol shared by every primitive before two real migrations need it.
  • A compatibility layer that hides or wraps the installed source.

Acceptance example A1

A user asks for 20 messages. The installed primitive renders all 20 in authored sequence, then the user can change any bubble, selector, keyframe, or script directly without ejecting from a framework.