Initial commit after recreate

2026-04-11 09:21:22 +02:00
commit 02704133f4
378 changed files with 93091 additions and 0 deletions
@@ -0,0 +1,247 @@
+# Slide Template Guidelines
+
+This note gives a short “when to use it” rule for each supported GlitchPlayer slide template.
+
+The purpose is to help:
+
+- human authors
+- AI slide agents
+- editor integrations
+
+pick the simplest effective template for a given explanation beat.
+
+## General Rule
+
+Slides should not repeat the script.
+
+A slide should do one job:
+
+- show a visual
+- define a term
+- highlight a contrast
+- embed an interaction
+- frame a quote
+- focus attention on one equation
+
+If a slide is trying to do more than one of those at once, it is probably the wrong template.
+
+## Supported Templates
+
+## `SquareYellow`
+
+Use when:
+
+- one image does most of the work
+- you need a short strong header
+- the talking head should stay visible beside or below the slide
+
+Good for:
+
+- mood
+- framing
+- one clear visual metaphor
+
+Avoid when:
+
+- the idea needs more than one sentence
+- the viewer needs to compare two things
+- the slide is mainly about numbers or interaction
+
+## `FullscreenSplit`
+
+Use when:
+
+- one image and one short text block should share attention
+- you want a clean fullscreen transition
+- you need to conceal a segment seam under the slide
+
+Good for:
+
+- contrast
+- one visual plus one claim
+- scene-setting slides
+
+Avoid when:
+
+- the text starts turning into a paragraph
+- the image is decorative rather than explanatory
+
+## `EquationFocus`
+
+Use when:
+
+- one equation is the main thing the viewer should understand
+- the script is defining a formula or symbolic relationship
+
+Good for:
+
+- definitions
+- identities
+- simple derivation checkpoints
+
+Authoring rule:
+
+- keep the header short
+- keep the title short
+- use one LaTeX expression only
+- annotation should explain the equation in plain language
+
+Avoid when:
+
+- you need to compare two equations
+- the expression is too large or multi-step
+
+## `QuoteImage`
+
+Use when:
+
+- a quote is the slide
+- the image is there to support emotional or contextual framing
+
+Good for:
+
+- rhetorical emphasis
+- historical voice
+- strong claims
+
+Avoid when:
+
+- the quote is longer than the viewer can absorb quickly
+- the image is carrying a second unrelated message
+
+## `ChartSingle`
+
+Use when:
+
+- one compact chart tells the story
+- you are comparing a few values
+- the script needs one clean quantitative contrast
+
+Good for:
+
+- 3 to 5 bars
+- one pattern
+- one takeaway
+
+Authoring rule:
+
+- use a short header
+- keep the title direct
+- body is optional and should be brief
+- label names should be short
+
+Avoid when:
+
+- the viewer needs to inspect lots of data
+- the chart needs axes, legends, or technical notation to make sense
+
+## `ProcessFlow`
+
+Use when:
+
+- the script is describing a pipeline or mechanism
+- the viewer needs sequence, not comparison
+
+Good for:
+
+- 3 to 5 steps
+- causal flow
+- product/process explanations
+
+Avoid when:
+
+- the steps are too wordy
+- the process is branching or deeply conditional
+
+## `DefinitionCard`
+
+Use when:
+
+- the job of the slide is to define one concept
+- the audience needs a crisp shared term before moving on
+
+Good for:
+
+- vocabulary
+- named concepts
+- framing a new abstraction
+
+Authoring rule:
+
+- header is context
+- term is the anchor
+- definition is plain language
+- example is concrete
+
+Avoid when:
+
+- the concept needs a diagram more than text
+
+## `GlitchComponentFrame`
+
+Use when:
+
+- the explanation becomes clearer if the viewer can manipulate the model directly
+- the slide should host a real interactive Glitch component
+- the script benefits from 3D, simulation, or hands-on exploration
+
+Good for:
+
+- 3D scenes
+- parameterized simulations
+- interactive paradoxes
+- exploratory visual models
+
+This template is intended for hosted Glitch components, not static images.
+
+Current contract:
+
+- `header`
+- `componentId`
+- `componentUrl`
+- `caption`
+
+Current runtime model:
+
+- the slide embeds the component in an `iframe`
+- the component is expected to be hosted independently
+- if `componentUrl` is omitted, the player resolves a default path from:
+  - `VITE_GLITCH_COMPONENT_BASE_URL`
+  - the convention `glitch_${componentId.replace(/-/g, "_")}`
+  - and targets that component's `index.html`
+- the player treats it as an interactive surface
+
+Guidelines:
+
+- use this only when interaction adds real explanatory value
+- prefer a stable hosted URL or a stable `public/glitch/...` deployment path
+- keep the header short
+- caption should explain what the viewer should try or notice
+- assume the component itself provides the deeper interaction
+
+Avoid when:
+
+- a static image would do the job
+- the component is still too unstable to embed
+- the interaction is not tied to the narrated idea
+
+## Choosing Between Static And Interactive
+
+Default to a static template first.
+
+Use `GlitchComponentFrame` only if at least one of these is true:
+
+- the viewer learns by manipulating parameters
+- the shape, motion, or geometry matters
+- the explanation is weaker as a static image
+- the component can stand on its own as a small exploratory object
+
+If not, use:
+
+- `SquareYellow`
+- `FullscreenSplit`
+- `ChartSingle`
+- `EquationFocus`
+- `DefinitionCard`
+
+Those will usually produce a cleaner lecture.