Skip to content

feat(cli): add thread message stack - #3046

Closed
miguel-heygen wants to merge 7 commits into
mainfrom
feat/thread-message-stack
Closed

miguel-heygen wants to merge 7 commits into
mainfrom
feat/thread-message-stack

Conversation

@miguel-heygen

@miguel-heygen miguel-heygen commented Aug 5, 2026 •

Copy link
Copy Markdown
Collaborator

What

Adds the thread-message-stack registry block together with the CLI machinery it needs: a bounded caller-payload validator that materializes the block at install time, an OAuth-only install gate, a resumable install intent that survives the browser round-trip, and a privacy-safe funnel that spans catalog, auth, install, preview, and render.

Supersedes the closed mirror attempt in #3035.

Why

Every existing registry block ships fixed content, so hyperframes add only ever had to copy files. This block's content comes from the caller, which opens three holes the current add path cannot cover:

  1. No way to prove which upstream catalog artifact and version an installed copy came from.
  2. No way to refuse an install that is backed only by an API key, where a real account session is required.
  3. No way to finish an install that was interrupted mid-flow while the user completed OAuth in a browser, without either losing the intent or replaying it twice.

The block is the vehicle. The install path is the actual change.

How

  • Materialization is one function. packages/cli/src/registry/threadMessageStack.ts validates the entire payload before touching a file: at most 100 messages, text at most 8192 chars, sender at most 256, side restricted to incoming / outgoing, and stagger / hold finite numbers in 0 to 60. Only then does it rewrite the single data-hf-primitive-data island in the block HTML. Validate-then-mutate means a rejected payload can never leave a half-written file behind.
  • Install authorization is its own boundary. threadMessageStackAuthorization.ts requires a persisted OAuth credential and verifies it against the current-user endpoint. Environment and file API keys deliberately do not satisfy it, and the outcome is a closed set (authorized / api-key-only / cancelled / failed) so callers cannot treat an ambiguous result as success.
  • Install intent is durable and claimed once. commands/catalog-resume.ts persists a versioned record (item, artifact, version, funnel and install ids, status) through an atomic temp-file plus rename, with an explicit claim, so an install interrupted by the OAuth round-trip resumes exactly once instead of zero or twice.
  • Telemetry has a single side-effect contract. telemetry/primitive-funnel*.ts owns the lifecycle events. Discovery works fully anonymously, and the funnel context is persisted under .hyperframes/ so preview and render stay stitched to the same funnel after the user authenticates.
  • Provenance rides in the registry item. The registry-item schemas (docs/schema/registry-item.json, packages/core/schemas/registry-item.json) gain the upstream artifact and version fields, and the resolver validates the recorded source digest, so an installed copy is traceable to an immutable upstream projection.
  • Preview generation covers the new block. scripts/generate-catalog-previews.ts and scripts/catalog-preview-temp.ts extended so the block is rendered by the same pipeline as every other catalog entry.

Test plan

  • 134 focused tests covering validation, authorization, resume, funnel, and the registry item, including a real installer to Studio preview to producer compile chain that produces a deterministic 8-frame MP4.

  • Full CLI suite at the reviewed head: 2,498 passed, 2 skipped.

  • Catalog preview scripts: 2 passed.

  • npx hyperframes lint and npx hyperframes check on the installed temp project: clean, zero runtime errors.

  • CLI and core typechecks, schema sync, changed-file oxlint / oxfmt, fallow audit, CLI build.

  • CI at this head: 61 successful checks, 1 expected Mintlify skip.

  • Known and unchanged: aggregate registry lint still reports 38 pre-existing failures across older blocks. The new block passes with 0 warnings.

  • Unit tests added/updated

  • Manual testing performed (the end-to-end installer, preview, and render path is exercised in-suite rather than by hand)

  • Documentation updated (if applicable) - registry-item schemas

@mintlify

mintlify Bot commented Aug 5, 2026 •

Copy link
Copy Markdown

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated (UTC)
hyperframes 🟢 Ready View Preview Aug 5, 2026, 4:46 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

