@markgrafhq/markgraf-react 0.0.26 → 0.0.28

package/dist/markgraf-react.css

@@ -22,8 +22,10 @@
   overflow: hidden;
 }
 
-.markgraf-embed canvas[data-mg="stage"] {
+.markgraf-embed canvas[data-mg="stage"],
+.markgraf-embed svg[data-mg="stage"] {
   width: 100%;
+  height: auto;
   display: block;
   max-height: var(--mg-max-height, 90svh);
   object-fit: contain;

package/dist/markgraf-react.d.ts

@@ -3,6 +3,51 @@
 
 import type { FC, MutableRefObject } from "react";
 
+export type MarkgrafCueKind = "step" | "tokenLine";
+export type MarkgrafPlaybackDirection = "auto" | "forward" | "backward";
+
+export interface MarkgrafPlaybackOptions {
+  direction?: MarkgrafPlaybackDirection;
+  speed?: number;
+  duration?: number;
+  loop?: boolean;
+  stopAt?: MarkgrafCueKind[];
+}
+
+export interface MarkgrafCueBase {
+  readonly id: string;
+  readonly index: number;
+  readonly kind: MarkgrafCueKind;
+  readonly time: number;
+  readonly endTime: number;
+  readonly path: readonly string[];
+}
+
+export interface MarkgrafStepCue extends MarkgrafCueBase {
+  readonly kind: "step";
+  readonly name: string;
+}
+
+export interface MarkgrafTokenLineCue extends MarkgrafCueBase {
+  readonly kind: "tokenLine";
+  readonly tokenIndex: number;
+  readonly lineIndex: number;
+  readonly text: string;
+  readonly from: string;
+  readonly to: string;
+}
+
+export type MarkgrafCue = MarkgrafStepCue | MarkgrafTokenLineCue;
+
+export interface MarkgrafCompleteEvent {
+  readonly reason: "target" | "boundary" | string;
+  readonly direction: "forward" | "backward";
+  readonly targetId: string;
+  readonly targetStep: string;
+  readonly reached: boolean;
+  readonly time: number;
+}
+
 /**
  * Reactive view of a mounted markgraf player.  `time`, `keyframe`, and
  * `playing` update on every animation frame; the imperative methods are
@@ -27,21 +72,25 @@ export interface MarkgrafApi<E extends Element = HTMLCanvasElement> {
   readonly duration: number;
   /** `true` once parse + layout + first render have completed. */
   readonly ready: boolean;
-  play(): void;
+  readonly cues: readonly MarkgrafCue[];
+  readonly steps: readonly MarkgrafStepCue[];
+  play(options?: MarkgrafPlaybackOptions): void;
+  playWith(options?: MarkgrafPlaybackOptions): void;
   pause(): void;
   toggle(): void;
   /** Clamped to `[0, duration]`.  Pauses the player. */
   seek(seconds: number): void;
+  seekCue(cueId: string): void;
+  seekStep(stepName: string): void;
+  playToCue(cueId: string, options?: MarkgrafPlaybackOptions): void;
+  playToStep(stepName: string, options?: MarkgrafPlaybackOptions): void;
+  playNext(options?: MarkgrafPlaybackOptions): void;
+  playPrevious(options?: MarkgrafPlaybackOptions): void;
   /** `1.0` is normal playback speed. */
   setSpeed(speed: number): void;
-  /**
-   * Register a callback that fires every time the player enters the named
-   * keyframe.  Fires immediately if already in that frame.  Returns an
-   * unsubscribe function.
-   */
-  onFrameEnter(frameName: string, callback: () => void): () => void;
-  /** Seek to the start of the named keyframe.  No-op if the frame doesn't exist. */
-  seekFrame(frameName: string): void;
+  onCueEnter(callback: (cue: MarkgrafCue) => void): () => void;
+  onStepEnter(stepName: string, callback: (cue: MarkgrafStepCue) => void): () => void;
+  onComplete(callback: (event: MarkgrafCompleteEvent) => void): () => void;
 }
 
 export interface UseMarkgrafOptions<R extends "canvas" | "svg" = "canvas"> {
@@ -82,8 +131,13 @@ export function useMarkgraf(
 
 export interface MarkgrafPlayerProps {
   src: string;
-  /** `"canvas"` (default) or `"svg"`. */
-  renderer?: "canvas" | "svg";
+  /**
+   * `"canvas"` (default), `"svg"`, or `"sdf"` (alias `"webgl"`) — the WebGL
+   * raymarched 3D renderer.  The SDF renderer is self-driving: it ignores
+   * `width`/`height` (it fills its container) and isn't available through the
+   * lower-level `useMarkgraf` hook.
+   */
+  renderer?: "canvas" | "svg" | "sdf" | "webgl";
   /** Visual theme. `"light"` (default), `"dark"`, or `"blueprint"`. */
   theme?: "light" | "dark" | "blueprint";
   /** When `true`, skip the background fill so the page bg shows through. */