test(examples): slideshow demos — airbnb deck, startup pitch, fixture

[vanceingalls]

Slideshow mode — 5/5: demo compositions

Three runnable slideshow compositions exercising the full feature end to end. Builds on #1583.

Demos

• registry/examples/airbnb-deck/ — a current-Airbnb-branded remake of the 2009 seed pitch deck (11 slides): Three.js cinematic backgrounds (soft coral particle field, low-poly globe + arc routes on the market slide) on their own rAF; GSAP imperative entrances; a fragment reveal on the problem slide; a hotspot → market-sizing branch with full forward/back round-trip; the unified mute+nav capsule; and real HeyGen sound effects (sourced via the HeyGen MCP, played from the parent frame). Includes DESIGN.md and the sfx/ assets.
• registry/examples/startup-pitch/ — an animated FlowDesk investor pitch (no 3D), demonstrating the same playhead-driven scene/entrance harness.
• registry/examples/slideshow-demo/ — a minimal fixture used for lint/validate.

Each demo wraps <hyperframes-slideshow><hyperframes-player> and carries the island in the wrapper (the documented interim pattern). All pass hyperframes lint (0 slideshow errors) and were driven headless to verify nav, fragments, branch round-trip, presenter sync, and SFX cues.

Stack

core (#1580) → player (#1581) → studio (#1582) → skill (#1583) → examples.

🤖 Generated with Claude Code

[vanceingalls]

• fix(slideshow): address code-review findings #1580-1584 #1585
• test(examples): slideshow demos — airbnb deck, startup pitch, fixture #1584 👈 (View in Graphite)
• docs(skill): slideshow authoring guidance + standalone harness reference #1583
• feat(studio): slideshow branching editor panel UI #1592
• feat(studio): slideshow manifest persistence + panel helpers #1591
• feat(player): <hyperframes-slideshow> web component + presenter #1590
• feat(player): slideshow controller state machine #1589
• feat(core): slideshow schema, parser, and lint rule #1580 : 1 other dependent PR (#1581 )
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[miga-heygen]

PR Review — test(examples): slideshow demos

Reviewed the full 3,243-line diff across all seven new files. Overall this is solid demo/fixture work that exercises the slideshow schema from #1580 comprehensively. A few observations:

---

1. Test coverage — schema exercise ✅

All three examples produce well-formed application/hyperframes-slideshow+json islands that exercise the key schema features:

• slides[] with sceneId, notes, fragments, hotspots — all covered.
• slideSequences[] with branch slides (market-math-detail, market-sizing-drill, dive-deeper) — all three examples include at least one branch.
• hotspots with id, label, target, region {x,y,w,h} — exercised in airbnb-deck and startup-pitch main decks, plus the slideshow-demo fixture.
• Fragments — exercised in all three (airbnb-deck: 2 fragments, startup-pitch: 3 fragments, slideshow-demo: 2 fragments).

Good breadth. The fixture (slideshow-demo) keeps things minimal while still exercising fragments, hotspots, and branch sequences — exactly what a lint/validate fixture should do.

2. Demo quality ✅

Both full decks (Airbnb and FlowDesk) are realistic, investor-pitch-grade compositions that would actually validate the feature end-to-end:

• Airbnb deck: 11 main slides + 1 branch, Three.js backgrounds with deterministic seeded LCG (nice — no Math.random()), GSAP entrances, fragment reveals, hotspot branching. The DESIGN.md is a nice touch for documenting brand/design constraints.
• FlowDesk pitch: 9 main slides + 1 branch, no 3D (validates the no-WebGL path), same playhead-driven visibility + entrance pattern.

These aren't toy examples — they'd genuinely catch regressions in nav, fragments, branch round-trip, and scene lifecycle.

3. Fixture design ✅

slideshow-demo/index.html at 429 lines is focused — 3 main scenes + 2 branch scenes, no extra styling beyond what's needed. It exercises sceneId resolution (the comment at line 2267 explicitly notes this tests collectCompositionIdScenes). Appropriately minimal for a lint/validate target.

4. Hardcoded paths / secrets / environment values

No secrets or env-specific values found. Good.

Two observations on paths:

• demo.html files reference ../../../packages/player/dist/hyperframes-player.global.js and ../../../packages/player/dist/slideshow/hyperframes-slideshow.global.js — these are relative paths within the monorepo, which is the right pattern for registry examples. ✅
• CDN references use pinned versions: gsap@3.14.2, three@0.160.0 — good practice, no floating @latest. ✅
• The postMessage origin uses '*' — acceptable for iframe ↔ parent communication in demo contexts, and documented in comments. Would be worth tightening in production, but fine for examples.

5. DRY — duplication analysis

This is the one area worth flagging:

5a. JSON island duplication (demo.html ↔ index.html) — acknowledged, acceptable

Both airbnb-deck/demo.html and startup-pitch/demo.html carry a full copy of the slideshow JSON island from their respective index.html. This is explicitly called out in comments: "This duplication is intentional: <hyperframes-slideshow> reads the island from its OWN innerHTML (not from the composition loaded by <hyperframes-player>)." The comment also notes this is a "current workaround" to be resolved when the component reads directly from the composition. Fine — it's documented debt, not accidental duplication.

5b. Scene visibility controller + entrance driver — duplicated across all three compositions

The updateVisibility() + fireEntrance() + fragment-reveal pattern is copy-pasted across all three index.html files with only the scene list and fragment config varying. This is ~80-100 lines of near-identical imperative JS per file. For examples/fixtures, this is tolerable — the compositions need to be self-contained, runnable HTML files. But if this pattern proliferates to more examples, extracting a shared slideshow-driver.js utility would be worth it.

5c. Scene list duplication within each composition

Within the airbnb-deck index.html alone, the scene list (IDs + start/end times) appears in three separate places:

1. The visibility controller
2. The SFX transition patcher
3. The postMessage bootstrap

All three must stay in sync manually. This is the most fragile part of the PR — a scene timing change requires updating three arrays in the same file. Not a blocker for examples, but worth a // SYNC: marker comment pointing to the other locations if it isn't there already.

5d. Bélo SVG — repeated 11 times in airbnb-deck

The SVG path for the corner Bélo mark is copy-pasted on every slide (<svg width="36" height="36" viewBox="0 0 100 100" ...>). In a composition that must be a single self-contained HTML file, this is unavoidable — CSS background-image or an <svg><use> pattern could reduce it, but the current approach is the simplest and most maintainable for an example. No action needed.

---

Minor nits (non-blocking)

1. postMessage wildcard origin: parent.postMessage({...}, '*') is used in all three compositions. Fine for demos, but a comment like // '*' is safe here — composition and host are always same-origin would be even clearer.

2. WebGL fallback in airbnb-deck: The console.error suppression trick (lines 1343-1351) is clever but aggressive — it suppresses ALL console.error calls during renderer creation, including potential non-THREE errors. A more targeted approach would be to check WebGLRenderingContext support first. Not a blocker for an example.

3. startup-pitch/demo.html doesn't include the sound attribute on <hyperframes-slideshow> (line 2358), while airbnb-deck/demo.html does (line 136). Intentional? If FlowDesk has no SFX, removing sound is correct; if it should have SFX too, it's missing.

---

Verdict

Clean examples that exercise the full slideshow schema surface area — slides, fragments, hotspots, branch sequences, scene visibility, entrance animations, and SFX. No secrets, no environment coupling, good use of pinned CDN versions. The duplication is acknowledged and appropriate for self-contained example compositions. The scene-list-sync fragility within files is the only thing I'd want a // SYNC: comment for.

Recommend approval once the scene-list sync fragility is acknowledged (comment or not — author's call).

— Review by Miga

[miguel-heygen]

LGTM

[james-russo-rames-d-jusso]

Reviewed at: c21951bc041194bffc7088859a355a296bdf7e91 (HEAD)

Verdict: Comment — comprehensive demos, but missing registry-item.json for all 3 new examples breaks hyperframes add / catalog discoverability. Miga (review) caught the DRY + sync-comment items; layering with the registry omission, demo-realism notes, and a fixture-coverage gap.

---

Blocker — missing registry-item.json for all 3 new examples

Every existing registry/examples/* ships a registry-item.json (verified across decision-tree, play-mode, kinetic-type, nyt-graph, motion-blur). It declares the example to:

• packages/cli/src/commands/add.ts — enables npx hyperframes add airbnb-deck
• scripts/generate-catalog-pages.ts — surfaces the example on the docs catalog
• packages/core/src/registry/types.ts — declares dimensions/duration/files

The three new examples do not have one:

• registry/examples/airbnb-deck/ — DESIGN.md, demo.html, index.html, sfx/ only
• registry/examples/startup-pitch/ — demo.html, index.html only
• registry/examples/slideshow-demo/ — index.html only

Consequence: these demos exist as files in the repo but are invisible to the registry plumbing. The skill doc in #1583 points at these as "living reference implementations" — readers following the doc will be told to npx hyperframes add ... (or expect to) and get nothing. The fixture slideshow-demo is the smaller concern — it's primarily a lint target — but the two showcase decks should be addressable via hyperframes add or the catalog.

Fix: add registry-item.json to each (template: play-mode/registry-item.json). For airbnb-deck this should include the sfx/*.mp3 files in files[] so the installer copies them.

---

Layered on Miga's findings

7. Scene-list duplication within each composition (Miga 5c). Confirming the three-place sync risk. In airbnb-deck/index.html the scene IDs/times appear in: visibility controller, SFX patcher, postMessage bootstrap. A // SYNC: marker comment isn't free protection — a clean refactor would be to declare scenes once in a JS object at the top of the file and have all three consumers read from it. That fits within "self-contained HTML file" since it's all inline. Worth the polish before this becomes the reference shape that future examples cargo-cult.

8. Scene-driver duplication across decks (Miga 5b). updateVisibility()/fireEntrance()/fragment-reveal copy-pastes across all 3 index.html files. Agree it's tolerable for 3 examples but extracting to registry/examples/_shared/slideshow-driver.js (or similar) before the 4th example lands is the cheap-now-vs-expensive-later split. Not a blocker — but the standalone-harness reference in #1583 also documents these patterns verbatim, so the same drift can hit 3 places (each example file, the standalone-harness doc, plus the SKILL.md worked example) any time the controller changes.

Fixture coverage gap

9. slideshow-demo doesn't exercise data-end / data-hf-authored-end. PR #1585 expands lint parseTiming to accept data-end and data-hf-authored-end (matching runtime). The fixture only uses data-duration. If the fixture is the canonical lint-target test, it should exercise both code paths so a regression in the new data-end branch is caught. A single branch slide using data-end instead of data-duration would do it.

Demo-realism / asset audit

10. SFX assets — sourced + reasonable size. Verified the 4 .mp3 files (advance, back, branch-enter, fragment) are 9.6KB-54KB each (~155KB total). PR body claims "real HeyGen sound effects sourced via the HeyGen MCP" — no provenance/license note in DESIGN.md or sfx/README. For a registry example that ships under whatever the repo license is, worth a one-line attribution + license note in DESIGN.md so an external consumer doesn't republish without clearance.

11. postMessage(*, '*') is fine for demos but document the constraint. In all 3 compositions, parent ↔ iframe messaging uses the '*' origin. Miga's nit-1 covers commenting it; a stronger version is to compute iframe.contentWindow.location.origin once and hold it — same effort, less foot-gun for someone copy-pasting the pattern to a non-demo context. Both work; flagging because the harness doc in #1583 documents '*' as the blessed shape.

12. WebGL fallback console.error suppression (Miga nit 2). Confirming this — the airbnb-deck pattern at index.html lines ~1343-1351 swallows all console.error during new THREE.WebGLRenderer(). A targeted alternative: const canvas = document.createElement('canvas'); const ctx = canvas.getContext('webgl2') || canvas.getContext('webgl'); if (!ctx) { /* fallback */ }. Same intent, no console-mute side effect. Worth it because this pattern is also in the standalone-harness doc and will propagate.

demo.html ↔ index.html island duplication (Miga 5a)

Confirming this is documented debt with a comment pointing to the durable fix (engine-hosted preview). Acceptable today; flagging that PR #1585 adds another duplicated island in presenter-test.html — now there are three places to keep in sync for airbnb-deck alone. Not the moment to fix, but worth a single tracking issue so the cleanup happens when the engine-hosted path lands.

Cross-PR branching concern

Same branching strategy note as #1583 — this stack chains on ss-skill → ss-studio (the monolith #1582) not the split (#1589-#1592). If the team picks the split, this PR needs a rebase. Worth a stack-direction decision before any of #1583/#1584/#1585 lands.

Nits

• startup-pitch/demo.html legitimately omits sound attribute — verified, no SFX expected. Intentional, not a gap.
• The airbnb deck DESIGN.md is a strong touch; replicating it (even a 20-line version) for startup-pitch would help readers understand the design intent of the second deck.

What's good

• Schema coverage is thorough: slides, fragments, hotspots, branch sequences, scene visibility, entrance animations, SFX cues — all exercised end-to-end.
• Deterministic seeded LCG (no Math.random()) is the right call for examples that may be screenshot-tested or video-exported.
• Pinned CDN versions for GSAP/Three. Good practice.
• The fixture (slideshow-demo) is appropriately minimal at 429 lines.
• DESIGN.md for airbnb-deck is a quality touch worth replicating.

Item missing-registry-item.json is the only blocker. 7-9 are concerns worth addressing. 10-12 are tightening.

Review by Rames D Jusso

The base branch was changed.