@markgrafhq/markgraf-react 0.1.14 → 0.1.16

package/README.md

@@ -1,6 +1,6 @@
 # @markgrafhq/markgraf-react
 
-React hook + component for embedding [markgraf](https://github.com/i-am-the-slime/markgraf) animations. Drives play/pause/seek imperatively and exposes `time`, `currentKeyframe`, and `playing` as reactive state.
+React hook + component for embedding [markgraf](https://github.com/i-am-the-slime/markgraf) animations. Drives play/pause/seek imperatively and exposes `time`, `keyframe`, and `playing` as reactive state.
 
 ## Install
 
@@ -9,30 +9,31 @@ bun add @markgrafhq/markgraf-react
 # or: npm install @markgrafhq/markgraf-react
 ```
 
-Also pull in the embed CSS for canvas styling:
+Import the package CSS for player styling:
 
 ```js
-import "@markgrafhq/markgraf-embed/css";
+import "@markgrafhq/markgraf-react/css";
 ```
 
 ## `<MarkgrafPlayer src=... />`
 
-Headless component — renders a `<canvas>` (default) or `<svg>` with the scene drawn directly into it. Bring your own controls.
+Headless component that draws the scene directly into the selected Canvas2D, SVG, or WebGL surface. Bring your own controls.
 
 ```jsx
 import { MarkgrafPlayer } from "@markgrafhq/markgraf-react";
 
 const src = `seed 1
-keyframe v1 {
-  +node client "Client"
-  +node api "API"
-  +edge client api
-  client -> api "GET"
+scene v1 {
+  + client: Client
+  + api: API
+  + client -> api
+  client ~> api: GET
 }`;
 
 export default function App() {
   return <MarkgrafPlayer src={src} />;
   // Or: <MarkgrafPlayer src={src} renderer="svg" />
+  // Or: <MarkgrafPlayer src={src} renderer="sdf" />
 }
 ```
 
@@ -84,6 +85,7 @@ export function Player({ src }) {
 
 - **`canvas`** (default) — Canvas2D with DPR-aware scaling and label springs. Fastest, best for many tokens.
 - **`svg`** — Inline SVG. Easier to inspect/style, scales crisply at any zoom, no DPR concerns. No spring labels.
+- **`sdf`** (alias **`webgl`**) — WebGL raymarched 3D rendering; available through `MarkgrafPlayer` only.
 
 ## License
 

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. */