@miguel-heygen miguel-heygen changed the title feat(cli): add HeyGenVerse thread message stack feat(cli): add thread message stack Aug 5, 2026
WaterrrForever added a commit that referenced this pull request Aug 11, 2026
social-proof-card: the app-store close as one scene - wordmark, five stars,
proof line, three feature icons, CTA capsule - in a quiet stagger. Composes
with, not against, star-rating-fill / testimonial-proof-card / cta-lockup,
which stay the atomic owners of their moves.

marker-checklist-card: a hand-lettered paper card - marker headline, an
ellipse that draws itself around one word, checklist rows whose checks draw
on. The paper-and-marker sibling of mk-specs-list.

chat-thread: a conversation as a scene - measured bubble pop-ins, expo
lockstep shifts, typing dots holding the beat, a media placeholder. Message
content is one variable: heights are measured at mount and the choreography
is generated to fit. Relates to #3046's caller-payload stack; kept
independent.

notes-typing: the notes-app confession - lines typed on the measured human
keystroke rhythm, the caret riding every landed character. The scene
counterpart to typed-prompt's bare prompt line.

All four follow notification-stack's mountable-scene pattern: container
units, theme-contract tokens, one paused timeline registered under the
literal id. All demos pass the browser gate.
jrusso1020 pushed a commit that referenced this pull request Aug 11, 2026
… primitives (#3217)

* feat(registry): add the notification-cascade block and banner-push-in component

A vertical ad-template block: phone notifications land one after another on a
2.000s beat and stack up the screen, each banner pushing the pile down as it
arrives, before the whole stack lifts away into a closing card carrying the
HyperFrames lockup. Every decisive number - the 214px pitch, the 22px entry
rise, the expo.out restack - is measured from reference footage rather than
invented. The backdrop plate is a generated photograph, shipped with the item.

The banner-push-in component carries the reusable arrival move on its own:
one banner fades in and rises into place while everything already on screen
slides up one pitch in lockstep.

Both pass the full browser gate (runtime, layout, motion, WCAG AA contrast)
installed into a scratch project from a served registry.

* feat(registry): add the share-sheet-carousel block and sheet-spring-up component

A share sheet springs up from the bottom of the phone and cycles photographic
previews inside its card on a fast cut rhythm - fourteen cuts over 7.2s -
while the blurred ground swaps behind it on the same beats, ending on an
accept tap. A brand strip with the HyperFrames lockup rides the bottom of the
preview, as the reference's did. The four stills are generated photographs,
shipped with the item.

The sheet-spring-up component carries the arrival on its own: a real spring
sampled frame by frame from reference footage - up from below, 192px
overshoot, 0.72s settle - shipped as the sampled table rather than an ease
that approximates it.

Both pass the full browser gate (WCAG AA) installed from a served registry.

* feat(registry): add the typing-indicator and streaming-text components

Two chat primitives extracted from reference footage of real conversations.

typing-indicator is the three-dot bubble that says someone is writing: it
pops in at the thread's edge on the measured entry (scale 0.6 to 1, alpha
0.4 to 1, 0.10s power2.out), holds, and vanishes when the message lands. An
optional bounded dot wave is included for compositions that want the dots to
breathe.

streaming-text is not a typewriter: words arrive in the uneven bursts of a
streamed AI answer, on a token rhythm measured word-by-word from the
reference, each word landing grey and inking to full colour over 0.27s. The
GAPS table ships in the integration note and cycles for any word count.

Both demos pass the browser gate.

* feat(registry): add the ai-chat-reveal block

A question is typed on a rising keyboard - measured keystroke rhythm, steady
caret - sent, and answered by an AI that streams its reply word by word:
thinking dot on the measured alpha ramp, tokens arriving in uneven bursts,
a bulleted list, then a cut to a branded closing card.

The typing and streaming schedules are generated at load from the measured
gap tables, so every piece of copy is a variable - question, three answer
paragraphs, three bullets, and the whole closing card - while the rhythm
stays the reference's. Kept at the native 750x1624 capture size so the
measured keyboard geometry stays pixel-true.

Passes the full browser gate (145/145 WCAG AA) installed from a served
registry.

* feat(registry): add the message-thread-reveal block

