@elucim/dsl 0.6.0 → 0.8.0

package/README.md

@@ -59,9 +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
+- `theme?: ElucimTheme` — Custom color tokens as CSS custom properties (e.g. `{ foreground: '#fff', background: '#000' }`)
+- `colorScheme?: 'light' | 'dark' | 'auto'` — Inject light/dark theme variables automatically. `'auto'` detects from `prefers-color-scheme`. DSL docs using `$token` syntax adapt automatically.
+- `poster?: 'first' | 'last' | number` — Render a static frame instead of interactive player
+- `onError?: (errors: Array<{ path: string; message: string }>) => void` — Callback for validation errors
 - `ref?: React.Ref<DslRendererRef>` — Imperative handle for programmatic control
 
 ### `validate(doc: unknown): ValidationResult`
@@ -230,6 +231,59 @@ Used in `functionPlot.fn` and `vectorField.fn`. Safe evaluation — no `eval()`.
 - `"[-y, x]"` — Rotation vector field
 - `"[sin(y), cos(x)]"` — Wave vector field
 
+## Semantic Color Tokens
+
+Use `$token` syntax in your DSL JSON to create theme-adaptive visualizations:
+
+```json
+{
+  "type": "player",
+  "background": "$background",
+  "children": [
+    { "type": "text", "x": 400, "y": 300, "content": "Hello", "fill": "$foreground" },
+    { "type": "circle", "cx": 200, "cy": 200, "r": 50, "stroke": "$accent" }
+  ]
+}
+```
+
+**Available tokens:**
+
+| Token | Dark default | Light default | Usage |
+|-------|-------------|---------------|-------|
+| `$foreground` | `#c8d6e5` | `#334155` | Body text |
+| `$background` | `#0a0a1e` | `#f8fafc` | Slide/scene background |
+| `$title` | `#e0e7ff` | `#1e293b` | Heading text (brighter than foreground) |
+| `$subtitle` | `#94a3b8` | `#64748b` | Secondary/subtitle text |
+| `$muted` | `#64748b` | `#94a3b8` | Annotations, faint text |
+| `$primary` | `#4fc3f7` | `#2563eb` | Primary accent |
+| `$secondary` | `#a78bfa` | `#7c3aed` | Secondary accent |
+| `$tertiary` | `#f472b6` | `#db2777` | Tertiary accent |
+| `$success` | `#34d399` | `#16a34a` | Positive / success |
+| `$warning` | `#fbbf24` | `#d97706` | Warning / highlight |
+| `$error` | `#f87171` | `#dc2626` | Error / negative |
+| `$surface` | `#1e293b` | `#f8fafc` | Panel backgrounds |
+| `$border` | `#334155` | `#334155` | Borders, grid lines |
+| `$accent` | `#4fc3f7` | `#2563eb` | Alias for primary |
+
+Tokens resolve to CSS custom properties (`$background` → `var(--elucim-background, #0a0a1e)`). Pair with `colorScheme` to auto-adapt:
+
+```tsx
+<DslRenderer dsl={doc} colorScheme="auto" />
+```
+
+| colorScheme | Behavior |
+|-------------|----------|
+| `'dark'` | Injects dark palette variables |
+| `'light'` | Injects light palette variables |
+| `'auto'` | Detects `prefers-color-scheme` media query |
+| _(omitted)_ | Tokens fall back to built-in defaults (dark) |
+
+You can also override individual tokens with the `theme` prop:
+
+```tsx
+<DslRenderer dsl={doc} colorScheme="auto" theme={{ accent: '#ff6600' }} />
+```
+
 ## Examples
 
 See the [`examples/`](./examples/) directory:
@@ -281,6 +335,7 @@ const doc = presentation(darkTheme)
 ## Related
 
 - **[@elucim/core](https://www.npmjs.com/package/@elucim/core)** — The React rendering engine (peer dependency)
+- **[@elucim/editor](https://www.npmjs.com/package/@elucim/editor)** — Visual canvas editor for Elucim animations
 - **[Elucim Docs](https://elucim.com)** — Full docs with live interactive examples
 
 ## License

package/dist/index.d.ts

@@ -173,6 +173,17 @@ export declare interface DslRendererProps {
     style?: default_2.CSSProperties;
     /** Inject theme colors as CSS custom properties (e.g. --elucim-foreground) */
     theme?: ElucimTheme;
+    /**
+     * Color scheme for semantic token resolution.
+     * - `'dark'` — inject dark theme CSS variables
+     * - `'light'` — inject light theme CSS variables
+     * - `'auto'` — detect from `prefers-color-scheme` media query
+     *
+     * DSL documents using `$token` syntax (e.g. `$background`, `$foreground`)
+     * will automatically adapt. Explicit `theme` values take priority over
+     * colorScheme defaults.
+     */
+    colorScheme?: 'light' | 'dark' | 'auto';
     /** Render a static frame instead of interactive player. 'first' | 'last' | frame number */
     poster?: 'first' | 'last' | number;
     /** Callback fired when DSL validation fails */
@@ -566,12 +577,47 @@ export declare function renderRoot(node: SceneNode | PlayerNode | PresentationNo
 export declare interface RenderRootOverrides {
     frame?: number;
     playerRef?: default_2.RefObject<PlayerRef | null>;
+    /** CSS color-scheme to pass to Scene/Player. When set, overrides browser prefers-color-scheme. */
+    colorScheme?: 'light' | 'dark' | 'light dark';
 }
 
 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 at a specific frame directly to PNG bytes.
+ *
+ * Goes from DSL JSON → SVG string → PNG without requiring a mounted DOM
+ * element, blob URLs, or manual Image loading. Uses data URIs internally
+ * to avoid CSP issues in restricted webview contexts (e.g. Tauri).
+ *
+ * Works in any browser environment. Does NOT work in Node.js (needs
+ * canvas + Image APIs).
+ *
+ * @example
+ * ```ts
+ * import { renderToPng } from '@elucim/dsl';
+ *
+ * const png = await renderToPng(myDocument, 0);
+ * // png is a Uint8Array of PNG bytes
+ *
+ * // Save as file download:
+ * const blob = new Blob([png], { type: 'image/png' });
+ * const url = URL.createObjectURL(blob);
+ * ```
+ */
+export declare function renderToPng(dsl: ElucimDocument, frame: number, options?: RenderToPngOptions): Promise<Uint8Array>;
+
+export declare interface RenderToPngOptions {
+    /** Output width in pixels (default: document width) */
+    width?: number;
+    /** Output height in pixels (default: document height) */
+    height?: number;
+    /** Device pixel ratio for retina output (default: 2) */
+    scale?: number;
+}
+
 /**
  * Render a DSL document to an SVG string at a specific frame, without mounting to the DOM.
  * Uses react-dom/server's renderToStaticMarkup.
@@ -991,6 +1037,7 @@ export declare interface ValidationResult {
 
 export declare interface VectorFieldNode {
     type: 'vectorField';
+    id?: string;
     /** Vector expression string, e.g. "[-y, x]" */
     fn: string;
     domain?: [number, number];