Class: Stage

Presentation director managing scenes, step transitions, snapshots, and the virtual viewport.

Constructors

Constructor

new Stage(options?: object): Stage

Initializes a new presentation Stage.

Parameters

Parameter	Type	Description
options	{ channel?: string | false; defaultDuration?: number; frameRate?: number | "auto"; height?: number; logLevel?: LogLevel; scale?: number; target?: string | HTMLElement; theme?: ThemeConfig; width?: number; }	-
options.channel?	string | false	BroadcastChannel name for dual-screen presenter console synchronization. Pass false to disable presenter sync (recommended for embedded component previews and unit tests). Default: "stageroutine-channel".
options.defaultDuration?	number	Default transition duration in seconds (default: 0.6).
options.frameRate?	number | "auto"	Animation update limit in frames per second; "auto" follows display refresh. Default: "auto".
options.height?	number	Virtual stage height in pixels (default: 1080 or environment config).
options.logLevel?	LogLevel	Minimum log level (default: "warn"). Set to "debug" for verbose output or "silent" to suppress all.
options.scale?	number	Global content scale factor for typography, spacing, and padding. Values below 1 shrink UI chrome; values above 1 enlarge it. Element positions and explicit dimensions (stage units) are not affected. Default: 1.
options.target?	string | HTMLElement	Target HTML container or CSS selector to mount into (default: document.body).
options.theme?	ThemeConfig	Initial theme color overrides (default: defaultDark).
options.width?	number	Virtual stage width in pixels (default: 1920 or environment config).

Returns

Stage

Remarks

As a side effect, the constructor sets this instance as the module-global activeStage singleton used by standalone component factories and motion helpers. Creating multiple Stage instances simultaneously in the same JS execution context will cause the latter instance to overwrite activeStage.

Properties

Property	Type
_metrics	MetricRegistry

Accessors

frameRate

Get Signature

get frameRate(): number | "auto"

Animation update limit in fps; "auto" follows display refresh. Default: "auto".

Returns

number | "auto"

Set Signature

set frameRate(value: number | "auto"): void

Parameters

Parameter	Type
value	number | "auto"

Returns

void

---

height

Get Signature

get height(): number

Virtual stage canvas height in pixels (default: 1080).

Returns

number

---

isMounted

Get Signature

get isMounted(): boolean

Returns

boolean

---

isMoving

Get Signature

get isMoving(): boolean

Whether the stage is currently animating. Default: false.

Returns

boolean

---

unitsTall

Get Signature

get unitsTall(): number

Stage height in stage units (always 90).

Returns

number

---

unitsWide

Get Signature

get unitsWide(): number

Stage width in stage units (160 on a 16:9 stage).

Returns

number

---

width

Get Signature

get width(): number

Virtual stage canvas width in pixels (default: 1920).

Returns

number

Methods

_cancelPropertyTransition()

_cancelPropertyTransition(elementId: string, property: string): void

Parameters

Parameter	Type
elementId	string
property	string

Returns

void

---

_getCurrentPropertyValue()

_getCurrentPropertyValue(elementId: string, property: string): unknown

Parameters

Parameter	Type
elementId	string
property	string

Returns

unknown

---

_recordAction()

_recordAction(action: () => void): void

Parameters

Parameter	Type
action	() => void

Returns

void

---

_recordMutation()

_recordMutation(elementId: string, property: string, from: unknown, to: unknown, durationMs: number, delayMs: number, curve: EaseCurve, triggerElementId?: string, triggerMilestone?: AnimationMilestone, triggerProperty?: string, motion?: PositionMotion): void

Parameters

Parameter	Type
elementId	string
property	string
from	unknown
to	unknown
durationMs	number
delayMs	number
curve	EaseCurve
triggerElementId?	string
triggerMilestone?	AnimationMilestone
triggerProperty?	string
motion?	PositionMotion

Returns

void

---

_registerPendingFlush()

_registerPendingFlush(flush: () => void): () => void

Parameters

Parameter	Type
flush	() => void

Returns

() => void

---

_setCurrentPropertyValue()

_setCurrentPropertyValue(elementId: string, property: string, value: unknown): void

Parameters

Parameter	Type
elementId	string
property	string
value	unknown

Returns

void

---

background()

background(bg: string | ReactiveElementBase | Background): this

Selects the background for subsequent steps. Default: theme canvas. Restored on navigation.

Parameters

Parameter	Type
bg	string | ReactiveElementBase | Background

Returns

this

Example

stage.background("#0f172a");
stage.background(Starfield());

---

dispose()

dispose(): void

Tears down the stage: stops animation loops and releases the background, overlays, element media, DOM, and communication resources.

Disposal is final. A disposed stage cannot be mounted again.

Returns

void

---

emit()

emit<K extends keyof StageEventMap>(event: K, ...args: StageEventMap[K] extends undefined ? [] : [StageEventMap[K]]): void

Type Parameters

Type Parameter
K extends keyof StageEventMap

Parameters

Parameter	Type
event	K
...args	StageEventMap[K] extends undefined ? [] : [StageEventMap[K]]

Returns

void

---

mount()

mount(target?: string | HTMLElement): this

Mounts the presentation stage into the target container element and begins playback.

Parameters

Parameter	Type
target?	string | HTMLElement

Returns

this

---

note()

note(text: string | string[]): this

Sets presenter speaker notes for the current step.

Parameters

Parameter	Type
text	string | string[]

Returns

this

---

notesDocument()

notesDocument(doc: string): this

Loads a full markdown presenter notes document for the presentation.

Parameters

Parameter	Type
doc	string

Returns

this

---

on()

on<K extends keyof StageEventMap>(event: K, handler: (data: StageEventMap[K]) => void): () => void

Type Parameters

Type Parameter
K extends keyof StageEventMap

Parameters

Parameter	Type
event	K
handler	(data: StageEventMap[K]) => void

Returns

() => void

---

overlay()

overlay(plugin: OverlayPlugin): this

Attaches an overlay plugin to the stage.

If the stage is already mounted, the overlay is mounted immediately. Otherwise it is queued and mounted when mount() is called.

Parameters

Parameter	Type
plugin	OverlayPlugin

Returns

this

Example

stage.overlay(NavigationOverlay());

---

pause()

pause(): void

Completes the current presentation step, recording pending mutations and transitions into a snapshot.

Returns

void

---

scene()

scene(name: string): Scene

Declares a new presentation scene and returns a builder to populate its elements.

Parameters

Parameter	Type
name	string

Returns

Scene

---

theme()

theme(config: ThemeConfig): this

Apply global or per-scene theme variable overrides. Updates CSS custom properties on the stage container and preserves them across step snapshots.

Parameters

Parameter	Type
config	ThemeConfig

Returns

this

Example

stage.theme({
  background: "#0f172a",
  surface: "#1e293b",
  surfaceBorderColor: "#334155",
  text: "#f8fafc",
});