A full text conversation plays out on a phone: bubbles popping in on their
measured entries, typing indicators holding the beat, a shared link card,
an emoji burst, delivered receipts, the composer typing five messages
keystroke by keystroke - and the whole thread scrolling up beat by beat on
the measured y-choreography until a warm closing card lands.

Every message swap keeps the measured keystroke tables intact: the new copy
is length-matched character for character to the reference's typed lines, so
all 97 typed frames land on their original beats. The footage plate is
replaced by a CSS room-and-phone-body, the link card carries a generated
still, and the closing card is rebuilt around the HyperFrames lockup with
its stars, proof line, and feature icons preserved.

Relates to the thread-message-stack work in #3046: that PR ships a
caller-payload message-stack component; this block is the complete
ad-template film around the same subject. Kept as its own commit so either
can move independently.

Passes the full browser gate (65/65 WCAG AA) installed from a served
registry.

* feat(registry): add the notes-reveal block and line-reveal-list component

A personal note is typed character by character in a notes app - the caret
riding every letter on the measured keystroke frames, the page scrolling up
on the measured settle curves as each line lands - then cuts to a paper card
with a marker headline, a circled word, a ticked checklist, and the video
card. New copy is length-matched line by line to the measured reveal table,
so all 176 keystrokes land on their original frames. The two hand-drawn
faces (Permanent Marker, Courier Prime - both OFL) ship with the item; the
reference's proprietary UI face is replaced by the system stack.

The line-reveal-list component carries the paragraph rhythm on its own:
lines land on the measured writing cadence that slows as the thought gets
heavier - 2.20s, 2.03s, 2.97s, 3.10s, 3.33s, 3.63s - and the page makes room
with the measured scroll-settle table instead of a linear glide.

Both pass the browser gate (366/366 WCAG AA for the block) installed from a
served registry.

* docs(catalog): publish the ten new ad-template items

Regenerated pages, payloads, navigation and the flat index for the five
blocks and five components added in the preceding commits. Every existing
page is untouched: the diff is ten new item pages, their payload assets, and
the two regenerated indexes.

* chore(registry): rebuild the on-device search index for the new items

* style(registry): run oxfmt over the new item sources

The repo-wide format gate covers registry HTML; the staged-file hook did
not reach these. Payloads and pages regenerated to match.

* feat(registry): restage the five component demos as device specimens

The first demos dropped each primitive onto a bare canvas, which stripped
the context the moves were measured in - a dark bubble on a black frame, a
sheet floating in empty gradient. Each demo now plays inside a phone on a
studio ground, in the move's native habitat - lock screen, chat thread,
share sheet, assistant answer, notes page - with a specimen caption naming
the component and its measured numbers. Interiors are authored at 1080x1920
and scaled into the screen, so they reuse the blocks' gate-proven geometry.
Timelines are unchanged. All five pass the browser gate.

* refactor(registry): shelve the five ad-template films as showcases

The video-primitive tag pins an item to the Motion Primitives shelf and
overrides every other grouping rule - right for an atomic move, wrong for a
25-second film. The five ad-template blocks move to the Showcases shelf
(Scenes & demos), where complete scenes live; the primitives shelf keeps
only the moves.

* refactor(registry): retire banner-push-in and line-reveal-list

Reviewed against the shelf they would join and cut as duplicates.
banner-push-in was the thinnest cut against the existing notification
family - notification-stack already owns the arrival-plus-lockstep-shift
move, mirrored. line-reveal-list was pinched from both sides: the existing
line-by-line-slide owns generic staggered lines, and the incoming
notes-typing scene carries the measured writing cadence and scroll-settle
at scene level. Their measured tables live on inside the films they were
extracted from.

* feat(registry): add four scene primitives - the moments, mountable

social-proof-card: the app-store close as one scene - wordmark, five stars,
proof line, three feature icons, CTA capsule - in a quiet stagger. Composes
with, not against, star-rating-fill / testimonial-proof-card / cta-lockup,
which stay the atomic owners of their moves.

marker-checklist-card: a hand-lettered paper card - marker headline, an
ellipse that draws itself around one word, checklist rows whose checks draw
on. The paper-and-marker sibling of mk-specs-list.

