Back to Details

slideshow

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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.
HyperFrames幻灯片是一种标准的HyperFrames作品，包含场景、片段、GSAP时间线，额外增加了一个核心元素：JSON孤岛，用于声明哪些场景是幻灯片以及它们的关联方式。播放器的
SlideshowController
会读取该孤岛内容，将连续的GSAP时间线转换为可独立导航的演示文稿。
请先阅读
/hyperframes-core
中的基础作品规范（片段、轨道、
data-*
属性、确定性规则）。本文档仅涵盖新增内容：孤岛 schema、幻灯片编写规则、分段展示、分支导航、验证机制以及包装组件。

The two pieces

两大核心部分

1. Scenes — declared the normal way

1. 场景——按标准方式声明

Every slide is backed by a scene. Declare scenes with 
data-composition-id
, 
data-start
, 
data-duration
, and 
data-label
:
html
<div
  data-composition-id="problem"
  data-start="0"
  data-duration="8"
  data-label="The problem"
  data-width="1920"
  data-height="1080"
>
  <!-- clips go here -->
</div>
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.
每张幻灯片都对应一个场景。使用
data-composition-id
、
data-start
、
data-duration
和
data-label
声明场景：
html
<div
  data-composition-id="problem"
  data-start="0"
  data-duration="8"
  data-label="The problem"
  data-width="1920"
  data-height="1080"
>
  <!-- clips go here -->
</div>
分支幻灯片（仅可通过热点访问，不属于主流程）的声明方式完全相同——它们仅出现在孤岛的
slideSequences
条目里，不会加入主
slides
数组。

2. The JSON island — one script block per composition

2. JSON孤岛——每个作品对应一个脚本块

Add exactly one 
<script type="application/hyperframes-slideshow+json">
block to the composition HTML. It holds all slideshow metadata:
html
<script type="application/hyperframes-slideshow+json">
  {
    "slides": [...],
    "slideSequences": [...]
  }
</script>
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 
<body>
, before the scene divs, so it is easy to find.
在作品HTML中添加且仅添加一个
<script type="application/hyperframes-slideshow+json">
块，用于存储所有幻灯片元数据：
html
<script type="application/hyperframes-slideshow+json">
  {
    "slides": [...],
    "slideSequences": [...]
  }
</script>
孤岛是幻灯片顺序、备注、分段停留点、热点和分支序列的唯一数据源。请将其放在
<body>
顶部、场景div之前，以便查找。

Schema

Schema定义

SlideshowManifest
(the top-level island object)

SlideshowManifest
（顶层孤岛对象）

json
{
  "slides": [
    /* SlideRef[] — the main line, in order */
  ],
  "slideSequences": [
    /* SlideSequence[] — off-line branch sequences */
  ]
}
json
{
  "slides": [
    /* SlideRef[] — 主流程，按顺序排列 */
  ],
  "slideSequences": [
    /* SlideSequence[] — 离线分支序列 */
  ]
}

SlideRef

SlideRef

json
{
  "sceneId": "problem",
  "notes": "Lead with the pain, not the company.",
  "fragments": [3.5, 5.2, 7.0],
  "hotspots": [
    /* SlideHotspot[] */
  ],

  "ttsScript": null,
  "ttsAudioUrl": null,
  "ttsDurationMs": null
}
FieldRequiredNotes
sceneId
yesMust match a scene's 
data-composition-id
exactly. The lint rule resolves both 
data-composition-id
and 
.clip[id]
.
notes
noPresenter-only text. Never shown to the audience.
fragments
noArray of times (seconds) within the slide's 
[start, end]
range — see Fragments below.
hotspots
noInteractive overlays that trigger a branch — see Branching below.
startTime
noOptional. Override the matched scene's time bounds; defaults to the scene's start/end.
endTime
noOptional. Override the matched scene's time bounds; defaults to the scene's start/end.
ttsScript
, 
ttsAudioUrl
, 
ttsDurationMs
noReserved. Schema fields exist but TTS playback is not yet wired. Omit unless you are pre-populating for a future build.
json
{
  "sceneId": "problem",
  "notes": "Lead with the pain, not the company.",
  "fragments": [3.5, 5.2, 7.0],
  "hotspots": [
    /* SlideHotspot[] */
  ],

  "ttsScript": null,
  "ttsAudioUrl": null,
  "ttsDurationMs": null
}
字段必填说明
sceneId
是必须与场景的
data-composition-id
完全匹配。lint规则会解析
data-composition-id
和
.clip[id]
。
notes
否仅演讲者可见的文本，不会展示给观众。
fragments
否幻灯片
[start, end]
时间范围内的时间点数组（单位：秒）——详见下方「分段展示」部分。
hotspots
否触发分支导航的交互式覆盖层——详见下方「分支导航」部分。
startTime
否可选。覆盖匹配场景的时间范围；默认使用场景的start/end值。
endTime
否可选。覆盖匹配场景的时间范围；默认使用场景的start/end值。
ttsScript
, 
ttsAudioUrl
, 
ttsDurationMs
否预留字段。Schema已定义但TTS播放功能尚未实现。除非为未来版本预填充，否则请忽略。

