Autorenvertrag für Slideshows
Eine HyperFrames-Slideshow ist eine normale HyperFrames-Komposition — Szenen, Clips, GSAP-Timelines — mit einer zusätzlichen Zutat: einer JSON-Insel, die deklariert, welche Szenen Folien sind und wie sie zusammenhängen. Der SlideshowController des Players liest die Insel und verwandelt die kontinuierliche GSAP-Timeline in ein diskretes, navigierbares Deck.
Lies zuerst /hyperframes-core für den grundlegenden Kompositionsvertrag (Clips, Tracks, data-*-Attribute, Determinismus-Regeln). Diese Fähigkeit behandelt nur das, was neu ist: das Insel-Schema, Schreibregeln für Folien, Fragmente, Verzweigungen, Validierung und die umschließende Komponente.
Ausgabe — ein navigierbares Deck, kein lineares MP4
Die Ausgabe einer Slideshow ist das laufende Deck: Serviere es mit hyperframes present <project-dir> (oder dem Studio-Präsentationsmodus) — der SlideshowController des Players liest die Insel und steuert Navigation, Fragmente, Verzweigungen und den Präsentatormodus. Siehe Präsentation und Übergabe unten.
Führe hyperframes render nicht für eine Slideshow aus, um ein einzelnes MP4 zu erstellen. Ein Deck wird als mehrere Szenenkompositionen auf oberster Ebene (eine data-composition-id pro Folie) ohne übergeordnete Root-Komposition erstellt, die sie umschließt. Daher löst render nur die erste Komposition auf und gibt ein stillschweigend abgeschnittenes MP4 aus (z. B. 6 Sekunden eines 40-Sekunden-Decks). Ein linearer Hauptlinien-Export (nur Hauptfolien, ohne Verzweigungssequenzen) ist zurückgestellt — bis er ausgeliefert ist, sind die unterstützten Ausgaben das Live-present-Deck und snapshot-Standbilder pro Folie. Wenn ein Benutzer heute ein lineares MP4 benötigt, zeige diese Einschränkung auf, anstatt render auf das Deck zu verweisen.
Absichtsbestätigung
Wenn der Benutzer explizit nach einer Slideshow, Diashow oder HyperFrames-Slideshow fragt, fahre mit dieser Fähigkeit fort.
Wenn die Fähigkeit durch eine verwandte Anfrage wie „Präsentation“, „Pitch-Deck“, „Deck“, „interaktives Deck“ oder „diese Seite konvertieren“ ausgelöst wurde, halte vor dem Erstellen inne und skizziere die Wahl, bevor du um Bestätigung bittest. Erkläre kurz, dass eine HyperFrames-Slideshow ein ausführbares Deck mit diskreten Folien, integrierter Navigation und Präsentatormodus, bearbeitbaren Sprechernotizen, gemeinsam genutzter Medienverwaltung und Validierung vor der Übergabe bedeutet. Bei Quellseiten-Konvertierungen erwähne auch, dass das Ziel darin besteht, das visuelle Design der Originalseite, Interaktionen, Bewegungen und das Medienverhalten zu bewahren, während die Seitenbewegung in Folien-zu-Folien-Übergänge übersetzt wird.
Stelle dann eine kurze Bestätigungsfrage:
Möchtest du das als HyperFrames-Slideshow?
Verwende eine Ja/Nein-Auswahloberfläche, wenn die Umgebung eine bietet; ansonsten stelle die Frage in Klartext.
Setze die Slideshow erst um, wenn der Benutzer mit Ja antwortet. Wenn er Nein sagt, beende die Nutzung dieser Fähigkeit und wechsle zum entsprechenden Nicht-Slideshow-Workflow.
Die beiden Teile
1. Szenen — auf die normale Weise deklariert
Jede Folie wird durch eine Szene untermauert. Deklariere Szenen mit data-composition-id, data-start, data-duration und data-label:
<div
data-composition-id="problem"
data-start="0"
data-duration="8"
data-label="Das Problem"
data-width="1920"
data-height="1080"
>
<!-- Clips kommen hier hin -->
</div>
Verzweigungsfolien (nur über einen Hotspot erreichbar, von der Hauptlinie ausgeschlossen) werden auf die gleiche Weise deklariert — sie erscheinen nur in einem slideSequences-Eintrag in der Insel, nicht im Haupt-slides-Array.
2. Die JSON-Insel — ein Script-Block pro Komposition
Füge dem Kompositions-HTML genau einen <script type="application/hyperframes-slideshow+json">-Block hinzu. Er enthält alle Metadaten der Slideshow:
<script type="application/hyperframes-slideshow+json">
{
"slides": [...],
"slideSequences": [...]
}
</script>
Die Insel ist die einzige Quelle der Wahrheit für Folienreihenfolge, Notizen, Fragment-Haltepositionen, Hotspots und Verzweigungssequenzen. Halte sie in der Nähe des <body>-Anfangs, vor den Szenen-divs, damit sie leicht zu finden ist.
Verstecke das Slideshow-Manifest nicht hinter einem alternativen <script type="application/json">-Block plus Laufzeitcode, der die Insel erstellt. Der present-Befehl liest das Kompositions-HTML statisch und erwartet, dass die echte application/hyperframes-slideshow+json-Insel bereits vorhanden ist.
Schema
SlideshowManifest (das Insel-Objekt der obersten Ebene)
{
"slides": [
/* SlideRef[] — die Hauptlinie, in der Reihenfolge */
],
"slideSequences": [
/* SlideSequence[] — Offline-Verzweigungssequenzen */
]
}
SlideRef
{
"sceneId": "problem",
"notes": "Beginne mit dem Schmerz, nicht mit dem Unternehmen.",
"fragments": [3.5, 5.2, 7.0],
"hotspots": [
/* SlideHotspot[] */
],
"ttsScript": null,
"ttsAudioUrl": null,
"ttsDurationMs": null
}
| Feld | Erforderlich | Hinweise |
|---|---|---|
sceneId | ja | Muss exakt mit data-composition-id einer Szene übereinstimmen (oder explizite startTime/endTime angeben). Die Lint-Regel löst Szenen über data-composition-id auf. |
notes | nein | Nur für den Präsentator. Niemals dem Publikum gezeigt. |
fragments | nein | Array von Zeiten (Sekunden) innerhalb des [start, end]-Bereichs der Folie — siehe Fragmente unten. |
hotspots | nein | Interaktive Overlays, die eine Verzweigung auslösen — siehe Verzweigungen unten. |
startTime | nein | Optional. Überschreibt die zeitlichen Grenzen der gefundenen Szene; standardmäßig Start/Ende der Szene. |
endTime | nein | Optional. Überschreibt die zeitlichen Grenzen der gefundenen Szene; standardmäßig Start/Ende der Szene. |
ttsScript, ttsAudioUrl, ttsDurationMs | nein | Reserviert. Schema-Felder existieren, aber die TTS-Wiedergabe ist noch nicht verdrahtet. Weglassen, es sei denn, du befüllst sie für einen zukünftigen Build vor. |
SlideHotspot
{
"id": "h1",
"label": "Wie haben wir das berechnet?",
"target": "markttiefgang",
"region": { "x": 60, "y": 10, "w": 35, "h": 20 }
}
| Feld | Erforderlich | Hinweise |
|---|---|---|
id | ja | Eindeutig innerhalb der Folie. |
label | ja | Tooltip-/Schaltflächentext, der dem Publikum gezeigt wird. |
target | ja | Muss mit einer SlideSequence.id in slideSequences übereinstimmen. |
region | nein | Prozentualer Begrenzungsrahmen der Folie: {x, y, w, h} in 0–100. Weglassen, um den Hotspot als eine vollflächige beschriftete Schaltfläche darzustellen. |
SlideSequence
{
"id": "markttiefgang",
"label": "Methodik der Marktgrößenbestimmung",
"slides": [{ "sceneId": "mkt-1" }, { "sceneId": "mkt-2" }]
}
slides innerhalb einer Sequenz verwendet die gleiche SlideRef-Form wie die Hauptlinie. Fragmente und verschachtelte Hotspots sind erlaubt.
Schreibregeln für Folien
Dies sind harte Einschränkungen, keine Vorschläge. Eine Folie, die dagegen verstößt, wird bei der Prüfung durch einen Reviewer glatt ersetzt.
- Die Überschrift ist eine Behauptung in einem vollständigen Satz, kein Label. Schreibe „KMU verbringen 14 Stunden pro Woche mit manueller Terminplanung“, nicht „Planungsproblem“. Der Satz sollte auch dann für sich allein stehen, wenn die Grafik ignoriert wird.
- Eine Idee + eine Grafik pro Folie. Wenn du versucht bist, eine zweite Aufzählungsliste oder ein zweites Diagramm hinzuzufügen, teile die Folie auf.
- Beginne mit der Hauptaussage. Der stärkste Punkt kommt zuerst – auf der Folie und in der Reihenfolge des Decks. Investoren lesen von links nach rechts, von oben nach unten, und sie hören auf.
- Nur Bottom-up-Marktgrößenbestimmung. Schreibe niemals „50 Mrd. $ TAM“, ohne die Berechnung zu zeigen. Baue von den Einzelwirtschaftlichkeiten auf: Konten × ACV oder Transaktionen × Take-Rate.
- Schriftart mindestens 30pt Äquivalent. Bei 1920×1080 ist eine Überschrift 72–96px; Fließtext ist 48px. Gehe bei Text, den das Publikum lesen muss, niemals unter 40px.
Portieren von Quellseiten
Beim Konvertieren einer vorhandenen Seite in eine Slideshow ist die Quelltreue Teil des Vertrags. Ersetze quellspezifische Widgets nicht durch vereinfachte Annäherungen, es sei denn, der Benutzer bittet ausdrücklich um ein Redesign.
- Bewahre das visuelle Design der Originalseite, die Bewegungssprache, das interaktive Verhalten, das Medienverhalten und die Präsentationsmöglichkeiten so genau wie möglich. Wenn das Slideshow-System den Präsentatormodus unterstützt, füge Sprechernotizen mit dem gemeinsamen bearbeitbaren Notizverhalten ein, anstatt einer deckspezifischen Implementierung.
- Portiere mechanische Grafiken aus dem Quell-DOM/CSS/JS so genau wie praktikabel: Benutzerdefinierte Player, Canvas-Visualisierungen, Timelines, Abspielköpfe, Stems, sich ausdehnende Kreise, Hover-Zustände und andere interaktive Details sollten die Konvertierung überstehen.
- Behandle native
<video>-/<audio>-Elemente als Quelle der Wahrheit für jede benutzerdefinierte Medien-Chrome, Canvas-Visualisierung, Wellenform, Beat-Grid oder Abspielkopf. Verbinde die Medienereignisse der Quelle (play,pause,timeupdate,seeking,seeked,ended,ratechange,volumechange) und leite den visuellen Zustand vonmedia.currentTimeab; führe keinen separaten Timer aus, der von der tatsächlichen Wiedergabe abweichen kann. - Jedes kopierte
<video>oder<audio>mitsrcmuss vor dem Lint HyperFrames-Zeitattribute haben:data-startunddata-duration, plusdata-has-audio="true", wenn hörbares natives Audio erhalten bleiben soll. Verwende den Zeitbereich der Szene für folienspezifische Medien; für benutzergesteuerte Beweisvideos, die von mehreren fokussierten Folien aus abgespielt werden können, verwende einen deckweiten Bereich. Lassepreload="none"nicht auf Medien; verwendemetadataoderauto. - Löse Quell-Schriftart-Token vor der Validierung auf. Wenn benutzerdefinierte Quell-Schriftarten beibehalten werden, füge
@font-face-Regeln für lokale/erfasste Schriftdateien hinzu. Wenn System-Fallbacks verwendet werden, ersetze tokenisierte Deklarationen wiefont-family: var(--f-body)durch konkrete render-sichere Stapel wiesystem-ui, sans-serifoderui-monospace, monospace; lassevar(...)nicht als Schriftfamilienwert stehen. - Überprüfe die Quelle auf atypische Seitenbewegungen, insbesondere Verhalten, das durch Scrollen, Rad, Berührung, Hash-Zustand, Größenänderung oder eine requestAnimationFrame-Schleife gesteuert wird. Behandle feste Viewports mit übersetzten/skalierten „Welt“-Ebenen, Parallaxe, angehefteten Panels, horizontalen Scrollern, scrollgescrubbten Timelines, Abschnitts-Snapping und Zoom-zu-Element-Kameras als Quellverhalten. Scrollen ist oft der Auslöser für Übergänge in der Quelle, also bewahre den Übergang, indem du seine Fortschrittsstopps, Easing und Kamera-/Fokus-Zustände extrahierst und diese Bewegung dann auf die Slideshow-Navigation durch Timeline-Positionen, Fragmente oder einen wiederverwendbaren Player-/Harness-Hook überträgst. Eigenständige Wrapper, die zu Folienhaltepositionen springen, benötigen dennoch einen expliziten Navigations-Kamera-Übergangs-Hook; die Berechnung von Kamera-Transformationen pro Folie reicht nicht aus. Simuliere keinen buchstäblichen Seiten-Scroll-nach-unten-Übergang innerhalb der Folie; der Betrachter sollte eine Kamerareise/einen Zoom von einem Brennpunkt zum anderen spüren, nicht eine gescrollte Webseite sehen. Halte jeden Folien-zu-Folien-Kamera-Bewegung kontinuierlich: vermeide Zwischenrouten-Stopps, die die x/y-Richtung oder den Zoom umkehren, es sei denn, die Quelle tut dies sichtbar an derselben Grenze. Ein Übergang, der vor dem Landen herumirrt, ist schlimmer als ein einfacherer direkter Fokuswechsel.
- Bewahre die Medienzuschnitt-Semantik der Quelle. Behandle Screenshots, Tweets/Sozialbeiträge, Produkt-UI-Erfassungen, Diagramme, Dokumente, Code, Bestenlisten und alle Bilder mit lesbarem Text als Beweisinhalte, nicht als dekorative Medien: Verwende das Seitenverhältnis der Quelle (
height: auto) oderobject-fit: containinnerhalb eines stabilen Rahmens. Verwendeobject-fit: covernur, wenn die Quelle es tat, oder für absichtlich dekorative/Hintergrund-/filmische Miniaturansichten. Überprüfe nach dem Einfügen dieser Erfassungen in eine Folie alle vier Kanten auf abgeschnittenen Text, Logos, Bedienelemente oder Bildunterschriften; ein sichtbarer Zuschnitt bei sinnvollen Inhalten ist ein Fehler, es sei denn, die Quelle selbst hat ihn beschnitten. - Wenn ein Verhalten für Slideshows generisch ist, lege es im Player/Controller oder in einem wiederverwendbaren Skill-Snippet ab. Löse es nicht mit einmaligen Deck-Skripten.
- Gestapelte Szenen-Frames dürfen niemals die Interaktion auf der aktiven Folie blockieren. Versteckte Frames benötigen sowohl visuelles Verstecken als auch Ereignis-Sperrung:
.scene-frame {
opacity: 0;
visibility: hidden;
pointer-events: none;
}
.scene-frame.is-active {
opacity: 1;
visibility: visible;
pointer-events: auto;
}
Wenn Sichtbarkeit imperativ gesteuert wird, setze alle drei Eigenschaften (opacity, visibility und pointerEvents) im Sichtbarkeits-Controller. opacity: 0 allein hinterlässt immer noch eine unsichtbare Ebene, die Klicks verschlucken kann.
Fragmente: Enthüllungs-Haltepositionen innerhalb einer Folie
Ein Fragment ist eine absolute Zeit auf der Kompositions-Timeline (Sekunden) innerhalb des [start, end]-Bereichs einer Folie, an der der Controller einen Enthüllungszustand halten soll.
Wie es funktioniert:
- Der Player betritt eine fragmentierte Folie – er sucht direkt
fragments[0]auf und hält dort. - Der Benutzer drückt Weiter (oder →) – der Controller sucht
fragments[1]auf und hält. - Nach dem letzten Fragment rückt Weiter zur nächsten Folie vor.
- Eine Folie ohne Fragmente beginnt an einem Ruheframe innerhalb der Folie, normalerweise ihrem Mittelpunkt, nicht genau bei
slide.end.
Fragmentzeiten müssen innerhalb von [start, end] liegen.