slideshow

First, keep this skill fresh — confirm with the user before running: npx hyperframes skills update slideshow. A fast no-op when everything is current; otherwise it refreshes this skill plus the core domain skills it depends on before you rely on them.

figma source: If the deck's content or storyboard comes from a figma.com URL, run /figma first — asset export, brand tokens, and storyboard reconstruction if the source is a strip of scene frames — then build from its output. Don't drive Figma via raw MCP tools directly: that skips SVG sanitization, .media/manifest.jsonl provenance, and brand-token var() binding, so a later brand change can't propagate without a full re-import.

Slideshow authoring contract

A HyperFrames slideshow is a normal HyperFrames composition — scenes, clips, GSAP timelines — with one extra ingredient: a JSON island that declares which scenes are slides and how they connect. The player's SlideshowController reads the island and turns the continuous GSAP timeline into a discrete, navigable deck.

Read /hyperframes-core first for the base composition contract (clips, tracks, data-* attributes, determinism rules). This skill covers only what is new: the island schema, slide writing rules, fragments, branching, validation, and the wrapping component.

Output — a navigable deck, not a linear MP4

A slideshow's output is the running deck: serve it with hyperframes present (or Studio present mode) — the player's SlideshowController reads the island and drives navigation, fragments, branching, and presenter mode. See Presenting and handoff below.

Do not hyperframes render a slideshow into a single MP4. A deck is authored as several top-level scene compositions (one data-composition-id per slide) with no master-root composition wrapping them, so render resolves only the first composition and emits a silently truncated MP4 (e.g. 6s of a 40-second deck). A linear main-line export (main slides only, branch sequences excluded) is deferred — until it ships, the supported outputs are the live present deck and per-slide snapshot stills. If a user needs a linear MP4 today, surface this limitation rather than pointing render at the deck.

Intent confirmation

If the user explicitly asks for a slideshow, slide show, or HyperFrames slideshow, proceed with this skill. When the request arrived through /hyperframes, the intent layer's triage owns this confirmation — routed here means already confirmed, so don't re-ask; the layer's run-shape questions don't apply (the deliverable is a deck, not a rendered video). A BRIEF.md, when present, carries the confirmed intent — read it.

If the skill triggered from an adjacent request such as "presentation", "pitch deck", "deck", "interactive deck", or "convert this page", pause before authoring and frame the choice before asking for confirmation. Briefly explain that a HyperFrames slideshow means a runnable deck with discrete slides, built-in navigation and presenter mode, editable speaker notes, shared media handling, and validation before handoff. For source-page conversions, also mention that the goal is to preserve the original page's visual design, interactions, motion, and media behavior while translating page movement into slide-to-slide transitions.

Then ask a short confirmation question:

Do you want this as a HyperFrames slideshow?

Use a yes/no choice UI when the environment provides one; otherwise ask the question in plain text.

Do not implement the slideshow until the user says yes. If they say no, stop using this skill — read /hyperframes and let the intent layer re-route. This confirmation is a routing decision, not a preference gate — per ../hyperframes-core/references/brief-contract.md § 1 it survives autonomous mode ("surprise me" does not skip it): building the wrong deliverable type is a quality failure, not a creative call.

---

The two pieces

1. Scenes — declared the normal way

Every slide is backed by a scene. Declare scenes with data-composition-id, data-start, data-duration, and data-label:

  <!-- clips go here -->

Branch slides (reachable only via a hotspot, excluded from the main line) are declared exactly the same way — they just appear only in a slideSequences entry in the island, not in the main slides array.

2. The JSON island — one script block per composition

Add exactly one `

The island is the single source of truth for slide order, notes, fragment hold-points, hotspots, and branch sequences. Keep it near the top of the ``, before the scene divs, so it is easy to find.

Do not hide the slideshow manifest behind an alternate `

  <!-- Slide 1 — hook -->
  
    
      
        SMBs lose $40B/year to manual scheduling
      
    
  

  <!-- Slide 2 — problem (3 fragments) -->
  
    
      
        Three gaps operators can not close
      
      
        No-shows cost 23% of booked revenue
      
      
        Manual reminders take 4h/week per staff
      
      
        Rescheduling friction drives 40% churn
      
    
  

  <!-- Slide 3 — solution -->
  
    
      
        Acme automates scheduling for service SMBs — no-shows down 80% in 90 days
      
    
  

  <!-- Branch slide — excluded from main line -->
  
    
      
        2.3M SMBs × $17k ACV = $39B serviceable market
      
    
  

  