SlideHotspot

SlideHotspot

json
{
  "id": "h1",
  "label": "How did we calculate this?",
  "target": "market-deep-dive",
  "region": { "x": 60, "y": 10, "w": 35, "h": 20 }
}
FieldRequiredNotes
id
yesUnique within the slide.
label
yesTooltip / button text shown to the audience.
target
yesMust match a 
SlideSequence.id
in 
slideSequences
.
region
noPercentage-of-slide bounding box: 
{x, y, w, h}
in 
0–100
. Omit to render the hotspot as a full-slide labeled button instead.
json
{
  "id": "h1",
  "label": "How did we calculate this?",
  "target": "market-deep-dive",
  "region": { "x": 60, "y": 10, "w": 35, "h": 20 }
}
字段必填说明
id
是在当前幻灯片内唯一。
label
是展示给观众的提示文本/按钮文本。
target
是必须匹配
slideSequences
中的
SlideSequence.id
。
region
否幻灯片百分比边界框：
{x, y, w, h}
取值范围为
0–100
。若省略，热点将渲染为全屏带标签按钮。

SlideSequence

SlideSequence

json
{
  "id": "market-deep-dive",
  "label": "Market sizing methodology",
  "slides": [{ "sceneId": "mkt-1" }, { "sceneId": "mkt-2" }]
}
slides
inside a sequence uses the same 
SlideRef
shape as the main line. Fragments and nested hotspots are allowed.
json
{
  "id": "market-deep-dive",
  "label": "Market sizing methodology",
  "slides": [{ "sceneId": "mkt-1" }, { "sceneId": "mkt-2" }]
}
序列中的
slides
使用与主流程相同的
SlideRef
结构，支持分段展示和嵌套热点。

Slide writing rules

幻灯片编写规则

These are hard constraints, not suggestions. A slide that violates them will be outright replaced when a reviewer sees it.
  • Headline is a complete-sentence claim, not a label. Write "SMBs spend 14 hours/week on manual scheduling" not "Scheduling problem". The sentence should stand alone if the visual is ignored.
  • One idea + one visual per slide. If you are tempted to add a second bullet cluster or a second chart, split the slide.
  • Lead with the punchline. The strongest point goes first — on the slide and in the deck order. Investors read left-to-right, top-to-bottom, and they stop.
  • Bottom-up market sizing only. Never write "$50B TAM" without showing the math. Build from unit economics up: accounts × ACV, or transactions × take-rate.
  • Font minimum 30pt equivalent. At 1920×1080, a headline is 72–96px; body copy is 48px. Never go below 40px for any text the audience must read.
以下为硬性约束，而非建议。违反规则的幻灯片会被审核者直接替换。
  • 标题需为完整句子式主张，而非标签。请写「中小企业每周在手动排程上花费14小时」，而非「排程问题」。即使忽略视觉内容，句子也应能独立表意。
  • 每张幻灯片一个核心观点+一个视觉元素。若你想添加第二组项目符号或第二个图表，请拆分幻灯片。
  • 开门见山展示核心结论。最强论点放在最前面——无论是幻灯片内部还是整个演示文稿的顺序。投资者会按从左到右、从上到下的顺序阅读，且随时可能停止。
  • 仅采用自下而上的市场规模测算方式。绝不要只写「500亿美元总可寻址市场」却不展示计算过程。从单位经济效益向上推导：客户数量×平均客户生命周期价值，或交易次数×抽成比例。
  • 字体最小等效30pt。在1920×1080分辨率下，标题字体为72–96px；正文为48px。观众必须阅读的文本绝不能小于40px。

Fragments: reveal hold-points within a slide

分段展示：幻灯片内的停留点

