ev-interactivity-core 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,158 @@
+//#region src/types.d.ts
+type SceneId = string;
+/** Geometry in percent of the player viewport, top-left anchored. All values 0–100. */
+interface Position {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+interface ButtonStyle {
+  btnBg: string;
+  /** Text colour. Name kept for backward-compat with persisted interactions. */
+  textBg: string;
+}
+type Action = {
+  type: "next_scene";
+} | {
+  type: "go_to_scene";
+  targetSceneId: SceneId;
+} | {
+  type: "open_url";
+  url: string;
+  target: "_blank" | "_self";
+} | {
+  type: "end_video";
+};
+interface QuizOption {
+  id: string;
+  label: string;
+  correct: boolean;
+}
+interface InteractionBase {
+  id: string;
+  timeStart: number;
+  timeEnd: number;
+  position: Position;
+  waitForClick: boolean;
+  /** Gate: the learner cannot skip past or resume until this is satisfied. */
+  required?: boolean;
+}
+interface ButtonInteraction extends InteractionBase {
+  type: "button";
+  label: string;
+  style: ButtonStyle;
+  action: Action;
+}
+interface SingleChoiceInteraction extends InteractionBase {
+  type: "single_choice";
+  question: string;
+  options: QuizOption[];
+  action: Action;
+}
+interface MultiChoiceInteraction extends InteractionBase {
+  type: "multi_choice";
+  question: string;
+  options: QuizOption[];
+  action: Action;
+}
+type Interaction = ButtonInteraction | SingleChoiceInteraction | MultiChoiceInteraction;
+interface ScenesShape {
+  id: SceneId;
+  order: number;
+  interactions?: Interaction[];
+  terminal?: boolean;
+}
+type NavigateIntent = {
+  type: "navigate";
+  sceneId: SceneId | null;
+};
+type PauseIntent = {
+  type: "pause";
+};
+type SeekIntent = {
+  type: "seek";
+  time: number;
+};
+type OpenUrlIntent = {
+  type: "open_url";
+  url: string;
+  target: "_blank" | "_self";
+};
+type Intent = NavigateIntent | PauseIntent | SeekIntent | OpenUrlIntent;
+//#endregion
+//#region src/schema.d.ts
+declare function parseInteractionsSafe(raw: unknown): Interaction[];
+//#endregion
+//#region src/resolver.d.ts
+declare function resolveAction(scenes: ScenesShape[], currentId: SceneId, action: Action): NavigateIntent | OpenUrlIntent;
+//#endregion
+//#region src/navigation.d.ts
+/** The next scene in display order after `currentId`, or null if it is last/unknown. */
+declare function nextSceneByOrder(scenes: ScenesShape[], currentId: SceneId): SceneId | null;
+//#endregion
+//#region src/visibility.d.ts
+/** Visible while the playhead is in [timeStart, timeEnd). A waitForClick interaction
+*  gates playback and stays visible from timeStart regardless of timeEnd (its window
+*  is the pause, not a fixed duration). */
+declare function getVisibleInteractions(scene: ScenesShape | undefined, currentTime: number): Interaction[];
+//#endregion
+//#region src/schedule.d.ts
+/** A scene's playback length, supplied by the host (e.g. from the rendered composition). */
+interface SceneTiming {
+  id: SceneId;
+  duration: number;
+}
+interface SceneLocation {
+  sceneId: SceneId;
+  localTime: number;
+}
+/**
+* Maps between a merged/global timeline (scenes played back-to-back) and
+* per-scene local time. Pure: the host owns the clock and scene durations,
+* core owns the arithmetic so every player agrees on it.
+*/
+interface Schedule {
+  /** Total duration of all scenes. */
+  readonly total: number;
+  /** Global start offset of a scene, or null if the scene is unknown. */
+  startOf(sceneId: SceneId): number | null;
+  /** Scene playing at a given global time (clamps to the last scene past the end). */
+  locate(globalTime: number): SceneLocation | null;
+}
+declare function createSchedule(timings: SceneTiming[]): Schedule;
+/**
+* A concrete instruction for a player host to execute. Decouples the intent
+* (what the interaction means) from the engine (how the host plays it), so the
+* in-app preview and the learner-facing player share identical navigation logic.
+*/
+type PlayerCommand = {
+  type: "seek";
+  time: number;
+} | {
+  type: "open_url";
+  url: string;
+  target: "_blank" | "_self";
+} | {
+  type: "pause";
+} | {
+  type: "end";
+};
+/** Resolve a player Intent into a host-agnostic command, using the schedule for navigation. */
+declare function resolveIntentCommand(intent: Intent, schedule: Schedule): PlayerCommand;
+//#endregion
+//#region src/graph.d.ts
+interface BrokenLink {
+  sceneId: SceneId;
+  interactionId: string;
+  targetSceneId: SceneId;
+}
+interface GraphValidationResult {
+  orphans: SceneId[];
+  deadEnds: SceneId[];
+  brokenLinks: BrokenLink[];
+}
+declare function validateGraph(scenes: ScenesShape[]): GraphValidationResult;
+//#endregion
+export { type Action, type BrokenLink, type ButtonInteraction, type ButtonStyle, type GraphValidationResult, type Intent, type Interaction, type MultiChoiceInteraction, type NavigateIntent, type OpenUrlIntent, type PauseIntent, type PlayerCommand, type Position, type QuizOption, type SceneId, type SceneLocation, type SceneTiming, type ScenesShape, type Schedule, type SeekIntent, type SingleChoiceInteraction, createSchedule, getVisibleInteractions, nextSceneByOrder, parseInteractionsSafe, resolveAction, resolveIntentCommand, validateGraph };
+//# sourceMappingURL=index.d.mts.map