@markdy/renderer-dom

Web Animations API renderer for MarkdyScript scenes. Translates a parsed AST into DOM elements and drives the animation timeline.

Features

• Browser-native — Web Animations API + CSS transforms, no Canvas or GSAP
• Auto-layout diagrams — renders positioned nodes and orthogonal, obstacle-aware edges from a compiled RenderPlan
• Flow edges — -> request, <- response, ~> event, -- dependency, each with its own stroke, plus a pulse that travels the edge as it draws
• Beat-driven cues — show, hide, glow, and focus, sequenced by named beats
• Semantic node cards — compact SVG glyphs for browsers, services, gateways, queues, workers, databases, storage, CDN, security, platform, and more
• Seek-safe — manual currentTime control enables reliable seek() in any direction
• Playback-rate controls — set timeline speed to slow down or speed up diagrams without rebuilding animations
• Semantic themes — midnight and paper, with per-role node colors
• Single dependency — only @markdy/core

Installation

pnpm add @markdy/core @markdy/renderer-dom

Package position (text)

@markdy/core -> @markdy/renderer-dom -> browser scene playback

This package consumes parsed AST and drives DOM + Web Animations API timelines.

Output preview

Usage

import { createPlayer } from "@markdy/renderer-dom";

const player = createPlayer({
  container: document.getElementById("scene")!,
  code: `
    scene "Request" theme=paper
    browser Web
    service API
    beat main:
      show $nodes
      Web -> API "GET /users"
  `,
  autoplay: true,
});

// Playback control
player.pause();
player.seek(1.5);   // jump to 1.5 seconds
player.play();
player.destroy();    // clean up DOM + cancel animations

API

createPlayer(options: PlayerOptions): Player

| Option | Type | Default | Description | |---|---|---|---| | container | HTMLElement | (required) | DOM element to mount the scene into | | code | string | (required) | MarkdyScript source code | | autoplay | boolean | true | Start playing immediately | | loop | boolean | true | Loop the animation when it reaches the end | | copyright | boolean | true | Show a small "Powered by Markdy" badge below the animation | | progressBar | boolean | true | Deprecated compatibility flag for the rainbow scene-boundary progress bar | | sceneBoundaryProgress | boolean | progressBar ?? true | Preferred flag for the rainbow scene-boundary progress bar | | playbackRate | number | 1 | Timeline speed multiplier | | onWarning | (warning: Diagnostic) => void | console.warn | Called for each soft parse warning | | onTimeUpdate | (seconds: number, durationSeconds: number) => void | — | Called whenever playback or seek changes the current time | | onPlayStateChange | (playing: boolean) => void | — | Called when playback starts or pauses |

Player

| Method | Description | |---|---| | play() | Start or resume playback | | pause() | Pause at current position | | seek(seconds) | Jump to a specific time | | setPlaybackRate(rate) | Change timeline speed; ignores non-positive or non-finite values | | playbackRate() | Current timeline speed multiplier | | currentTime() | Current playback position in seconds | | duration() | Total scene duration in seconds | | isPlaying() | Whether the scene is currently playing | | beats() | Named beat ranges, in author order (empty if none) | | seekToBeat(name) | Seek to the start of a named beat; no-op if the name doesn't match | | destroy() | Remove DOM elements and cancel all animations |

Module Structure

src/
  index.ts        — Barrel exports (createPlayer)
  player.ts       — Public API, rAF loop, progress bar, responsive scaling
  nodes.ts        — Node element factory + scene title
  edges.ts        — Flow-edge SVG runtime, routing, and cue animations
  geometry/
    rect.ts       — Rects, points, and hit-testing (DOM-free, unit tested)
    path.ts       — Polyline measurement + obstacle-aware orthogonal routing
  theme.ts        — Scene ambience styles and theme-token application

Adding a cue or edge kind

Cue and edge animations live in edges.ts (buildCueAnimations). Add the new keyword or operator to @markdy/core's registry.ts so the parser accepts it, then handle it in the corresponding branch of buildCueAnimations.

Documentation

• Syntax Reference — complete DSL language spec
• Architecture — renderer internals and playback design

License

MIT