chat-thread: a conversation as a scene - measured bubble pop-ins, expo
lockstep shifts, typing dots holding the beat, a media placeholder. Message
content is one variable: heights are measured at mount and the choreography
is generated to fit. Relates to #3046's caller-payload stack; kept
independent.

notes-typing: the notes-app confession - lines typed on the measured human
keystroke rhythm, the caret riding every landed character. The scene
counterpart to typed-prompt's bare prompt line.

All four follow notification-stack's mountable-scene pattern: container
units, theme-contract tokens, one paused timeline registered under the
literal id. All demos pass the browser gate.

* docs(catalog): regenerate for the reshelved films and scene primitives

Ten pages become twelve: the five films move to the Showcases shelf, the
two retired components' pages are gone, and the four scene primitives get
pages under Motion Scenes. Every untouched page is byte-identical.

* feat(registry): bring chat-thread to film fidelity, with a per-message type switch

The scene now carries everything the reference conversation carries: status
bar, back badge, avatar and name pill, bubbles with real iMessage tails, a
Delivered receipt under the last sent bubble, large emoji rows, a media
placeholder, and a link card with title, domain and chevron.

Every message picks its type by prefix, the way marker-highlight picks a
style: recv:/sent: text bubbles, emoji: a large row, img a media
placeholder, card:Title~domain a link card. Heights are still measured at
mount and the choreography generated, so any mix of types fits.

* feat(registry): add chat-message - the atom, with its type as an enum

ONE message arrives on the measured entry, growing from its sender's
corner. The type is a proper enum - Received, Sent, Emoji, Image, Link
card - switched on the catalog page the way marker-highlight switches its
style, with the bubble tail and the Delivered receipt as their own
switches. chat-thread remains the conversation-as-scene built from
arrivals like this one; the pipe grammar belongs at that level, the enum
belongs here. Demo cycles all five types, one at a time, with a type chip
naming each.

* fix(registry): neutral composer placeholder, gsap 3.14.2 pin, exact font licences

Review fixes for #3217:
- Rendered composer placeholder "iMessage" -> "Message" in chat-thread,
  its demo, and message-thread-reveal (technique comments stay as provenance)
- notes-reveal now loads [email protected] like every other item
- Licence wording names each face: Courier Prime OFL 1.1,
  Permanent Marker Apache-2.0 (verified against embedded name-table records)

Mirrored catalog payloads and pages regenerated for the four touched items.

@miga-heygen miga-heygen left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Reviewed at exact head. Large feature PR that adds the thread-message-stack primitive: OAuth authorization gate, HeyGenVerse catalog resolver, registry provenance schema, catalog-resume command, and primitive funnel telemetry. Well-structured with extensive test coverage (8 test files, integration tests for both the OAuth boundary and the data pipeline). The authorization gate correctly blocks download/materialization before registry resolution when OAuth is missing.

— Miga

@miga-heygen
miga-heygen enabled auto-merge (squash) September 4, 2026 18:06
* feat(cli): align primitive funnel measurement

* fix(cli): make primitive claims process-atomic

* fix(cli): keep primitive funnel terminals from losing events

Terminal funnel events took a durable single-use claim before they were
sent, but delivery was the fire-and-forget exit flush: a detached child
with no retry and no way to report failure. An unacknowledged send left
the claim spent on an event PostHog never received, so that step could
never be emitted again. Observed in a real install, where
primitive_preview_succeeded was claimed and never arrived.

The terminal path now awaits delivery and hands the claim back when the
batch is not acknowledged. That trades a permanent loss for a possible
duplicate, which is the cheaper failure: every funnel event carries a
stable event_id, so duplicates collapse downstream while a loss is
unrecoverable. Claims are also no longer spent while telemetry is
opted out.

Separately, funnel order is now carried by an explicit funnel_step
rather than inferred from timestamps. Auth completion and install start
are emitted back to back inside one command and land in the same
millisecond, so ordering by time resolved them arbitrarily and could
report an install beginning before the auth that authorized it.
@miga-heygen miga-heygen closed this Sep 4, 2026
auto-merge was automatically disabled September 4, 2026 19:45

Pull request was closed

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.

3 participants