@elucim/dsl 0.10.0 → 0.12.0

package/dist/index.d.ts

@@ -106,6 +106,15 @@ export declare interface BezierCurveNode {
     zIndex?: number;
 }
 
+export declare interface BuilderTheme extends ElucimTheme {
+    /** Box fill colors for diagrams */
+    boxFill: string;
+    /** Box stroke color */
+    boxStroke: string;
+    /** Palette of 8 colors for sequential use */
+    palette: string[];
+}
+
 export declare interface CircleNode {
     type: 'circle';
     id?: string;
@@ -155,7 +164,13 @@ export declare interface CubicBezierEasing {
     y2: number;
 }
 
-export declare const darkTheme: Theme;
+/** Dark theme preset — the default Elucim content theme. */
+export declare const DARK_THEME: Required<Pick<ElucimTheme, 'foreground' | 'background' | 'title' | 'subtitle' | 'primary' | 'secondary' | 'tertiary' | 'muted' | 'surface' | 'border' | 'accent' | 'success' | 'warning' | 'error'>>;
+
+/** Pre-computed CSS variable maps for colorScheme resolution. */
+export declare const DARK_THEME_VARS: Record<string, string>;
+
+export declare const darkTheme: BuilderTheme;
 
 export declare interface DrawNode {
     type: 'draw';
@@ -171,7 +186,11 @@ export declare interface DslRendererProps {
     dsl: ElucimDocument;
     className?: string;
     style?: default_2.CSSProperties;
-    /** Inject theme colors as CSS custom properties (e.g. --elucim-foreground) */
+    /**
+     * Theme for semantic token resolution.
+     * Keys map to `--elucim-{key}` CSS custom properties and `$token` DSL syntax.
+     * Values can be hex colors, named colors, or CSS `var()` references.
+     */
     theme?: ElucimTheme;
     /**
      * Color scheme for semantic token resolution.
@@ -179,13 +198,28 @@ export declare interface DslRendererProps {
      * - `'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.
+     * 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;
+    /** Override the document's controls setting (Player root only). */
+    controls?: boolean;
+    /** Override the document's autoPlay setting (Player root only). */
+    autoPlay?: boolean;
+    /** Override the document's loop setting (Player root only). */
+    loop?: boolean;
+    /**
+     * When true, the rendered scene fills its parent container width and
+     * scales proportionally.  Default: false.
+     */
+    fitToContainer?: boolean;
+    /** Called whenever playback state changes (play/pause). */
+    onPlayStateChange?: (playing: boolean) => void;
+    /** Called when a React render error occurs inside the scene tree. */
+    onRenderError?: (error: Error) => void;
+    /** Custom fallback UI shown when a render error occurs. */
+    fallback?: default_2.ReactNode;
     /** Callback fired when DSL validation fails */
     onError?: (errors: Array<{
         path: string;
@@ -226,11 +260,52 @@ export declare interface ElucimDocument {
     root: RootNode;
 }
 
+/**
+ * Unified Elucim theme system.
+ *
+ * `ElucimTheme` is the single theme type used across the entire Elucim ecosystem:
+ * DslRenderer, ElucimEditor, and $token resolution all share this contract.
+ *
+ * Token names map 1:1 to the `$token` DSL syntax and `--elucim-*` CSS custom
+ * properties.  For example, `{ primary: '#2563eb' }` sets `--elucim-primary`
+ * and is referenced in DSL documents as `$primary`.
+ *
+ * Values can be hex colors, named CSS colors, or CSS `var()` references
+ * (e.g. `{ accent: "var(--my-app-accent)" }`).
+ */
+/**
+ * Canonical theme interface for Elucim content rendering and editor chrome.
+ * All fields are optional — unset fields fall back to the active colorScheme defaults.
+ */
 export declare interface ElucimTheme {
+    /** Default text color. Maps to `$foreground` / `--elucim-foreground`. */
     foreground?: string;
+    /** Scene background. Maps to `$background` / `--elucim-background`. */
     background?: string;
+    /** Title text color. Maps to `$title` / `--elucim-title`. */
+    title?: string;
+    /** Subtitle / secondary text. Maps to `$subtitle` / `--elucim-subtitle`. */
+    subtitle?: string;
+    /** Primary accent color. Maps to `$primary` / `--elucim-primary`. */
+    primary?: string;
+    /** Secondary accent. Maps to `$secondary` / `--elucim-secondary`. */
+    secondary?: string;
+    /** Tertiary accent. Maps to `$tertiary` / `--elucim-tertiary`. */
+    tertiary?: string;
+    /** Muted text / annotations. Maps to `$muted` / `--elucim-muted`. */
+    muted?: string;
+    /** Elevated surface color. Maps to `$surface` / `--elucim-surface`. */
+    surface?: string;
+    /** Border color. Maps to `$border` / `--elucim-border`. */
+    border?: string;
+    /** Alias for primary — `$accent` / `--elucim-accent`. */
     accent?: string;
-    [key: string]: string | undefined;
+    /** Success / positive. Maps to `$success` / `--elucim-success`. */
+    success?: string;
+    /** Warning / highlight. Maps to `$warning` / `--elucim-warning`. */
+    warning?: string;
+    /** Error / negative. Maps to `$error` / `--elucim-error`. */
+    error?: string;
 }
 
 export declare interface FadeInNode {
@@ -362,7 +437,12 @@ export declare interface LaTeXNode {
     zIndex?: number;
 }
 
-export declare const lightTheme: Theme;
+/** Light theme preset. */
+export declare const LIGHT_THEME: Required<Pick<ElucimTheme, 'foreground' | 'background' | 'title' | 'subtitle' | 'primary' | 'secondary' | 'tertiary' | 'muted' | 'surface' | 'border' | 'accent' | 'success' | 'warning' | 'error'>>;
+
+export declare const LIGHT_THEME_VARS: Record<string, string>;
+
+export declare const lightTheme: BuilderTheme;
 
 export declare interface LineNode {
     type: 'line';
@@ -579,6 +659,16 @@ export declare interface RenderRootOverrides {
     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';
+    /** Override Player controls visibility. */
+    controls?: boolean;
+    /** Override Player autoPlay setting. */
+    autoPlay?: boolean;
+    /** Override Player loop setting. */
+    loop?: boolean;
+    /** When true, scene fills its parent container. */
+    fitToContainer?: boolean;
+    /** Callback fired when playback state changes. */
+    onPlayStateChange?: (playing: boolean) => void;
 }
 
 export declare function renderScene(node: SceneNode, overrides?: RenderRootOverrides): default_2.ReactNode;
@@ -633,14 +723,13 @@ export declare interface RenderToSvgStringOptions {
 }
 
 /**
- * Resolve a color value. If it starts with `$`, treat it as a semantic token
- * and return a CSS `var()` reference. Otherwise return the value unchanged.
+ * Resolve a color value.  If it starts with `$`, treat it as a semantic token
+ * and return a CSS `var()` reference.  Otherwise return the value unchanged.
  *
  * @example
- * resolveColor('$foreground')  // → 'var(--elucim-foreground, #e0e0e0)'
- * resolveColor('$accent')      // → 'var(--elucim-accent, #4fc3f7)'
- * resolveColor('#ff0000')      // → '#ff0000'  (unchanged)
- * resolveColor(undefined)      // → undefined   (pass-through)
+ * resolveColor('$foreground')  // → 'var(--elucim-foreground, #c8d6e5)'
+ * resolveColor('#ff0000')      // → '#ff0000'
+ * resolveColor(undefined)      // → undefined
  */
 export declare function resolveColor(value: string | undefined): string | undefined;
 
@@ -667,7 +756,7 @@ export declare interface SceneNode {
 /** Preset dimensions for common scene sizes */
 export declare type ScenePreset = 'card' | 'slide' | 'square';
 
-/** Standard semantic color tokens with their CSS variable and default fallback. */
+/** Standard semantic color tokens with their CSS variable and dark-mode fallback. */
 export declare const SEMANTIC_TOKENS: Record<string, {
     cssVar: string;
     fallback: string;
@@ -963,40 +1052,14 @@ export declare interface TextNode {
 }
 
 /**
- * Theme configuration for presentation builders.
- * Provides consistent colors across slides.
+ * @deprecated Use `BuilderTheme` instead. Kept for backward compatibility.
  */
-export declare interface Theme {
-    background: string;
-    /** Title text color */
-    title: string;
-    /** Subtitle / secondary text */
-    subtitle: string;
-    /** Primary accent (arrows, highlights) */
-    primary: string;
-    /** Secondary accent */
-    secondary: string;
-    /** Tertiary accent */
-    tertiary: string;
-    /** Muted text / annotations */
-    muted: string;
-    /** Default text color */
-    text: string;
-    /** Box fill colors for diagrams */
-    boxFill: string;
-    /** Box stroke color */
-    boxStroke: string;
-    /** Success / positive color */
-    success: string;
-    /** Warning / highlight color */
-    warning: string;
-    /** Error / negative color */
-    error: string;
-    /** Palette of 8 colors for sequential use */
-    palette: string[];
-}
+export declare type Theme = BuilderTheme;
+
+/** Convert an ElucimTheme (or arbitrary token record) to CSS custom properties (`--elucim-*`). */
+export declare function themeToVars(theme?: ElucimTheme | Record<string, string | undefined>): Record<string, string>;
 
-/** List of token names for documentation / autocomplete. */
+/** List of standard token names. */
 export declare const TOKEN_NAMES: ReadonlyArray<string>;
 
 export declare interface TransformNode {