posit-dev
diff --git a/‎CLAUDE.md‎
Lines changed: 9 additions & 62 deletions b/‎CLAUDE.md‎
Lines changed: 9 additions & 62 deletions
diff --git a/‎doc/syntax/layer/type/line.qmd‎
Lines changed: 40 additions & 7 deletions b/‎doc/syntax/layer/type/line.qmd‎
Lines changed: 40 additions & 7 deletions
diff --git a/‎doc/syntax/layer/type/path.qmd‎
Lines changed: 37 additions & 5 deletions b/‎doc/syntax/layer/type/path.qmd‎
Lines changed: 37 additions & 5 deletions
@@ -569,7 +569,9 @@ The codebase includes connection string parsing and feature flags for additional
 
 **Responsibility**: Convert DataFrame + Plot → output format (JSON, PNG, R code, etc.)
 
-#### Writer Trait (`mod.rs`)
+**Internal Architecture**: For Vega-Lite writer implementation details (unified dataset system, layer rendering pipeline, GeomRenderer lifecycle), see [`src/writer/vegalite/CLAUDE.md`](src/writer/vegalite/CLAUDE.md).
+
+#### Writer Trait
 
 ```rust
 pub trait Writer {
@@ -578,68 +580,13 @@ pub trait Writer {
 }
 ```
 
-#### Vega-Lite Writer (`vegalite.rs`)
-
-**Current Production Writer** - Fully implemented and tested.
-
-**Features**:
-
-- Converts Plot → Vega-Lite JSON specification
-- Multi-layer composition support
-- Scale type → Vega field type mapping
-- Faceting (wrap and grid layouts)
-- Axis label customization
-- Inline data embedding
-
-**Architecture**:
+#### Available Writers
 
-```rust
-impl Writer for VegaLiteWriter {
-    fn write(&self, df: &DataFrame, spec: &Plot) -> Result<String> {
-        // 1. Convert DataFrame to JSON values
-        let data_values = self.dataframe_to_json(df)?;
-
-        // 2. Build Vega-Lite spec
-        let mut vl_spec = json!({
-            "$schema": "https://vega.github.io/schema/vega-lite/v6.json",
-            "data": {"values": data_values},
-            "width": 600,
-            "autosize": {"type": "fit", "contains": "padding"}
-        });
-
-        // 3. Handle single vs multi-layer
-        if spec.layers.len() == 1 {
-            // Single layer: flat structure
-            vl_spec["mark"] = self.geom_to_mark(&spec.layers[0].geom);
-            vl_spec["encoding"] = self.build_encoding(&spec.layers[0], df, spec)?;
-        } else {
-            // Multi-layer: layered structure
-            let layers: Vec<Value> = spec.layers.iter()
-                .map(|layer| {
-                    let mut layer_spec = json!({
-                        "mark": self.geom_to_mark(&layer.geom),
-                        "encoding": self.build_encoding(layer, df, spec)?
-                    });
-                    // Apply axis labels to each layer
-                    apply_axis_labels(&mut layer_spec, &spec.labels);
-                    Ok(layer_spec)
-                })
-                .collect::<Result<Vec<_>>>()?;
-            vl_spec["layer"] = json!(layers);
-        }
-
-        // 4. Add faceting, title, etc.
-        self.add_faceting(&mut vl_spec, spec)?;
-        if let Some(labels) = &spec.labels {
-            if let Some(title) = labels.labels.get("title") {
-                vl_spec["title"] = json!(title);
-            }
-        }
-
-        Ok(serde_json::to_string_pretty(&vl_spec)?)
-    }
-}
-```
+**VegaLiteWriter** (Production-ready):
+- Generates Vega-Lite v6 JSON specifications
+- Multi-layer composition with unified dataset architecture
+- Full support for scales, faceting, projections, and labels
+- Automatic geom-specific optimizations (segmentation, decomposition)
 
 ---
 
 
@@ -14,10 +14,10 @@ The following aesthetics are recognised by the line layer.
 * Secondary axis (e.g. `y`): The value of the dependent variable.
 
 ### Optional
-* `colour`/`stroke`: The colour of the line
-* `opacity`: The opacity of the line
-* `linewidth`: The width of the line
-* `linetype`: The type of line, i.e. the dashing pattern
+* `colour`/`stroke`: The colour of the line.
+* `opacity`: The opacity of the line.
+* `linewidth`: The width of the line. If `linewidth` varies within a group, `linetype` is incompatible.
+* `linetype`: The type of line, i.e. the dashing pattern.
 
 ## Settings
 * `position`: Position adjustment. One of `'identity'` (default), `'stack'`, `'dodge'`, or `'jitter'`