A fragment is a time (in seconds) within a slide's 
[start, end]
range where the controller pauses before the next reveal.
How it works:
  1. Player enters the slide — seeks to 
    start
    , then plays.
  2. Controller pauses at 
    fragments[0]
    . The first element's GSAP entrance has just landed.
  3. User presses Next (or →) — plays to 
    fragments[1]
    , pauses again.
  4. After the last fragment, Next plays to 
    slide.end
    and holds.
  5. Next again advances to the next slide.
Fragment times must be strictly inside 
[start, end]
. The lint rule rejects fragments outside that range.
Fragment times are absolute composition-timeline positions — the same coordinate space as 
data-start
— not offsets relative to the scene's start.
Each fragment is a play-to-and-hold, not a seek jump — so every element that enters between the previous hold-point and this one plays its GSAP entrance animation. Design the clip entrance animations to work as sequential reveals.
分段展示是指幻灯片
[start, end]
时间范围内的某个时间点（单位：秒），控制器会在此暂停，等待下一次展示。
工作原理：
  1. 播放器进入幻灯片——跳转到
    start
    位置，开始播放。
  2. 控制器在
    fragments[0]
    处暂停。此时第一个元素的GSAP入场动画刚完成。
  3. 用户点击「下一页」（或按→键）——播放到
    fragments[1]
    ，再次暂停。
  4. 最后一个分段展示完成后，点击「下一页」会播放到
    slide.end
    并停留。
  5. 再次点击「下一页」将跳转到下一张幻灯片。
分段时间必须严格处于
[start, end]
范围内。lint规则会拒绝超出范围的分段时间。
分段时间为作品时间线的绝对位置——与
data-start
使用同一坐标空间——而非相对于场景起始点的偏移量。
每个分段都是「播放到该点并停留」，而非直接跳转——因此在上一个停留点到当前点之间入场的所有元素都会播放其GSAP入场动画。请设计片段入场动画以支持顺序展示。

Branching: hotspots and slide sequences

分支导航：热点与幻灯片序列

Branch slides are real scenes in the same composition timeline. They are listed only under 
slideSequences
and are excluded from main-line navigation — the player never visits them unless a hotspot fires.
Navigation model:
  • Clicking a hotspot pushes 
    {sequenceId, slideIndex: 0}
    onto the nav stack and enters the branch's first slide.
  • back() pops the stack and returns to the exact parent slide (the one that held the hotspot).
  • backToMain() clears the entire stack and returns to the root slide.
  • Breadcrumb renders from the stack: 
    Main deck › Market sizing methodology › Slide 2
    .
  • The slide counter inside a branch is scoped to that sequence (
    1 of 2
    , not the main-deck total).
What to avoid:
  • Do not add branch scene IDs to the main 
    slides
    array. They must appear only inside a 
    slideSequences
    entry. The lint rule flags overlap.
  • Branch scenes are included in the continuous timeline, so a naive linear video export would include them. Export reads main-line slides only (deferred; flagged in the spec).
分支幻灯片是同一作品时间线中的真实场景。它们仅在
slideSequences
中列出，不属于主流程导航——除非触发热点，否则播放器不会访问它们。
导航模型：
  • 点击热点会将
    {sequenceId, slideIndex: 0}
    推入导航栈，并进入分支的第一张幻灯片。
  • back()：弹出栈顶元素，返回触发热点的父幻灯片（精确位置）。
  • backToMain()：清空整个导航栈，返回主流程的第一张幻灯片。
  • 面包屑根据导航栈渲染：
    主演示文稿 › 市场规模测算方法 › 第2页
    。
  • 分支内的幻灯片计数器仅针对当前序列（显示「2/2」，而非主演示文稿的总页数）。
注意事项：
  • 请勿将分支场景ID添加到主
    slides
    数组中。它们只能出现在
    slideSequences
    条目内。lint规则会标记重叠情况。
  • 分支场景包含在连续时间线中，因此直接导出线性视频会包含这些分支。目前导出功能仅读取主流程幻灯片（该功能暂未实现，已在规范中标记）。

Worked example: 3-slide deck with fragments and a branch

示例：包含分段展示和分支的3页演示文稿

Scene HTML (skeleton)

场景HTML（框架）

