DSL Overview

The @elucim/dsl package lets agents and content pipelines describe Elucim visuals as JSON or YAML documents instead of JSX. Elucim documents are normalized scene graphs with explicit elements, timelines, and optional state machines.

ElucimDocument

Every DSL document is an ElucimDocument object:

import type {
  ElucimDocument,
  ElucimElement,
  ElucimMetadata,
  ElucimScene,
  ElucimStateMachine,
  ElucimTimeline,
} from '@elucim/dsl';

interface ElucimDocument {
  $schema?: string;         // Optional JSON Schema URL for editor autocomplete
  version: '2.0';           // Current document format version
  scene: ElucimScene;       // Root scene/player settings
  elements: Record<string, ElucimElement>;
  timelines?: Record<string, ElucimTimeline>;
  stateMachines?: Record<string, ElucimStateMachine>;
  defaultStateMachine?: string;
  metadata?: ElucimMetadata;
}

The scene chooses the render surface and references top-level element IDs. Elements are stored by ID so timelines and state machines can target stable objects directly.

Minimal Example

JSON

{
  "version": "2.0",
  "scene": {
    "type": "player",
    "width": 800,
    "height": 600,
    "fps": 30,
    "background": "#0a0a1e",
    "children": ["orb"]
  },
  "elements": {
    "orb": {
      "id": "orb",
      "type": "circle",
      "props": {
        "type": "circle",
        "cx": 400,
        "cy": 300,
        "r": 60,
        "stroke": "$accent",
        "strokeWidth": 3,
        "opacity": 0
      }
    }
  },
  "timelines": {
    "intro": {
      "id": "intro",
      "duration": 30,
      "tracks": [
        {
          "target": "orb",
          "property": "opacity",
          "keyframes": [
            { "frame": 0, "value": 0 },
            { "frame": 30, "value": 1 }
          ]
        }
      ]
    }
  },
  "defaultStateMachine": "main",
  "stateMachines": {
    "main": {
      "id": "main",
      "entry": "intro",
      "states": { "intro": { "timeline": "intro" } },
      "transitions": [
        { "id": "entry-start", "from": "entry", "to": "intro", "trigger": "onStart" }
      ]
    }
  }
}

YAML

The same document in YAML — parsed with fromYaml():

version: "2.0"
scene:
  type: player
  width: 800
  height: 600
  fps: 30
  background: "#0a0a1e"
  children: [orb]
elements:
  orb:
    id: orb
    type: circle
    props:
      type: circle
      cx: 400
      cy: 300
      r: 60
      stroke: "$accent"
      strokeWidth: 3
      opacity: 0
timelines:
  intro:
    id: intro
    duration: 30
    tracks:
      - target: orb
        property: opacity
        keyframes:
          - { frame: 0, value: 0 }
          - { frame: 30, value: 1 }
defaultStateMachine: main
stateMachines:
  main:
    id: main
    entry: intro
    states:
      intro: { timeline: intro }
    transitions:
      - { id: entry-start, from: entry, to: intro, trigger: onStart }

import { fromYaml } from '@elucim/dsl';

const doc = fromYaml(yamlString);
// doc is a validated ElucimDocument

Note

fromYaml uses a JSON-compatible YAML schema, so values like on, yes, and NO stay as strings instead of being coerced to booleans. This matches the behavior you’d get from JSON.

Node Types

Every node has a "type" field. The full set of supported types:

Document Sections

Section	Description
scene	Root scene/player settings with top-level child element IDs
elements	ID-keyed primitive/group definitions
timelines	Explicit property tracks and keyframes
stateMachines	Entry/state/transition controllers for interactive playback

Primitive Nodes

Type	Description
circle	SVG circle (cx, cy, r, fill, stroke)
line	SVG line or straight connector (x1, y1, x2, y2, lineStyle, startCap, endCap)
bezierCurve	Smooth connector/path (x1, y1, cx1, cy1, cx2, cy2, x2, y2, startCap, endCap)
rect	Rectangle (x, y, width, height, rx, ry)
polygon	Polygon from a points array
text	Text label (x, y, content, fontSize)

Math & Data Nodes

Type	Description
axes	2D coordinate system with ticks and optional grid
functionPlot	Plot a math expression as a curve
vector	Arrow from origin to a point, with optional label
vectorField	Grid of vectors computed from an expression
matrix	Bracketed matrix display
graph	Node-and-edge graph visualization
latex	LaTeX expression rendered via KaTeX
barChart	Labeled bar chart

Motion

Animation is represented by timeline tracks and state-machine transitions, not wrapper nodes like fadeIn or sequence. This keeps generated documents inspectable and gives the editor/viewer a single motion model.

Next Steps

• DslRenderer — render a document in React
• Validation — validate documents before rendering
• Agent documents — author interactive timeline flows
• Themes — semantic color tokens ($accent, $foreground, etc.)