feat: rework includes

Author: LeadcodeDev

.claude/skills/rustmotion/SKILL.md

@@ -448,11 +448,87 @@ Scene entries can reference external scenario files to inject their scenes inlin
 | --- | --- | --- | --- |
 | `include` | string | required | Path (relative to parent) or URL to a scenario JSON file |
 | `scenes` | array of usize | `null` | Only include scenes at these 0-based indices |
+| `config` | object | `null` | Config overrides for structural components |
 
 - The included file's `video` config is ignored
 - Audio tracks from included files are merged
 - Includes can be nested (max depth: 8)
 
+#### Structural Components (Config)
+
+Structural components are reusable scenarios with **declared config** (type + default). When rendered standalone, defaults apply. When included, the parent can override config values. Config supports all types including `array` and `object`, allowing full component trees (e.g. rich_text spans) to be passed as parameters.
+
+**Defining a structural component (`components/outro.json`):**
+```json
+{
+  "config": {
+    "cta_text": { "type": "string", "default": "Book your demo" },
+    "accent_color": { "type": "string", "default": "#5C39EE" },
+    "logo_src": { "type": "string", "default": "assets/logo.svg" },
+    "counter_target": { "type": "number", "default": 400 },
+    "tagline_spans": {
+      "type": "array",
+      "default": [
+        { "text": "Don't " },
+        { "text": "miss ", "color": "#B041F0" },
+        { "text": "any lead" }
+      ]
+    }
+  },
+  "video": { "width": 1080, "height": 1920, "fps": 30 },
+  "scenes": [
+    {
+      "duration": 7.0,
+      "children": [
+        { "type": "svg", "src": "$logo_src" },
+        { "type": "text", "content": "$cta_text", "style": { "color": "$accent_color" } },
+        { "type": "counter", "from": 0, "to": { "$var": "counter_target" } },
+        { "type": "rich_text", "spans": { "$var": "tagline_spans" } }
+      ]
+    }
+  ]
+}
+```
+
+**Config reference syntax:**
+
+| Syntax | When to use | Behavior |
+| --- | --- | --- |
+| `"$name"` | Whole string value | Replaced by the config value (preserves type: number, boolean, etc.) |
+| `"text $name text"` | String interpolation | Inline substitution (value must be string/number/boolean) |
+| `{ "$var": "name" }` | Non-string in object position | Replaced by the config value (arrays, objects, numbers) |
+| `"$$literal"` | Escape | Produces literal `"$literal"` |
+
+**Including with overrides:**
+```json
+{
+  "scenes": [
+    { "duration": 5.0, "children": [...] },
+    {
+      "include": "components/outro.json",
+      "config": {
+        "cta_text": "Try WhatsApp",
+        "accent_color": "#25D366",
+        "tagline_spans": [
+          { "text": "Stop losing " },
+          { "text": "customers", "color": "#25D366" }
+        ]
+      }
+    }
+  ]
+}
+```
+
+Config types: `string`, `number`, `boolean`, `object`, `array`. Omitted overrides use defaults. Referencing an undefined config key is an error.
+
+**Rules for generation:**
+- Always declare config entries with a `type` and `default`
+- Use `"$name"` for string fields (src, content, color) — replaces the whole value
+- Use `{ "$var": "name" }` for non-string fields (numbers, arrays, objects) to preserve the type
+- Use `array` type to pass component trees (spans, children, gradient color stops)
+- Use `$$` to escape literal dollar signs
+- Never reference config values inside the `"config"` definition block itself
+
 #### Transitions
 
 ```json

README.md

@@ -216,13 +216,92 @@ Scene entries can reference external scenario files to inject their scenes inlin
 |---|---|---|---|
 | `include` | `string` | (required) | Path (relative to parent file) or URL to a scenario JSON |
 | `scenes` | `usize[]` | | Only include scenes at these 0-based indices. Omit to include all |
+| `config` | `object` | | Config overrides to pass to a structural component (see below) |
 
 - The included file's `video` config is ignored
 - Audio tracks from included files are merged
 - Includes can be nested (max depth: 8)
 
 ---
 
+## Structural Components (Variables)
+
+Structural components are reusable scenario files with **declared variables**. When rendered standalone, default values apply. When included from a parent, the parent can override any variable.
+
+### Defining config
+
+Add a `config` object at the root of a scenario. Each entry has a `type`, a `default` value, and an optional `description`:
+
+```json
+{
+  "config": {
+    "cta_text": { "type": "string", "default": "Book your demo" },
+    "accent_color": { "type": "string", "default": "#5C39EE" },
+    "logo_src": { "type": "string", "default": "assets/logo.svg" },
+    "counter_target": { "type": "number", "default": 400 },
+    "tagline_spans": {
+      "type": "array",
+      "default": [
+        { "text": "Don't ", "color": "#5C39EE" },
+        { "text": "miss any lead" }
+      ]
+    }
+  },
+  "video": { "width": 1080, "height": 1920, "fps": 30 },
+  "scenes": [
+    {
+      "duration": 7.0,
+      "children": [
+        { "type": "svg", "src": "$logo_src" },
+        { "type": "text", "content": "$cta_text", "style": { "color": "$accent_color" } },
+        { "type": "counter", "from": 0, "to": { "$var": "counter_target" } },
+        { "type": "rich_text", "spans": { "$var": "tagline_spans" } }
+      ]
+    }
+  ]
+}
+```
+
+Supported types: `string`, `number`, `boolean`, `object`, `array`. Array and object types allow passing full components (e.g. rich_text spans, children arrays).
+
+### Referencing config values
+
+| Syntax | Context | Behavior |
+|---|---|---|
+| `"$var_name"` | Entire string value | Replaced by the config value (any type) |
+| `"prefix $var_name suffix"` | String interpolation | Replaced inline (value must be string/number/boolean) |
+| `{ "$var": "var_name" }` | Any position | Replaced by the config value (for non-string types in object position) |
+| `"$$literal"` | Escape | Produces the literal string `"$literal"` |
+
+### Including with overrides
+
+```json
+{
+  "scenes": [
+    { "duration": 5.0, "children": [ ... ] },
+    {
+      "include": "components/outro.json",
+      "config": {
+        "cta_text": "Try WhatsApp",
+        "accent_color": "#25D366",
+        "tagline_spans": [
+          { "text": "Stop losing " },
+          { "text": "customers", "color": "#25D366" }
+        ]
+      }
+    }
+  ]
+}
+```
+
+Config entries not listed in overrides keep their default values. Referencing an undefined config key produces an error.
+
+### Standalone rendering
+
+When rendering a structural component directly (`rustmotion render components/outro.json`), all default values are applied automatically.
+
+---
+
 ## Components
 
 All components are discriminated by `"type"`. Rendered in array order (first = bottom, last = top).

src/error.rs

@@ -82,6 +82,19 @@ pub enum RustmotionError {
     #[error("Scenario cannot have both top-level 'scenes' and 'composition' — use one or the other")]
     CompositionAndScenesConflict,
 
+    // --- Variables ---
+    #[error("Variable '${name}' is not defined in '{path}'")]
+    UndefinedVariable { name: String, path: String },
+
+    #[error("Variable '{name}' in '{path}' is missing a default value")]
+    VariableMissingDefault { name: String, path: String },
+
+    #[error("Unresolved variable reference '${name}' after substitution in '{path}'")]
+    UnresolvedVariable { name: String, path: String },
+
+    #[error("Cannot interpolate non-string variable '${name}' into string in '{path}'")]
+    VariableInterpolationTypeError { name: String, path: String },
+
     // --- Encoding ---
     #[error("No frames to render (total duration is 0)")]
     NoFrames,

src/include.rs

@@ -21,6 +21,7 @@ pub enum IncludeSource {
 /// Expand all include directives in a scenario, producing resolved views.
 pub fn resolve_includes(scenario: Scenario, source: &IncludeSource) -> Result<ResolvedScenario> {
     let mut audio = scenario.audio;
+    let mut included_paths = Vec::new();
     let has_scenes = !scenario.scenes.is_empty();
     let has_composition = scenario.composition.is_some();
 
@@ -32,7 +33,7 @@ pub fn resolve_includes(scenario: Scenario, source: &IncludeSource) -> Result<Re
         // New format: composition with views
         let mut views = Vec::with_capacity(composition.len());
         for view in composition {
-            let scenes = resolve_entries(view.scenes, source, 0, &mut audio)?;
+            let scenes = resolve_entries(view.scenes, source, 0, &mut audio, &mut included_paths)?;
             views.push(ResolvedView {
                 view_type: view.view_type,
                 scenes,
@@ -46,7 +47,7 @@ pub fn resolve_includes(scenario: Scenario, source: &IncludeSource) -> Result<Re
         views
     } else {
         // Backward compat: wrap top-level scenes in a single slide view
-        let scenes = resolve_entries(scenario.scenes, source, 0, &mut audio)?;
+        let scenes = resolve_entries(scenario.scenes, source, 0, &mut audio, &mut included_paths)?;
         vec![ResolvedView {
             view_type: ViewType::Slide,
             scenes,
@@ -63,6 +64,7 @@ pub fn resolve_includes(scenario: Scenario, source: &IncludeSource) -> Result<Re
         audio,
         fonts: scenario.fonts,
         views,
+        included_paths,
     })
 }
 
@@ -71,6 +73,7 @@ fn resolve_entries(
     source: &IncludeSource,
     depth: u8,
     audio: &mut Vec<crate::schema::AudioTrack>,
+    included_paths: &mut Vec<PathBuf>,
 ) -> Result<Vec<Scene>> {
     let mut result = Vec::new();
 
@@ -86,7 +89,7 @@ fn resolve_entries(
                         path: directive.include.clone(),
                     }.into());
                 }
-                let scenes = fetch_and_resolve(&directive, source, depth + 1, audio)?;
+                let scenes = fetch_and_resolve(&directive, source, depth + 1, audio, included_paths)?;
                 result.extend(scenes);
             }
         }
@@ -100,6 +103,7 @@ fn fetch_and_resolve(
     parent_source: &IncludeSource,
     depth: u8,
     audio: &mut Vec<crate::schema::AudioTrack>,
+    included_paths: &mut Vec<PathBuf>,
 ) -> Result<Vec<Scene>> {
     let is_remote = directive.include.starts_with("http://")
         || directive.include.starts_with("https://");
@@ -113,18 +117,30 @@ fn fetch_and_resolve(
         let body = std::fs::read_to_string(&path).map_err(|_| {
             RustmotionError::IncludeFileNotFound { path: path.display().to_string() }
         })?;
+        // Track this included file for watch mode
+        included_paths.push(path.clone());
         let child_source = IncludeSource::File(path);
         (body, child_source)
     };
 
-    let child_scenario: Scenario = serde_json::from_str(&json_str)
-        .map_err(RustmotionError::from)?;
+    // Parse as raw Value first, apply variable substitution, then deserialize
+    let mut json_value: serde_json::Value =
+        serde_json::from_str(&json_str).map_err(RustmotionError::from)?;
+
+    crate::variables::apply_variables(
+        &mut json_value,
+        directive.config.as_ref(),
+        &directive.include,
+    )?;
+
+    let child_scenario: Scenario =
+        serde_json::from_value(json_value).map_err(RustmotionError::from)?;
 
     // Merge audio tracks from the included file
     audio.extend(child_scenario.audio);
 
     // Recursively resolve any nested includes
-    let mut scenes = resolve_entries(child_scenario.scenes, &child_source, depth, audio)?;
+    let mut scenes = resolve_entries(child_scenario.scenes, &child_source, depth, audio, included_paths)?;
 
     // Apply scene index filter if specified
     if let Some(ref indices) = directive.scenes {