html
<body style="margin: 0">
  <script type="application/hyperframes-slideshow+json">
    {
      "slides": [
        {
          "sceneId": "hook",
          "notes": "Open with the stat. Pause on the $40B number."
        },
        {
          "sceneId": "problem",
          "notes": "Walk through each pain point one at a time.",
          "fragments": [11.0, 15.0],
          "hotspots": [
            {
              "id": "h1",
              "label": "Where does the $40B figure come from?",
              "target": "market-detail",
              "region": { "x": 55, "y": 60, "w": 40, "h": 20 }
            }
          ]
        },
        {
          "sceneId": "solution",
          "notes": "One sentence: what we do and who it is for."
        }
      ],
      "slideSequences": [
        {
          "id": "market-detail",
          "label": "Market sizing methodology",
          "slides": [{ "sceneId": "mkt-math", "notes": "Bottom-up: 2.3M SMBs × $17k ACV." }]
        }
      ]
    }
  </script>

  <!-- Slide 1 — hook -->
  <div
    data-composition-id="hook"
    data-start="0"
    data-duration="6"
    data-label="The hook"
    data-width="1920"
    data-height="1080"
    style="position: relative; width: 1920px; height: 1080px; overflow: hidden; background: #0a0a0a"
  >
    <section
      class="clip"
      data-start="0"
      data-duration="6"
      data-track-index="1"
      style="position: absolute; inset: 0; display: grid; place-items: center"
    >
      <h1 id="hook-headline" style="font-size: 80px; color: #fff; font-family: sans-serif">
        SMBs lose $40B/year to manual scheduling
      </h1>
    </section>
  </div>

  <!-- Slide 2 — problem (3 fragments) -->
  <div
    data-composition-id="problem"
    data-start="6"
    data-duration="15"
    data-label="The problem"
    data-width="1920"
    data-height="1080"
    style="position: relative; width: 1920px; height: 1080px; overflow: hidden; background: #0a0a0a"
  >
    <section
      class="clip"
      data-start="6"
      data-duration="15"
      data-track-index="1"
      style="position: absolute; inset: 0; padding: 120px 160px; box-sizing: border-box"
    >
      <h2 id="pain-headline" style="font-size: 64px; color: #fff; font-family: sans-serif">
        Three gaps operators can not close
      </h2>
      <p id="pain-1" style="font-size: 48px; color: #ccc; opacity: 0; font-family: sans-serif">
        No-shows cost 23% of booked revenue
      </p>
      <p id="pain-2" style="font-size: 48px; color: #ccc; opacity: 0; font-family: sans-serif">
        Manual reminders take 4h/week per staff
      </p>
      <p id="pain-3" style="font-size: 48px; color: #ccc; opacity: 0; font-family: sans-serif">
        Rescheduling friction drives 40% churn
      </p>
    </section>
  </div>

  <!-- Slide 3 — solution -->
  <div
    data-composition-id="solution"
    data-start="21"
    data-duration="8"
    data-label="The solution"
    data-width="1920"
    data-height="1080"
    style="position: relative; width: 1920px; height: 1080px; overflow: hidden; background: #0a0a0a"
  >
    <section
      class="clip"
      data-start="21"
      data-duration="8"
      data-track-index="1"
      style="position: absolute; inset: 0; display: grid; place-items: center"
    >
      <h2 id="solution-headline" style="font-size: 72px; color: #fff; font-family: sans-serif">
        Acme automates scheduling for service SMBs — no-shows down 80% in 90 days
      </h2>
    </section>
  </div>

  <!-- Branch slide — excluded from main line -->
  <div
    data-composition-id="mkt-math"
    data-start="29"
    data-duration="7"
    data-label="Market math"
    data-width="1920"
    data-height="1080"
    style="position: relative; width: 1920px; height: 1080px; overflow: hidden; background: #111"
  >
    <section
      class="clip"
      data-start="29"
      data-duration="7"
      data-track-index="1"
      style="position: absolute; inset: 0; display: grid; place-items: center"
    >
      <p id="mkt-formula" style="font-size: 56px; color: #fff; font-family: sans-serif">
        2.3M SMBs × $17k ACV = $39B serviceable market
      </p>
    </section>
  </div>

  <script>
    window.__timelines = window.__timelines || {};

    // Slide 2 fragment entrance animations
    gsap.registerPlugin(); // load any plugins before use

    const tl = gsap.timeline({ paused: true });
    window.__timelines["problem"] = tl;

    // Insert positions are absolute composition-timeline times (same as data-start / fragment values).
    tl.from("#pain-1", { opacity: 0, y: 20, duration: 0.4 }, 11.0);
    tl.from("#pain-2", { opacity: 0, y: 20, duration: 0.4 }, 15.0);
    // pain-3 lands at end of slide
    tl.from("#pain-3", { opacity: 0, y: 20, duration: 0.4 }, 13.0);
  </script>
