Presentation Mode Reference
Technical reference for presentation mode including step structure, intent types, visibility actions, viewport animation, tween engine, and playback configuration.
This reference documents the technical specifications for presentation mode, including data structures, animation system, playback configuration, and performance characteristics.
Architecture Overview
Presentation mode uses a sparse intent architecture where each step stores only the changes from the previous step, not the full diagram state.
Step Structure
Each presentation step contains the following properties:
Intent Types
Four intent types describe the changes that occur at each step.
| Intent Type | Purpose | Key Properties |
|---|---|---|
| add | Element appears in this step | addedObject (full shape or connection) |
| remove | Element disappears from this step | targetId only |
| modify | Element properties change | changes (sparse diff of changed properties) |
| visibility | Element fades in/out | visibilityAction (action type and direction) |
Visibility Actions
Four visibility action types control how elements appear and disappear.
| Action | Animation | Direction Support | Use Case |
|---|---|---|---|
| appear | Instant show | No | Immediate visibility without transition |
| disappear | Instant hide | No | Immediate removal without transition |
| fadeIn | Opacity 0 to 1 | No | Gentle introduction of elements |
| fadeOut | Opacity 1 to 0 | No | Graceful removal of elements |
Viewport Structure
The viewport defines the visible area and zoom level for a step.
Configuration Object
The presentation configuration controls playback behaviour.
Exit Animation Types
Six exit animation types are available for after the final step.
| Type | Effect | Duration |
|---|---|---|
| none | Stop at final frame, diagram remains visible | N/A |
| fadeOut | Entire diagram fades to transparent | 1000ms |
| scaleDown | Diagram shrinks while fading out | 1000ms |
| slideOutLeft | Diagram slides off to the left | 1000ms |
| slideOutRight | Diagram slides off to the right | 1000ms |
| slideOutUp | Diagram slides off upward | 1000ms |
| slideOutDown | Diagram slides off downward | 1000ms |
Tween Engine
The tween engine interpolates between step states for smooth 60fps animation.
State Resolution
The state resolver reconstructs the full diagram state at any step by applying intents forward from the base state.
True Base Computation
When a document with presentation steps is loaded, elements added in step intents must be filtered from the base state.
The algorithm:
- Collect all element IDs from
addintents across all steps - Filter
document.shapesto exclude these IDs - The result is the "true base" containing only original elements
This prevents elements added mid-presentation from appearing at step 0.
Playback Controller
The playback controller manages animation timing and state updates.
| Feature | Description |
|---|---|
| State caching | All step states pre-computed on initialisation |
| Animation loop | requestAnimationFrame for 60fps rendering |
| Step navigation | Jump to any step instantly |
| Play/Pause/Stop | Full playback control |
| Speed multiplier | 0.5x, 1x, 2x, or custom |
| Loop mode | Smooth restart after final step |
| Reduced motion | Respects prefers-reduced-motion media query |
Accessibility
Presentation mode includes built-in accessibility features.
Performance Characteristics
Understanding performance helps optimise presentations for smooth playback.
| Operation | Complexity | Notes |
|---|---|---|
| Resolve state at step N | O(N x S) | N elements, S steps to target |
| Diff two states | O(N) | Linear scan with deep diff |
| Pre-compute all states | O(S x N) | Done once on initialisation |
| Interpolate single frame | O(N) | Linear over all elements |
| Deep clone | O(N) | JSON.parse(JSON.stringify) |
File Structure
Presentation data can be stored within a diagram document or as a standalone presentation file.
interface PresentationDiagramDocument {
schemaVersion: string;
id: string;
type?: 'presentation'; // Set for standalone files
shapes: DiagramShapeState[];
connections: DiagramConnectionState[];
presentationConfig?: PresentationConfig;
presentationSteps?: PresentationStep[];
}The presentationConfig and presentationSteps fields are optional. When absent, the diagram has no presentation and displays as a static diagram.
Standalone Presentation Files
Presentations can be saved as standalone .presentation.json files alongside the diagram they are derived from. These files have type: 'presentation' set and contain the full presentation definition: base shapes, connections, animation steps, and configuration.
| Aspect | Description |
|---|---|
| File extension | .presentation.json |
| Naming convention | [diagram-name].[slug].presentation.json |
| Type field | type: 'presentation' |
| Content block | presentation-diagram (in Diagrams category) |
| Discovery | Diagram blocks auto-discover sibling presentation files |
| Published viewer | Standalone presentations appear as additional tabs |
Content Block Playback
The Presentation Diagram content block embeds standalone presentations with step navigation controls. All steps are pre-rendered on load using the state resolver for instant navigation.
| Control | Behaviour |
|---|---|
| Previous button | Navigate to previous step (disabled at step 1) |
| Step counter | Displays current position, e.g. 3 / 12 |
| Next button | Navigate to next step (disabled at final step) |