Key points in the example

• The island sceneId values ("hook", "problem", "solution", "mkt-math") exactly match data-composition-id values on scene divs.
• mkt-math appears only in slideSequences — it is never in the top-level slides array.
• Fragment times (11.0, 15.0) are within the problem scene's [6, 21] range (times are absolute composition-timeline positions).
• The hotspot region (x: 55, y: 60, w: 40, h: 20) positions the clickable area in the lower-right quadrant of the problem slide.
• GSAP timelines are registered on window.__timelines and are paused — the HyperFrames engine drives playback; do not call .play() at construction time.

---

Wrapping component

Wrap the composition in around in any embedding context:

`` provides the navigation chrome (Present, Prev / Next, counter, global mute when sound is present, fullscreen), keyboard handling (← / →, Space / Backspace, and P for Present), touch swipe, and hotspot overlays.

The slideshow automatically sets the interactive attribute on every inner at mount time, so clickable controls, links, native media controls, and custom players inside the composition iframe receive pointer events as expected. (Outside a slideshow wrapper, you must add `interactive` manually on — the player defaults to pointer-events: none on the iframe so clicks on the player host don't get hijacked into toggling timeline playback.)

Presenter mode: use the built-in Present icon button in the slideshow nav capsule, or press P. It calls window.open('?mode=audience') for a fullscreen audience tab; the originating tab becomes the presenter view (current slide reduced, next-slide preview, notes, elapsed timer). The two tabs sync via BroadcastChannel('hf-slideshow:' + location.pathname). Do not add a custom wrapper-level Present button; the shared component owns its placement, icon, styling, and audience-mode hiding.

Presenting over Google Meet / Zoom (screen share): share the audience surface, keep the presenter view on your own screen.

• Google Meet (or any in-Chrome share): Present → in Meet choose Share screen → A tab → pick the audience tab → switch back to the presenter tab. Chrome keeps a captured tab rendering while backgrounded, so animations and slide nav stay live. Do not share "A window" or "Entire screen" — a fully covered window stops rendering (frozen slides for viewers), and entire-screen exposes your notes.
• Zoom (desktop app): drag the audience tab out into its own window and share that window. Zoom captures via the OS, so if the audience window becomes fully covered it freezes — use a second monitor, or keep a sliver of the audience window visible behind the presenter view.

Presenter-driven media playback has an autoplay-policy constraint: BroadcastChannel can sync intent, time, and state, but it cannot transfer the presenter's user activation to the audience tab. The shared slideshow player mirrors native media events and starts remote audience playback muted first; only fall back to the standalone harness's audience unlock behavior if muted media.play() is rejected or if the deck specifically requires audible audience playback. Do not keep applying remote timeupdate messages after a rejected play, or the audience will silently seek through the video without playback.

Presenter notes are editable in the presenter view. Edits are stored in localStorage per deck and slide, layered over the manifest notes without rewriting the composition file. Do not add one-off note-editing scripts to decks; rely on the shared slideshow player behavior. If a standalone/custom wrapper truly needs to implement this outside the shared player, use the deterministic storage snippet in skills/slideshow/references/standalone-harness.md.

Media cleanup on slide exit

The slideshow controller owns slide-exit media cleanup. When navigation changes slide or sequence, it calls hyperframes-player.stopMedia() before entering the next slide. That command:

• posts stop-media to the iframe runtime, which stops WebAudio and pauses native / elements;
• pauses same-origin iframe media directly as a fallback; and
• pauses parent-frame proxies adopted from iframe media.

Same-slide fragment navigation does not stop media. Global/deck-level parent audio, such as a background track wired through audio-src, is not treated as slide media.

Do not add per-slide cleanup scripts for normal media players. Keep slide video/audio as normal media in the composition; use data-has-audio="true" only when the player should preserve audible native video audio instead of treating it as silent visual media.

If the source page has custom controls or visualizations attached to media, those controls must listen to the same native element the slideshow player stops and mutes. A pause caused by slide exit, presenter sync, native controls, custom controls, or the global mute button should all update the visible custom UI through media events, not through parallel state.

When implementing direct iframe fallback cleanup, treat iframe media as cross-realm DOM. Do not test iframe nodes with the parent page's el instanceof HTMLMediaElement; that returns false in real browsers. Use el.ownerDocument.defaultView.HTMLMediaElement (or an equivalent tag/duck-type guard) before setting muted or calling pause().

Global nav mute

When `` renders the nav mute button, that button is the global mute control for the page. It must mute:

• child `` instances, including same-origin iframe media;
• top-level page / elements; and
• wrapper-owned SFX/global Audio objects via the hf-sound event.

Do not add a second mute button inside the composition. If a wrapper script creates new Audio(...) objects that are not attached to the DOM, it must listen for hf-sound and set clip.muted = detail.muted on each object, not merely skip future plays.

The same cross-realm rule applies here: global mute must reach iframe / elements through the child frame's DOM realm. A passing unit test in a single DOM realm is not enough; verify in a browser that the actual iframe media elements report muted: true after clicking the nav mute button.

hyperframes present serves built bundles from packages/player/dist. After changing player or slideshow chrome behavior, run bun run build in packages/player and restart the present server before testing in a browser.

---

Running a slideshow standalone (interim)

The durable answer is engine-hosted: hyperframes preview --slideshow / studio present mode will host the composition over the real HyperFrames engine, which drives seek-timelines, owns the gesture frame, and reads the island from the composition. That path is coming; prefer it once it ships.

Until then, standalone demos (a composition opened via the bare player bundle in a browser, without the engine) require workarounds for three gaps: the composition must expose a seekable root timeline, the island must be duplicated into the wrapper, and wrapper-owned SFX/global audio should live in the parent frame. These patterns are documented in:

skills/slideshow/references/standalone-harness.md

Do not treat the patterns there as the blessed model — they exist only to bridge the gap until the engine-hosted path lands.

Handoff

For a public or user-facing slideshow project, the root index.html should be a runnable slideshow entrypoint. Opening it in a browser should show slideshow navigation and respond to Next/Prev; it should not expose only the raw composition and require the user to know about Studio or an internal wrapper file. If the raw HyperFrames composition must remain separate for CLI compatibility, put it in a subdirectory such as composition/index.html and point scripts/commands at that directory.

The direct-open wrapper must rely on the built-in Present icon button rendered by ``. Do not add a bespoke #present-btn, fixed-position button, or wrapper-specific Present styling. The shared component owns the control bar, hides Present in ?mode=audience, and supports P as a keyboard shortcut.

Validate the direct-open path before handoff. If file:// browser restrictions break iframe media, local scripts, or same-origin player access, use a self-contained wrapper or make the handoff command start a local server and open the working URL; do not leave index.html in a broken or ambiguous state.

For a completed slideshow deck, the primary user-facing next step is presenter mode, not Studio. Run or provide:

npx hyperframes present 

Studio/preview is useful for editing a composition, but it is not a clear final destination for a slideshow user. If you create a package.json for a slideshow project where the raw composition lives in composition/, make the default runnable script start presenter mode:

{
  "scripts": {
    "dev": "npx hyperframes present ./composition",
    "studio": "npx hyperframes preview ./composition --background"
  }
}

At handoff, include the local presenter URL printed by the command and the minimal instruction: "Click Present, or press P, to open the audience tab." If the user will present over Google Meet or Zoom, also pass on the screen-share guidance from the Presenting section above (share the audience tab in Meet; a dragged-out audience window in Zoom). Keep the server running if the user asked you to start it.

---

Validation

After authoring or editing a slideshow composition, run:

npx hyperframes lint

Then run runtime validation:

npx hyperframes check

Treat lint errors and validation StaticGuard contract messages as blockers even if a command exits successfully. Fix the file and rerun until lint reports 0 error(s) and validation reports no runtime errors.

The slideshow lint rule checks:

• Every slide.sceneId resolves to an existing scene (by data-composition-id).
• Every hotspot.target references a defined slideSequence id.
• Fragment times fall within each slide's [start, end] range.
• No two main-line slides overlap in time.

Fix all violations before previewing. A composition that fails lint will not parse correctly in the player.