</body>
html
<body style="margin: 0">
  <script type="application/hyperframes-slideshow+json">
    {
      "slides": [
        {
          "sceneId": "hook",
          "notes": "Open with the stat. Pause on the $40B number."
        },
        {
          "sceneId": "problem",
          "notes": "Walk through each pain point one at a time.",
          "fragments": [11.0, 15.0],
          "hotspots": [
            {
              "id": "h1",
              "label": "Where does the $40B figure come from?",
              "target": "market-detail",
              "region": { "x": 55, "y": 60, "w": 40, "h": 20 }
            }
          ]
        },
        {
          "sceneId": "solution",
          "notes": "One sentence: what we do and who it is for."
        }
      ],
      "slideSequences": [
        {
          "id": "market-detail",
          "label": "Market sizing methodology",
          "slides": [{ "sceneId": "mkt-math", "notes": "Bottom-up: 2.3M SMBs × $17k ACV." }]
        }
      ]
    }
  </script>

  <!-- Slide 1 — hook -->
  <div
    data-composition-id="hook"
    data-start="0"
    data-duration="6"
    data-label="The hook"
    data-width="1920"
    data-height="1080"
    style="position: relative; width: 1920px; height: 1080px; overflow: hidden; background: #0a0a0a"
  >
    <section
      class="clip"
      data-start="0"
      data-duration="6"
      data-track-index="1"
      style="position: absolute; inset: 0; display: grid; place-items: center"
    >
      <h1 id="hook-headline" style="font-size: 80px; color: #fff; font-family: sans-serif">
        SMBs lose $40B/year to manual scheduling
      </h1>
    </section>
  </div>

  <!-- Slide 2 — problem (3 fragments) -->
  <div
    data-composition-id="problem"
    data-start="6"
    data-duration="15"
    data-label="The problem"
    data-width="1920"
    data-height="1080"
    style="position: relative; width: 1920px; height: 1080px; overflow: hidden; background: #0a0a0a"
  >
    <section
      class="clip"
      data-start="6"
      data-duration="15"
      data-track-index="1"
      style="position: absolute; inset: 0; padding: 120px 160px; box-sizing: border-box"
    >
      <h2 id="pain-headline" style="font-size: 64px; color: #fff; font-family: sans-serif">
        Three gaps operators can not close
      </h2>
      <p id="pain-1" style="font-size: 48px; color: #ccc; opacity: 0; font-family: sans-serif">
        No-shows cost 23% of booked revenue
      </p>
      <p id="pain-2" style="font-size: 48px; color: #ccc; opacity: 0; font-family: sans-serif">
        Manual reminders take 4h/week per staff
      </p>
      <p id="pain-3" style="font-size: 48px; color: #ccc; opacity: 0; font-family: sans-serif">
        Rescheduling friction drives 40% churn
      </p>
    </section>
  </div>

  <!-- Slide 3 — solution -->
  <div
    data-composition-id="solution"
    data-start="21"
    data-duration="8"
    data-label="The solution"
    data-width="1920"
    data-height="1080"
    style="position: relative; width: 1920px; height: 1080px; overflow: hidden; background: #0a0a0a"
  >
    <section
      class="clip"
      data-start="21"
      data-duration="8"
      data-track-index="1"
      style="position: absolute; inset: 0; display: grid; place-items: center"
    >
      <h2 id="solution-headline" style="font-size: 72px; color: #fff; font-family: sans-serif">
        Acme automates scheduling for service SMBs — no-shows down 80% in 90 days
      </h2>
    </section>
  </div>

  <!-- Branch slide — excluded from main line -->
  <div
    data-composition-id="mkt-math"
    data-start="29"
    data-duration="7"
    data-label="Market math"
    data-width="1920"
    data-height="1080"
    style="position: relative; width: 1920px; height: 1080px; overflow: hidden; background: #111"
  >
    <section
      class="clip"
      data-start="29"
      data-duration="7"
      data-track-index="1"
      style="position: absolute; inset: 0; display: grid; place-items: center"
    >
      <p id="mkt-formula" style="font-size: 56px; color: #fff; font-family: sans-serif">
        2.3M SMBs × $17k ACV = $39B serviceable market
      </p>
    </section>
  </div>

  <script>
    window.__timelines = window.__timelines || {};

    // Slide 2 fragment entrance animations
    gsap.registerPlugin(); // load any plugins before use

    const tl = gsap.timeline({ paused: true });
    window.__timelines["problem"] = tl;

    // Insert positions are absolute composition-timeline times (same as data-start / fragment values).
    tl.from("#pain-1", { opacity: 0, y: 20, duration: 0.4 }, 11.0);
    tl.from("#pain-2", { opacity: 0, y: 20, duration: 0.4 }, 15.0);
    // pain-3 lands at end of slide
    tl.from("#pain-3", { opacity: 0, y: 20, duration: 0.4 }, 13.0);
  </script>