@@ -26,7 +26,9 @@ The following aesthetics are recognised by the line layer.
     * `'transposed'` to align the layer's primary axis with the coordinate system's second axis.
 
 ## Data transformation
-The line layer sorts the data along its primary axis.
+The line layer sorts the data along its primary axis. 
+If the line has a variable `stroke` or `opacity` aesthetic within groups, the line is broken into segments. 
+Each segment gets the property of the preceding datapoint, so the last datapoint in a group does not transfer these properties.
 
 ## Orientation
 Line plots are sorted and connected along their primary axis. Since the primary axis cannot be deduced from the mapping it must be specified using the `orientation` setting. If you wish to create a vertical line plot, you need to set `orientation => 'transposed'` to indicate that the primary layer axis follows the second axis of the coordinate system.  
@@ -50,10 +52,41 @@ DRAW line
   PARTITION BY Month
 ```
 
-or split them with an aesthetic
+or split them with a *discrete* aesthetic. 
+We can make a continuous variable (`Month`) discrete by using an ordinal scale.
 
 ```{ggsql}
 VISUALISE FROM ggsql:airquality
 DRAW line
-  MAPPING Day AS x, Temp AS y, Month AS color
+  MAPPING Day AS x, Temp AS y, Month AS stroke
+  SCALE ordinal stroke
 ```
+
+When `stroke` or `opacity` varies, the properties of the preceding datapoint carry over. In the case below, we don't see the blue of the last datapoint.
+
+```{ggsql}
+WITH data(x, y, z) AS (VALUES
+  (1, 2, 1),
+  (2, 5, 3),
+  (3, 3, 5),
+)
+VISUALISE x, y FROM data
+DRAW line
+  MAPPING z AS stroke
+SCALE stroke TO ['red', 'green', 'blue']
+```
+
+The `linewidth` aesthetic can vary point to point.
+
+```{ggsql}
+WITH data(x, y, z) AS (VALUES
+  (1, 2, 1),
+  (2, 5, 3),
+  (3, 3, 5),
+)
+
+VISUALISE x, y FROM data
+DRAW line
+  MAPPING z AS linewidth
+SCALE linewidth TO [0, 30]
+```
@@ -14,16 +14,18 @@ The following aesthetics are recognised by the path layer.
 * Secondary axis (e.g. `y`): Position along the secondary axis.
 
 ### Optional
-* `colour`/`stroke`: The colour of the path
-* `opacity`: The opacity of the path
-* `linewidth`: The width of the path
-* `linetype`: The type of path, i.e. the dashing pattern
+* `colour`/`stroke`: The colour of the path.
+* `opacity`: The opacity of the path.
+* `linewidth`: The width of the path. If `linewidth` varies within a group, `linetype` is incompatible.
+* `linetype`: The type of path, i.e. the dashing pattern.
 
 ## Settings
 * `position`: Position adjustment. One of `'identity'` (default), `'stack'`, `'dodge'`, or `'jitter'`
 
 ## Data transformation
-The path layer does not transform its data but passes it through unchanged
+The path layer does not transform its data but passes it through unchanged.
+If the path has a variable `stroke` or `opacity` aesthetic within groups, the line is broken into segments. 
+Each segment gets the property of the preceding datapoint, so the last datapoint in a group does not transfer these properties.
 
 ## Orientation
 The path layer has no orientation. The axes are treated symmetrically.
@@ -87,3 +89,33 @@ DRAW polygon
 DRAW path 
   MAPPING 'Path' AS stroke
 ```
+
+When `stroke` or `opacity` varies, the properties of the preceding datapoint carry over. In the case below, we don't see the blue of the last datapoint.
+
+```{ggsql}
+WITH data(x, y, z) AS (VALUES
+  (1, 2, 1),
+  (3, 3, 3),
+  (2, 5, 5),
+)
+
+VISUALISE x, y FROM data
+DRAW path
+  MAPPING z AS stroke
+SCALE stroke TO ['red', 'green', 'blue']
+```
+
+The `linewidth` aesthetic can vary point to point.
+
+```{ggsql}
+WITH data(x, y, z) AS (VALUES
+  (1, 2, 1),
+  (3, 3, 3),
+  (2, 5, 5),
+)
+
+VISUALISE x, y FROM data
+DRAW path
+  MAPPING z AS linewidth
+SCALE linewidth TO [0, 30]
+```