@elucim/dsl 0.2.1 → 0.4.0

package/README.md

@@ -59,6 +59,10 @@ Validates the DSL document and renders it as React components. If validation fai
 - `dsl: ElucimDocument` — The DSL document to render
 - `className?: string` — CSS class for the wrapper div
 - `style?: CSSProperties` — Inline styles for the wrapper div
+- `theme?: 'light' | 'dark'` — Override the color theme
+- `poster?: number` — Frame number to display as a static poster before playback
+- `onError?: (errors: ValidationError[]) => void` — Callback for validation errors
+- `ref?: React.Ref<DslRendererRef>` — Imperative handle for programmatic control
 
 ### `validate(doc: unknown): ValidationResult`
 
@@ -74,6 +78,27 @@ if (!result.valid) {
 }
 ```
 
+### `renderToSvgString(doc, frame, options?)`
+
+Renders a DSL document to an SVG string without a browser DOM — useful for server-side rendering, thumbnails, and static export.
+
+```ts
+import { renderToSvgString } from '@elucim/dsl';
+const svg = renderToSvgString(myDoc, 0);
+```
+
+Uses `react-dom/server` under the hood. Validates the DSL and throws on invalid input.
+
+### `DslRendererRef`
+
+Imperative handle exposed via `ref` on `<DslRenderer>`. Methods:
+
+- `getSvgElement()` — Returns the underlying `SVGSVGElement`
+- `seekToFrame(frame)` — Jump to a specific frame
+- `getTotalFrames()` — Total frame count of the document
+- `play()` / `pause()` — Control playback
+- `isPlaying()` — Whether the animation is currently playing
+
 ### `compileExpression(expr: string)`
 
 Compile a math expression string into a callable function.
@@ -115,6 +140,8 @@ Every document has this structure:
 | `player` | Interactive player with controls, scrub bar, play/pause |
 | `presentation` | Slide-based presentation with transitions |
 
+All root types accept an optional `preset` field: `'card'` (640×360), `'slide'` (1280×720), `'square'` (600×600). When set, `width` and `height` are derived from the preset automatically.
+
 ### Element Types
 
 #### Primitives
@@ -125,6 +152,7 @@ Every document has this structure:
 | `arrow` | `x1`, `y1`, `x2`, `y2` | Line with arrowhead |
 | `rect` | `x`, `y`, `width`, `height` | Rectangle |
 | `polygon` | `points` (array of [x,y]) | Polygon/polyline |
+| `bezierCurve` | `x1`, `y1`, `cx1`, `cy1`, `x2`, `y2` | Quadratic/cubic Bezier curve |
 | `text` | `x`, `y`, `content` | Text element |
 | `image` | `src`, `x`, `y`, `width`, `height` | Embed external images (PNG, SVG, etc.) |
 | `barChart` | `bars` | Animated bar chart with labels and colors |
@@ -222,6 +250,10 @@ When instructing an LLM to create Elucim diagrams:
 5. **Wrap elements in animation nodes** (`fadeIn`, `draw`, `stagger`) for entrance effects
 6. **Use math expression strings** for function plots and vector fields
 
+**Tips:**
+- Use `poster` on `<DslRenderer>` to show a static preview frame before playback starts
+- Use `renderToSvgString(doc, frame)` to generate SVG previews server-side — ideal for thumbnails and social cards
+
 Example prompt:
 > "Create an Elucim DSL JSON document that shows a coordinate system with sin(x) and cos(x) plotted, 
 > with the sin curve drawing first, then the cos curve drawing 30 frames later, 

package/dist/index.d.ts

@@ -1,5 +1,4 @@
 import { default as default_2 } from 'react';
-import { JSX as JSX_2 } from 'react/jsx-runtime';
 
 export declare interface ArrowNode {
     type: 'arrow';
@@ -80,6 +79,33 @@ export declare interface BarChartNode {
     zIndex?: number;
 }
 
+export declare interface BezierCurveNode {
+    type: 'bezierCurve';
+    id?: string;
+    x1: number;
+    y1: number;
+    cx1: number;
+    cy1: number;
+    cx2?: number;
+    cy2?: number;
+    x2: number;
+    y2: number;
+    stroke?: string;
+    strokeWidth?: number;
+    fill?: string;
+    strokeDasharray?: string;
+    opacity?: number;
+    fadeIn?: number;
+    fadeOut?: number;
+    draw?: number;
+    easing?: EasingSpec;
+    rotation?: number;
+    rotationOrigin?: [number, number];
+    scale?: number | [number, number];
+    translate?: [number, number];
+    zIndex?: number;
+}
+
 export declare interface CircleNode {
     type: 'circle';
     id?: string;
@@ -139,12 +165,36 @@ export declare interface DrawNode {
     children: ElementNode[];
 }
 
-export declare function DslRenderer({ dsl, className, style }: DslRendererProps): JSX_2.Element;
+export declare const DslRenderer: default_2.ForwardRefExoticComponent<DslRendererProps & default_2.RefAttributes<DslRendererRef>>;
 
 export declare interface DslRendererProps {
     dsl: ElucimDocument;
     className?: string;
     style?: default_2.CSSProperties;
+    /** Inject theme colors as CSS custom properties (e.g. --elucim-foreground) */
+    theme?: ElucimTheme;
+    /** Render a static frame instead of interactive player. 'first' | 'last' | frame number */
+    poster?: 'first' | 'last' | number;
+    /** Callback fired when DSL validation fails */
+    onError?: (errors: Array<{
+        path: string;
+        message: string;
+    }>) => void;
+}
+
+export declare interface DslRendererRef {
+    /** Get the underlying SVG element */
+    getSvgElement(): SVGSVGElement | null;
+    /** Seek to a specific frame */
+    seekToFrame(frame: number): void;
+    /** Get total frames count */
+    getTotalFrames(): number;
+    /** Start playback */
+    play(): void;
+    /** Pause playback */
+    pause(): void;
+    /** Whether currently playing */
+    isPlaying(): boolean;
 }
 
 /** An easing function maps progress (0→1) to an eased value (typically 0→1) */
@@ -154,7 +204,7 @@ declare type EasingName = 'linear' | 'easeInQuad' | 'easeOutQuad' | 'easeInOutQu
 
 export declare type EasingSpec = EasingName | SpringEasing | CubicBezierEasing;
 
-export declare type ElementNode = SequenceNode | GroupNode | CircleNode | LineNode | ArrowNode | RectNode | PolygonNode | TextNode | ImageNode | AxesNode | FunctionPlotNode | VectorNode | VectorFieldNode | MatrixNode | GraphNode | LaTeXNode | BarChartNode | FadeInNode | FadeOutNode | DrawNode | WriteNode | TransformNode | MorphNode | StaggerNode | ParallelNode | PlayerNode | SceneNode;
+export declare type ElementNode = SequenceNode | GroupNode | BezierCurveNode | CircleNode | LineNode | ArrowNode | RectNode | PolygonNode | TextNode | ImageNode | AxesNode | FunctionPlotNode | VectorNode | VectorFieldNode | MatrixNode | GraphNode | LaTeXNode | BarChartNode | FadeInNode | FadeOutNode | DrawNode | WriteNode | TransformNode | MorphNode | StaggerNode | ParallelNode | PlayerNode | SceneNode;
 
 export declare interface ElucimDocument {
     /** JSON Schema URL for editor autocomplete */
@@ -165,6 +215,13 @@ export declare interface ElucimDocument {
     root: RootNode;
 }
 
+export declare interface ElucimTheme {
+    foreground?: string;
+    background?: string;
+    accent?: string;
+    [key: string]: string | undefined;
+}
+
 export declare interface FadeInNode {
     type: 'fadeIn';
     duration?: number;
@@ -358,6 +415,7 @@ export declare interface ParallelNode {
 
 export declare interface PlayerNode {
     type: 'player';
+    preset?: ScenePreset;
     width?: number;
     height?: number;
     fps?: number;
@@ -369,6 +427,21 @@ export declare interface PlayerNode {
     children: ElementNode[];
 }
 
+declare interface PlayerRef {
+    /** Get the underlying SVG element */
+    getSvgElement(): SVGSVGElement | null;
+    /** Seek to a specific frame */
+    seekToFrame(frame: number): void;
+    /** Get total frames count */
+    getTotalFrames(): number;
+    /** Start playback */
+    play(): void;
+    /** Pause playback */
+    pause(): void;
+    /** Whether currently playing */
+    isPlaying(): boolean;
+}
+
 export declare interface PolygonNode {
     type: 'polygon';
     id?: string;
@@ -436,6 +509,7 @@ export declare class PresentationBuilder {
 
 export declare interface PresentationNode {
     type: 'presentation';
+    preset?: ScenePreset;
     width?: number;
     height?: number;
     background?: string;
@@ -481,6 +555,37 @@ export declare interface RectNode {
     zIndex?: number;
 }
 
+export declare function renderElement(node: ElementNode, key: number): default_2.ReactNode;
+
+export declare function renderPlayer(node: PlayerNode, overrides?: RenderRootOverrides): default_2.ReactNode;
+
+export declare function renderPresentation(node: PresentationNode): default_2.ReactNode;
+
+export declare function renderRoot(node: SceneNode | PlayerNode | PresentationNode, overrides?: RenderRootOverrides): default_2.ReactNode;
+
+export declare interface RenderRootOverrides {
+    frame?: number;
+    playerRef?: default_2.RefObject<PlayerRef | null>;
+}
+
+export declare function renderScene(node: SceneNode, overrides?: RenderRootOverrides): default_2.ReactNode;
+
+export declare function renderSlide(node: SlideNode, key: number): default_2.ReactNode;
+
+/**
+ * Render a DSL document to an SVG string at a specific frame, without mounting to the DOM.
+ * Uses react-dom/server's renderToStaticMarkup.
+ *
+ * Note: This renders the scene at the given frame by overriding the root node's properties.
+ * For 'player' roots, it converts to a 'scene' internally (no controls needed for static output).
+ */
+export declare function renderToSvgString(dsl: ElucimDocument, frame: number, options?: RenderToSvgStringOptions): string;
+
+export declare interface RenderToSvgStringOptions {
+    width?: number;
+    height?: number;
+}
+
 /**
  * Resolve an EasingSpec (string name or spring/cubicBezier object) to an EasingFunction.
  * Returns undefined if the spec is undefined.
@@ -492,6 +597,7 @@ export declare type RootNode = SceneNode | PlayerNode | PresentationNode;
 
 export declare interface SceneNode {
     type: 'scene';
+    preset?: ScenePreset;
     width?: number;
     height?: number;
     fps?: number;
@@ -500,6 +606,9 @@ export declare interface SceneNode {
     children: ElementNode[];
 }
 
+/** Preset dimensions for common scene sizes */
+export declare type ScenePreset = 'card' | 'slide' | 'square';
+
 export declare interface SequenceNode {
     type: 'sequence';
     from: number;