</body>

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.
  • 孤岛中的
    sceneId
    值（
    "hook"
    、
    "problem"
    、
    "solution"
    、
    "mkt-math"
    ）与场景div的
    data-composition-id
    值完全匹配。
  • mkt-math
    仅出现在
    slideSequences
    中——从未加入顶层
    slides
    数组。
  • 分段时间（
    11.0
    、
    15.0
    ）处于
    problem
    场景的
    [6, 21]
    范围内（时间为作品时间线的绝对位置）。
  • 热点
    region
    （
    x: 55, y: 60, w: 40, h: 20
    ）将可点击区域定位在problem幻灯片的右下象限。
  • GSAP时间线注册在
    window.__timelines
    上且处于暂停状态——由HyperFrames引擎驱动播放；请勿在初始化时调用
    .play()
    。

Wrapping component

包装组件

Wrap the composition in 
<hyperframes-slideshow>
around 
<hyperframes-player>
in any embedding context:
html
<hyperframes-slideshow>
  <hyperframes-player src="deck.html"></hyperframes-player>
</hyperframes-slideshow>
<hyperframes-slideshow>
provides the navigation chrome (Prev / Next buttons, progress dots, breadcrumb, counter), keyboard handling (← / → and Space / Backspace), touch swipe, and hotspot overlays.
Presenter mode: the Present button calls 
window.open('?mode=audience')
for a fullscreen audience window; the originating tab becomes the presenter view (current slide reduced, next-slide preview, notes, elapsed timer). Both windows sync via 
BroadcastChannel('hf-slideshow')
.
在任何嵌入环境中，将作品包裹在
<hyperframes-slideshow>
组件内，内部嵌套
<hyperframes-player>
：
html
<hyperframes-slideshow>
  <hyperframes-player src="deck.html"></hyperframes-player>
</hyperframes-slideshow>
<hyperframes-slideshow>
提供导航控件（上一页/下一页按钮、进度点、面包屑、计数器）、键盘操作支持（←/→以及空格键/退格键）、触摸滑动和热点覆盖层。
**演讲者模式：**点击「演示」按钮会调用
window.open('?mode=audience')
打开全屏观众窗口；原标签页变为演讲者视图（当前幻灯片缩小、下一页预览、备注、计时）。两个窗口通过
BroadcastChannel('hf-slideshow')
同步。

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 four gaps: the player does not drive GSAP seek-timelines, the island must be duplicated into the wrapper, audio must live in the parent frame, and animations must be self-driving. 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.
长期方案是由引擎托管：
hyperframes preview --slideshow
/ 工作室演示模式将通过真实HyperFrames引擎托管作品，引擎驱动跳转时间线、处理手势框架并从作品中读取孤岛内容。该方案即将推出，建议在发布后优先使用。
在此之前，独立演示（通过浏览器中的裸播放器 bundle 打开作品，无引擎支持）需要解决四个问题：播放器无法驱动GSAP跳转时间线、孤岛内容必须复制到包装器中、音频必须放在父框架中、动画必须自驱动。这些模式记录在：
skills/slideshow/references/standalone-harness.md
请勿将这些模式视为标准方案——它们仅用于在引擎托管方案推出前过渡使用。

Validation

验证

After authoring or editing a slideshow composition, run:
bash
npx hyperframes lint
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.
创作或编辑幻灯片作品后，请运行：
bash
npx hyperframes lint
幻灯片lint规则会检查：
  • 每个
    slide.sceneId
    都能解析到现有场景（通过
    data-composition-id
    ）。
  • 每个
    hotspot.target
    都引用已定义的
    slideSequence
    id。
  • 分段时间处于对应幻灯片的
    [start, end]
    范围内。
  • 主流程幻灯片之间无时间重叠。
预览前请修复所有违规项。未通过lint检查的作品无法在播放器中正确解析。