@elucim/dsl 0.3.0 → 0.4.1

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';
@@ -166,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) */
@@ -192,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;
@@ -385,6 +415,7 @@ export declare interface ParallelNode {
 
 export declare interface PlayerNode {
     type: 'player';
+    preset?: ScenePreset;
     width?: number;
     height?: number;
     fps?: number;
@@ -396,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;
@@ -463,6 +509,7 @@ export declare class PresentationBuilder {
 
 export declare interface PresentationNode {
     type: 'presentation';
+    preset?: ScenePreset;
     width?: number;
     height?: number;
     background?: string;
@@ -508,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.
@@ -519,6 +597,7 @@ export declare type RootNode = SceneNode | PlayerNode | PresentationNode;
 
 export declare interface SceneNode {
     type: 'scene';
+    preset?: ScenePreset;
     width?: number;
     height?: number;
     fps?: number;
@@ -527,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;